Sub-Agents in the Claude Agent SDK

Why sub-agents exist

Every agent runs inside a context window. The longer an agent works — reading files, making tool calls, building up conversation history — the more of that window it consumes. Complex tasks that require dozens of tool calls can saturate a single agent's context before the work is finished.

Sub-agents solve this by distributing work. Instead of one agent doing everything, a parent agent delegates specific tasks to independent workers. Each sub-agent gets its own context window, does its assigned work, and returns a result to the parent. The parent's context stays clean. The total throughput increases.

The other benefit is parallelism. When you have tasks that do not depend on each other — research five competitors, pull data from four client folders, draft three separate deliverables — sub-agents can run those tasks simultaneously rather than sequentially. Work that would take 15 minutes end-to-end can complete in 5.

> The pattern for operators. Any workflow where you are gathering information from multiple sources at once is a candidate for sub-agents. Competitive research, multi-client status sweeps, pre-call briefing packages — these are tasks where the sub-agent pattern delivers immediate time savings.

How sub-agents work in the SDK

The Claude Agent SDK provides a built-in tool called the agent tool. When the parent agent has access to this tool, it can spin up sub-agents programmatically.

A critical naming note: Anthropic renamed this tool from task to agent in a recent SDK update. If you have worked with the SDK before and used the task tool for sub-agents, the current name is agent. Update your code accordingly.

Each sub-agent is defined using an AgentDefinition object. The definition has five parts:

• description — what the parent agent sees to decide when to delegate to this sub-agent (similar to how tools declare what they do)
• prompt — the system prompt for the sub-agent itself, defining its role and behavior
• tools — which tools the sub-agent has access to (you can restrict this independently of the parent agent)
• model — which Claude model the sub-agent uses (you can run sub-agents on a cheaper, faster model than the parent)
• maxTurns — optional cap on how many turns the sub-agent can take before returning

Sub-agents cannot spawn their own sub-agents. They can use any tool the parent agent can use, with that single exception.

Building sub-agents in code

Here is the structure of an agent configuration with two sub-agents:

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query(
  "Plan a camping trip to Yosemite and write the plan to a file.",
  {
    model: "claude-sonnet-4-5",
    tools: ["read", "write", "agent"],
    permissionMode: "bypassPermissions",
    dangerouslyAllowBypassPermissions: true,
    agents: {
      planner: {
        description: "Trip planner. Use for creating travel plans.",
        prompt: "You are a trip planner. Create a short, practical plan for the trip.",
        tools: ["read", "write"],
        model: "claude-sonnet-4-5",
      },
      writer: {
        description: "Writer. Use for creating documents from plans.",
        prompt: "You are a writer. Create a well-structured document based on the plan provided.",
        tools: ["read", "write"],
        model: "claude-haiku-4-5",
      },
    },
  }
)) {
  if (message.type === "assistant" && message.content[0]?.type === "text") {
    console.log(message.content[0].text);
  }
}

What happens at runtime. The parent agent receives the prompt and identifies that it has two sub-agents available. It determines that the planner should go first, delegates the planning task, receives the plan back, and then delegates the writing task to the writer sub-agent. The writer reads the plan and produces the document. The parent then reports the final result.

The parent agent coordinates. The sub-agents execute. None of them interfere with each other's context.

Model selection for sub-agents. Using a cheaper model for sub-agents handling simpler tasks is a practical cost optimization. In the example above, the planner uses Sonnet for quality reasoning. The writer uses Haiku for fast, cheap document generation. The main agent uses whichever model best fits the overall complexity of the workflow.

> How the description works. The parent agent reads the description field to decide which sub-agent to delegate to. Write descriptions that make the decision obvious. "Use for creating travel plans" is unambiguous. "Use when needed" is not. The clearer the description, the more reliably the parent agent routes tasks correctly.

Three built-in sub-agents

The SDK includes three default sub-agents that are always available without any custom configuration:

• General purpose — the default sub-agent for any task that does not match a custom agent's description
• Explorer — specialized for reading and analyzing existing content
• Plan agent — specialized for structured planning tasks

These mirror the built-in agent types available in Claude Code. You can keep them enabled alongside your custom agents or disable them if you want tighter control over delegation behavior.

For most production agents, you will want to define your own sub-agents with descriptions and prompts tuned to your specific workflow. The built-in defaults are useful for general experimentation.

Practical workflows for fractional leaders

Competitive pricing research. You need a market positioning snapshot for a client. One sub-agent per competitor, each pulling pricing, positioning language, and recent announcements simultaneously. By the time you have reviewed the task assignment, all agents are running in parallel. The parent synthesizes a consolidated competitive summary.

Multi-client Monday brief. You manage four active engagements and need a status summary for each before your first call. Configure one sub-agent per client folder. Each reads the latest notes, activity logs, and open items and returns a structured summary. Four clients, processed in parallel, ready before the first meeting of the week.

Pre-call research package. Before a discovery call, three sub-agents run simultaneously: one on the company background, one on recent news and press, one on the competitive landscape. You walk into the call with a brief that would have taken an hour to compile manually.

The mechanics are consistent across all of these. Define the tasks, configure the sub-agents, let the parent coordinate. The value compounds once you turn these into reusable custom commands — one prompt triggers the full multi-agent workflow every time.

> Start with one. Pick one research workflow you run at least weekly. Build a single sub-agent for it. Refine the description and prompt until the delegation is reliable. Then add the second sub-agent. Building incrementally produces more reliable results than configuring five sub-agents at once and debugging the whole chain.

---

Author: FractionalSkill