# Claude Managed Agents Multi-Agent **Beta** (research preview at launch; as of October 2026 the docs list it under the base `managed-agents-2026-04-01` header, renamed "multiagent orchestration"). Lets a coordinator agent inside [[Claude Managed Agents]] delegate work to other agents within the same session. Each subagent runs in its own context-isolated **thread** with its own conversation history, model, system prompt, tools, MCP servers, and skills. They all share the session's sandbox, filesystem and [[Claude Managed Agents|vault credentials]]. ## Why it matters A single agent juggling code review, test writing, and research will blow through its context window and lose focus. Splitting them into specialized agents with tighter system prompts and scoped tools is the standard fix; this feature bakes it into the platform instead of forcing you to hand-roll it. Patterns the docs recommend: **parallelization** (fan out independent subtasks, let the coordinator synthesize), **specialization** (domain-focused agents instead of one agent with every capability) and **escalation** (consult a more capable model for the hard parts). Good candidates: - **Code review agent**: read-only tools, reviewer persona - **Test-generation agent**: writes/runs tests without touching production code - **Research agent**: web tools only; summarizes findings back to the coordinator ## How threads work - The session-level event stream is the **primary thread**; it carries a condensed view of all activity - Each `callable_agent` the coordinator invokes spawns a new session **thread** (`session.thread_created`) with its own event stream - Threads are **persistent**: the coordinator can send a follow-up to a thread from 10 turns ago and the subagent retains everything - Tools and context are **not shared** across threads; only the filesystem is ## Declaring the roster The research-preview field was `callable_agents`. The current API uses a `multiagent` object of type `coordinator` with an `agents` roster: ```python coordinator = client.beta.agents.create( name="Engineering Lead", model="claude-opus-5-5", system="You coordinate engineering. Delegate review to the reviewer agent, tests to the test agent.", tools=[{"type": "agent_toolset_20260401"}], multiagent={ "type": "coordinator", "agents": [ {"type": "agent", "id": reviewer.id}, {"type": "agent", "id": tester.id, "version": tester.version}, ], }, ) ``` Roster entries: - `{"type": "agent", "id": ...}`: pinned to the latest version at the time the coordinator is created; add `version` to pin a specific one. The roster is snapshotted, so later agent updates aren't picked up until you update the coordinator - `{"type": "self"}`: the coordinator can spawn copies of itself - `{"type": "advisor", "model": "..."}`: gives the primary thread an advisor model to consult mid-turn (at most one per roster; the agent's own model can't be more capable than its advisor). Consultations run as `anthropic.advisor` threads, are billed at the advisor's rates, and don't count against the thread limit - With `ant apply`, an entry can be a path to another agent file (`./reviewer.md`) Limits: one level of delegation only (referencing an agent that has its own roster fails validation), max 20 unique agents in the roster (the coordinator can call several copies of each), max 25 concurrent threads (archive idle threads to free slots). If agents pin `inference_geo`, all pins must match or all be unset. Start the session referencing just the coordinator; the roster is resolved from its config. MCP servers stay agent-scoped while vault credentials are session-scoped, so the session's vaults need a credential for every MCP server any agent uses. A session budget is one shared cap across all threads. ## Multi-agent event types | Type | Meaning | |---|---| | `session.thread_created` | A thread was created (`session_thread_id`, `agent_name`) | | `session.thread_status_running` | A thread started activity | | `session.thread_status_idle` | A thread is awaiting input (with a `stop_reason`); replaces the preview-era `session.thread_idle` | | `session.thread_status_terminated` | A thread was archived or hit a terminal error | | `agent.thread_message_sent` | On the primary thread: the coordinator sent a task or follow-up to another agent | | `agent.thread_message_received` | On the primary thread: an agent sent a report or question to the coordinator | Drill into any thread via `/v1/sessions/{session_id}/threads/{thread_id}/stream` (accepts `event_deltas[]` to preview a subagent's text live) or list its past events. Send `user.interrupt` with a `session_thread_id` to stop one thread; without it, every non-archived thread stops. The session status is `running` as long as one thread is running. ## Tool confirmation in threads When a subagent needs permission to run an `always_ask` tool or a custom tool result, the request surfaces on the **primary stream** with a `session_thread_id` field. Echo that ID on your reply (`user.tool_confirmation` / `user.custom_tool_result`) so the platform routes it back to the right thread. Primary-thread requests have no `session_thread_id`; reply without it. ## Access ~~Research preview: `managed-agents-2026-04-01-research-preview` beta header and form access required.~~ As of October 2026: beta, base `managed-agents-2026-04-01` header only, no form. Also available on [[Claude Platform on AWS]]. ## References - Multiagent orchestration docs (current URL): https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration - Original URL (research preview): https://platform.claude.com/docs/en/managed-agents/multi-agent - Managed Agents overview (research-preview scope): https://platform.claude.com/docs/en/managed-agents/overview - Claude Platform on AWS, Managed Agents section: https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#claude-managed-agents ## Related - [[Claude Managed Agents]] - [[Claude Platform on AWS]] - [[AI Subagents]] - [[AI Agent Swarms]] - [[AI Agent Orchestration]]