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 規範,擷取時不需要身份驗證。
curl https://www.magisterium.com/.well-known/agent.jsonA2A 端點
所有 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 技能傳送一個問題:
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 中:
{
"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": [ /* ... */ ] } }
]
}
]
}
}