Permita que os seus agentes de IA descubram as capacidades do Magisterium AI, comuniquem com ele e lhe deleguem tarefas através do protocolo aberto A2A (Agent-to-Agent).

Porquê A2A?

Enquanto o MCP permite que as ferramentas de IA acedam ao conhecimento do Magistério, o A2A permite que os agentes de IA colaborem com o Magisterium como um par. Um agente orquestrador pode descobrir as capacidades do Magisterium, enviar-lhe tarefas e receber resultados estruturados — tudo através de uma interface JSON-RPC padrão.

É necessário um plano pago. O endpoint A2A está disponível nos planos Pro, Organization e Enterprise. As contas gratuitas recebem um erro PLAN_REQUIRED (-32005). Consulte os Preços do MCP para ver os limites atuais de cada plano — o A2A partilha o mesmo conjunto de limites de utilização.

Descoberta do agente

O Magisterium AI publica uma Agent Card pública em:

https://www.magisterium.com/.well-known/agent.json

É assim que agentes externos descobrem as habilidades disponíveis, os requisitos de autenticação e o URL do endpoint A2A. A card segue a especificação A2A e não requer autenticação para ser obtida.

curl https://www.magisterium.com/.well-known/agent.json

Endpoint A2A

O endpoint JSON-RPC para todas as operações A2A é:

https://www.magisterium.com/api/v1/a2a

Todas as requisições usam POST com um cabeçalho Content-Type: application/json e um envelope JSON-RPC 2.0 padrão.

Capacidades

A Agent Card anuncia as seguintes capacidades:

Autenticação

O A2A utiliza a mesma autenticação por token de utilizador OAuth 2.0 que o servidor MCP do Magisterium. Tem de possuir uma conta em magisterium.com para invocar o endpoint A2A.

O Magisterium publica os metadados OAuth 2.0 em https://www.magisterium.com/.well-known/oauth-authorization-server, incluindo o endpoint de autorização, o endpoint de token e o endpoint de registo dinâmico de clientes. Os clientes que implementem o fluxo Authorization Code do OAuth 2.0 (com PKCE) podem obter um token de acesso a partir destes metadados; consulte a documentação de autenticação do MCP para a configuração padrão do lado do cliente.

Assim que tiver um token de acesso, inclua-o no cabeçalho Authorization de cada requisição A2A:

Authorization: Bearer $MAGISTERIUM_TOKEN

As chaves de API de longa duração geradas na Consola de API destinam-se apenas aos endpoints Chat Completions, Search e News — não autenticam contra o A2A. Utilize antes um token de utilizador emitido via OAuth.

Tokens em falta ou inválidos devolvem um erro UNAUTHORIZED (-32004).

Exemplo rápido

Envie uma pergunta à habilidade catholic_qa:

curl -X POST https://www.magisterium.com/api/v1/a2a \
    -H "Authorization: Bearer $MAGISTERIUM_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "message/send",
      "params": {
        "message": {
          "role": "user",
          "messageId": "msg-001",
          "kind": "message",
          "parts": [{ "kind": "text", "text": "What does the Church teach about the Real Presence?" }],
          "metadata": { "skillId": "catholic_qa" }
        }
      }
    }'

A resposta é uma Task concluída com a resposta e as citações dentro de result.artifacts:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "id": "task_abc123",
    "contextId": "ctx_def456",
    "kind": "task",
    "status": { "state": "completed", "timestamp": "2026-04-20T12:00:00.000Z" },
    "artifacts": [
      {
        "artifactId": "art_ghi789",
        "name": "catholic_qa_response",
        "parts": [
          { "kind": "text", "text": "The Catholic Church teaches..." },
          { "kind": "data", "data": { "citations": [ /* ... */ ] } }
        ]
      }
    ]
  }
}

Próximos passos

• Primeiros passos — faça a sua primeira requisição A2A em curl, Python e TypeScript.
• Habilidades — a lista completa de habilidades expostas através do A2A, com as estruturas de entrada e saída de cada uma.
• Referência da API — métodos JSON-RPC, códigos de erro e ciclo de vida das tarefas.