所有方法均通过使用 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 可以在无需代理的情况下由基于浏览器的编排器直接调用。