Why Sub-Agents?
A single agent with every tool and responsibility quickly becomes unwieldy. It is like having one employee who does sales, engineering, accounting, and customer support — they will be mediocre at everything. The solution is delegation: a main agent that coordinates specialized sub-agents, each focused on what it does best.
Real-world analogy: A film director does not operate the camera, write the script, compose the music, and edit the footage. They coordinate specialists. Your main agent is the director. Sub-agents are the crew — each with a specific role, specific tools, and specific instructions.
Defining Sub-Agents
The SDK lets you define sub-agents using the agents option. Each sub-agent gets its own name, instructions, model, and tools. The main agent can delegate tasks to any sub-agent by name:
TypeScript — defining a team of sub-agents
import { Claude } from "@anthropic-ai/claude-agent";
const agent = new Claude({
model: "claude-sonnet-4-6",
tools: "defaults",
systemPrompt: `You are a project manager. Delegate tasks to your team:
- Use the "researcher" agent for gathering information
- Use the "coder" agent for writing and editing code
- Use the "reviewer" agent for quality checks
Coordinate their work and report the final result.`,
// Define specialized sub-agents
agents: [
{
name: "researcher",
model: "claude-sonnet-4-6",
tools: ["Read", "Grep", "Glob"], // read-only tools
instructions: "You are a code researcher. Find information in the codebase. Be thorough and report what you find accurately.",
},
{
name: "coder",
model: "claude-sonnet-4-6",
tools: ["Read", "Write", "Edit", "Bash"],
instructions: "You are a senior developer. Write clean, tested code. Always include error handling.",
},
{
name: "reviewer",
model: "claude-sonnet-4-6",
tools: ["Read", "Grep"], // can read but not modify
instructions: "You are a code reviewer. Check for bugs, security issues, and best practices. Be specific about problems and suggest fixes.",
},
],
});
// The main agent coordinates all three sub-agents
const result = await agent.query(
"Add input validation to the user registration endpoint in src/routes/auth.ts"
);
console.log(result.text);