所有方法皆透過以 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[]	是	至少一個 part（文字或資料）。
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_PARAMS 以及 Invalid state transition 訊息。

參數:

欄位	類型	是否必填	描述
id	string	是	要取消的任務 ID。

返回: 更新後的 Task 物件,其 status.state 為 "canceled"。

任務生命週期

Magisterium 的技能皆為同步執行,因此任務僅在技能完成後才會持久化到儲存中 —— 始終處於終止狀態。submitted 與 working 狀態屬於更廣泛的 A2A 規範,但 Magisterium 的實作 從不產生 這兩種狀態;您只會觀察到下列三種終止狀態之一。

狀態	含意
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 需要專業版、組織版或企業版計劃。

HTTP 狀態碼對應錯誤類別:UNAUTHORIZED 為 401、PLAN_REQUIRED 為 403、RATE_LIMITED 為 429,其他所有 JSON-RPC 錯誤皆為 200（依 JSON-RPC 慣例,以 200 返回且在內文中攜帶 error）。

速率限制

A2A 與 MCP 共用同一個速率限制池 —— 每個計劃的請求上限請參閱 MCP 定價。

強制執行兩種變體:

• 預設 —— 適用於 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 可以在不需要代理的情況下,由以瀏覽器為基礎的編排器直接呼叫。