Enable your AI agents to discover, communicate with, and delegate tasks to Magisterium AI using the open A2A (Agent-to-Agent) protocol.

Why A2A?

While MCP lets AI tools access Magisterium's knowledge, A2A lets AI agents collaborate with Magisterium as a peer. An orchestrating agent can discover Magisterium's capabilities, send it tasks, and receive structured results — all through a standard JSON-RPC interface.

Paid plan required. The A2A endpoint is available on the Pro, Organization, and Enterprise plans. Free accounts receive a PLAN_REQUIRED (-32005) error. See MCP Pricing for current plan limits — A2A shares the same rate-limit pool.

Agent Discovery

Magisterium AI publishes a public Agent Card at:

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

This is how external agents discover available skills, authentication requirements, and the A2A endpoint URL. The card follows the A2A specification and requires no authentication to fetch.

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

A2A Endpoint

The JSON-RPC endpoint for all A2A operations is:

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

All requests use POST with a Content-Type: application/json header and a standard JSON-RPC 2.0 envelope.

Capabilities

The Agent Card advertises the following capabilities:

Authentication

A2A uses the same OAuth 2.0 user-token authentication as the Magisterium MCP server. You must have an account on magisterium.com to call the A2A endpoint.

Magisterium publishes OAuth 2.0 metadata at https://www.magisterium.com/.well-known/oauth-authorization-server, including the authorization endpoint, token endpoint, and dynamic client-registration endpoint. Clients that implement the OAuth 2.0 Authorization Code flow (with PKCE) can obtain an access token from this metadata; see the MCP authentication docs for the standard client-side setup.

Once you have an access token, include it in the Authorization header of every A2A request:

Authorization: Bearer $MAGISTERIUM_TOKEN

The long-lived API keys generated in the API Console are for the Chat Completions, Search, and News endpoints only — they will not authenticate against A2A. Use an OAuth-issued user token instead.

Missing or invalid tokens return an UNAUTHORIZED (-32004) error.

Quick Example

Send a question to the catholic_qa skill:

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" }
        }
      }
    }'

The response is a completed Task with the answer and citations inside 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": [ /* ... */ ] } }
        ]
      }
    ]
  }
}

Next Steps

• Getting Started — walk through your first A2A request in curl, Python, and TypeScript.
• Skills — the full list of skills exposed via A2A, with per-skill input and output shapes.
• API Reference — JSON-RPC methods, error codes, and task lifecycle.