Call an agent from another agent¶

Send messages or query tasks through A2A JSON-RPC. Generating a workflow and executing it are separate operations.

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

Preparation before calling¶

Get the Agent Card to check capabilities. To generate or revise a workflow candidate, also list available models and select a generation model.

Prepare a personal access token with access to the target workspace and the workspace ID.

Request example¶

$AGENT_ID and $AGENT_WORKSPACE_ID come from the same agent list item’s id and workspace_id. $WORKSPACE_ID identifies the workspace for this task. $MODEL is a returned model name, not a model configuration ID. Generate unique $REQUEST_ID and $MESSAGE_ID strings for this request and message.

This example marks the conversation for workflow generation. Other agent messages can omit conversation_purpose; whether they require an explicit model depends on the target agent.

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": "Generate a manually triggered text-cleaning workflow with a required string input text, using a registered cleaning operator. Submit a deployable candidate; do not deploy or run it."
          }
        ]
      }
    }
  }'

Path parameters¶

Parameter	Type	Required	Description
`workspace_id`	string	Yes	Task workspace; must match the workspace header.
`agent_id`	string	Yes	Target agent ID from the agent list.

Query parameters¶

Parameter	Type	Required	Description
`agent_workspace_id`	string	No	Agent’s owning workspace: the current workspace or `system`. Defaults to the current workspace.

The generic POST /v5/agents/a2a endpoint takes agent_id and optional agent_workspace_id in its body; supported built-in codes can use agent_code. The workspace-scoped endpoint above places selectors in the path and query, and accepts only JSON-RPC in the body.

Request body¶

Field	Type	Required	Description
`jsonrpc`	string	Yes	Set to `2.0`.
`id`	string or number	No	JSON-RPC request ID, echoed in the response.
`method`	string	Yes	`message/send` to send a message or `tasks/get` to query a task.
`params`	object	Yes	Method parameters.
`params.model`	string	For workflow generation	Available model name; required for generation and revisions, not task queries.
`params.metadata`	object	No	Extension information such as conversation purpose.
`params.metadata.conversation_purpose`	string	No	Use `workflow` for workflow generation.
`params.message`	object	For sending	A2A message.
`params.message.kind`	string	For sending	Set to `message`.
`params.message.role`	string	For sending	Use `user` for the request in this example.
`params.message.messageId`	string	For sending	Unique message identifier.
`params.message.contextId`	string	No	Previous task’s `result.contextId` when revising in the same conversation.
`params.message.parts`	object[]	For sending	Message parts.
`params.message.parts[].kind`	string	Yes	Use `text` for text parts.
`params.message.parts[].text`	string	For text parts	Natural-language requirements.
`params.id`	string	For task queries	Actual task ID for `tasks/get`; `params.taskId` is also supported.

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

Successful response¶

Returns JSON-RPC. Sending a message may return a message or a task. An accepted or working task still needs polling and is not a completed result.

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

Field	Type	Description
`jsonrpc`	string	`2.0`.
`id`	string, number, or null	Echoed request ID.
`result`	object	Method result.
`result.kind`	string	Task or message type.
`result.id`	string	Task ID in a task result.
`result.contextId`	string	Conversation context for subsequent revisions.
`result.status`	object	Task status.
`result.status.state`	string	`submitted`, `working`, `input-required`, `auth-required`, `completed`, `failed`, `canceled`, or `rejected`.
`result.artifacts`	object[]	Task artifacts; check for a valid candidate when generating workflows.

Send tasks/get to the same URL with this body. Use result.id, not a conversation or message ID.

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

Provide requested information or authorization for tasks waiting on input or authorization. Stop deployment if generation fails, is canceled, or is rejected. Even a completed task may have no deployable candidate. In that case, ask the assistant to continue with a new message ID, the previous contextId, and params.model again.

Error response¶

The workspace-scoped endpoint returns this error excerpt when a workflow generation request omits the model. Error display text may be localized.

{
  "jsonrpc": "2.0",
  "id": "req_01",
  "error": {
    "code": -32602,
    "message": "智能体运行时请求无效。",
    "data": {
      "domain": "moi-core.agent_runtime",
      "meta": {
        "cause": "workflow agent model is required"
      },
      "reason": "INVALID_PARAMS"
    }
  }
}

HTTP status	Error code	Cause and action
400	`-32602`	Invalid agent parameters, such as a missing workflow generation model. Inspect `error.data.meta.cause` and set `params.model` to an available model name.
500	`ErrServer`	Generic endpoint forwarding or processing failure. Save request time and request/trace IDs; check the workspace-scoped endpoint for details. Query conversations and tasks before resubmitting an uncertain request.

Use error.data.trace_id when available to locate a request. Generic endpoint errors use a different envelope from runtime JSON-RPC errors; handle both formats.

Follow-up operations¶

Keep result.id for polling and result.contextId for revisions.

Last updated on Oct 19, 2026