Configure a coordinator to delegate to child Agents or consult an Advisor, and observe execution through Session Threads.
Multiagent orchestration lets one Agent act as a coordinator that delegates work to other Agents. Each child Agent runs in an independent Session Thread, and the coordinator combines their results into the final response. You can also configure an Advisor to give the main Agent an independent perspective at important steps.
Use it for complex tasks that can be divided by responsibility, run in parallel, or executed in stages. For one-step work, strictly sequential tasks, or tasks where multiple workers would frequently edit the same files, use a single Agent to keep the workflow simpler.
Multiagent orchestration is built on the Session Thread model. The Agent selected when you create a Session becomes the coordinator. Based on its system prompt, it selects child Agents from the
Resources, contexts, and configurations within a multiagent Session have the following scopes:
Design the list and coordinator system prompt around task dependencies and responsibility boundaries:
To delegate to ordinary child Agents, set
The platform resolves each Agent entry's display name. See Agent schemas for name sources,
To add or remove child Agents or change their versions, get the main Agent, then submit your changes with
When submitting an update:
The coordinator creation example shows three choices:
An Advisor gives the main Agent advice on tasks such as design reviews and complex problem analysis. The main Agent decides when to consult it and whether to use its advice. You can specify consultation criteria in the system prompt.
In the console, create or edit an Agent, select Add Advisor in Multiagent, and choose a model. You can also configure it through the API:
Each Agent can have one Advisor alongside ordinary child Agents, without adding it to
The Advisor uses the main Agent's current conversation context to provide advice without executing tools. The main Agent continues after receiving the result. It can consult the same Advisor more than once; the console shows a separate record for each consultation.
If a consultation fails, the main Agent continues with the task. Error details are available in the Advisor's event history. See Advisor events to retrieve results and status through the API.
You can interrupt a consultation or update the Agent to remove its Advisor; configuration changes apply only to new Sessions.
The Advisor uses the current conversation context, and each consultation adds model cost and waiting time.
Create a Session with the coordinator that has
The
Configuring a list does not force delegation. The coordinator still decides based on its judgment and system prompt. State the delegation criteria explicitly instead of only listing child Agents.
See Create Session and Send Session Events.
MCP servers, tools, and skills are Agent-scoped. Vaults are bound when you create a Session:
Use the Session event stream to observe the overall collaboration:
The following thread events appear during multiagent orchestration:
Related events include
To inspect the complete execution of one child Agent, connect to its Thread event stream:
Use the Session event stream for cross-thread progress and the coordinator's final result. Use a Thread event stream to debug an individual child Agent. See List Session Threads, List Thread Events, and Stream Thread Events.
Send a
Each Thread uses the tool configuration and permission policy in its own Agent snapshot. A tool call that requires confirmation emits
Do not include
If a child reference in
Common causes include an invalid Agent or version reference, or a
How it works
Multiagent orchestration is built on the Session Thread model. The Agent selected when you create a Session becomes the coordinator. Based on its system prompt, it selects child Agents from the multiagent.agents list and delegates tasks to them.
| Concept | Description |
|---|---|
| Coordinator | The single coordinating thread in each Session. It breaks down work, selects child Agents, follows up on results, and produces the final response |
| Child Agent | An Agent in the multiagent.agents list. It can have its own model, system prompt, tools, MCP servers, and skills |
| Advisor | A model the main thread can consult for advice. It cannot execute tools or take over the task. Each consultation uses a temporary Thread |
| Session Thread | The execution thread for a coordinator or child Agent, with an ID prefixed by sthr_. Each thread has its own conversation history, Agent snapshot, and status |
| Agent list | Configured in multiagent.agents to specify which child Agents the coordinator can call. It can also include an Advisor |
| Scope | Behavior |
|---|---|
| Environment and filesystem | All threads in a Session share the same Environment, Sandbox, and filesystem |
| Vaults | Bound when the Session is created and available to authorized Agents in that Session |
| Conversation history | Isolated per Thread. A child Agent does not automatically receive the full context of other threads |
| Agent configuration | Each Thread uses its own Agent version snapshot, including its model, system prompt, tools, MCP servers, and skills |
| Event streams | The Session event stream exposes main-thread and cross-thread collaboration events, not the union of all child events. Thread endpoints expose one thread's events |
What to delegate
Design the list and coordinator system prompt around task dependencies and responsibility boundaries:
- Assign independent research, module implementation, or data collection tasks to different Agents so they can run in parallel.
- Split implementation, testing, and review by responsibility. For example, an implementation Agent can write code while a review Agent reads the code and returns an issue list. Route work that needs a stronger model or specialized tools to the appropriate Agent.
- Run dependent tasks in stages, such as implementation followed by review. The coordinator uses the review result to decide whether another iteration is needed.
Configure the coordinator
Configure in the console
- In the Cloud Agents console, open Agents and create the Agents that will collaborate.
- Create or edit the coordinator. In the Multiagent section, select the Agents available for delegation. The console saves the current version of each selected Agent.
- In the coordinator system prompt, define task decomposition, delegation criteria, deliverable formats, and conflict handling.
- Save the coordinator and use it to create a Session.
{"type":"self"}.
Create an Agent with the API
To delegate to ordinary child Agents, set multiagent and include agent_toolset_20260401 in tools. An Advisor-only list does not require this toolset:
multiagent.agents accepts the following formats:
| Format | Example | Description |
|---|---|---|
| Agent object | {"type":"agent","id":"agent_00nc01ht8gcn4w8sb7zv","version":2} | References another Agent. id is required and version is optional |
| Self object | {"type":"self"} | Uses the coordinator's own Agent configuration for a child thread |
| Advisor object | {"type":"advisor","model":"ultimate"} | Configures a model the main thread can consult. At most one per list; see Configure an Advisor |
| String shorthand | "agent_00nc01ht8gcn4w8sb7zv" | Equivalent to {"type":"agent","id":"agent_00nc01ht8gcn4w8sb7zv"} |
name field handling, uniqueness requirements, and other validation rules.
Update an Agent with the API
To add or remove child Agents or change their versions, get the main Agent, then submit your changes with POST to Update an agent.
This example updates the child Agent list of the main Agent (coordinator). Replace the Agent IDs and version numbers with your own.
multiagentreplaces the entire configuration. Include all child Agents,self, and Advisor entries you want to keep; usenullto disable orchestration.- Set the top-level
versionto the main Agent's current version. On 409, fetch the configuration again, reconcile your changes, and retry. On 405, check the URL and usePOSTas shown above. - The updated configuration takes effect only in new Sessions created with the updated Agent version. Existing Sessions are unaffected.
Agent versions and Session snapshots
The coordinator creation example shows three choices:
"latest": new Sessions adopt the child's latest version.- Integer: use a tested version for rollback and reproducibility.
self: create a child thread with the current Session's coordinator configuration.
"version": "latest" in multiagent.agents. After the child is updated from v2 to v3, new Sessions created with that parent use child Agent v3. Sessions created before the update, including their subsequent child threads, continue to use child Agent v2.
Omitting version in the API pins the child Agent’s latest version when saving the coordinator. New Sessions keep using that version even after the child is updated. See child Agent version rules.
Configure an Advisor
An Advisor gives the main Agent advice on tasks such as design reviews and complex problem analysis. The main Agent decides when to consult it and whether to use its advice. You can specify consultation criteria in the system prompt.
In the console, create or edit an Agent, select Add Advisor in Multiagent, and choose a model. You can also configure it through the API:
enabled_tools. Choose a model from List Models; see Agent schemas for configuration fields.
Consultation lifecycle
The Advisor uses the main Agent's current conversation context to provide advice without executing tools. The main Agent continues after receiving the result. It can consult the same Advisor more than once; the console shows a separate record for each consultation.
Events and failures
If a consultation fails, the main Agent continues with the task. Error details are available in the Advisor's event history. See Advisor events to retrieve results and status through the API.
Interrupt or remove an Advisor
You can interrupt a consultation or update the Agent to remove its Advisor; configuration changes apply only to new Sessions.
Cost and context
The Advisor uses the current conversation context, and each consultation adds model cost and waiting time.
Create and run a Session
Create a Session with the coordinator that has multiagent configured:
agent object requires type: "agent". Replace the example IDs with your resource IDs and version with the version number of your main Agent (coordinator).
Send a task message to the Session. The coordinator uses its system prompt to decide whether and how to delegate:
Connect MCP servers and Vaults
MCP servers, tools, and skills are Agent-scoped. Vaults are bound when you create a Session:
- Only an Agent configured with the relevant MCP server or toolset can call that capability.
- All threads share the Vaults bound to the Session, but each Agent remains subject to its own tool configuration and permission policy.
- Credential URLs in a Vault must match the MCP server URLs in the Agent configuration.
- A coordinator usually needs only orchestration and aggregation capabilities. Grant high-privilege credentials only to Agents that need them.
Observe threads and events
Use the Session event stream to observe the overall collaboration:
| Event type | Description |
|---|---|
session.thread_created | A child thread was created |
session.thread_status_running | A thread started executing |
session.thread_status_rescheduled | A thread task was retried and rescheduled |
session.thread_status_idle | A thread completed its current work or is waiting for follow-up |
session.thread_status_terminated | A thread was archived or terminated |
agent.thread_message_sent | The coordinator sent a task or follow-up to a child thread |
agent.thread_message_received | The coordinator received a message from a child thread |
session_thread_id so you can identify the originating thread. List the threads in a Session:
Interrupt one thread
Send a user.interrupt event to the Session with session_thread_id to interrupt only the target Thread. Omitting it requests interruption of the work currently in progress across the Session. Ordinary child Threads are not archived by interruption. Advisor Threads are archived after completion, failure, or interruption, but their history remains available.
Tool permissions and interactions
Each Thread uses the tool configuration and permission policy in its own Agent snapshot. A tool call that requires confirmation emits agent.tool_use; reply with user.tool_confirmation and provide tool_use_id and result. A Custom Tool call emits agent.custom_tool_use; after your client executes it, reply with user.custom_tool_result and provide custom_tool_use_id.
When actions are pending, the event stream emits session.status_idle with stop_reason.type set to requires_action. stop_reason.event_ids lists the event IDs that need responses. The session_thread_id on the related Agent events identifies the requesting Thread.
The following example allows a tool call that requires confirmation:
session_thread_id in a tool response. The platform uses tool_use_id or custom_tool_use_id to route the response to the originating Thread. If stop_reason.event_ids contains multiple IDs, respond to each one; the current turn remains paused while any action is unresolved. A requires_action idle state means the Session is waiting for input, not that it has completed. Before archiving a child thread, make sure it has no pending tool interaction. See Send Session Events.
Limits
| Item | Behavior or limit |
|---|---|
| Roster size | Up to 20 distinct ordinary Agent entries plus one Advisor. The list cannot be empty |
| Session Threads | Up to 25 unarchived ordinary Threads per Session, including the coordinator. Advisor Threads do not count toward this limit |
| Delegation depth | Only the coordinator can create child threads. Child Agents cannot create another layer of child threads |
| Session idle state | A Session becomes idle only after all Threads stop running |
| Agent references | Missing, archived, or inaccessible Agents and versions cause configuration to fail |
| Toolset | agent_toolset_20260401 is required for a list with ordinary Agent or self entries, but not for an Advisor-only list |
Troubleshooting
The coordinator does not delegate
- Confirm that the current coordinator version has a non-empty
multiagent.agentslist. See Agent schemas for configuration rules. - Confirm that the system prompt states the delegation criteria and each Agent's responsibility.
Why does a new Session still use an older child Agent version?
If a child reference in multiagent.agents specifies a numeric version or omits version (the default), the coordinator saves a fixed version. Updating the child Agent does not change that reference, so new Sessions still use the older version.
Set the child Agent’s version in multiagent.agents to "latest", save, and create a new Session.
Creating or updating the coordinator returns 400
Common causes include an invalid Agent or version reference, or a multiagent configuration that fails validation. Use the API error message to locate the corresponding field. See Agent schemas for the complete rules.