Permite que tus agentes de IA descubran las capacidades de Magisterium AI, se comuniquen con ella y le deleguen tareas mediante el protocolo abierto A2A (Agent-to-Agent).

¿Por qué A2A?

Mientras que MCP permite a las herramientas de IA acceder al conocimiento de Magisterium, A2A permite a los agentes de IA colaborar con Magisterium como un par. Un agente orquestador puede descubrir las capacidades de Magisterium, enviarle tareas y recibir resultados estructurados, todo a través de una interfaz JSON-RPC estándar.

Se requiere un plan de pago. El endpoint de A2A está disponible en los planes Pro, Organización y Empresa. Las cuentas gratuitas reciben un error PLAN_REQUIRED (-32005). Consulta los Precios de MCP para ver los límites actuales de cada plan — A2A comparte el mismo grupo de límites de uso.

Descubrimiento del agente

Magisterium AI publica una Agent Card pública en:

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

Así es como los agentes externos descubren las habilidades disponibles, los requisitos de autenticación y la URL del endpoint A2A. La tarjeta sigue la especificación A2A y no requiere autenticación para obtenerla.

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

Endpoint de A2A

El endpoint JSON-RPC para todas las operaciones de A2A es:

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

Todas las solicitudes usan POST con una cabecera Content-Type: application/json y un envoltorio JSON-RPC 2.0 estándar.

Capacidades

La Agent Card anuncia las siguientes capacidades:

Autenticación

A2A utiliza la misma autenticación mediante token de usuario OAuth 2.0 que el servidor MCP de Magisterium. Debes tener una cuenta en magisterium.com para llamar al endpoint de A2A.

Magisterium publica los metadatos de OAuth 2.0 en https://www.magisterium.com/.well-known/oauth-authorization-server, incluyendo el endpoint de autorización, el endpoint de token y el endpoint de registro dinámico de clientes. Los clientes que implementan el flujo de Authorization Code de OAuth 2.0 (con PKCE) pueden obtener un token de acceso a partir de estos metadatos; consulta la documentación de autenticación de MCP para la configuración estándar del lado del cliente.

Una vez que tengas un token de acceso, inclúyelo en la cabecera Authorization de cada solicitud A2A:

Authorization: Bearer $MAGISTERIUM_TOKEN

Las claves de API de larga duración generadas en la Consola de API sirven únicamente para los endpoints de Chat Completions, Search y News — no autentican contra A2A. Usa en su lugar un token de usuario emitido por OAuth.

Los tokens ausentes o inválidos devuelven un error UNAUTHORIZED (-32004).

Ejemplo rápido

Envía una pregunta a la habilidad 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 respuesta es una Task completada con la respuesta y las citas 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 pasos

• Primeros pasos — recorre tu primera solicitud A2A en curl, Python y TypeScript.
• Habilidades — la lista completa de habilidades expuestas a través de A2A, con las formas de entrada y salida de cada una.
• Referencia de API — métodos JSON-RPC, códigos de error y ciclo de vida de las tareas.