Permetti ai tuoi agenti IA di scoprire le capacità di Magisterium AI, comunicare con essa e delegarle attività tramite il protocollo aperto A2A (Agent-to-Agent).

Perché A2A?

Mentre MCP consente agli strumenti di IA di accedere alla conoscenza del Magistero, A2A consente agli agenti di IA di collaborare con Magisterium come pari. Un agente orchestratore può scoprire le capacità di Magisterium, inviarle attività e ricevere risultati strutturati — il tutto tramite un'interfaccia JSON-RPC standard.

Richiesto un piano a pagamento. L'endpoint A2A è disponibile sui piani Pro, Organizzazione ed Enterprise. Gli account gratuiti ricevono un errore PLAN_REQUIRED (-32005). Consulta i Prezzi MCP per i limiti attuali di ciascun piano — A2A condivide lo stesso pool di limiti di utilizzo.

Individuazione dell'agente

Magisterium AI pubblica una Agent Card pubblica all'indirizzo:

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

È così che gli agenti esterni scoprono le competenze disponibili, i requisiti di autenticazione e l'URL dell'endpoint A2A. La card segue la specifica A2A e non richiede autenticazione per essere scaricata.

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

Endpoint A2A

L'endpoint JSON-RPC per tutte le operazioni A2A è:

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

Tutte le richieste utilizzano POST con un header Content-Type: application/json e una envelope JSON-RPC 2.0 standard.

Capacità

L'Agent Card dichiara le seguenti capacità:

Autenticazione

A2A utilizza la stessa autenticazione tramite token utente OAuth 2.0 del server MCP Magisterium. Devi avere un account su magisterium.com per chiamare l'endpoint A2A.

Magisterium pubblica i metadati OAuth 2.0 all'indirizzo https://www.magisterium.com/.well-known/oauth-authorization-server, inclusi l'endpoint di autorizzazione, l'endpoint del token e l'endpoint di registrazione dinamica dei client. I client che implementano il flusso Authorization Code di OAuth 2.0 (con PKCE) possono ottenere un token di accesso a partire da questi metadati; consulta la documentazione di autenticazione MCP per la configurazione standard lato client.

Una volta ottenuto un token di accesso, includilo nell'header Authorization di ogni richiesta A2A:

Authorization: Bearer $MAGISTERIUM_TOKEN

Le chiavi API a lunga durata generate nella Console API sono destinate esclusivamente agli endpoint Chat Completions, Search e News — non autenticano contro A2A. Utilizza invece un token utente emesso tramite OAuth.

I token mancanti o non validi restituiscono un errore UNAUTHORIZED (-32004).

Esempio rapido

Invia una domanda alla competenza 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" }
        }
      }
    }'

La risposta è una Task completata con la risposta e le citazioni all'interno di 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": [ /* ... */ ] } }
        ]
      }
    ]
  }
}

Prossimi passi

• Iniziare — effettua la tua prima richiesta A2A in curl, Python e TypeScript.
• Competenze — l'elenco completo delle competenze esposte tramite A2A, con le strutture di input e output per ciascuna.
• Riferimento API — metodi JSON-RPC, codici di errore e ciclo di vita delle attività.