由其他智能体调用¶

通过 A2A JSON-RPC 向目标智能体发送消息或查询任务。常规智能体调用必须提供 agent_id；通用入口只为受支持的内置智能体代码处理 agent_code。

POST https://moi.matrixorigin.cn/newmoi/agents/a2a

调用前准备¶

先获取智能体调用说明确认目标能力和调用地址。准备有目标工作区访问权限的个人访问令牌、目标工作区 ID 和智能体 ID。

下方示例使用：

$AI_STUDIO_API_KEY：实际个人访问令牌，通过 X-API-Key Header 传递。
$WORKSPACE_ID：目标工作区 ID，通过 X-Workspace-ID Header 传递。
$AGENT_ID：目标智能体 ID。

请求体由智能体选择器和 A2A JSON-RPC 请求组成。agent_id、agent_workspace_id 和 agent_code 由入口处理，不会传递给 A2A 方法处理器。

请求体¶

参数	类型	是否必填	说明
`agent_id`	string	常规调用时是	目标智能体 ID。
`agent_workspace_id`	string	否	目标智能体所属工作区 ID。未提供时使用当前工作区；只能指定当前工作区或系统工作区。
`agent_code`	string	否	受支持的内置智能体代码。不能作为普通智能体 ID 的替代。
`jsonrpc`	string	是	固定为 `2.0`。
`id`	string 或 number	否	调用方生成的 JSON-RPC 请求 ID；响应会回显该值。
`method`	string	是	A2A 方法。例如发送非流式消息使用 `message/send`，查询任务使用 `tasks/get`。
`params.message`	object	`message/send` 时是	A2A 消息对象。
`params.message.kind`	string	`message/send` 时是	固定为 `message`。
`params.message.role`	string	`message/send` 时是	消息角色，例如 `user`。
`params.message.messageId`	string	`message/send` 时是	调用方生成的消息 ID。
`params.message.parts`	object（对象数组）	`message/send` 时是	消息内容分段。例如文本分段可使用 `{"kind":"text","text":"..."}`。
`params.id` 或 `params.taskId`	string	`tasks/get` 时是	要查询的任务 ID。

请求示例¶

以下示例发送一条非流式消息。响应中的任务处于非终止状态时，不代表智能体已经完成处理。

curl -X POST "https://moi.matrixorigin.cn/newmoi/agents/a2a" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "agent_id": "'"$AGENT_ID"'",
    "jsonrpc": "2.0",
    "id": "<REQUEST_ID>",
    "method": "message/send",
    "params": {
      "message": {
        "kind": "message",
        "role": "user",
        "messageId": "<MESSAGE_ID>",
        "parts": [
          {
            "kind": "text",
            "text": "汇总本季度各区域销售额"
          }
        ]
      }
    }
  }'

成功响应¶

成功时返回 200 和 JSON-RPC 响应。result 的结构由所调用的方法决定。

对于 message/send：

返回消息： 直接按消息结果处理。
返回任务： 当任务状态为 submitted、working、input-required 或 auth-required 时，继续查询任务；这些状态不表示智能体已经完成处理。

{
  "jsonrpc": "2.0",
  "id": "req_01",
  "result": {
    "kind": "task",
    "id": "task_01",
    "status": {
      "state": "submitted"
    }
  }
}

响应字段如下。

字段	类型	说明
`jsonrpc`	string	固定为 `2.0`。
`id`	string 或 number 或 null	与请求中的 JSON-RPC ID 对应。
`result`	object	调用成功的结果；字段由 A2A 方法决定。
`result.kind`	string	结果类型。发送消息后可能为 `task` 或消息类型。
`result.id`	string	`result.kind` 为 `task` 时的任务 ID。
`result.status`	object	任务状态；任务结果中可用。
`result.status.state`	string	任务状态：`submitted`、`working`、`input-required`、`auth-required`、`completed`、`failed`、`canceled` 或 `rejected`。

使用 tasks/get 查询任务时，传入任务 ID：

{
  "agent_id": "<AGENT_ID>",
  "jsonrpc": "2.0",
  "id": "<REQUEST_ID>",
  "method": "tasks/get",
  "params": {
    "id": "<TASK_ID>"
  }
}

错误响应¶

A2A 运行时错误使用 JSON-RPC error 对象，不使用通用 code、data 包络。

{
  "jsonrpc": "2.0",
  "id": "req_01",
  "error": {
    "code": -32602,
    "message": "invalid params"
  }
}

常见 HTTP 错误¶

HTTP 状态码	错误代码	常见原因	建议操作
`400`	`-32700`、`-32600`、`-32602`	JSON 无法解析、`jsonrpc` 或请求结构无效，或方法参数不符合要求。	检查 JSON-RPC 包络、智能体选择器和 `params`。
`401`	`-32004`	当前请求缺少有效身份。	检查 API Key 和工作区请求头。
`403`	`-32005`	当前身份不具备目标智能体的运行时调用权限。	使用有权限的身份，或联系管理员授权。
`404`	`-32601`、`-32001`、`-32008`	方法、任务或智能体不存在。	检查 `method`、任务 ID 和智能体 ID。
`409`	`-32002`、`-32006`	任务不能取消或当前任务状态与请求冲突。	先查询任务状态，再选择允许的操作。
`422`	`-32003`、`-32009`	目标智能体不支持该能力，或当前不可运行。	获取 Agent Card，确认能力和智能体状态。
`503`	`-32007`	运行时提供商不可用。	稍后重试；不要把该响应当作任务结果。
`500`	`-32603`	运行时内部错误。	记录请求 ID 和错误信息后重试。

后续操作¶

先使用获取智能体调用说明确认目标能力。对于任务结果，使用相同选择器和 tasks/get 查询；任务要求补充输入时，按任务返回的要求提交输入。

最后更新于 2026 年 8 月 22 日