Magisterium AI

開發者
分享:

入門指南

本指南將引導您向 Magisterium A2A 端點發出第一個請求、擷取產生的任務並讀取結構化回應。

前置條件

  1. 付費的 Magisterium 計劃（專業版、組織版或企業版）。免費帳戶會從 A2A 收到 PLAN_REQUIRED 錯誤。
  2. 與您 magisterium.com 帳戶繫結的 OAuth 2.0 存取權杖。A2A 使用與 Magisterium MCP 伺服器 相同的 OAuth 流程；可從 https://www.magisterium.com/.well-known/oauth-authorization-server 的 OAuth 中繼資料中發現授權端點、權杖端點和動態註冊端點。
  3. 您想要呼叫的技能 —— 完整清單請參閱 技能。

請注意: 在 API 控制台 中建立的長期 API 金鑰可用於 Chat Completions、Search 和 News,但 不適用於 A2A —— A2A 僅接受 OAuth 簽發的使用者權杖。

將存取權杖匯出為環境變數,這樣以下範例就能自動讀取:

bash
export MAGISTERIUM_TOKEN=<your-access-token-here>

步驟 1:發現代理

在呼叫端點之前,您可以先擷取公開的 Agent Card,以檢視有哪些可用技能並確認協定版本:

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

擷取該卡片不需要身份驗證。編排器可以快取它一小時 —— 該端點設定了 Cache-Control: public, max-age=3600。

步驟 2:傳送您的第一則訊息

所有 A2A 操作都透過單一 JSON-RPC 端點:POST https://www.magisterium.com/api/v1/a2a。以下範例針對 catholic_qa 技能呼叫 message/send。

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" }
        }
      }
    }'
typescript
const accessToken = process.env.MAGISTERIUM_TOKEN!;

const response = await fetch("https://www.magisterium.com/api/v1/a2a", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${accessToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    jsonrpc: "2.0",
    id: 1,
    method: "message/send",
    params: {
      message: {
        role: "user",
        messageId: crypto.randomUUID(),
        kind: "message",
        parts: [
          { kind: "text", text: "What does the Church teach about the Real Presence?" },
        ],
        metadata: { skillId: "catholic_qa" },
      },
    },
  }),
});

const { result: task } = await response.json();
console.log(task.id, task.status.state);
for (const artifact of task.artifacts ?? []) {
  for (const part of artifact.parts) {
    if (part.kind === "text") console.log(part.text);
  }
}
python
import os
import uuid
import httpx

access_token = os.environ["MAGISTERIUM_TOKEN"]

payload = {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "message/send",
    "params": {
        "message": {
            "role": "user",
            "messageId": str(uuid.uuid4()),
            "kind": "message",
            "parts": [
                {"kind": "text", "text": "What does the Church teach about the Real Presence?"}
            ],
            "metadata": {"skillId": "catholic_qa"},
        }
    },
}

response = httpx.post(
    "https://www.magisterium.com/api/v1/a2a",
    headers={
        "Authorization": f"Bearer {access_token}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=60,
)
task = response.json()["result"]
print(task["id"], task["status"]["state"])
for artifact in task.get("artifacts", []):
    for part in artifact["parts"]:
        if part["kind"] == "text":
            print(part["text"])

步驟 3:讀取回應

message/send 會返回一個 kind: "task" 的 Task 物件。同步的技能呼叫一定會以兩種終止狀態之一結束:

  • status.state == "completed" —— 結果位於 result.artifacts 中。每個 artifact 都有一個 artifactId、一個可選的 name,以及一個或多個 parts（text、data 或 file）。
  • status.state == "failed" —— 失敗原因位於 status.message.parts[0].text 中。
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": [] } }
        ]
      }
    ]
  }
}

步驟 4:擷取或取消任務

任務會保存 24 小時,可以使用 tasks/get 透過 ID 重新擷取:

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": 2,
      "method": "tasks/get",
      "params": { "id": "task_abc123" }
    }'

若您需要中止任務,請以相同 ID 呼叫 tasks/cancel。由於所有 Magisterium 技能皆為同步解析,取消操作僅在少數重試場景中有用 —— 已 completed 或 failed 的任務無法被取消,並會返回 INVALID_PARAMS。

常見錯誤

代碼含意解決方式
-32004未授權檢查 Authorization 標頭,並確認存取權杖有效且未過期。
-32005需付費計劃請在 magisterium.com/plan 升級您的帳戶。
-32002找不到技能確認 metadata.skillId 與 Agent Card 中列出的某個 ID 相符。
-32003超出速率限制在重試前等待 retryAfter 秒（位於錯誤的 data 中）。

完整方法與錯誤碼請參閱 API 參考。