sub-agent-delegation

Sub-Agent Delegation

Sub-agents are isolated agent invocations spawned from a parent. They run in a fresh context, do focused work, and return a single result. Use them to parallelize, specialize, and protect context.

When to Use

• Parallel research (5 topics × 1 agent each, run concurrently)
• Context-heavy sub-tasks that would bloat the parent's window
• Specialist work (a "code reviewer" sub-agent, a "security auditor" sub-agent)
• Independent work items where errors shouldn't compound

When NOT to Use

• Trivial single-step tasks — sub-agent overhead isn't worth it
• Tasks that need to see the parent's full context — you'll have to pass it, defeating the isolation
• Highly interactive work — sub-agents don't ask clarifying questions back

The Model

Parent agent sees a Task (or Agent) tool. When invoked, it spawns a sub-agent with:

• A fresh conversation (no parent history)
• Its own tool set (may be a subset of parent's)
• A single prompt describing the work
• A requirement to return ONE final response

The sub-agent's intermediate tool calls are NOT visible to the parent — only the final result.

SDK Usage

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

for await (const msg of query({
  prompt: "Research and compare the top 3 vector databases. Summarize pros/cons.",
  options: {
    model: "claude-sonnet-4-6",
    allowedTools: ["Task", "WebFetch", "Read"],
  },
})) { /* ... */ }

The parent agent decides to invoke Task with a prompt like "Research Pinecone's pros and cons. Use WebFetch. Report in under 200 words." Three parallel Task calls, three independent contexts, three summaries returned.

Parallel Spawning

The parent can issue multiple tool calls in one step:

Parent: Let me research all three in parallel.
[tool_use: Task]   Research Pinecone...
[tool_use: Task]   Research Weaviate...
[tool_use: Task]   Research Qdrant...

Three sub-agents run concurrently. Parent waits for all three results, then synthesizes.