CertSafari
    Anthropic Claude Certified Architect – Professional (CCAR-P) - December 7 onwards· Lessons

    Domain 1 · Lesson 4/39

    Evaluating orchestrator and subagent decompositions

    Orchestrator and Subagent Decomposition

    18 min read
    3% of exam
    6 sources
    Published 18 Nov 2026
    Docs as of 18 Nov 2026

    What you will be able to do

    • Check that each subagent gets the facts it needs in its delegation prompt, given what a fresh subagent does and doesn't receive
    • Spot task boundaries that will collide on shared files or depend on each other, and fix them with single ownership or sequencing
    • Pick runtime controls that cap fan-out, depth and spend no matter how the orchestrator decides to delegate
    • Judge whether a decomposition meets observability and error-recovery requirements, comparing subagent threads with workflow runs
    • Find where result synthesis can report success that the subagents' work doesn't support

    Key concept

    Context isolation at the delegation boundary — A subagent works in its own conversation. It learns only what the delegation hands it, and the orchestrator gets back only the subagent's final message. Every boundary, recovery path and synthesis step in a decomposition depends on what crosses that line in each direction.

    1.What a decomposition buys and what it costs

    An orchestrator/subagent decomposition splits a multi-step workload so that a lead agent plans the work and hands slices of it to subagents, each running in its own context. The main thing it buys is isolation. A research subagent can read dozens of files, and the parent gets a short summary back instead of every file. Several subagents can also run at the same time, so independent subtasks finish in the time of the slowest one rather than the sum of all of them. Whether a workload should be split at all is a pattern-selection question, covered in choosing between workflow patterns and agents. This page assumes someone has already proposed a split and asks whether it will hold up.

    The same isolation makes a decomposition fragile. Anything the subagent needs and isn't given, it doesn't have. Anything it learns and leaves out of its final message, the orchestrator never sees. Teams that built separate agents for planning, execution, review and iteration found they lost context at every handoff and spent more tokens coordinating than executing. Multi-agent setups typically use 3–10x more tokens than a single agent doing the same task. The extra comes from duplicated context, coordination messages, and summaries written for each handoff.

    Reviewing a proposal comes down to four questions. Does each boundary give the subagent everything it needs while keeping it out of its siblings' way? Is the control flow bounded by the runtime, or only by what the prompt asks for? Can an operator see each subagent's work and recover when one fails? And does the synthesis step check what comes back before reporting it?

    Checkpoint 1 of 9· Check yourself

    An orchestrator sends a research subagent to survey a codebase. The subagent reads 40 files and spots a deprecated API in one of them, but its final message does not mention it. What does the orchestrator learn about the deprecated API?

    Sources12

    2.Task boundaries: what crosses into a subagent

    In the Agent SDK, a regular subagent starts fresh. It doesn't see the conversation that produced its task, so any decision made in that conversation has to be written into the delegation prompt. A thirty-turn agreement on a target schema, a list of excluded tables and a rollback rule is lost if the delegation says only "Write the migration scripts." There are two fixes. Put those decisions directly in the Agent tool prompt, or start the worker as a fork. A fork is the one kind of subagent whose conversation doesn't start fresh, so it gets the history. The cost is that the fork then carries the parent's whole history in its own context, which gives up some of the isolation.

    What a regular Agent SDK subagent starts with
    The subagent receivesThe subagent doesn’t receive
    Its own system prompt (AgentDefinition.prompt) and the Agent tool’s promptThe parent’s conversation history or tool results
    Project CLAUDE.md (loaded via settingSources), unless the agent sets omitClaudeMdPreloaded skill content, unless listed in AgentDefinition.skills
    Tool definitions, inherited from the parent or the subset in toolsThe parent’s system prompt

    Use the table to rule out the tempting non-fixes. Listing items in AgentDefinition.skills preloads skill content. It does not load the parent's conversation. Changing the parent's system prompt doesn't help either, because the subagent never receives it. A subagent can't infer decisions it was never shown, however much effort it spends.

    A good delegation is more than a list of facts. Anthropic's research system found that each subagent needs an objective, an output format, guidance on which tools and sources to use, and clear task boundaries. With vague instructions like "research the semiconductor shortage," subagents misread the task or ran the same searches as their siblings. Without clear boundaries, agents duplicate work, leave gaps, or miss information they needed.

    Boundaries also have to divide the shared state, not just the topics. Suppose a logging-library migration is split into three write-capable subagents, one per service. All three services import a shared utils/ package. The boundaries look clean, but each subagent will edit utils/, and parallel edits to the same files conflict at random. Workloads with many dependencies between agents are a poor fit for parallel decomposition. Two changes remove the dependency itself:

    • Single ownership. One subagent owns utils/. The others report the shared changes they need instead of making them.
    • Sequencing. A first step updates utils/, and the three service subagents then run in parallel against the finished package.

    Neither of the obvious patches fixes the boundary. Telling each subagent to re-read a file just before editing it only narrows the window in which a conflict can happen. Giving every subagent the orchestrator's history tells it what was planned, but nothing stops two subagents from writing the same file at once.

    Checkpoint 2 of 9· Check yourself

    A logging-library migration is split across three write-capable subagents running in parallel, one per service. All three services import the shared utils/ package. Which change to the decomposition removes the conflict?

    Checkpoint 3 of 9· Check yourself

    After thirty turns, an Agent SDK orchestrator and the user agree on a target schema, a list of excluded tables and a rollback rule. The orchestrator then delegates "Write the migration scripts" to a regular (non-fork) subagent. Which fix gets those decisions to the subagent?

    Checkpoint 4 of 9· Exam question

    An orchestrator in the Agent SDK has spent thirty turns with a user agreeing on a migration plan covering the target schema, the tables to exclude and a rollback rule. It then spawns a regular migration-writer subagent with the prompt "Write the migration scripts." The scripts ignore the exclusions and the rollback rule. Which two changes fix the handoff? Choose two.(Select 2)

    0 of 2 selected

    Checkpoint 5 of 9· Exam question

    An orchestrator built on the Claude Agent SDK splits a logging-library migration into three write-capable subagents, one per service team. All three services import a shared utils/ package. Runs intermittently end with conflicting edits to the same shared files, and the orchestrator's synthesized summary still reports success. Which two changes to the decomposition most directly fix this task-boundary problem? Choose two.(Select 2)

    0 of 2 selected

    Sources13

    3.Control flow: bounding fan-out, depth and spend

    When Claude decides how many subagents to spawn, the system prompt steers that decision but the runtime is what limits it. Early versions of Anthropic's research system spawned 50 subagents for simple queries. The fix there was explicit scaling rules in the prompt: one agent with 3–10 tool calls for simple fact-finding, and 2–4 subagents for direct comparisons. Rules like these lower how often over-spawning happens. If the requirement is a hard ceiling no matter how Claude delegates, you need a limit the runtime enforces. A delegation rule in the prompt is not one.

    Agent SDK limits that bound delegation regardless of the prompt
    LimitSet it withDefaultAt the limit
    DepthCLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH3 layers below the main agent; 1 stops subagents spawning their ownA bottom-layer subagent can't spawn and does its delegated work itself
    ConcurrencyCLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS20 subagents running at onceRefuses to spawn, returning Concurrent subagent limit reached, until the running count drops
    SpendmaxBudgetUsd (TypeScript), max_budget_usd (Python)No limit; subagent requests countRefuses further spawns with Budget limit reached, stops background subagents, ends the query with error_max_budget_usd

    Each control fixes a different failure. Deep chains of nested subagents call for a lower depth limit, and a value of 1 makes delegation flat. Wide bursts of spawning call for a lower concurrency limit. A bill far above forecast calls for a spend cap, because that is the only one of the three that stops the run. Depth, concurrency and spend are the three documented controls on spawning. A setting that limits something else, such as how many turns one subagent may take, does not cap how many subagents the parent creates.

    Claude Managed Agents enforces stricter limits by design. Delegation is one level deep, so an agent that references another agent with multiagent set fails validation. A session can have at most 25 child threads at a time, including idle ones. Spend there is governed by a session budget: a single cap shared by all of a session's threads, including workflow runs. When the cap is reached, threads pause independently.

    Checkpoint 6 of 9· Check yourself

    Finance requires a hard ceiling on what one Claude Managed Agents session can spend, including any workflow runs, however the lead agent decides to delegate. Which design meets that requirement?

    Checkpoint 7 of 9· Exam question

    A code-audit agent built on the Agent SDK lets Claude decide how many subagents to spawn. A run against a monorepo produced deep chains of nested subagents and a bill several times the forecast, even though the prompt already tells it to delegate sparingly. Finance now wants fan-out and spend bounded no matter how Claude chooses to delegate. Which two controls meet this? Choose two.(Select 2)

    0 of 2 selected

    Sources1345

    4.Observability and error recovery across threads

    In Managed Agents, the session-level stream gives an operator a summary of each subagent's work, not the full detail. That primary thread shows a condensed view of activity across all threads: the start and end of each subagent's work, plus blocking events such as tool permission requests. To inspect a specific agent's reasoning and tool calls, open that thread's own stream at /v1/sessions/{session_id}/threads/{thread_id}/stream. A child's live previews never appear on the session-level stream. In the Console session viewer, the Threads tab lists every thread with its status, context size and cost, and the timeline gives each thread its own lane. If a requirement says that every subagent's tool calls must be auditable, the design has to read per-thread streams. Watching the primary stream won't meet it. Which signals to collect in the first place is covered in instrumentation and monitoring gaps.

    Thread lifecycle events on the Managed Agents primary stream
    EventWhat it tells an operator
    session.thread_createdA thread was created; includes session_thread_id and agent_name
    session.thread_status_idleThe thread's agent is awaiting input; includes a stop_reason
    session.thread_status_terminatedThe thread accepts no further input, e.g. archived or hit an unrecoverable error
    agent.thread_message_receivedA subagent sent the primary agent a report or question

    The two Managed Agents delegation modes differ most in how you recover from errors. With subagents, a thread persists until you archive it. The orchestrator can send a follow-up to a subagent it called earlier, and that subagent keeps everything from its previous turns, so a bad result can be corrected inside the context that produced it. With dynamic workflows, a program that Claude writes runs the agents in the background. The orchestrator can't send follow-ups to a run's threads, and the server archives each one by the end of the run. On a run's threads, a session.thread_status_terminated event tells you a thread is done, but no event records the result it returned to the workflow. A requirement like "retry or correct a failed step in place, and audit what each step returned" favours subagents. A long, parallel audit where per-step correction isn't needed suits a workflow run.

    Interrupts also behave differently inside workflow runs. An interrupt doesn't end a run, and an interrupt that names one of the run's threads stops nothing. A design whose error-recovery plan says "interrupt the failing worker" therefore needs to say which mode that worker runs in. For retry and backoff policy beyond this, see production reliability controls.

    Checkpoint 8 of 9· Match them up

    You are reviewing a Claude Managed Agents design. Match each requirement to the design choice that meets it.

    Tap a term, then the definition that fits it.

    Sources546

    5.Result synthesis: where success gets misreported

    Synthesis works only from what the subagents chose to return. Each subagent's intermediate tool calls stay inside it, and only its final message reaches the parent. In the research pattern below, the lead agent breaks the query into facets, waits for every subagent, then synthesizes whatever came back. Nothing in that loop checks that two results agree, or that a reported change actually landed. In the logging migration, three subagents can each report success while their edits to utils/ overwrite one another. If the synthesis step just combines those reports, the summary says the migration succeeded.

    Fan-out and synthesis: the lead agent sees only the returned resultspython
    async def research_topic(query: str) -> dict:
        # Lead agent breaks query into research facets
        facets = await lead_agent.decompose_query(query)
    
        # Spawn subagents to research each facet in parallel
        tasks = [
            research_subagent(facet)
            for facet in facets
        ]
        results = await asyncio.gather(*tasks)
    
        # Lead agent synthesizes findings
        return await lead_agent.synthesize(results)

    Synthesis holds up when the decomposition plans for it. First, the delegation prompt fixes an output format, so returned results can be compared instead of just read. Second, the lead agent treats synthesis as a decision point. In Anthropic's research system, the lead synthesizes results and then decides whether more research is needed. It can spawn more subagents or change its strategy before it answers. Third, a dedicated final stage can check the combined output. That system passes every finding to a separate CitationAgent, which attributes each claim to a source before the report goes to the user. Where results come from a workflow run, no event preserves what each thread returned. If you need to audit a summary, the workflow has to persist its intermediate results itself.

    Checkpoint 9 of 9· Fill the gap

    In this fan-out-and-synthesis loop, what does the lead agent pass to its synthesis step? Pick the token that completes the sample.

    async def research_topic(query: str) -> dict:
        # Lead agent breaks query into research facets
        facets = await lead_agent.decompose_query(query)
    
        # Spawn subagents to research each facet in parallel
        tasks = [
            research_subagent(facet)
            for facet in facets
        ]
        results = await asyncio.gather(*tasks)
    
        # Lead agent synthesizes findings
        return await lead_agent.synthesize( ? )

    Sources153

    Sources

    (6)

    Every claim above is drawn from one of these pages, quoted as it was written on the date shown.

    1. 1.
      “intermediate tool calls and results stay inside the subagent; only its final message returns to the parent”
      ↩︎ What a decomposition buys and what it costs
      “Its own system prompt (AgentDefinition.prompt) and the Agent tool’s prompt”
      ↩︎ Task boundaries: what crosses into a subagent
      “each subagent runs in its own conversation, which starts fresh unless the subagent is a fork”
      ↩︎ Task boundaries: what crosses into a subagent
      “Leaves a subagent at the bottom layer unable to spawn, so it does its delegated work itself.”
      ↩︎ Control flow: bounding fan-out, depth and spend
      “ends the query with the error_max_budget_usd result subtype”
      ↩︎ Control flow: bounding fan-out, depth and spend
      “The parent receives a concise summary, not every file the subagent read.”
      ↩︎ Result synthesis: where success gets misreported
      “intermediate tool calls and results stay inside the subagent; only its final message returns to the parent”
      ↩︎ Key concept
      “each subagent runs in its own conversation, which starts fresh unless the subagent is a fork”
      ↩︎ Exam trap 1
      “Refuses to spawn another subagent, returning Concurrent subagent limit reached, until the running count drops below the limit.”
      ↩︎ Exam trap 2
      “intermediate tool calls and results stay inside the subagent; only its final message returns to the parent.”
      ↩︎ Checkpoint
      “each subagent runs in its own conversation, which starts fresh unless the subagent is a fork.”
      ↩︎ Checkpoint
    2. 2.
      “multi-agent implementations typically use 3-10x more tokens than single-agent approaches for equivalent tasks”
      ↩︎ What a decomposition buys and what it costs
      “they suffered from lost context at each handoff and spent more tokens coordinating than executing”
      ↩︎ What a decomposition buys and what it costs
    3. 3.
      “Each subagent needs an objective, an output format, guidance on the tools and sources to use, and clear task boundaries.”
      ↩︎ Task boundaries: what crosses into a subagent
      “Without detailed task descriptions, agents duplicate work, leave gaps, or fail to find necessary information.”
      ↩︎ Task boundaries: what crosses into a subagent
      “involve many dependencies between agents are not a good fit for multi-agent systems today”
      ↩︎ Task boundaries: what crosses into a subagent
      “spawning 50 subagents for simple queries”
      ↩︎ Control flow: bounding fan-out, depth and spend
      “Simple fact-finding requires just 1 agent with 3-10 tool calls, direct comparisons might need 2-4 subagents with 10-15 calls each”
      ↩︎ Control flow: bounding fan-out, depth and spend
      “The LeadResearcher synthesizes these results and decides whether more research is needed”
      ↩︎ Result synthesis: where success gets misreported
      “involve many dependencies between agents are not a good fit for multi-agent systems today”
      ↩︎ Exam trap 4
    4. 4.
      “Delegation is one level deep, and a session can have at most 25 child threads at a time, idle ones included.”
      ↩︎ Control flow: bounding fan-out, depth and spend
      “The agent can send a follow-up to a subagent it called earlier, and that subagent retains everything from its previous turns.”
      ↩︎ Observability and error recovery across threads
      “The agent can’t send follow-up messages to a run’s threads, and the server archives each one by the end of its run.”
      ↩︎ Exam trap 3
      “Every agent in a run uses tokens, so set a session budget to cap the session’s spend, runs included.”
      ↩︎ Checkpoint
      “A subagent’s thread stays available until you archive it, so the agent can send it follow-up messages.”
      ↩︎ Checkpoint
    5. 5.
      “A session budget is a single shared cap across all of a session’s threads.”
      ↩︎ Control flow: bounding fan-out, depth and spend
      “You don’t see the full activity from subagents, but you do see the start and end of their work”
      ↩︎ Observability and error recovery across threads
      “No event records the result it returned to the workflow.”
      ↩︎ Observability and error recovery across threads
      “An interrupted child doesn’t send the primary thread’s agent the report it sends when a turn ends.”
      ↩︎ Observability and error recovery across threads
      “No event records the result it returned to the workflow.”
      ↩︎ Result synthesis: where success gets misreported

    Ready to test yourself?

    Practise Anthropic Claude Certified Architect – Professional (CCAR-P) - December 7 onwards in quiz mode.

    Spotted a mistake, or was something unclear? Tell us.