Magisterium AI

开发者
分享:

A2A（协议）
Beta

通过开放的 A2A（Agent-to-Agent） 协议，让您的 AI 智能体能够发现 Magisterium AI、与其通信并向其委派任务。

为什么选择 A2A？

MCP 让 AI 工具 能够访问 Magisterium 的知识，而 A2A 则让 AI 智能体 能够以对等方的身份与 Magisterium 协作。一个编排型智能体可以发现 Magisterium 的能力、向其发送任务并接收结构化结果 —— 这一切都通过标准的 JSON-RPC 接口完成。

需要付费计划。 A2A 端点仅在专业版、组织版和企业版计划中可用。免费账户将收到 PLAN_REQUIRED（-32005）错误。请参阅 MCP 定价 以了解当前计划限制 —— A2A 与 MCP 共享同一个速率限制池。

智能体发现

Magisterium AI 在以下地址发布一张公开的 Agent Card：

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

这是外部智能体发现可用技能、身份验证要求以及 A2A 端点 URL 的方式。该卡片遵循 A2A 规范，获取时无需身份验证。

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

A2A 端点

所有 A2A 操作的 JSON-RPC 端点为：

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

所有请求均使用 POST 方法，需带上 Content-Type: application/json 请求头以及标准的 JSON-RPC 2.0 封装。

能力

Agent Card 公布了以下能力：

能力是否支持备注
streaming否所有技能都是同步的 —— 已完成的任务会在单次响应中返回。
pushNotifications否客户端通过轮询 tasks/get 来获取之前已完成的任务。
stateTransitionHistory是每个任务都会保留其用户和智能体消息的 history。

身份验证

A2A 使用与 Magisterium MCP 服务器 相同的 OAuth 2.0 用户令牌身份验证。您必须在 magisterium.com 上拥有账户才能调用 A2A 端点。

Magisterium 在 https://www.magisterium.com/.well-known/oauth-authorization-server 发布 OAuth 2.0 元数据，其中包含授权端点、令牌端点和动态客户端注册端点。实现 OAuth 2.0 授权码流程（带 PKCE）的客户端可以根据这些元数据获取访问令牌；标准的客户端配置请参阅 MCP 身份验证文档。

获得访问令牌后，请在每个 A2A 请求的 Authorization 请求头中携带它：

Authorization: Bearer $MAGISTERIUM_TOKEN

在 API 控制台 中生成的长期 API 密钥仅适用于 Chat Completions、Search 和 News 端点 —— 它们 无法 用于 A2A 身份验证。请改用 OAuth 颁发的用户令牌。

缺失或无效的令牌将返回 UNAUTHORIZED（-32004）错误。

快速示例

向 catholic_qa 技能发送一个问题：

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

响应是一个已完成的 Task，答案和引用位于 result.artifacts 中：

json
{
  "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": [ /* ... */ ] } }
        ]
      }
    ]
  }
}

后续步骤

  • 入门指南 —— 通过 curl、Python 和 TypeScript 完成您的第一个 A2A 请求。
  • 技能 —— 通过 A2A 公开的全部技能列表，以及每个技能的输入和输出结构。
  • API 参考 —— JSON-RPC 方法、错误码和任务生命周期。