由其他智能体调用¶

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

POST https://api.moi.matrixorigin.cn/v5/agents/a2a

调用前准备¶

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

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

请求体¶

请求示例

curl -X POST "https://api.moi.matrixorigin.cn/v5/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": "汇总本季度各区域销售额"
          }
        ]
      }
    }
  }'

字段说明

请求字段

字段	类型	必填	说明
`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`	array of object	message/send 时是	消息内容分段。例如文本分段可使用 {“kind”:”text”,”text”:”…”}。
`params.id 或 params.taskId`	string	tasks/get 时是	要查看的任务 ID。

成功响应¶

响应示例

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

字段说明

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

对于 message/send：

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

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

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

通用字段

字段	类型	说明
`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。

错误响应¶

响应示例

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

字段说明

A2A 运行时错误使用 JSON-RPC error 对象，不使用通用 code、data 响应格式。

常见 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 年 9 月 11 日