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.

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

Preparation before calling¶

First get the intelligent agent calling instructions 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.

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.

{
  "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:

{
  "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.

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

Common HTTP errors¶

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 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.

Last updated on Sep 3, 2026