What you will be able to do
- Configure a Managed Agents coordinator roster and stay within its delegation limits
- Define specialised subagents with restricted tools in the Agent SDK and Claude Code
- Choose between subagents, agent teams and dynamic workflows for a given orchestration need
1.Configuring a coordinator in Claude Managed Agents
In Claude Managed Agents, you list the agents a coordinator may delegate to in its multiagent field. In this example, an Opus coordinator delegates code review and test writing to two Haiku agents. This is specialisation and escalation in one roster: cheaper models handle well-scoped work, and the coordinator runs on the stronger model.
---
name: Engineering Lead
model: claude-opus-5-5
tools:
- type: agent_toolset_20260401
multiagent:
type: coordinator
agents: # paths: ant apply substitutes {type: agent, id, version}
- ./reviewer.md
- ./test-writer.md
---A roster entry can take four forms: an agent ID (pinned to that agent's latest version when the coordinator is created), an agent ID with an explicit version, self so the coordinator can spawn copies of itself, or advisor. The coordinator's configuration is snapshotted when it is created or updated. Referenced agents stay on the versions resolved at that moment, so to delegate to a newer version you update the coordinator. Three structural limits shape the design. Delegation is one level deep only: a roster member that has its own roster fails validation. At most 20 unique agents can be listed, although the coordinator can call several copies of each. And there can be at most one advisor, which is a model the primary thread consults mid-turn for planning, getting unstuck or reviewing work. The advisor has to be at least as capable as the agent consulting it; models of equal capability can be paired.
Checkpoint 1 of 4· Check yourself
An architect wants a three-tier hierarchy: a coordinator delegates to a 'research lead' agent, which has its own roster of searcher agents. What happens when the coordinator is created?
Managed Agents allows only one level of delegation. A roster entry that has its own multiagent.agents roster is rejected at create or update time.
“The coordinator can only delegate to one level of agents”Source: platform.claude.com
Checkpoint 2 of 4· Exam question
You are configuring a doc-reviewer subagent that should be able to analyze documentation for accuracy and clarity but must never modify files or execute commands, even accidentally. How should you define its tool access?
Correct answer: A — Set tools to only Read and Grep so it can examine content without any write or execution capability
- A. Correct. Restricting the tools field to Read and Grep gives the subagent everything it needs to analyze documentation while structurally removing any ability to write files or execute commands.
- B. Omitting the tools field makes the subagent inherit all tools from the parent, which would include Edit, Write, and Bash, directly contradicting the requirement that it never modify files or run commands.
- C. Granting Edit and relying on a hook to deny every attempt still leaves an unnecessary attack surface and depends on the hook firing correctly every time, instead of removing the capability at the source.
- D. Bash access would let the subagent execute arbitrary commands, which violates the requirement that it must never execute commands even for seemingly safe purposes like linting.
Sources1
2.Defining specialised subagents in the Agent SDK and Claude Code
In the Claude Agent SDK you can define subagents in code with the agents parameter of query(), or as markdown files in .claude/agents/. Claude can also call a built-in general-purpose subagent without any definition from you. Each definition uses the same levers as the design principles on the first page: a description that tells Claude when to delegate, a focused system prompt, a tool allowlist, and an optional model override.
| Field | Required | What it controls |
|---|---|---|
| description | Yes | Natural-language description of when to use this agent |
| prompt | Yes | The agent's system prompt, defining its role and behaviour |
| tools | No | Allowed tool names; if omitted, inherits every tool available to subagents |
| model | No | Model override, such as 'sonnet', 'haiku' or 'inherit' |
| maxTurns | No | Maximum agentic turns before the agent stops and returns partial output |
Restricting tools is both a safety measure and a way to specialise. A doc-reviewer limited to Read and Grep can analyse files but can never modify them. Leaving tools out is not neutral, because the subagent then inherits every tool available to subagents. In Claude Code, the same definition can live in a file whose frontmatter declares the allowlist and the model.
Checkpoint 3 of 4· Fill the gap
Which frontmatter field limits this Claude Code subagent to read-only tools?
---
name: code-reviewer
description: Reviews code for quality and best practices
? : Read, Glob, Grep
model: sonnet
---tools is the allowlist. disallowedTools removes tools instead, and skills preloads skill content rather than granting tools.
Sources2
3.Choosing between subagents, agent teams and workflows
Claude Code has three orchestration mechanisms, and they differ mainly in who decides what runs next and where intermediate results are kept. Subagents report back to the agent that called them, which suits focused tasks where only the result matters. In agent teams, teammates share a task list, claim work and message each other directly. That suits work that needs discussion, such as debugging with competing hypotheses, but each teammate is a separate Claude instance, so the token cost is higher. Dynamic workflows hand control to a script that Claude writes. The script coordinates the agents, and the agents themselves do the reading, writing and running of commands.
| Aspect | Subagents | Agent teams | Workflows |
|---|---|---|---|
| What it is | A worker Claude spawns | A lead agent supervising peer sessions | A script the runtime executes |
| Who decides what runs next | Claude, turn by turn | The lead agent, turn by turn | The script |
| Where intermediate results live | Claude's context window | A shared task list | Script variables |
| Scale | A few delegated tasks per turn | A handful of long-running peers | Dozens to hundreds of agents per run |
Workflows exist for large fan-outs such as codebase audits and migrations, so they come with their own limits: by default up to 16 concurrent agents, at most 1,000 agents per run, and no user input mid-run. If you need sign-off between stages, run each stage as its own workflow.
Checkpoint 4 of 4· Match them up
Match each requirement to the mechanism that fits it best
Tap a term, then the definition that fits it.
Subagents return a result to the caller. Teammates coordinate with each other through messages and a task list. A workflow script runs dozens to hundreds of agents and can be run again.
“In agent teams, teammates share a task list, claim work, and communicate directly with each other.”Source: code.claude.com
Exam traps
Each one states something that sounds right. Open it to see what is actually true.
1.A Managed Agents coordinator can delegate to agents that themselves coordinate sub-rosters, building a deep hierarchy.Why is that wrong?
Delegation is one level deep only. A roster member with its own multiagent.agents roster fails validation.
Covered in Configuring a coordinator in Claude Managed Agents
2.When you update a reviewer agent, coordinators that reference it start using the new version automatically.Why is that wrong?
Roster references are pinned when the coordinator is created or updated. To pick up a newer version, update the coordinator.
Covered in Configuring a coordinator in Claude Managed Agents
Practise it for real
Deploy a coordinator with two specialised agents in Claude Managed Agents and observe how the roster is pinned and validated
1.Create reviewer.md and test-writer.md, each with frontmatter giving a name and model: claude-haiku-4-5, followed by a one-line system prompt such as 'You are a code reviewer.'
Why: Specialised agents get narrow system prompts and a cheaper model for well-scoped work.
You should see: Two agent definition files on disk.
2.Create engineering-lead.md with the coordinator frontmatter shown in this lesson, listing ./reviewer.md and ./test-writer.md under multiagent.agents.
Why: The roster declares which agents the coordinator may delegate to.
You should see: A coordinator file whose roster refers to the other two files by path.
3.Run: ant apply engineering-lead.md reviewer.md test-writer.md
Why: Apply creates each referenced agent first and replaces each path with a pinned reference.
You should see: All three agents exist, and the coordinator's roster holds {type: agent, id, version} references instead of paths.
4.Add a multiagent roster to reviewer.md and apply the coordinator again.
Why: This tests the one-level delegation limit.
You should see: The create or update request fails with a validation error.
Stuck? Get a nudge
If a change to reviewer.md seems to have no effect, remember that the coordinator is pinned to the version it resolved. Update the coordinator so its roster references the new version.
Sources
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.
“A maximum of 20 unique agents can be listed in multiagent.agents, but the coordinator can call multiple copies of each agent.”
↩︎ Configuring a coordinator in Claude Managed Agents“A roster can contain at most one advisor entry, alongside any of the other roster forms.”
↩︎ Configuring a coordinator in Claude Managed Agents“a model it can consult mid-turn for strategic guidance, such as planning an approach, getting unstuck, or reviewing work before finishing”
↩︎ Configuring a coordinator in Claude Managed Agents“models of equal capability can pair”
↩︎ Configuring a coordinator in Claude Managed Agents“The coordinator can only delegate to one level of agents”
↩︎ Exam trap 1“Referenced agents stay pinned to the versions resolved at that time and do not automatically pick up later updates to their definitions.”
↩︎ Exam trap 2“The coordinator can only delegate to one level of agents”
↩︎ Checkpoint - 2.https://code.claude.com/docs/en/agent-sdk/subagentsOfficial docs
“subagents can be limited to specific tools, reducing the risk of unintended actions”
↩︎ Defining specialised subagents in the Agent SDK and Claude Code“Programmatically: use the agents parameter in your query() options.”
↩︎ Defining specialised subagents in the Agent SDK and Claude Code“If omitted, inherits every tool available to subagents”
↩︎ Defining specialised subagents in the Agent SDK and Claude Code - 3.https://code.claude.com/docs/en/agent-teamsOfficial docs
“Subagents report results back to the main agent.”
↩︎ Choosing between subagents, agent teams and workflows“In agent teams, teammates share a task list, claim work, and communicate directly with each other.”
↩︎ Checkpoint - 4.https://code.claude.com/docs/en/workflowsOfficial docs
“Dynamic workflows orchestrate many subagents from a script Claude writes and you can rerun.”
↩︎ Choosing between subagents, agent teams and workflows“For sign-off between stages, run each stage as its own workflow”
↩︎ Choosing between subagents, agent teams and workflows“1,000 agents total per run”
↩︎ Choosing between subagents, agent teams and workflows