CertSafari
    Anthropic Claude Certified Developer – Professional (CCDV-P)· Lessons

    Domain 1 · Lesson 1/25

    Multi-agent orchestration: supervisors, subagents and approval flows

    Multi-Agent Orchestration

    21 min read
    4.25% of exam
    7 sources
    Published 19 Nov 2026
    Docs as of 18 Nov 2026

    What you will be able to do

    • Decide when an orchestrator-subagent design pays for its extra token cost and when a single agent is the better choice
    • Draw delegation boundaries: what a subagent sees, which tools and credentials it gets, and what comes back to the parent
    • Design parallel fan-out that cannot corrupt shared state, and bound it with runtime limits rather than prompt instructions
    • Choose how agents exchange work (persistent subagent threads, programmatic workflows, or an advisor) and localize a fault to one worker
    • Explain how inter-agent communication flows in a supervisor hierarchy and when peer messaging between workers calls for a different design
    • Enforce human approval on risky tool calls with a permission callback or pre-tool hook instead of a system-prompt rule

    Key concept

    Context-isolated delegation — An orchestrator hands a subtask to a subagent that runs in its own conversation. The subagent's intermediate work stays inside it and only its final message returns to the parent. Every multi-agent decision is a decision about what crosses that boundary: instructions going in, tools and credentials granted, results coming out.

    1.When a supervisor with workers beats one agent

    The orchestrator-subagent pattern is a hierarchy: a lead agent breaks the work into subtasks, spawns specialized subagents for them, and combines what they report. It is the simplest multi-agent coordination model, so it is where most production designs start. Each worker runs with a separate conversation context, which protects the lead's context, allows parallel work, and supports a degree of specialization that one agent cannot keep up.

    The pattern is expensive. Multi-agent implementations typically use 3 to 10 times more tokens than a single agent doing the same task. The overhead has three sources: context duplicated across agents, coordination messages between them, and summaries written for every handoff. Each extra agent is also one more point of failure and one more prompt to maintain. Teams have spent months building planner, executor, reviewer and iterator agents, then found that better prompting on a single agent gave equivalent results.

    Three situations reliably justify the cost:

    • Context pollution. One subtask produces a large volume of material that later subtasks do not need, such as thousands of tokens of order history while the agent is diagnosing a technical fault.
    • Parallelizable work. Independent pieces can be explored at the same time.
    • Specialization. One agent holding every tool starts picking the wrong one. Warning signs are 20 or more tools, tools spread across unrelated domains, or new tools degrading performance on existing tasks.

    Outside these situations, coordination usually costs more than it returns. In platform terms, the fit is complex work that spans several surfaces or splits into multiple well-scoped tasks serving one goal.

    Inter-agent communication in a supervisor hierarchy runs vertically: workers report up to the lead and do not talk to each other. A subagent returns its result to the conversation that spawned it, so a fact one worker finds that another needs has to travel through the lead's next delegation prompt. Peer messaging belongs to a different design, agent teams, where teammates message each other directly and share a task list; that mode is experimental and disabled by default. The hierarchy wins when subtasks are independent and the lead should see every result. Teams win when workers must stay in sync while they run.

    Checkpoint 1 of 9· Check yourself

    A team proposes four changes to a production agent. Which one is the strongest case for adding subagents under a supervisor?

    Sources123

    2.Delegation and context-isolation boundaries

    A subagent sees what you pass it and nothing more. Its conversation starts fresh unless it is a fork. A research subagent can read dozens of files and return a short summary, so none of those files pile up in the parent's context. This cuts both ways. Anything the parent learned over a long conversation, such as a customer's preferred tone or an exception agreed on turn 30, is invisible to a fresh subagent unless the delegation prompt carries it. A one-line prompt is enough for a self-contained job like scanning logs for an error code. It is not enough for drafting a reply that depends on the conversation history.

    In the Agent SDK, you define subagents in the agents option. Each AgentDefinition has a description that tells Claude when to use it, a prompt that serves as its system prompt, and optional tools, disallowedTools and model. The parent invokes subagents through the Agent tool, so Agent must be in allowedTools. If you leave out tools, the subagent inherits every tool available to subagents. Least privilege therefore has to be explicit: a doc-reviewer limited to Read and Grep can analyze files but cannot edit them.

    Agent SDK (TypeScript): the parent's allowedTools includes Agent so it can delegate, and each subagent is described by when to use ittypescript
        // Auto-approve these tools
        allowedTools: ["Read", "Grep", "Glob", "Agent"],
        agents: {
          "code-reviewer": {
            // description tells Claude when to use this subagent
            description:
              "Expert code review specialist. Use for quality, security, and maintainability reviews.",

    Credentials follow similar boundaries in Managed Agents. MCP servers are agent-scoped: a researcher agent can declare the GitHub MCP server while the lead agent has no access to it. Vault credentials are session-scoped. The vault_ids passed when the session is created apply to every thread, so a secret never has to be pasted into a delegation prompt. Inline agents are the gap. An inline agent has no agent definition of its own, so it runs with the session agent's MCP servers and tools and cannot be narrowed. To allow only vetted agents, set inline_agents to disabled and list at least one predefined agent. If inline agents are off and the predefined list is empty, the request fails with a 400 error.

    Managed Agents: inline agents disabled for both subagents and workflows, so only listed agents (and copies of itself) can do delegated workjson
    {
      "multiagent": {
        "type": "multiagent_20261001",
        "subagents": {
          "type": "enabled",
          "inline_agents": { "type": "disabled" },
          "predefined_agents": ["agent_01J8XkN5uT3vHpLqRfWdY2", { "type": "self" }]
        },
        "workflows": {
          "type": "enabled",
          "inline_agents": { "type": "disabled" },
          "predefined_agents": [
            { "type": "agent", "id": "agent_01Lm4cV8yQ2tNs7XbKdR5h", "version": 2 }
          ]
        }
      }
    }

    Predefined agents are also pinned. The configuration is snapshotted when the parent agent is created or updated, so referenced agents keep the versions resolved at that moment. If you improve the reviewer agent, the lead keeps delegating to the old version until you update the lead's list to reference the new one.

    Checkpoint 2 of 9· Fill the gap

    A Managed Agents lead must delegate only to one vetted agent and to copies of itself. It must never delegate to an agent it defines on the fly, because such an agent would run with the lead's own MCP servers and tools. Which value completes the subagents block?

        "subagents": {
          "type": "enabled",
          "inline_agents": { "type": " ? " },
          "predefined_agents": ["agent_01J8XkN5uT3vHpLqRfWdY2", { "type": "self" }]
        },

    Sources41

    3.Parallel subagent dispatch and shared state

    Fan-out runs independent subtasks at the same time and then synthesizes the results. Concurrent subagents finish in the time of the slowest one rather than the sum of all of them, so a style checker, a security scanner and a coverage analyzer can review the same change side by side. The lead decomposes the question into facets, dispatches a worker for each, gathers the results and merges them.

    Speed is not the main payoff. Because total computation increases, a multi-agent run often takes longer end to end than a single agent would. The primary benefit is thoroughness: parallel agents cover a larger search space than one agent can hold in its context. Choose fan-out when coverage matters, and expect to pay for it in tokens.

    Isolated conversations do not mean an isolated workspace. Two subagents writing the same file in the same working tree will overwrite each other. Re-reading the file before each edit does not fix this, because nothing prevents the other agent from writing between the read and the write. Giving one agent a larger budget or merging both jobs into one prompt does not fix it either. The fix belongs in the orchestrator's design:

    • give each worker files that no other worker touches, or a separate git worktree so changes cannot collide
    • run tasks that must touch the same file one after another
    • dispatch only work that is truly independent in parallel, such as read-only reviews or edits to disjoint modules

    Checkpoint 3 of 9· Check yourself

    An architect wants to split one research question across five parallel subagents, with each one investigating a different facet. Which result should they promise stakeholders?

    Checkpoint 4 of 9· Exam question

    Driftwood Freight runs a production rate-quoting platform, and its coding coordinator dispatches two parallel coding subagents against one shared working tree. One subagent is refactoring a pricing module while the other adds tax logic, and both edited pricing/core.py. The second write overwrote the first, and CI shows missing changes. Neither subagent raised an error, and the transcripts show no sign that either knew the other was editing the file. Both had read the file at the start of their tasks, and each final report described only its own changes. Both agents also finished well within their turn allowances. The team wants to keep as much work concurrent as possible, since the release window is tight, and needs the merged result to be deterministic. What is the best redesign?

    Sources4152

    4.Bounding delegation with runtime limits

    A system-prompt line saying "delegate sparingly" is a request, and a model that delegates more eagerly can ignore it. Spend and worker count are bounded by limits the runtime enforces. A limit in configuration makes the runtime refuse a spawn that would exceed it. An instruction in the prompt only asks the model not to try.

    Claude Managed Agents enforces several such limits:

    • Nesting depth. Delegation is one level deep. If you reference an agent that has multiagent set of its own, the create or update request fails with a 400 validation error, so a subagent cannot become an orchestrator.
    • Concurrency. A session can have at most 25 child threads at a time, idle ones included. Advisor threads and workflow-run threads do not count.
    • Roster size. Each predefined_agents list can name up to 20 unique agents, though the agent can run several copies of each within the thread limit.
    • Spend. Every agent in a workflow run uses tokens, so you set a session budget to cap the whole session's spend, runs included.

    In the Agent SDK, a subagent's maxTurns stops it after a fixed number of agentic turns and returns its output marked as partial.

    Checkpoint 5 of 9· Check yourself

    What happens when you create a Managed Agents lead whose subagents.predefined_agents list references a research agent that has its own multiagent block, so that the researcher can coordinate a further layer of workers?

    Checkpoint 6 of 9· Exam question

    Dune Telecom runs a research orchestrator in production that compiles nightly network-reliability briefings for its regional operations teams, unattended between 01:00 and 05:00. After switching to a model that delegates far more eagerly, the nightly run spawns subagents that spawn their own subagents. Spend per run tripled, and one run produced 60 concurrent workers. A system-prompt line already tells the orchestrator to delegate sparingly, and that same wording held on the previous model but failed on this one. The team must keep the new model because its briefings scored higher in quality review. Finance requires that no single run can exceed its agreed footprint, whatever the model decides to do, and nobody is awake to intervene. Which change bounds this most directly?

    Sources14

    5.How agents pass work and results

    How results cross between agents determines what can go wrong at a handoff. A good handoff carries only what the receiver needs. In one design, an order-lookup agent reads the full order history and the support agent receives a summary of 50 to 100 tokens. A bad handoff drops something the receiver needed. Teams that split planning, execution and review across separate agents have seen context lost at every handoff and more tokens spent coordinating than executing.

    Managed Agents offers three ways to pass work, and they differ in who directs the next step and whether a conversation can continue. With subagents, the lead agent decides what happens next. A subagent's thread stays open, so the lead can send follow-ups and the subagent keeps everything from its previous turns. With dynamic workflows, Claude writes a program that runs agents in phases and passes context and results between them in code. This leaves the main thread free to talk to the user, but run threads cannot receive follow-ups and are archived by the end of the run.

    Three ways an agent in Claude Managed Agents can involve other agents or models
    ApproachWho directs the next stepFollow-upsBest whenWatch for
    SubagentsThe lead agent, after reading each reportYes; the thread persists until archivedThe lead needs to follow up, or needs listed specialists with their own prompts and toolsOne level deep; at most 25 child threads per session
    Dynamic workflowsA program Claude writes, run in the background as one workflow runNo; run threads are archived by the end of the runAudits, migrations, deep research, cross-checking: many pieces or parallel workEvery agent uses tokens; set a session budget
    AdvisorThe primary thread, which keeps doing the workNot applicable; it is a mid-turn consultationOne agent does the work but needs stronger judgment when planning or reviewingOnly the primary thread can consult it; billed at the advisor model's rates

    When a multi-agent answer is wrong, start by finding which worker introduced the error. Each subagent works in its own session thread that you can list and stream, so read the clause-extractor's thread and the risk-scorer's thread separately. Comparing each one's output with what the next agent received shows whether the fault was in the worker or lost in the handoff. Reading only the final answer cannot tell those apart.

    Checkpoint 7 of 9· Match them up

    A Managed Agents lead can involve other agents or models in three ways. Match each approach to how work and results move under it.

    Tap a term, then the definition that fits it.

    Sources12

    6.Human-in-the-loop approval that the runtime enforces

    A rule in the system prompt such as "ask a human before refunds above 500 EUR" is guidance. After a long or adversarial conversation, the model may not follow it. An approval gate has to sit at the point where the tool is called, outside the model's discretion. A nightly reconciliation job or a reviewer agent reading finished transcripts both detect a bad refund after the money has gone out. Neither stops it.

    The Agent SDK provides that gate in two forms. The canUseTool callback runs whenever Claude wants a tool that is not auto-approved by a permission rule or permission mode. It receives the tool name and its input, and it returns allow (optionally with modified input) or deny with a message Claude sees. A PreToolUse hook can inspect the arguments of a call to a tool like issue_refund and return a permission decision. "deny" blocks the call, and "ask" sends it to a person for confirmation. A check on the amount in the hook means the tool runs above the threshold only after sign-off.

    Agent SDK (TypeScript): a canUseTool callback that pauses for a human decision before any non-auto-approved tool runstypescript
    canUseTool: async (toolName, input) => {
      console.log(`Claude wants to use ${toolName}`);
      const approved = await askUser("Allow this action?");
    
      if (approved) {
        return { behavior: "allow", updatedInput: input };
      }
      return { behavior: "deny", message: "User declined" };
    };

    An approver has more choices than yes or no:

    • approve the call as requested
    • approve with changes, for example sanitizing a path or adding a constraint
    • approve and remember, so matching calls skip the prompt next time
    • reject the call and say why
    • reject it and suggest an alternative
    • redirect Claude entirely through streaming input

    "Approve and remember" is also how you keep an approval queue meaningful. When people approve nearly every request in a few seconds, routine calls are flooding the queue and the risky ones get the same reflexive yes. Turning the routine approvals into permission rules leaves only the calls that need real judgment in front of a human. Clarifying questions use the same channel: Claude calls AskUserQuestion, which must be included if you specify a tools array.

    Checkpoint 8 of 9· Fill the gap

    Your refund agent must not run a non-auto-approved tool until a person signs off. When the reviewer says no, the call has to be blocked and Claude has to be told why. Which value completes the callback?

    canUseTool: async (toolName, input) => {
      console.log(`Claude wants to use ${toolName}`);
      const approved = await askUser("Allow this action?");
    
      if (approved) {
        return { behavior: "allow", updatedInput: input };
      }
      return { behavior: " ? ", message: "User declined" };
    };

    Checkpoint 9 of 9· Exam question

    Fjord Travel runs a claims agent in production that can call an issue_refund tool against its payment provider. The system prompt tells the agent to ask a human before issuing any refund above 500 EUR. An audit found two 900 EUR refunds issued with no approval, both at the end of long chats in which the customer repeatedly pressured the agent and argued the rule did not apply to their case. Refunds settle to the customer's card within seconds and cannot be recalled. Fjord Travel's compliance policy requires that approval exist before money leaves the account. The team has already reworded the prompt rule twice, yet the agent still sometimes talks itself past it in long conversations. What is the most direct control to ensure refunds above 500 EUR never go out without a human's approval?

    Sources67

    Sources

    (7)

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

    1. 1.
      “Multiagent coordination is best suited for complex tasks that either require work across a variety of surfaces or consist of multiple well-scoped tasks”
      ↩︎ When a supervisor with workers beats one agent
      “An inline agent has no agent definition, so it uses the MCP servers and tools of the agent that the session runs.”
      ↩︎ Delegation and context-isolation boundaries
      “Vault credentials are session-scoped: vault_ids passed at session creation apply to every thread.”
      ↩︎ Delegation and context-isolation boundaries
      “All agents share the same sandbox, filesystem, and vault credentials, but each agent runs in its own session thread”
      ↩︎ Parallel subagent dispatch and shared state
      “Delegation is one level deep, and a session can have at most 25 child threads at a time, idle ones included.”
      ↩︎ Bounding delegation with runtime limits
      “Referencing another agent that has multiagent set fails the create or update request with a 400 validation error.”
      ↩︎ Bounding delegation with runtime limits
      “Every agent in a run uses tokens, so set a session budget to cap the session’s spend, runs included.”
      ↩︎ Bounding delegation with runtime limits
      “The agent can send a follow-up to a subagent it called earlier, and that subagent retains everything from its previous turns.”
      ↩︎ How agents pass work and results
      “Context and results are passed programmatically from one agent to another”
      ↩︎ How agents pass work and results
      “The agent can’t send follow-up messages to a run’s threads”
      ↩︎ How agents pass work and results
      “Each subagent works in its own session thread, which you can list and stream.”
      ↩︎ How agents pass work and results
      “Only the primary thread can consult the advisor, and consultations are billed at the advisor model’s rates.”
      ↩︎ How agents pass work and results
      “Referencing another agent that has multiagent set fails the create or update request with a 400 validation error.”
      ↩︎ Exam trap 3
      “To limit an agent’s access, declare only the servers it needs in its agent definition. You can’t limit an inline agent this way.”
      ↩︎ Exam trap 4
      “All agents share the same sandbox, filesystem, and vault credentials, but each agent runs in its own session thread”
      ↩︎ Prediction
      “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.”
      ↩︎ Checkpoint
    2. 2.
      “a hierarchical model where a lead agent spawns and manages specialized subagents for specific subtasks”
      ↩︎ When a supervisor with workers beats one agent
      “In our testing, multi-agent implementations typically use 3-10x more tokens than single-agent approaches for equivalent tasks.”
      ↩︎ When a supervisor with workers beats one agent
      “when context pollution degrades performance, when tasks can run in parallel, and when specialization improves tool selection or task focus”
      ↩︎ When a supervisor with workers beats one agent
      “The primary benefit of parallelization is thoroughness, not speed.”
      ↩︎ Parallel subagent dispatch and shared state
      “they suffered from lost context at each handoff and spent more tokens coordinating than executing”
      ↩︎ How agents pass work and results
      “The main agent receives only the 50-100 tokens it actually needs, keeping context focused.”
      ↩︎ How agents pass work and results
      “The primary benefit of parallelization is thoroughness, not speed.”
      ↩︎ Exam trap 2
    3. 3.
      “Subagents report results back to the conversation that spawned them”
      ↩︎ When a supervisor with workers beats one agent
      “Teammates in an agent team message each other directly and, when they have the Task tools, share a task list.”
      ↩︎ When a supervisor with workers beats one agent
    4. 4.
      “each subagent runs in its own conversation, which starts fresh unless the subagent is a fork.”
      ↩︎ Delegation and context-isolation boundaries
      “If omitted, inherits every tool available to subagents”
      ↩︎ Delegation and context-isolation boundaries
      “independent subtasks finish in the time of the slowest one rather than the sum of all of them”
      ↩︎ Parallel subagent dispatch and shared state
      “Maximum number of agentic turns before the agent stops.”
      ↩︎ Bounding delegation with runtime limits
      “intermediate tool calls and results stay inside the subagent; only its final message returns to the parent.”
      ↩︎ Key concept
    5. 5.
      “Isolate parallel Claude Code sessions in separate git worktrees so changes don’t collide.”
      ↩︎ Parallel subagent dispatch and shared state
    6. 6.
      “Claude wants to use a tool that isn’t auto-approved by a permission rule or permission mode.”
      ↩︎ Human-in-the-loop approval that the runtime enforces
      “Approve and remember: echo a suggested permission rule back so matching calls skip the prompt next time”
      ↩︎ Human-in-the-loop approval that the runtime enforces
      “If you specify a tools array, include AskUserQuestion for this to work.”
      ↩︎ Human-in-the-loop approval that the runtime enforces
    7. 7.
      “"deny" prevents the tool call. "ask" prompts the user to confirm.”
      ↩︎ Human-in-the-loop approval that the runtime enforces
      “"deny" prevents the tool call. "ask" prompts the user to confirm.”
      ↩︎ Exam trap 1

    Ready to test yourself?

    Practise Anthropic Claude Certified Developer – Professional (CCDV-P) in quiz mode.

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