Tutti i metodi vengono invocati tramite POST su https://www.magisterium.com/api/v1/a2a utilizzando JSON-RPC 2.0. Ogni richiesta deve includere Authorization: Bearer $MAGISTERIUM_TOKEN (un token utente emesso tramite OAuth — vedi Autenticazione) e Content-Type: application/json.

Metodi

message/send

Invia un messaggio a una competenza e ricevi un'attività completata. Tutte le competenze Magisterium sono sincrone — la risposta contiene lo stato terminale dell'attività (completed o failed), mai uno stato intermedio working.

Parametri:

Campo	Tipo	Obbligatorio	Descrizione
message	Message	Sì	Il messaggio dell'utente con parti e metadati opzionali.
message.role	string	Sì	Deve essere "user".
message.messageId	string	Sì	ID univoco per questo messaggio.
message.kind	string	Sì	Deve essere "message".
message.parts	Part[]	Sì	Almeno una parte (text o data).
message.metadata.skillId	string	No	Competenza da invocare. Valore predefinito: catholic_qa.
message.contextId	string	No	ID di contesto opzionale per raggruppare attività correlate. Se omesso, il server ne genera uno.
configuration	object	No	Riservato a usi futuri.

Restituisce: un oggetto Task con kind: "task".

tasks/get

Recupera un'attività creata in precedenza tramite il suo ID.

Parametri:

Campo	Tipo	Obbligatorio	Descrizione
id	string	Sì	L'ID dell'attività restituito da message/send.

Restituisce: l'oggetto Task, oppure un errore TASK_NOT_FOUND se è scaduta o non esiste. Le attività vengono conservate per 24 ore.

tasks/cancel

Annulla un'attività se si trova in uno stato annullabile. Poiché tutte le competenze si risolvono in modo sincrono, la maggior parte delle attività è già in uno stato terminale (completed / failed) al momento della risposta — tentare di annullare un'attività terminale restituisce INVALID_PARAMS con il messaggio Invalid state transition.

Parametri:

Campo	Tipo	Obbligatorio	Descrizione
id	string	Sì	L'ID dell'attività da annullare.

Restituisce: l'oggetto Task aggiornato con status.state: "canceled".

Ciclo di vita dell'attività

Le competenze di Magisterium vengono eseguite in modo sincrono, quindi un'attività viene persistita nello storage solo dopo che la competenza termina — sempre in uno stato terminale. Gli stati submitted e working fanno parte della più ampia specifica A2A ma non vengono mai prodotti dall'implementazione di Magisterium; osserverai sempre soltanto uno dei tre stati terminali elencati di seguito.

Stato	Significato
completed	Terminale — i risultati si trovano in artifacts. Restituito da message/send quando la competenza termina con successo.
failed	Terminale — status.message contiene il motivo del fallimento. Restituito da message/send quando la competenza solleva un'eccezione.
canceled	Terminale — raggiungibile solo chiamando tasks/cancel su un'attività non terminale. Poiché le attività sono già terminali nel momento in cui message/send restituisce, in pratica l'annullamento viene rifiutato con INVALID_PARAMS per qualsiasi attività di cui si disponga di un riferimento.

Ogni attività include inoltre:

• contextId — un identificatore di raggruppamento che puoi riutilizzare tra messaggi di follow-up per collegare attività correlate.
• history — l'elenco ordinato dei messaggi dell'utente e dell'agente che hanno prodotto gli artefatti dell'attività.

Codici di errore

Codice	Nome	Descrizione
-32700	Parse error	Corpo JSON non valido.
-32600	Invalid request	Campi jsonrpc, method o id mancanti.
-32601	Method not found	Metodo JSON-RPC sconosciuto.
-32602	Invalid params	Parametri mancanti o non validi (restituito anche per transizioni di stato non valide di tasks/cancel).
-32603	Internal error	Errore inaspettato lato server.
-32001	Task not found	L'ID dell'attività non esiste o è scaduto.
-32002	Skill not found	skillId sconosciuto nei metadati del messaggio.
-32003	Rate limit exceeded	Troppe richieste. Controlla retryAfter (secondi) nel data dell'errore.
-32004	Unauthorized	Token Bearer mancante o non valido.
-32005	Paid plan required	A2A richiede un piano Pro, Organizzazione o Enterprise.

Lo stato HTTP rispecchia la classe dell'errore: 401 per UNAUTHORIZED, 403 per PLAN_REQUIRED, 429 per RATE_LIMITED e 200 per tutti gli altri errori JSON-RPC (secondo la convenzione JSON-RPC di restituire 200 con un corpo error).

Limiti di utilizzo

A2A condivide lo stesso pool di limiti di utilizzo di MCP — consulta i Prezzi MCP per i limiti di richieste per ciascun piano.

Vengono applicate due varianti:

• Predefinita — si applica a document_search, document_fetch, liturgical_readings e saints_of_the_day.
• Intensiva — si applica solo a catholic_qa, perché esegue una pipeline di risposta basata su LLM. Questa variante utilizza un limite più rigoroso e più basso.

Quando raggiungi un limite, l'oggetto data dell'errore contiene retryAfter in secondi. I chiamanti devono attendere tale intervallo prima di riprovare.

CORS

L'endpoint risponde alle richieste preflight OPTIONS e restituisce header CORS permissivi (Access-Control-Allow-Origin: *, Allow-Methods: POST, OPTIONS, Allow-Headers: Content-Type, Authorization), in modo che A2A possa essere chiamato da orchestratori basati su browser senza un proxy.