Skip to main content
Subagents are separate agent instances that your main agent can spawn to handle focused subtasks. Use them to isolate context, run multiple analyses in parallel, and apply specialized instructions without adding to the main agent’s prompt.

Overview

You can create subagents in three ways:
  • Programmatically: use the agents parameter in your query() options. See the TypeScript and Python references
  • Filesystem-based: define agents as markdown files in .claude/agents/ directories. See defining subagents as files
  • Built-in general-purpose: Claude can invoke the built-in general-purpose subagent at any time via the Agent tool without you defining anything
This guide focuses on the programmatic approach, which is recommended for SDK applications.

Benefits of using subagents

Because subagents are separate agent instances, delegating work to them gives you four benefits:
  • Context isolation: each subagent runs in its own conversation, which starts fresh unless the subagent is a fork. Either way, intermediate tool calls and results stay inside the subagent; only its final message returns to the parent. A research-assistant subagent can explore dozens of files without any of that content accumulating in the main conversation. The parent receives a concise summary, not every file the subagent read. See What subagents inherit for exactly what’s in the subagent’s context.
  • Parallelization: multiple subagents can run concurrently, so independent subtasks finish in the time of the slowest one rather than the sum of all of them. During a code review, you can run style-checker, security-scanner, and test-coverage subagents simultaneously instead of sequentially.
  • Specialized instructions and knowledge: each subagent can have a tailored system prompt with specific expertise, best practices, and constraints. A database-migration subagent can have detailed knowledge about SQL best practices, rollback strategies, and data integrity checks that would be unnecessary noise in the main agent’s instructions.
  • Tool restrictions: subagents can be limited to specific tools, reducing the risk of unintended actions. A doc-reviewer subagent might only have access to Read and Grep tools, ensuring it can analyze but never accidentally modify your documentation files.

Create subagents

Define subagents directly in your code using the agents parameter. Claude invokes subagents through the Agent tool. Most examples on this page print only the final result. To confirm that Claude delegated to a subagent rather than answering directly, see Detect subagent invocation. This example creates two subagents: a code reviewer with read-only access and a test runner that can execute commands.

AgentDefinition configuration