Learn · Agentic architecture & orchestration · CCAR-F task 1.3

Configuring subagents

Define a subagent, restrict its tools, and brief it fully: it starts with a fresh context and sees nothing you didn't pass.

Key ideas

• Claude Code subagents are Markdown files in .claude/agents/ (project) or ~/.claude/agents/ (personal).
• The description drives automatic delegation; you can also name or @-mention a subagent.
• tools restricts a subagent to least privilege; omit it and the subagent inherits all tools.
• In the Agent SDK, AgentDefinition holds description, prompt, tools and model; the coordinator must be allowed the Agent (formerly Task) tool.
• Subagents start with a fresh context: pass goal, constraints, prior findings and output format.
• Issue several subagent calls in one response to run independent subtasks in parallel.

Worked example: A coordinator with two subagents in the Agent SDK

The researcher runs on a fast model with web tools only; the writer can only read. Because the coordinator's allowed_tools include Agent, it can delegate to either.

Exam traps

• Assuming a subagent can see the coordinator's conversation. It starts fresh; missing context is a common root cause of poor results.
• Forgetting to include the Agent (Task) tool in the coordinator's allowed tools.
• Omitting tools on a reviewer subagent, which then inherits write access it doesn't need.
• Writing the coordinator's brief as a rigid step-by-step procedure instead of goals and quality criteria.
• Spawning independent subagents one per turn instead of several calls in one response.

Official docs

• Subagents in Claude Code
• Subagents in the Agent SDK

Practise CCAR-F questions · Next lesson: Enforcement and handoff