A managed agent is an isolated, single-purpose LLM agent that a parent "orchestrator" spawns like a function call — with its own brief, its own tools, its own model — and that returns a result when done. This is the visual field guide.
Start with what an agent is: an LLM running in a loop — think, call a tool, read the result, think again — until a task is done. A managed agent is that same loop, but spawned and supervised by another agent.
A manager doesn't research, write, and review everything personally. They brief a researcher, a writer, and a reviewer — then synthesize. The parent agent works exactly this way.
A child agent is not a persistent session. It spawns, runs to completion, returns a string, and is gone. No state survives unless the parent explicitly carries it forward.
Because tasks outgrow their containers, twice. First a single LLM call isn't enough. Then a single agent loop isn't enough.
Multi-step work needs tools, intermediate results, and decisions that depend on earlier steps. One completion can't search the web, read the results, and revise its plan.
Context fills up with noisy tool output. One agent juggling five concerns produces mediocre results at each. Nothing runs in parallel. And every tool is exposed to every step.
Read 10 web pages and your context window is full of raw HTML. Subagents absorb the noise and return only the distilled answer.
window limitsAn agent that is a researcher AND writer AND reviewer in one loop context-switches constantly. Specialists produce sharper output.
focusIndependent subtasks shouldn't wait in line. Only separate agents can truly run at the same time.
parallelismThe agent that reads untrusted data shouldn't hold the keys to sending email. Separate agents give you hard tool boundaries.
least privilegeThe single most important thing to understand: a child agent knows only what the parent writes into its prompt. No inherited conversation. No shared memory. No access to the parent's tool results.
The child never says "I need more info." It works with what it has — confidently. There is no way for it to ask the parent for clarification mid-run.
Write subagent prompts a stranger could execute: goal, constraints, relevant facts, expected output format. If it's not in the brief, it doesn't exist.
Fresh context means a critic agent reviews work with genuinely fresh eyes, and one task's noise never pollutes another's reasoning.
In the Claude Agent SDK, spawning a managed agent is a tool call. Here's the shape, and what each part is really doing.
# Parent agent decides to delegate result = Agent( description="Competitive pricing researcher", # short label prompt=""" Research Competitor X's pricing tiers. Context you need: - We already know they raised $50M in March (TechCrunch) ← pass facts explicitly! - Focus on their enterprise tier changes Return a structured JSON summary: { tiers: [...], changes: [...] } """, subagent_type="researcher", # which agent definition to use model="haiku", # can be cheaper than the parent ) # result is a plain string — the child's final message
Goal, context, constraints, output format. Self-contained. This is where most of the engineering effort belongs.
most important fieldThe parent can run a powerful model while children run cheaper ones matched to their task difficulty. More in chapter 06.
cost controlNo magic return type. If you need JSON downstream, say so in the brief — and validate it when it comes back.
validate outputsIndependent subtasks shouldn't queue. Spawning multiple children at once turns total time from the sum of task times into the max of task times.
# Spawn all three in the same turn — they run concurrently research = Agent(description="Research competitors", prompt="...") pricing = Agent(description="Analyze pricing", prompt="...") risks = Agent(description="Identify risks", prompt="...")
Decomposition's quiet superpower: once tasks are separated, each one can run on the cheapest model that does it well. A monolithic agent pays flagship prices for every token.
Keyword detection, extraction, formatting, simple binary judgments, per-item classification at scale.
Orchestration decisions, nuanced evaluation, synthesis across many inputs, anything requiring cross-inference.
Run 50 samples through both. If the small model agrees with the big one ≳95% of the time on that subtask, downgrade it.
Nearly every production multi-agent system is one of these five shapes, or a combination of them.
Parent decomposes a big question into 5 sub-questions, spawns 5 researchers in parallel, synthesizes their focused summaries. Beats one agent drowning in 20 open tabs.
context relief + speedOne agent writes; a second agent — with no memory of writing it — critiques. Fresh context is what makes the second opinion genuine rather than self-serving.
isolation as quality toolA writes code. B writes tests from the spec (not from A's code — avoids circular validation). C runs them. Parent loops until green. Hard tool boundaries between roles.
separation of duties500 documents → 10 batches → 10 parallel children each summarize a batch → parent reduces to themes. The classic pattern for anything at scale.
throughputThe file-reading agent physically cannot send messages; the messaging agent never sees raw files. Scoped tools enforce policy as architecture, not as a polite request in a prompt.
security boundaryEvaluate everything cheaply; spawn an expensive analysis child only for flagged outliers. Pay for depth exactly where depth is deserved.
conditional spendThe most senior thing you can know about an architecture is when it's overkill. Subagents add latency, cost, and briefing overhead — they must earn their place.
Treat every child agent like an external API: it can fail loudly, fail slowly, or — worst of all — succeed with the wrong answer.
Timeout, error, malformed output. Easiest to handle: validate the returned string, catch exceptions, retry or route to a review queue. Never let one child sink the batch.
try / validate / retryOutput parses fine but the reasoning was wrong. Defenses: run ambiguous items twice and compare (self-reported confidence is unreliable; disagreement between runs is a real signal).
consistency checks50 of 1,000 children failed and the summary agent was never told. It summarizes 950 results as if they were 1,000 — confidently wrong. Always pass failure metadata downstream.
report the gapstry: result = Agent(prompt=brief, ...) data = json.loads(result) # structurally valid? assert required_fields <= data.keys() # complete? except Exception as e: flag_for_review(item, reason=str(e)) # degrade gracefully # and when summarizing, always include the denominator: summary = Agent(prompt=f"Evaluated: {ok_count}/{total}. Failed: {fail_count}. ...")
Any agent that reads untrusted content — web pages, emails, user chats, documents — can be handed instructions by an attacker hiding them in that content.
descriptionShort human-readable label for the task.
promptThe self-contained brief: goal, context, constraints, output format. Your most important code.
subagent_typeWhich agent definition to use — its tools and defaults come from the definition.
modelOverride the child's model. Small for mechanical work, large for judgment.
isolation: "worktree"For code tasks — gives the child its own git worktree sandbox.
SendMessageContinue a previously spawned agent with its context intact, instead of spawning cold.
| dimension | single agent loop | managed agents |
|---|---|---|
| context | fills with tool noise | children absorb noise, return distillate |
| speed | strictly sequential | independent work runs in parallel |
| cost | one model prices all tokens | model matched per subtask |
| quality | generalist juggling | focused specialists + fresh-eyes review |
| security | all tools, all steps | least-privilege tool scoping per child |
| overhead | none | spawn latency + briefing discipline |
| best for | simple, fast, tightly-coupled | large, parallel, mixed-difficulty |