すべてのメソッドは、JSON-RPC 2.0 を使って https://www.magisterium.com/api/v1/a2a に対して POST で呼び出されます。すべてのリクエストには Authorization: Bearer $MAGISTERIUM_TOKEN（OAuth で発行されたユーザートークン — 認証 を参照）と Content-Type: application/json を含める必要があります。

メソッド

message/send

スキルにメッセージを送信し、完了済みのタスクを受け取ります。すべての Magisterium スキルは同期的です — レスポンスには終端タスクの状態（completed または failed）が含まれ、中間の working ステータスが返されることはありません。

パラメータ:

フィールド	型	必須	説明
message	Message	はい	part とオプションのメタデータを含むユーザーメッセージ。
message.role	string	はい	"user" である必要があります。
message.messageId	string	はい	このメッセージの一意な ID。
message.kind	string	はい	"message" である必要があります。
message.parts	Part[]	はい	少なくとも 1 つの part（text または data）。
message.metadata.skillId	string	いいえ	呼び出すスキル。既定は catholic_qa。
message.contextId	string	いいえ	関連するタスクをグループ化するためのオプションの context ID。省略された場合、サーバーが生成します。
configuration	object	いいえ	将来のために予約されています。

戻り値: kind: "task" を持つ Task オブジェクト。

tasks/get

以前に作成されたタスクを ID で取得します。

パラメータ:

フィールド	型	必須	説明
id	string	はい	message/send から返されたタスク ID。

戻り値: Task オブジェクト、または期限切れ・欠落している場合は TASK_NOT_FOUND エラー。タスクは 24 時間 保存されます。

tasks/cancel

タスクがキャンセル可能な状態にある場合にキャンセルします。すべてのスキルは同期的に解決されるため、レスポンスが返ってくる時点ですでに多くのタスクが終端状態（completed / failed）にあります — 終端状態のタスクのキャンセルを試みると、Invalid state transition メッセージと共に INVALID_PARAMS が返されます。

パラメータ:

フィールド	型	必須	説明
id	string	はい	キャンセルするタスク ID。

戻り値: status.state: "canceled" となった更新済みの Task オブジェクト。

タスクのライフサイクル

Magisterium のスキルは同期的に実行されるため、タスクはスキルが終了した後にのみストレージに永続化されます — 常に終端状態です。submitted と working の状態は、より広範な A2A 仕様の一部ですが、Magisterium の実装では 決して生成されません。観察できるのは以下の 3 つの終端状態のいずれかだけです。

状態	意味
completed	終端 — 結果は artifacts にあります。スキルが正常に完了したときに message/send から返されます。
failed	終端 — status.message に失敗の理由が含まれます。スキルが例外をスローしたときに message/send から返されます。
canceled	終端 — 非終端状態のタスクに対して tasks/cancel を呼び出した場合にのみ到達します。message/send が返ってくる時点でタスクはすでに終端状態にあるため、実際にはハンドルを持っているどのタスクに対しても、キャンセルは INVALID_PARAMS で拒否されます。

各タスクには以下も含まれます：

• contextId — 関連するタスクを結びつけるために、後続のメッセージで再利用できるグループ識別子。
• history — タスクの artifact を生成した、ユーザーとエージェントのメッセージの順序付きリスト。

エラーコード

コード	名前	説明
-32700	Parse error	JSON ボディが無効です。
-32600	Invalid request	jsonrpc、method、または id フィールドが欠落しています。
-32601	Method not found	未知の JSON-RPC メソッド。
-32602	Invalid params	パラメータが欠落または無効です（tasks/cancel の無効な状態遷移でも返されます）。
-32603	Internal error	予期しないサーバー側の障害。
-32001	Task not found	タスク ID が存在しないか、期限切れです。
-32002	Skill not found	メッセージのメタデータ内の skillId が未知です。
-32003	Rate limit exceeded	リクエストが多すぎます。エラーの data にある retryAfter（秒）を確認してください。
-32004	Unauthorized	Bearer トークンが欠落または無効です。
-32005	Paid plan required	A2A には Pro、Organization、または Enterprise プランが必要です。

HTTP ステータスはエラークラスを反映します: UNAUTHORIZED には 401、PLAN_REQUIRED には 403、RATE_LIMITED には 429、その他の JSON-RPC エラーはすべて 200（200 と共に error ボディを返す JSON-RPC の規約に従う）。

レートリミット

A2A は MCP と同じレートリミットプールを共有します — プランごとのリクエスト上限については MCP 価格 を参照してください。

2 つの変種が適用されます:

• 既定 — document_search、document_fetch、liturgical_readings、および saints_of_the_day に適用されます。
• 高コスト — catholic_qa のみに適用されます。これは LLM ベースの回答パイプラインを実行するためです。この変種はより厳しい、低い上限を使用します。

制限に達した場合、エラーの data オブジェクトに retryAfter が秒単位で含まれます。呼び出し元は、再試行する前にその間隔だけバックオフする必要があります。

CORS

このエンドポイントは OPTIONS プリフライトリクエストに応答し、寛容な CORS ヘッダー（Access-Control-Allow-Origin: *、Allow-Methods: POST, OPTIONS、Allow-Headers: Content-Type, Authorization）を返すため、A2A はプロキシなしでブラウザーベースのオーケストレーターから呼び出すことができます。