# 由其他智能体调用

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

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

## 调用前准备

先[获取智能体调用说明](get-agent-card.md)确认目标能力和调用地址。准备有目标工作区访问权限的个人访问令牌、目标工作区 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。 |

## 请求示例

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

```bash
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` 时，继续查询任务；这些状态不表示智能体已经完成处理。

```json
{
  "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：

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

## 错误响应

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

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

### 常见 HTTP 错误

```{list-table}
:header-rows: 1
:widths: 12 22 32 34

* - 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 和错误信息后重试。
```

## 后续操作

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