Magisterium AI

開発者
共有:

はじめに

このガイドでは、Magisterium A2A エンドポイントへの最初のリクエスト作成、結果のタスクの取得、および構造化レスポンスの読み取りについて順を追って説明します。

前提条件

  1. 有料の Magisterium プラン（Pro、Organization、または Enterprise）。無料アカウントでは 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

このカードの取得に認証は不要です。オーケストレーターは 1 時間キャッシュできます — エンドポイントは 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 オブジェクトを返します。同期的なスキル呼び出しは常に次の 2 つの終端状態のいずれかで終了します：

  • status.state == "completed" — 結果は result.artifacts にあります。各 artifact には artifactId、オプションの name、および 1 つ以上の 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レートリミット超過再試行する前にエラーの data にある retryAfter 秒だけ待ってください。

すべてのメソッドとエラーコードについては、完全な API リファレンス を参照してください。