# Claude Managed Agents Multi-Agent **Research preview.** 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 — but they all share the session's container and filesystem. ## 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. 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 callable agents Add `callable_agents` at agent creation. One level of delegation only — subagents can't spawn their own subagents. ```python orchestrator = client.beta.agents.create( name="Engineering Lead", model="claude-sonnet-4-6", system="You coordinate engineering. Delegate review to the reviewer agent, tests to the test agent.", tools=[{"type": "agent_toolset_20260401"}], callable_agents=[ {"type": "agent", "id": reviewer.id, "version": reviewer.version}, {"type": "agent", "id": tester.id, "version": tester.version}, ], ) ``` Start the session referencing just the orchestrator; callable agents are resolved from its config. ## Multi-agent event types | Type | Meaning | |---|---| | `session.thread_created` | Coordinator spawned a subagent thread | | `session.thread_idle` | A thread finished its current turn | | `agent.thread_message_sent` | Coordinator messaged a subagent | | `agent.thread_message_received` | Subagent received a message | Drill into any thread via `/sessions/:id/threads/:thread_id/stream` or list events via `/threads/:thread_id/events`. ## 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 [[Claude Managed Agents|form access]] required. ## References - https://platform.claude.com/docs/en/managed-agents/multi-agent ## Related - [[Claude Managed Agents]] - [[AI Subagents]] - [[AI Agent Swarms]] - [[AI Agent Orchestration]]