Page history
multiagent-orchestration
managed-agents/multiagent-orchestration
History
managed-agents/multiagent-orchestration Changed · +66 / -50 lines
from line 63
) ``` - ```bash CLI - ant beta:agents create <<YAML - name: Engineering Lead - model: claude-opus-5 - system: You coordinate engineering work. Delegate code review to the reviewer agent and test writing to the test agent. - tools: - - type: agent_toolset_20260401 - multiagent: - type: coordinator - agents: - - type: agent - id: $REVIEWER_AGENT_ID - - type: agent - id: $TEST_WRITER_AGENT_ID - YAML - ``` + <MultiFileExample language="cli" label="CLI"> + ```bash CLI + ant beta:agents create < coordinator.agent.yaml + ``` + <File filename="coordinator.agent.yaml"> + ```yaml + name: Engineering Lead + model: claude-opus-5 + system: You coordinate engineering work. Delegate code review to the reviewer agent and test writing to the test agent. + tools: + - type: agent_toolset_20260401 + multiagent: + type: coordinator + agents: + - type: agent + id: $REVIEWER_AGENT_ID # replace before running command + - type: agent + id: $TEST_WRITER_AGENT_ID # replace before running command + ``` + </File> + </MultiFileExample> + ```python Python coordinator = client.beta.agents.create( name="Engineering Lead",
from line 426
echo "$session_id" ``` - ```bash CLI - research_agent_id=$(ant beta:agents create --transform id --raw-output <<YAML - name: researcher - model: claude-haiku-4-5 - mcp_servers: - - type: url - name: github - url: https://api.githubcopilot.com/mcp/ - tools: - - type: mcp_toolset - mcp_server_name: github - YAML - ) + <MultiFileExample language="cli" label="CLI"> + ```bash CLI + research_agent_id=$(ant beta:agents create --transform id --raw-output < researcher.agent.yaml) + ``` - coordinator_id=$(ant beta:agents create --transform id --raw-output <<YAML - name: coordinator - model: claude-opus-5 - tools: - - type: agent_toolset_20260401 - multiagent: - type: coordinator - agents: - - type: agent - id: $research_agent_id - YAML - ) + <File filename="researcher.agent.yaml"> + ```yaml + name: researcher + model: claude-haiku-4-5 + mcp_servers: + - type: url + name: github + url: https://api.githubcopilot.com/mcp/ + tools: + - type: mcp_toolset + mcp_server_name: github + ``` + </File> - session_id=$(ant beta:sessions create \ - --agent "$coordinator_id" \ - --environment-id "$environment_id" \ - --vault-id "$vault_id" \ - --transform id --raw-output) - echo "$session_id" - ``` + <File filename="subagent-coordinator.agent.yaml"> + ```yaml + name: coordinator + model: claude-opus-5 + tools: + - type: agent_toolset_20260401 + multiagent: + type: coordinator + agents: + - type: agent + id: $research_agent_id # replace before running command + ``` + </File> + + ```bash CLI + coordinator_id=$(ant beta:agents create --transform id --raw-output < subagent-coordinator.agent.yaml) + + session_id=$(ant beta:sessions create \ + --agent "$coordinator_id" \ + --environment-id "$environment_id" \ + --vault-id "$vault_id" \ + --transform id --raw-output) + echo "$session_id" + ``` + </MultiFileExample> ```python Python research_agent = client.beta.agents.create(
managed-agents/multiagent-orchestration First recorded · 1507 lines, first recorded
## How it works ### What to delegate ## Configure the coordinator ### Give the session an advisor #### How consultations work #### Advisor threads #### Removing the advisor ## Create the session ## Connect agents to MCP servers ## Threads ### Primary thread events ### Session thread events ### Tool permissions and custom tools
The first capture of this source. The page was already there, and this is what it said.
---
title: Multiagent orchestration
url: https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration
description: Coordinate multiple agents within a single session.
---
Multiagent orchestration lets one agent coordinate with others to complete complex work. Agents can act in parallel with their own isolated context, which helps improve output quality and can also improve time to completion.
Not sure a multiagent setup fits your problem? See [when to use multiagent systems (and when not to)](https://claude.com/blog/building-multi-agent-systems-when-and-how-to-use-them).
<Note>
Managed Agents API requests require the `managed-agents-2026-04-01` beta header, except memory store endpoints, which use `agent-memory-2026-07-22` instead. The SDK sets the correct beta header automatically. See [Beta headers](https://platform.claude.com/docs/en/api/beta-headers#endpoint-specific-headers).
</Note>
## How it works
All agents share the same sandbox, filesystem, and [vault credentials](https://platform.claude.com/docs/en/managed-agents/vaults), but each agent runs in its own **session thread**, a context-isolated event stream with its own conversation history. The coordinator reports activity in the **primary thread** (which is the same as the session-level [event stream](https://platform.claude.com/docs/en/managed-agents/events-and-streaming)); additional threads are spawned at runtime when the coordinator delegates work.
Threads are persistent: the coordinator can send a follow-up to an agent it called earlier, and that agent retains everything from its previous turns.
Each agent uses its own configuration: model, system prompt, tools, MCP servers, and skills. Session-level [agent configuration overrides](https://platform.claude.com/docs/en/managed-agents/sessions#override-agent-configuration-for-a-session) are the exception; they apply to the coordinator and its `self` copies. Tools, MCP servers, and context are not shared.
### What to delegate
Multiagent coordination is best suited for complex tasks that either require work across a variety of surfaces, or where multiple well-scoped tasks contribute to an overall goal.
Patterns that work well:
* **Parallelization:** Fan out independent subtasks simultaneously (searching multiple sources, analyzing separate files) and have the coordinator synthesize the results.
* **Specialization:** Route to agents with domain-focused system prompts and tools, such as a security agent or a documentation agent, rather than loading a single agent with every capability.
* **Escalation:** Consult a more capable agent or model for a subset of complex subtasks.
## Configure the coordinator
When [defining your agent](https://platform.claude.com/docs/en/managed-agents/agent-setup), set `multiagent` to declare the roster of agents the coordinator can delegate to:
<CodeGroup defaultLanguage="CLI">
```bash cURL
coordinator=$(curl -fsS https://api.anthropic.com/v1/agents \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: managed-agents-2026-04-01" \
-H "content-type: application/json" \
-d @- <<EOF
{
"name": "Engineering Lead",
"model": "claude-opus-5",
"system": "You coordinate engineering work. Delegate code review to the reviewer agent and test writing to the test agent.",
"tools": [
{
"type": "agent_toolset_20260401"
}
],
"multiagent": {
"type": "coordinator",
"agents": [
{"type": "agent", "id": "$REVIEWER_AGENT_ID"},
{"type": "agent", "id": "$TEST_WRITER_AGENT_ID"}
]
}
}
EOF
)
```
```bash CLI
ant beta:agents create <<YAML
name: Engineering Lead
model: claude-opus-5
system: You coordinate engineering work. Delegate code review to the reviewer agent and test writing to the test agent.
tools:
- type: agent_toolset_20260401
multiagent:
type: coordinator
agents:
- type: agent
id: $REVIEWER_AGENT_ID
- type: agent
id: $TEST_WRITER_AGENT_ID
YAML
```
```python Python
coordinator = client.beta.agents.create(
name="Engineering Lead",
model="claude-opus-5",
system="You coordinate engineering work. Delegate code review to the reviewer agent and test writing to the test agent.",
tools=[
{"type": "agent_toolset_20260401"},
],
multiagent={
"type": "coordinator",
"agents": [
{"type": "agent", "id": reviewer_agent.id},
{"type": "agent", "id": test_writer_agent.id},
],
},
)
```
```typescript TypeScript
const coordinator = await client.beta.agents.create({
name: "Engineering Lead",
model: "claude-opus-5",
system:
"You coordinate engineering work. Delegate code review to the reviewer agent and test writing to the test agent.",
tools: [{ type: "agent_toolset_20260401" }],
multiagent: {
type: "coordinator",
agents: [
{ type: "agent", id: reviewerAgent.id },
{ type: "agent", id: testWriterAgent.id },
],
},
});
```
```csharp C#
var coordinator = await client.Beta.Agents.Create(new()
{
Name = "Engineering Lead",
Model = BetaManagedAgentsModel.ClaudeOpus5,
System = "You coordinate engineering work. Delegate code review to the reviewer agent and test writing to the test agent.",
Tools =
[
new BetaManagedAgentsAgentToolset20260401Params
{
Type = BetaManagedAgentsAgentToolset20260401ParamsType.AgentToolset20260401,
},
],
Multiagent = new BetaManagedAgentsMultiagentParams
{
Type = BetaManagedAgentsMultiagentParamsType.Coordinator,
Agents = [reviewerAgent.ID, testWriterAgent.ID],
},
});
```
```go Go
coordinator, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{
Name: "Engineering Lead",
Model: anthropic.BetaManagedAgentsModelConfigParams{ID: anthropic.BetaManagedAgentsModelClaudeOpus5},
System: anthropic.String("You coordinate engineering work. Delegate code review to the reviewer agent and test writing to the test agent."),
Tools: []anthropic.BetaAgentNewParamsToolUnion{{
OfAgentToolset20260401: &anthropic.BetaManagedAgentsAgentToolset20260401Params{
Type: anthropic.BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401,
},
}},
Multiagent: anthropic.BetaManagedAgentsMultiagentParams{
Type: anthropic.BetaManagedAgentsMultiagentParamsTypeCoordinator,
Agents: []anthropic.BetaManagedAgentsMultiagentRosterEntryParamsUnion{
{OfString: anthropic.String(reviewerAgent.ID)},
{OfString: anthropic.String(testWriterAgent.ID)},
},
},
})
if err != nil {
panic(err)
}
```
```java Java
var coordinator = client.beta().agents().create(
AgentCreateParams.builder()
.name("Engineering Lead")
.model(BetaManagedAgentsModel.CLAUDE_OPUS_5)
.system("You coordinate engineering work. Delegate code review to the reviewer agent and test writing to the test agent.")
.addTool(
BetaManagedAgentsAgentToolset20260401Params.builder()
.type(BetaManagedAgentsAgentToolset20260401Params.Type.AGENT_TOOLSET_20260401)
.build()
)
.multiagent(BetaManagedAgentsMultiagentParams.builder()
.type(BetaManagedAgentsMultiagentParams.Type.COORDINATOR)
.addAgent(BetaManagedAgentsAgentParams.builder()
.type(BetaManagedAgentsAgentParams.Type.AGENT)
.id(reviewerAgent.id())
.build())
.addAgent(BetaManagedAgentsAgentParams.builder()
.type(BetaManagedAgentsAgentParams.Type.AGENT)
.id(testWriterAgent.id())
.build())
.build())
.build()
);
```
```php PHP
$coordinator = $client->beta->agents->create(
name: 'Engineering Lead',
model: 'claude-opus-5',
system: 'You coordinate engineering work. Delegate code review to the reviewer agent and test writing to the test agent.',
tools: [
['type' => 'agent_toolset_20260401'],
],
multiagent: [
'type' => 'coordinator',
'agents' => [
['type' => 'agent', 'id' => $reviewerAgent->id],
['type' => 'agent', 'id' => $testWriterAgent->id],
],
],
);
```
```ruby Ruby
coordinator = client.beta.agents.create(
name: "Engineering Lead",
model: "claude-opus-5",
system: "You coordinate engineering work. Delegate code review to the reviewer agent and test writing to the test agent.",
tools: [
{type: "agent_toolset_20260401"}
],
multiagent: {
type: "coordinator",
agents: [
{type: "agent", id: reviewer_agent.id},
{type: "agent", id: test_writer_agent.id}
]
}
)
```
</CodeGroup>
`multiagent.agents` can accept any of the following:
* `{"type": "agent", "id": agent.id}` references a previously created `agent` by ID. If no `version` is specified, the reference is pinned to the latest version of that agent at the time the coordinator is created.
* `{"type": "agent", "id": agent.id, "version": agent.version}` pins a specific agent version.
* `{"type": "self"}` allows the coordinator to spawn copies of itself. If the session was created with [agent configuration overrides](https://platform.claude.com/docs/en/managed-agents/sessions#override-agent-configuration-for-a-session), those overrides also apply to these copies; roster entries referenced by ID are unaffected.
* `{"type": "advisor", "model": "<model id>"}` gives the session's primary thread an advisor it can consult mid-turn. At most one advisor entry per roster. See [Give the session an advisor](https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration#give-the-session-an-advisor).
The coordinator's configuration, including its `multiagent.agents` roster, is snapshotted when the coordinator is created or updated. Referenced agents stay pinned to the versions resolved at that time and do not automatically pick up later updates to their definitions. To delegate to a newer version of a referenced agent, [update the coordinator](https://platform.claude.com/docs/en/managed-agents/agent-setup#update-an-agent) so its roster references that version.
The coordinator can only delegate to one level of agents; referencing an agent that has its own `multiagent.agents` roster fails the create or update request with a validation error. A maximum of 20 unique agents can be listed in `multiagent.agents`, but the coordinator can call multiple copies of each agent.
When agents pin an [inference geography](https://platform.claude.com/docs/en/manage-claude/data-residency) (`model.inference_geo` in the [agent definition](https://platform.claude.com/docs/en/managed-agents/agent-setup)), the coordinator's pin and every roster member's pin must either all be set to the same value or all be unset. A mismatched roster is rejected with a 400 validation error, both when the agent is saved and when a [session-create override](https://platform.claude.com/docs/en/managed-agents/sessions#override-agent-configuration-for-a-session) changes any of the pins.
### Give the session an advisor
An advisor entry in `multiagent.agents` gives the session's primary thread an **advisor**: a model it can consult mid-turn for strategic guidance, such as planning an approach, getting unstuck, or reviewing work before finishing. The entry has exactly two fields, `type` and `model`:
```bash cURL
curl -fsS https://api.anthropic.com/v1/agents \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: managed-agents-2026-04-01" \
-H "content-type: application/json" \
-d '{
"name": "Backend engineer",
"model": "claude-sonnet-5",
"system": "You implement backend features end to end. Consult the advisor before major backend design decisions.",
"multiagent": {
"type": "coordinator",
"agents": [
{"type": "advisor", "model": "claude-opus-5"}
]
}
}'
```
A roster can contain at most one advisor entry, alongside any of the other roster forms. The entry occupies the reserved roster name `anthropic.advisor`: a roster that lists both an advisor entry and a member literally named `anthropic.advisor` is rejected with a 400 validation error. In responses, the advisor entry is echoed last in the roster regardless of the position it was submitted in.
The advisor model must meet a minimum capability bar, and the agent's own model must not be more capable than its advisor; models of equal capability can pair. An invalid pairing is rejected with a 400 validation error when the agent is saved. Valid pairings follow the advisor tool's [model compatibility](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool#model-compatibility) table.
The advisor is also available as a [server tool on the Messages API](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool). The Managed Agents surface differs in configuration and delivery: the roster entry has no `max_uses`, `max_tokens`, or `caching` fields, and advice arrives through thread events rather than `advisor_tool_result` blocks.
#### How consultations work
Each consultation runs as a platform-spawned thread named `anthropic.advisor` that terminates itself when the consultation completes, and the advice is delivered to the primary thread as an `agent.thread_message_received` event. A consultation emits the standard thread events, identified by the reserved name `anthropic.advisor` (the thread lifecycle events carry it as `agent_name`, and the advice delivery carries it as `from_agent_name`), typically in this order:
1. `session.thread_created`
2. `session.thread_status_running`
3. `agent.thread_message_received` (the advice)
4. `session.thread_status_idle` (`stop_reason: end_turn`)
5. `session.thread_status_terminated`
No `agent.tool_use` events are emitted for a consultation, and no `agent.thread_message_sent` event appears on the session's event stream, because the consultation input is composed by the platform rather than sent by the agent. If you list the advisor thread's own events, the advice also appears there as an `agent.thread_message_sent` event. The advice delivery (event 3) is not guaranteed to arrive before the advisor thread's idle and terminated events, so don't treat those as a signal that the advice has already been delivered.
Whether your client can read the advice is the advisor model's policy, and it mirrors the [result variants](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool#result-variants) split on the Messages API advisor tool. Advisor models that return plaintext results there deliver the advice as readable text content here; advisor models that return redacted results there deliver a `[{"type": "redacted"}]` placeholder as the message content on every client surface, while the agent itself still reads the full advice server-side. In the preceding example, Claude Opus 5 is a redacted-result advisor, so your client sees the placeholder while the agent reads the full advice; choose Claude Opus 4.8 as the advisor instead if you want the advice readable on the event stream. Advisor thinking is never surfaced. Clients cannot send `redacted` blocks themselves; an event containing one is rejected with a 400 validation error.
A failed or interrupted consultation never fails the agent's turn: the agent continues after a generic notice that the consultation failed. A session-level `user.interrupt` during a consultation terminates the advisor thread with no advice delivered; a `user.interrupt` with the advisor thread's `session_thread_id` abandons only that consultation.
#### Advisor threads
The advisor is not a roster agent: it is invisible to the coordinator's `list_agents` tool, it cannot be messaged with `send_to_agent`, and only the session's primary thread can consult it. Roster agents cannot.
Advisor threads are exempt from the concurrent-thread limit. They appear in the session's [thread list](https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration#threads) with `agent` set to the advisor form exactly as configured (`{"type": "advisor", "model": ...}`) and `parent_thread_id` set to the primary thread.
Prompt caching on the advisor's side is automatic; there is nothing to configure. Consultations are billed at the advisor model's rates, and their tokens appear in the advisor thread's usage and in the session's usage totals.
#### Removing the advisor
To remove the advisor, [update the agent](https://platform.claude.com/docs/en/managed-agents/agent-setup#update-an-agent) with a roster that no longer includes the advisor entry. If the advisor is the roster's only entry, clear the roster entirely by setting `"multiagent": null`.
## Create the session
Create a session referencing the coordinator. The coordinator delegates to the agents in its roster as needed.
<CodeGroup>
```bash cURL
Cut at 300 lines.