Umožněte svým AI agentům objevit Magisterium AI, komunikovat s ním a delegovat na něj úlohy pomocí otevřeného protokolu A2A (Agent-to-Agent).

Proč A2A?

Zatímco MCP umožňuje AI nástrojům přistupovat ke znalostem Magisteria, A2A umožňuje AI agentům spolupracovat s Magisteriem jako s rovnocenným partnerem. Orchestrátorský agent dokáže objevit schopnosti Magisteria, posílat mu úlohy a přijímat strukturované výsledky — to vše prostřednictvím standardního JSON-RPC rozhraní.

Vyžadován placený plán. Endpoint A2A je k dispozici v plánech Pro, Organization a Enterprise. Bezplatné účty obdrží chybu PLAN_REQUIRED (-32005). Aktuální limity pro jednotlivé plány naleznete v Ceníku MCP — A2A sdílí stejný pool limitů požadavků.

Objevování agenta

Magisterium AI publikuje veřejnou Agent Card na adrese:

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

Takto externí agenti objevují dostupné dovednosti, požadavky na autentizaci a URL endpointu A2A. Karta odpovídá specifikaci A2A a nevyžaduje žádnou autentizaci k získání.

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

Endpoint A2A

JSON-RPC endpoint pro všechny operace A2A:

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

Všechny požadavky používají POST s hlavičkou Content-Type: application/json a standardní obálkou JSON-RPC 2.0.

Schopnosti

Agent Card inzeruje následující schopnosti:

Autentizace

A2A používá stejnou autentizaci pomocí uživatelského OAuth 2.0 tokenu jako server Magisterium MCP. Pro volání endpointu A2A musíte mít účet na magisterium.com.

Magisterium publikuje metadata OAuth 2.0 na https://www.magisterium.com/.well-known/oauth-authorization-server, včetně autorizačního endpointu, token endpointu a endpointu pro dynamickou registraci klienta. Klienti, kteří implementují tok OAuth 2.0 Authorization Code (s PKCE), si z těchto metadat mohou získat přístupový token; standardní klientské nastavení viz dokumentace k autentizaci MCP.

Jakmile máte přístupový token, vkládejte jej do hlavičky Authorization každého A2A požadavku:

Authorization: Bearer $MAGISTERIUM_TOKEN

Dlouhodobé API klíče vygenerované v API Console jsou určeny pouze pro endpointy Chat Completions, Search a News — proti A2A se s nimi nelze autentizovat. Místo toho použijte uživatelský token vydaný přes OAuth.

Chybějící nebo neplatné tokeny vrátí chybu UNAUTHORIZED (-32004).

Rychlý příklad

Pošlete otázku dovednosti 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" }
        }
      }
    }'

Odpověď je dokončený Task s odpovědí a citacemi uvnitř 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": [ /* ... */ ] } }
        ]
      }
    ]
  }
}

Další kroky

• Začínáme — projděte si svůj první A2A požadavek v curl, Pythonu a TypeScriptu.
• Dovednosti — úplný seznam dovedností zpřístupněných přes A2A, s formáty vstupních a výstupních dat pro každou dovednost.
• API Reference — JSON-RPC metody, chybové kódy a životní cyklus úlohy.