由其他智能体调用¶

通过 A2A JSON-RPC 向目标智能体发送消息或查询任务。生成任务与执行工作流是两个独立过程。

POST https://api.moi.matrixorigin.cn/v5/workspaces/{workspace_id}/agents/{agent_id}/a2a

调用前准备¶

先获取智能体调用说明，确认目标能力。调用工作流助手生成或修订候选时，还需查询可用模型，选择生成使用的模型。

准备具有目标工作区访问权限的个人访问令牌和目标工作区 ID。

请求示例¶

$AGENT_ID 和 $AGENT_WORKSPACE_ID 来自智能体列表中同一项的 id 和 workspace_id。$WORKSPACE_ID 为本次调用所在工作区，$AI_STUDIO_API_KEY 为调用凭据。$MODEL 为可用模型列表中的 model，不是模型配置 ID。$REQUEST_ID 和 $MESSAGE_ID 是调用方为本次请求和消息生成的唯一字符串。

发送 message/send 时必须指定 params.model。普通智能体消息可省略 conversation_purpose；查询 tasks/get 时不传 params.model。

curl -X POST "https://api.moi.matrixorigin.cn/v5/workspaces/$WORKSPACE_ID/agents/$AGENT_ID/a2a?agent_workspace_id=$AGENT_WORKSPACE_ID" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": "'"$REQUEST_ID"'",
    "method": "message/send",
    "params": {
      "model": "'"$MODEL"'",
      "metadata": {
        "conversation_purpose": "workflow"
      },
      "message": {
        "kind": "message",
        "role": "user",
        "messageId": "'"$MESSAGE_ID"'",
        "parts": [
          {
            "kind": "text",
            "text": "生成一个手动运行的文本清洗工作流，接收必填字符串 text，使用已有清洗算子处理文本。请提交可部署候选，不要直接部署或运行。"
          }
        ]
      }
    }
  }'

路径参数¶

参数	类型	是否必填	说明
`workspace_id`	string	是	本次任务所在工作区，须与工作区请求头一致。
`agent_id`	string	是	智能体列表返回的目标智能体 ID。

查询参数¶

参数	类型	是否必填	说明
`agent_workspace_id`	string	否	目标智能体所属工作区，只能为当前工作区或 `system`；省略时使用当前工作区。

通用入口 POST /v5/agents/a2a 将 agent_id 和可选 agent_workspace_id 放在请求体中；受支持的内置代码也可使用 agent_code。本文的工作区级入口将选择器放在路径和查询参数中，请求体只提交 JSON-RPC。

请求体¶

字段	类型	是否必填	说明
`jsonrpc`	string	是	固定为 `2.0`。
`id`	string 或 number	否	JSON-RPC 请求 ID；响应回显该值。
`method`	string	是	本页使用 `message/send` 发送消息，使用 `tasks/get` 查询任务。
`params`	object	是	对应方法的参数。
`params.model`	string	发送消息时是	可用模型名称。从可用模型列表的 `model` 字段取得；`tasks/get` 不传此字段。缺少时返回 HTTP 400，错误原因为 `MODEL_REQUIRED`。
`params.metadata`	object	否	会话用途等扩展信息。
`params.metadata.conversation_purpose`	string	否	工作流生成填写 `workflow`。
`params.message`	object	发送消息时是	A2A 消息。
`params.message.kind`	string	发送消息时是	固定为 `message`。
`params.message.role`	string	发送消息时是	本页用户需求填写 `user`。
`params.message.messageId`	string	发送消息时是	本条消息的唯一标识。
`params.message.contextId`	string	否	同一会话修订时填写上一任务的 `result.contextId`。
`params.message.parts`	object[]（对象数组）	发送消息时是	消息分段。
`params.message.parts[].kind`	string	是	文本分段填写 `text`。
`params.message.parts[].text`	string	文本分段时是	自然语言需求。
`params.id`	string	查询任务时是	`tasks/get` 使用的真实任务 ID；也支持 `params.taskId`。

字段路径中的 [] 表示数组中的每一项。例如，params.message.parts[].text 表示每个分段的文本。类型后的 [] 表示数组，例如 object[] 是对象数组。

成功响应¶

成功时返回 JSON-RPC 响应。发送消息可能返回消息，也可能返回任务；任务刚受理或仍在处理时，应继续查询，不能视为已完成。

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

响应字段如下。

字段	类型	说明
`jsonrpc`	string	固定为 `2.0`。
`id`	string 或 number 或 null	回显请求 ID。
`result`	object	方法结果。
`result.kind`	string	任务或消息类型。
`result.id`	string	任务结果中的 task ID。
`result.contextId`	string	会话上下文 ID，可用于下一条修订消息。
`result.status`	object	任务状态。
`result.status.state`	string	`submitted`、`working`、`input-required`、`auth-required`、`completed`、`failed`、`canceled` 或 `rejected`。
`result.artifacts`	object[]（对象数组）	任务产物；生成工作流时还需检查是否包含有效候选。

使用相同工作区级 URL，通过 tasks/get 查询，请求体如下。$TASK_ID 来自 result.id，不能使用会话或消息 ID 替代。

{
  "jsonrpc": "2.0",
  "id": "get-task-1",
  "method": "tasks/get",
  "params": {
    "id": "task_01"
  }
}

待输入或待授权时按返回要求补充信息；失败、取消或拒绝时停止后续部署。任务完成仍不保证产生可部署候选。没有候选时，用新的消息 ID 和上一任务的 contextId 要求助手继续，并再次提供 params.model。

错误响应¶

发送消息缺少模型参数时，工作区级接口返回以下错误节选。

{
  "jsonrpc": "2.0",
  "id": "req_01",
  "error": {
    "code": -32602,
    "message": "请通过 params.model 指定模型。",
    "data": {
      "domain": "moi-core.agent_runtime",
      "meta": {
        "cause": "params.model is required"
      },
      "reason": "MODEL_REQUIRED"
    }
  }
}

常见 HTTP 错误¶

HTTP 状态码	错误代码	常见原因	建议操作
400	`-32602`	发送消息时未指定 `params.model`。	从可用模型列表选择 `model` 值填入 `params.model` 后重新发送消息。
500	`ErrServer`	通用入口转发或处理失败，返回通用包络。	保存请求时间、请求/追踪 ID，使用工作区级路径核对具体错误；未取得确定结果时先查询会话与任务，不盲目重复生成。

可用时，error.data.trace_id 用于定位请求。通用入口的错误包络与上述运行时 JSON-RPC 错误不同，不能只按一种格式解析所有错误。

后续操作¶

保留 result.id 查询任务，保留 result.contextId 用于同一会话的修订。取得有效工作流候选后，继续接受工作流候选；完整链路见通过 API 用自然语言搭建工作流。

最后更新于 2026 年 9 月 28 日