AnthropicClaude Certified Architect – Foundations2026-101.3 Configure subagent invocation, context passing, and spawning
Give each specialist an executable contract
Completed by the knowledge check
Learning objective
Define specialist subagent contracts with clear descriptions, role-specific system prompts, expected outputs, and scoped tool sets.
Core idea
For an architect building a coordinator, a specialist is more than a name attached to another model call. Its contract must tell the coordinator when to use it, tell the specialist how to work, define what it returns, and constrain the tools it can invoke. Those are separate responsibilities. A strong role prompt cannot compensate for an ambiguous delegation description or an unnecessarily broad tool set.
The Agent SDK represents programmatic specialists through the agents option, keyed by agent name. Each entry is an AgentDefinition. Its required description guides selection; its required prompt supplies the specialist’s system prompt. Its optional tools field narrows tool availability. Expected outputs belong in the instructions, rather than in an invented AgentDefinition output field.
In Claude Code, define the same contract in a Markdown file under .claude/agents/ for a project or ~/.claude/agents/ for a user. Frontmatter name identifies the specialist; description, tools, and disallowedTools map to the corresponding definition fields. The Markdown body becomes its system prompt, equivalent to AgentDefinition.prompt, and carries the role and output requirements.
See 1.2.3 for deciding whether the work needs a specialist. This lesson concerns the contract after you make that decision.
How it works
Separate selection from execution instructions
Write description for the coordinator that chooses among agents. Identify the work the specialist handles and the circumstances that make delegation useful. “Helpful researcher” offers little selection information. “Reviews supplied vendor documents for retention requirements and conflicting evidence” distinguishes the specialist from one that investigates pricing or analyzes code.
Write prompt for the specialist that performs the work. Define the role, the evidence it should trust, the boundaries it must respect, and the result it must produce. Anthropic’s multi-agent research account identifies an objective, output format, tool and source guidance, and clear task boundaries as necessary delegation information. Translate that pattern into a reusable role contract; leave request-specific documents and findings to the invocation prompt taught in 1.3.3.
Avoid defining the role solely through a fixed sequence of searches. A document reviewer needs criteria for recognizing sufficient evidence and contradictory clauses. Those criteria let it adapt when a relevant requirement appears in an unexpected appendix. The contract still needs a concrete deliverable: findings linked to supporting passages, explicit gaps, and a conclusion limited to the supplied scope.
Encode the role and output together
The following TypeScript definition illustrates the relevant AgentDefinition fields:
const agents = {
"document-reviewer": {
description: "Reviews supplied documents for requirements and conflicting evidence.",
prompt:
"You are a document evidence reviewer. Use the supplied scope. " +
"Return findings, supporting passages with locations, and gaps. " +
"Separate observed requirements from your interpretation. " +
"Do not change source files or invent missing evidence.",
tools: ["Read", "Grep", "Glob"],
},
};Pass this object as the agents option to query(). The key document-reviewer identifies the agent; it is not a tool name. The same definition fields description, prompt, and tools appear in Python’s AgentDefinition, supplied through ClaudeAgentOptions(agents=...).
The requested output is a behavioral contract expressed in prompt. It does not automatically become a machine-enforced schema. If your coordinator needs structured evidence, specify the application format and check the returned content before synthesis; see 1.3.4. Do not infer that a well-written role prompt guarantees every field or proves a finding correct.
Restrict capabilities through the definition
An explicit tools: ["Read", "Grep", "Glob"] gives the reviewer file-reading and search tools without the file-editing or command-execution tools. Omitting tools instead inherits the tools available to subagents. That default is a capability choice, not a harmless shorthand for a read-only specialist.
The disallowedTools field removes named tools from an inherited or specified set. For a narrowly defined reader, a small positive tools list makes the intended capability set visible beside its role. For a broad investigator that needs most tools except a few, a deny list can express the difference. In either case, review tool availability independently of the natural-language prohibition in prompt.
Tool availability also depends on the execution context. Claude Code filters tools available to non-fork subagents, with an additional filter for background runs, which are the default. The background filter removes built-in tools outside its list even when listed in tools, without an error unless the resulting tool list resolves to nothing. The example’s Read, Grep, and Glob are among the documented background tools.
Keep persistent memory out of this read-only definition. When a subagent’s memory is enabled, Claude Code automatically enables Read, Write, and Edit for memory management. Adding memory changes the capability assumptions you made from the small tool list; it is not merely a longer role description.
Restricting tools does not separate files. A subagent starts in the main conversation’s working directory, so an editing specialist changes the checkout the parent sees unless its definition sets isolation: worktree, which gives it an isolated copy of the repository.
Key distinctions and trade-offs
Each surface of the contract has its own reader, and each fails in its own way:
| Field | Read or enforced by | What goes wrong when it is weak |
|---|---|---|
description | The coordinator, when it selects an agent | “Research expert” on two agents leaves the choice between them ambiguous |
prompt | The specialist, as its system prompt | Without evidence rules and a deliverable, each result comes back in a new shape |
tools | The harness, which limits the specialist | Omitted, it inherits the tools available to subagents rather than a read-only set |
disallowedTools | The harness, which removes the named tools | A prohibition written only in prompt leaves the tool available |
Top-level allowedTools / allowed_tools (not in the definition) | The permission flow, which pre-approves calls | Read as a restriction, it leaves every unlisted tool available; see 1.3.2 |
Put selection cues in description and execution criteria in prompt.
Descriptions occupy the main context. When custom subagent descriptions together exceed 15,000 tokens, excluding built-in agents, Claude Code warns at startup. Trim description and move execution detail into the system prompt, which loads only when that specialist runs. This is a warning threshold, not a refusal to load the agents.
Role contract versus task assignment: The reusable definition describes how the specialist works. The Agent invocation supplies this investigation’s question, documents, and constraints. Rebuilding the entire role for every invocation obscures which behavior is stable and which is request-specific.
A narrower tool set reduces opportunities for unintended actions but also limits the evidence the specialist can retrieve. A local-document reviewer cannot satisfy a task that requires online discovery with only Read, Grep, and Glob. Resolve that mismatch by changing the task or its capability contract, rather than expecting the prompt to manufacture access.
Architecture / decision scenario
A multi-agent research coordinator compares two vendors using documents already downloaded into a project. It needs a requirements reviewer and a synthesis specialist. You define document-reviewer with a description about supplied-document requirements, a prompt requiring evidence and gaps, and the three reading tools from the example.
The synthesis specialist’s description instead names cross-document comparison. Its prompt requires a comparison against the request’s criteria and prohibits turning missing evidence into a positive claim. It also receives reading tools because it must inspect supplied evidence files. Neither role needs command execution or source modification.
For this request, the coordinator passes the reviewer the two document paths and the exact retention question. It asks for findings, passages, locations, and unresolved conflicts. The reviewer can inspect the inputs while its capability set excludes editing them. If the result lacks a passage for a conclusion, the coordinator requests a targeted correction before passing it to synthesis.
The alternative design uses two descriptions saying “research expert,” identical general prompts, and omitted tools. That design fails at every contract surface: selection is ambiguous, role boundaries overlap, returned results lack a defined shape, and both specialists inherit capabilities they do not need. Fix the definition and the assignment together.
Common exam traps
- Treating
descriptionas the specialist’s system prompt. - Putting output requirements only in an agent’s name.
- Assuming omitted
toolsmeans no tools or read-only tools. - Using top-level
allowedToolsas a specialist capability restriction. - Expecting a prompt prohibition to remove an available tool.
- Adding persistent memory without reconsidering automatically enabled tools.
What to remember
Give each specialist selection cues in description, role and output requirements in prompt, and an explicit capability decision in tools or disallowedTools. Supply request-specific context at invocation. The contract works when the requested deliverable is achievable with the tools the specialist actually receives.
Knowledge check
A research coordinator has two specialists whose description fields both read “Research expert”. Their prompts and tool sets differ, but the coordinator delegates retention questions to either one unpredictably. Which change fixes the selection?
prompt with a more detailed role definitiondescription to name its work and when it appliestools listprompt is read by the specialist only after it is selected, the key identifies the agent rather than defining its selection contract, and a tool list limits what the specialist can do rather than when it should be chosen.A document-reviewer definition has a clear description and a prompt that says “Never modify source files”, but no tools field. During a review it edits a file. The reviewer needs only to read and search. Which change prevents the edit at runtime?
promptRead , Grep , and Glob to the top-level allowedToolsdescription fieldtools to Read , Grep , and Globtools field inherits every tool available to subagents, so a prohibition written in text leaves the editing tools in place. An explicit tools list removes them. Top-level allowedTools only pre-approves calls and restricts nothing, and the description guides selection rather than limiting capability.A read-only reviewer is defined with tools: ["Read", "Grep", "Glob"]. The team wants it to remember recurring findings across projects and proposes adding memory: user to its definition. Before approving, what must the architect re-evaluate?
memory makes Claude Code turn on Read , Write , and Edit automatically so the subagent can manage its memory files, which changes the capability assumption behind the small read-only list. Memory is a persistent directory loaded into the subagent’s own system prompt, not the coordinator’s context or a copy of the parent’s conversation, and it changes neither the output contract nor the scheduling.A coordinator needs every review to come back with findings, supporting passages with locations, and gaps. Where does this requirement belong in the specialist’s AgentDefinition, and what does it provide?
description , so that the coordinator can validate each reportprompt , as a behavioral contract the coordinator still checkstools , by listing only tools that return structured resultsprompt is the specialist’s system prompt, so the expected output belongs there; it states a behavioral contract, not a machine-enforced schema, and the coordinator still checks the returned content before synthesis. AgentDefinition has no output field, the description serves selection, and the tool list governs capability rather than report shape.References
- Anthropic, Subagents in the SDK
- Anthropic, Create custom subagents
- Anthropic, Configure permissions
- Anthropic, How we built our multi-agent research system