# Called by other agents

Send messages or query tasks to target agents via A2A JSON-RPC. Regular agent calls must provide `agent_id`; the general entry only handles `agent_code` for supported built-in agent code.

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

## Preparation before calling

First [get the intelligent agent calling instructions](get-agent-card.md) to confirm the target capability and calling address. Prepare the personal access token, target workspace ID, and agent ID that have access to the target workspace.

The example below uses:

- `$AI_STUDIO_API_KEY`: The actual personal access token, passed through the `X-API-Key` Header.
- `$WORKSPACE_ID`: Target workspace ID, passed through `X-Workspace-ID` Header.
- `$AGENT_ID`: target agent ID.

The request body consists of the agent selector and the A2A JSON-RPC request. `agent_id`, `agent_workspace_id` and `agent_code` are handled by the entrance and are not passed to the A2A method handler.

## Request example

The following example sends a non-streaming message. When the task in the response is in a non-terminated state, it does not mean that the agent has completed processing.

```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": "汇总本季度各区域销售额"
          }
        ]
      }
    }
  }'
```

## Request body

| Parameters | Type | Is it required | Description |
| --- | --- | --- | --- |
| `agent_id` | string | Required for normal agent calls | Target agent ID. |
| `agent_workspace_id` | string | No | ID of the workspace to which the target agent belongs. If not provided, the current workspace is used; only the current workspace or the system workspace can be specified. |
| `agent_code` | string | No | Supported built-in agent code. Cannot be used as a replacement for a normal agent ID. |
| `jsonrpc` | string | Yes | Fixed to `2.0`. |
| `id` | string or number | No | The JSON-RPC request ID generated by the caller; the response echoes this value. |
| `method` | string | Yes | A2A method. For example, use `message/send` to send non-streaming messages and `tasks/get` for query tasks. |
| `params.message` | object | Required for `message/send` | A2A message object. |
| `params.message.kind` | string | Required for `message/send` | Fixed to `message`. |
| `params.message.role` | string | Required for `message/send` | Message role, for example, `user`. |
| `params.message.messageId` | string | Required for `message/send` | Caller-generated message ID. |
| `params.message.parts` | object[] | Required for `message/send` | Message content segmentation. For example, text segmentation can use `{"kind":"text","text":"..."}`. |
| `params.id` or `params.taskId` | string | Required for `tasks/get` | The task ID to be queried. |

`[]` after a type denotes an array. `[]` in a field path denotes each item in an array.

## Successful response

Returns `200` and a JSON-RPC response on success. The structure of `result` is determined by the method called.

For `message/send`:

- **Message result:** Process the message result directly.
- **Task result:** When the task state is `submitted`, `working`, `input-required`, or `auth-required`, continue querying the task; the result is not final.

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

The response fields are as follows.

| Field | Type | Description |
| --- | --- | --- |
| `jsonrpc` | string | Fixed to `2.0`. |
| `id` | string or number or null | Corresponds to the JSON-RPC ID in the request. |
| `result` | object | The result of a successful call; fields are determined by the A2A method. |
| `result.kind` | string | Result type. After sending the message it may be `task` or message type. |
| `result.id` | string | The task ID when `result.kind` is `task`. |
| `result.status` | object | Task status; available in task results. |
| `result.status.state` | string | Task status: `submitted`, `working`, `input-required`, `auth-required`, `completed`, `failed`, `canceled` or `rejected`. |

When querying tasks using `tasks/get`, pass in the task ID:

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

## Error response

A2A runtime error uses JSON-RPC `error` objects, not the generic `code`, `data` envelopes.

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

### Common HTTP errors

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

* - HTTP status code
  - error code
  - Common causes
  - Recommended actions
* - `400`
  - `-32700`、`-32600`、`-32602`
  - JSON cannot be parsed, `jsonrpc`, or the request structure is invalid, or the method parameters do not meet the requirements.
  - Check JSON-RPC envelopes, agent selectors and `params`.
* - `401`
  - `-32004`
  - The current request is missing a valid identity.
  - Check API Key and Workspace request headers.
* - `403`
  - `-32005`
  - The current identity does not have runtime calling permissions for the target agent.
  - Use an authorized identity, or contact the administrator for authorization.
* - `404`
  - `-32601`、`-32001`、`-32008`
  - The method, task or agent does not exist.
  - Check `method`, task ID and agent ID.
* - `409`
  - `-32002`、`-32006`
  - The task cannot be canceled or the current task status conflicts with the request.
  - Check task status first, then select allowed operations.
* - `422`
  - `-32003`、`-32009`
  - The target agent does not support this capability, or it is not currently operable.
  - Obtain Agent Card to confirm abilities and agent status.
* - `503`
  - `-32007`
  - The runtime provider is unavailable.
  - Try again later; do not treat this response as a task result.
* - `500`
  - `-32603`
  - Internal error at runtime.
  - Record the request ID and error message and try again.
```

## Follow-up operations

First use [Get the agent call instructions](get-agent-card.md) to confirm the target ability. For the task results, use the same selector and `tasks/get` query; when the task requires supplementary input, submit the input according to the requirements returned by the task.