Text of code.claude.com › docs › en › agent-sdk › subagents as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

Subagents in the SDK - Claude Code Docs

Documentation Index Fetch the complete documentation index at: /docs/llms.txt Use this file to discover all available pages before exploring further. Skip to main content Assistant Responses are generated using AI and may contain mistakes. 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 Programmatic definition (recommended) 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. import asyncio from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition async def main (): async for message in query( prompt = "Review the authentication module for security issues" , options = ClaudeAgentOptions( # Auto-approve these tools allowed_tools = [ "Read" , "Grep" , "Glob" , "Agent" ], agents = { "code-reviewer" : AgentDefinition( # description tells Claude when to use this subagent description = "Expert code review specialist.

Use for quality, security, and maintainability reviews." , # prompt defines the subagent's behavior and expertise prompt = """You are a code review specialist with expertise in security, performance, and best practices. When reviewing code: - Identify security vulnerabilities - Check for performance issues - Verify adherence to coding standards - Suggest specific improvements Be thorough but concise in your feedback.""" , # tools restricts what the subagent can do (read-only here) tools = [ "Read" , "Grep" , "Glob" ], # model overrides the default model for this subagent model = "sonnet" , ), "test-runner" : AgentDefinition( description = "Runs and analyzes test suites.

Use for test execution and coverage analysis." , prompt = """You are a test execution specialist. Run tests and provide clear analysis of results. Focus on: - Running test commands - Analyzing test output - Identifying failing tests - Suggesting fixes for failures""" , # Bash access lets this subagent run test commands tools = [ "Bash" , "Read" , "Grep" ], ), }, ), ): if hasattr (message, "result" ): print (message.result) asyncio.run(main()) import { query } from "@anthropic-ai/claude-agent-sdk" ; for await ( const message of query ({ prompt: "Review the authentication module for security issues" , options: { // 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." , // prompt defines the subagent's behavior and expertise prompt: `You are a code review specialist with expertise in security, performance, and best practices. When reviewing code: - Identify security vulnerabilities - Check for performance issues - Verify adherence to coding standards - Suggest specific improvements Be thorough but concise in your feedback.` , // tools restricts what the subagent can do (read-only here) tools: [ "Read" , "Grep" , "Glob" ], // model overrides the default model for this subagent model: "sonnet" }, "test-runner" : { description: "Runs and analyzes test suites.

Use for test execution and coverage analysis." , prompt: `You are a test execution specialist. Run tests and provide clear analysis of results. Focus on: - Running test commands - Analyzing test output - Identifying failing tests - Suggesting fixes for failures` , // Bash access lets this subagent run test commands tools: [ "Bash" , "Read" , "Grep" ] } } } })) { if ( "result" in message ) console . log ( message . result ); } AgentDefinition configuration Field Type Required Description description string Yes Natural language description of when to use this agent prompt string Yes The agent’s system prompt defining its role and behavior tools string[] No Array of allowed tool names.

If omitted, inherits every tool available to subagents disallowedTools string[] No Array of tool names to remove from the agent’s tool set. MCP server-level patterns are also accepted: mcp__server or mcp__server__* removes every tool from that server, and mcp__* removes every MCP tool from any server model string No Model override for this agent. Accepts an alias such as 'fable' , 'opus' , 'sonnet' , 'haiku' , 'inherit' , or a full model ID. 'inherit' uses the model of the agent that spawned this one.

When you omit model , Claude Code picks the model in the subagent model order skills string[] No List of skill names to preload into the agent’s context at startup. At most the first 32 distinct names in the list are preloaded. Unlisted skills remain invocable through the Skill tool memory 'user' | 'project' | 'local' No Memory source for this agent mcpServers (string | object)[] No MCP servers available to this agent, by name or inline config initialPrompt string No Auto-submitted as the first user turn when this agent runs as the main thread agent.

Ignored when the agent is invoked as a subagent maxTurns number No Maximum number of agentic turns before the agent stops. When the agent reaches the limit, Claude Code returns its output marked as partial, and you can resume the agent to continue. The partial marking requires Claude Code v2.1.246 or later autoCompactWindow number No Lower the auto-compact window for this agent when it runs as a subagent, to a token count of 100000 or more.

Requires TypeScript Agent SDK v0.3.296 or later. The Python SDK’s AgentDefinition doesn’t have this field background boolean No Run this agent as a non-blocking background task when inv

The rest of this page is on the live site.