Multi-agent orchestration turns a single agent into a coordinator that delegates to a roster of specialists. The mechanics are not what you would guess: delegates are pre-built resources, delegation is exactly one level deep, and every worker’s request still comes back to one stream.
In this article: You will learn how Claude Managed Agents multi-agent orchestration actually works, and why its rules differ from subagents in every other framework. We cover the shared-filesystem, separate-minds session shape, why workers are pre-built resources rather than inline definitions, the three numbers that govern a fan-out, and the single design choice that keeps coordination from becoming a nightmare. By the end you can turn a capable solo agent into a coordinated team.
Part 10 of “Building with Claude Managed Agents,” a 13-part guide to building production-ready AI agents.
A single agent is a single worker. Give it a goal and a way to verify its own work, and it will iterate to a passing result on its own. It is thorough. It is also one thing doing one thing at a time.
Watch it run a real job and the limit shows. An invoice agent reconciling a month of four hundred invoices works through them in sequence. One context window absorbs every invoice, every ledger lookup, and every flagged discrepancy, until that window strains under the weight of the whole job. No amount of self-evaluation fixes this. The bottleneck is not intelligence. It is that the work is serial and the memory is finite.
The fix is to stop thinking of the agent as a worker and start thinking of it as a lead. Claude Managed Agents multi-agent orchestration lets one agent become a coordinator that delegates to a roster of other agents, each running in its own isolated context, working in parallel. The coordinator breaks the job up, hands pieces to specialists, and synthesizes what comes back. Done well, this improves both quality and speed at once. Quality improves because each agent stays focused on a narrow task with a clean context. Speed improves because independent pieces run at the same time instead of in a line.
If you have used subagents in another agent framework, the idea is familiar. The mechanics are genuinely different, and the differences are exactly where people trip. This article builds the team and names every rule that is not the one you would guess. Note that multi-agent is a research-preview feature behind an access request, so plan for that gate before you build on it.
The shape: shared filesystem, separate minds
Two facts define how a multi-agent session behaves, and holding both at once is the key to reasoning about it.
All agents share the same container and filesystem. The coordinator and every agent it delegates to read and write the same /mnt/ directory. A worker that writes a partial result to a file is handing it to the others through the filesystem they all see. There is one sandbox, one set of files, and one working directory, shared across the whole team.
But each agent runs in its own session thread. A thread is a context-isolated event stream with its own conversation history. Tools and context are not shared between agents. The reviewer agent does not see what the line-item checker was reasoning about. It sees only what the coordinator passed it and what is on the shared filesystem. This isolation is the source of the quality gain: each agent gets a clean context scoped to its task, rather than one agent drowning in the combined history of everything.
So the mental model is a team sharing a workspace but not sharing a brain. They pass artifacts through files. They do not pass context through osmosis. The coordinator’s own activity runs in the primary thread, the same session-level event stream you stream for any agent. Additional threads spin up at runtime each time the coordinator delegates.
Delegates are pre-built resources, not inline definitions
Here is the first place Managed Agents diverges from subagents elsewhere, and it shapes how you structure your whole deployment. You do not define a worker inline inside the coordinator. The coordinator’s roster references previously created agents by ID. Each worker is its own full agent, created with its own model, system prompt, tools, MCP servers, and skills, before the coordinator ever mentions it.
That means the workers come first. For the invoice job you might create two specialists: a cheap, fast line-item checker that reconciles individual rows, and a more capable reviewer that scrutinizes the flagged discrepancies. Each one is an ordinary agents.create call. Once you have those agents and their IDs, the coordinator is an agent with a multiagent block declaring the roster.
coordinator = client.beta.agents.create(
name="Reconciliation Lead",
model="claude-opus-4-7",
system=(
"You coordinate invoice reconciliation. Split the invoices into batches "
"and delegate each batch to the line-item checker. Send anything it flags "
"to the reviewer for a closer look. Synthesize the results into one report."
),
tools=[{"type": "agent_toolset_20260401"}],
multiagent={
"type": "coordinator",
"agents": [
{"type": "agent", "id": line_item_checker.id},
{"type": "agent", "id": reviewer.id},
],
},
)The same shape in TypeScript:
const coordinator = await client.beta.agents.create({
name: "Reconciliation Lead",
model: "claude-opus-4-7",
system:
"You coordinate invoice reconciliation. Split the invoices into batches and " +
"delegate each batch to the line-item checker. Send anything it flags to the " +
"reviewer for a closer look. Synthesize the results into one report.",
tools: [{ type: "agent_toolset_20260401" }],
multiagent: {
type: "coordinator",
agents: [
{ type: "agent", id: lineItemChecker.id },
{ type: "agent", id: reviewer.id },
],
},
});
The roster accepts three kinds of entry:
{"type": "agent", "id": ...}references an agent and defaults to its latest version.{"type": "agent", "id": ..., "version": ...}pins a specific version. You want this in production so that a roster does not silently change when someone updates a worker.{"type": "self"}lets the coordinator spawn copies of itself. This is how you fan one kind of work across many parallel instances rather than across different specialists.
You start a session against the coordinator exactly as you would any agent, and it delegates at runtime as the work demands.
Because each worker is a standalone agent, the coordinator’s system prompt is doing real work: it is the delegation strategy. The agent will not magically know that flagged items go to the reviewer. You tell it, in plain language, how to use its roster. Treat the coordinator’s prompt as the org chart and the routing rules combined.
If you are a paid subscriber, thank you. Your support makes this work possible.
If you are a free subscriber and find these articles useful, please consider upgrading. A paid subscription is $80 per year or $8 per month.
