Skip to main content

Agents calling agents

An agent can hand work to another agent of the same project in three ways:

  • A2A. Any agent with an agent key, including a code agent or an agent running outside Orchestrate, calls another agent over the Agent2Agent protocol version 1.0, in its JSON-RPC, HTTP+JSON or gRPC binding.
  • Agent as a tool. A console-made agent is given another agent as one of its tools. The model decides when to call it.
  • MCP. An MCP client, such as Claude Desktop, an IDE or another agent framework, calls the project's agents as MCP tools. See Outside MCP clients.

Both kinds of agent can be called: console-made agents and code agents. Every way goes through the same checks.

To call an agent that runs outside the project, on another platform or another Orchestrate install, see Remote agents and trusted installs.

Requires code agents

The A2A surface and agent keys are part of the code agents feature. While your operator has code agents switched off (agents.enabled: false), the A2A endpoints answer 404. See Code agents.

Which agents can be called​

An agent can be called when it has a live version and its name is a DNS label: lowercase letters, digits and hyphens, such as billing-helper. Console names can be free text, and an agent whose name isn't a DNS label is left out of the directory and the tool list. Its A2A panel says so.

Calls stay inside one project. A key from another project is refused.

A2A​

Discover and call​

EndpointWhat it returns
GET /a2a/v1/agentsThe agents of the caller's project that the caller may call, as A2A agent cards.
GET /a2a/v1/agents/{name}/.well-known/agent-card.jsonOne agent's card.
POST /a2a/v1/agents/{name}JSON-RPC 2.0. Send the header A2A-Version: 1.0.

Supported methods: SendMessage (blocking, or return immediately), SendStreamingMessage, GetTask, ListTasks, CancelTask, SubscribeToTask (a stream of a working task's updates, for up to 15 minutes), the four push notification config methods, and GetExtendedAgentCard (the card plus a console-made agent's tools as skills).

Push notifications. A caller can register a webhook for a task, or pass one with the message. When the task ends, Orchestrate posts it there, at least once, with the X-A2A-Notification-Token header. Only hosts your operator allows for Agent API webhooks are accepted, and cards declare push notifications only when some are allowed. See Agent API.

The caller authenticates with an agent key (vcag_), bound to one project and one agent name, as Authorization: Bearer vcag_.... A project admin creates agent keys on the API keys page, under Agent keys. A code agent deployed by Orchestrate already has one, and reaches A2A through the platform's agent edge at the address in its VOIS_A2A_URL environment variable.

curl https://orchestrate-api.example.com/a2a/v1/agents/billing-helper \
-H "Authorization: Bearer $VOIS_AGENT_KEY" \
-H "A2A-Version: 1.0" \
-H "Content-Type: application/json" \
-d '{"jsonrpc": "2.0", "id": 1, "method": "SendMessage",
"params": {"message": {"messageId": "m-1", "role": "ROLE_USER",
"parts": [{"text": "Hello"}]}}}'

HTTP+JSON and gRPC​

The same agent answers the A2A 1.0 HTTP+JSON binding on the same per-agent URL:

RequestMethod
POST /a2a/v1/agents/{name}/message:sendSendMessage
POST /a2a/v1/agents/{name}/message:streamSendStreamingMessage, as server-sent events
GET /a2a/v1/agents/{name}/tasks/{id}, GET .../tasksGetTask, ListTasks
POST /a2a/v1/agents/{name}/tasks/{id}:cancelCancelTask
GET or POST /a2a/v1/agents/{name}/tasks/{id}:subscribeSubscribeToTask
GET /a2a/v1/agents/{name}/extendedAgentCardGetExtendedAgentCard

Errors are google.rpc.Status JSON with the status the spec gives, such as 404 for an unknown task and 409 for a task that can't be cancelled. The platform's own refusals keep 401, 403 and 429.

The gRPC binding is the A2A service lf.a2a.v1.A2AService. One service serves every agent, so the card's gRPC interface names the agent as tenant, and requests carry it. Send authorization and a2a-version as metadata. The card lists the gRPC address only when your operator has turned it on.

Requires gRPC exposure

The gRPC binding is off by default. Your operator turns it on with agents.a2a.grpc.enabled, and exposes it on the API host. See Configuration.

Whatever the binding, the decision, the audit events, the task and the stream are the same.

Snippets​

The A2A panel in the agent's Connect section has ready-made snippets: cURL, the a2a-sdk Python client from outside the platform, the same client from inside another code agent, and ADK's RemoteA2aAgent. A code agent that calls other agents adds a2a-sdk (or google-adk[a2a]) to its requirements. Both are in the offline package index, so this works on an air-gapped install.

Tasks​

A task is a run of the called agent. A contextId is a thread with that agent, so later messages in the same context continue the conversation.

Run stateTask state
Running, or waiting for a person to approve a tool callTASK_STATE_WORKING. metadata.vois.status is awaiting_approval and pending_approvals names the tools while a person must decide.
CompletedCOMPLETED, with the answer as the task's artifact
FailedFAILED
Rejected approvalREJECTED
CancelledCANCELED

An approval is decided by a person in the console, not by the calling agent, so a waiting task is WORKING, never INPUT_REQUIRED. Use GetTask to follow it.

Agent as a tool​

When you pick tools for a console-made agent, other agents of the project appear under Agents, as agent:<name>. The model sees a tool named agent__<name> that takes one argument, message. The called agent doesn't see the caller's conversation, so the tool's description tells the model to include everything it needs.

The call goes through the caller's approval gate like any tool call. The called agent's own tools are gated where it calls them. A console-made agent called this way gets up to an hour to answer.

In an eval run, an agent called as a tool runs in eval mode too: its write tools are blocked, not run.

The checks on every call​

  1. The called agent's caller list. By default every agent of the project may call it. A project admin can name the only agents that may, under Who may call it: every agent, only the agents listed, or none.
  2. The caller's tool list. If the calling agent's policy limits its tools, agent__<name> (or agent__*) must be on it.
  3. Policy. Open Policy Agent decides on a call_tool request with tool_name agent__<name> and connector_type agent. A custom Deny policy on connector_type: agent stops agent-to-agent calls. See Policy.
  4. Depth. A chain of calls is cut at four levels, so a loop such as A calls B calls A stops.
  5. Usage controls. The caller's key scope, budgets and rate limits apply. See Usage controls.

A refused A2A call is HTTP 403 with a JSON-RPC error whose data.reason says which check refused it. A refused tool call returns Error: <agent> refused this call: <reason> to the model, so it can explain.

Outside MCP clients​

The project's agents are also an MCP server, so any MCP client can call them as tools:

  • URL: POST /mcp/v1/agents on the API, streamable HTTP (MCP protocol versions 2025-06-18, 2025-03-26 and 2024-11-05).
  • Sign-in: an agent key of the project, as for A2A.
  • Tools: each agent the key's agent may call is a tool agent__<name> with one message argument. The list follows the same caller lists, policy and key scope as the A2A directory.

A call is an agent run on the mcp channel, with the same approvals, redaction, usage, audit and Runs & traces entry as an A2A call. A console-made agent gets up to five minutes to answer.

The agent's A2A section shows the MCP server URL and client snippets under Outside MCP clients.

What is recorded​

Every call writes the policy decision and two agent_call audit events, one when it is decided and one when it ends, under the caller. The run appears in Runs & traces, and its page says Called by the calling agent.

Was this page helpful?