Todos os métodos são chamados via POST para https://www.magisterium.com/api/v1/a2a utilizando JSON-RPC 2.0. Cada requisição deve incluir Authorization: Bearer $MAGISTERIUM_TOKEN (um token de utilizador emitido via OAuth — consulte Autenticação) e Content-Type: application/json.

Métodos

message/send

Envie uma mensagem a uma habilidade e receba uma tarefa concluída. Todas as habilidades do Magisterium são síncronas — a resposta contém o estado terminal da tarefa (completed ou failed), nunca um estado intermédio working.

Parâmetros:

Campo	Tipo	Obrigatório	Descrição
message	Message	Sim	A mensagem do utilizador com partes e metadados opcionais.
message.role	string	Sim	Deve ser "user".
message.messageId	string	Sim	ID único para esta mensagem.
message.kind	string	Sim	Deve ser "message".
message.parts	Part[]	Sim	Pelo menos uma parte (text ou data).
message.metadata.skillId	string	Não	Habilidade a invocar. Predefinição: catholic_qa.
message.contextId	string	Não	ID de contexto opcional para agrupar tarefas relacionadas. Se for omitido, o servidor gera um.
configuration	object	Não	Reservado para uso futuro.

Devolve: um objeto Task com kind: "task".

tasks/get

Obtenha uma tarefa previamente criada pelo seu ID.

Parâmetros:

Campo	Tipo	Obrigatório	Descrição
id	string	Sim	O ID da tarefa devolvido por message/send.

Devolve: o objeto Task, ou um erro TASK_NOT_FOUND se tiver expirado ou não existir. As tarefas são armazenadas durante 24 horas.

tasks/cancel

Cancele uma tarefa se estiver num estado cancelável. Como todas as habilidades se resolvem de forma síncrona, a maioria das tarefas já se encontra num estado terminal (completed / failed) no momento em que a resposta é devolvida — tentar cancelar uma tarefa terminal devolve INVALID_PARAMS com a mensagem Invalid state transition.

Parâmetros:

Campo	Tipo	Obrigatório	Descrição
id	string	Sim	O ID da tarefa a cancelar.

Devolve: o objeto Task atualizado com status.state: "canceled".

Ciclo de vida da tarefa

As habilidades do Magisterium são executadas de forma síncrona, pelo que uma tarefa só é persistida no armazenamento depois de a habilidade terminar — sempre num estado terminal. Os estados submitted e working fazem parte da especificação A2A mais alargada, mas nunca são produzidos pela implementação do Magisterium; só irá observar um dos três estados terminais apresentados abaixo.

Estado	Significado
completed	Terminal — os resultados estão em artifacts. Devolvido por message/send quando a habilidade termina com sucesso.
failed	Terminal — status.message contém o motivo da falha. Devolvido por message/send quando a habilidade lança uma exceção.
canceled	Terminal — apenas alcançável chamando tasks/cancel numa tarefa não terminal. Como as tarefas já se encontram num estado terminal no momento em que message/send devolve, na prática o cancelamento é rejeitado com INVALID_PARAMS para qualquer tarefa para a qual tenha uma referência.

Cada tarefa transporta ainda:

• contextId — um identificador de agrupamento que pode reutilizar em mensagens de seguimento para ligar tarefas relacionadas.
• history — a lista ordenada de mensagens do utilizador e do agente que produziram os artefactos da tarefa.

Códigos de erro

Código	Nome	Descrição
-32700	Parse error	Corpo JSON inválido.
-32600	Invalid request	Falta dos campos jsonrpc, method ou id.
-32601	Method not found	Método JSON-RPC desconhecido.
-32602	Invalid params	Parâmetros em falta ou inválidos (devolvido também para transições de estado inválidas em tasks/cancel).
-32603	Internal error	Falha inesperada no servidor.
-32001	Task not found	O ID da tarefa não existe ou expirou.
-32002	Skill not found	skillId desconhecido nos metadados da mensagem.
-32003	Rate limit exceeded	Demasiadas requisições. Verifique retryAfter (segundos) no data do erro.
-32004	Unauthorized	Token Bearer em falta ou inválido.
-32005	Paid plan required	O A2A requer um plano Pro, Organization ou Enterprise.

O estado HTTP espelha a classe do erro: 401 para UNAUTHORIZED, 403 para PLAN_REQUIRED, 429 para RATE_LIMITED e 200 para todos os restantes erros JSON-RPC (segundo a convenção JSON-RPC de devolver 200 com um corpo error).

Limites de utilização

O A2A partilha o mesmo conjunto de limites de utilização do MCP — consulte os Preços do MCP para os limites de requisições de cada plano.

São aplicadas duas variantes:

• Predefinida — aplica-se a document_search, document_fetch, liturgical_readings e saints_of_the_day.
• Intensiva — aplica-se apenas a catholic_qa, porque executa um pipeline de resposta baseado em LLM. Esta variante utiliza um limite mais estrito e baixo.

Quando atinge um limite, o objeto data do erro contém retryAfter em segundos. Os chamadores devem aguardar esse intervalo antes de tentar novamente.

CORS

O endpoint responde a requisições preflight OPTIONS e devolve cabeçalhos CORS permissivos (Access-Control-Allow-Origin: *, Allow-Methods: POST, OPTIONS, Allow-Headers: Content-Type, Authorization), pelo que o A2A pode ser chamado a partir de orquestradores baseados em navegador sem necessidade de um proxy.