Sub-Agents

Sub-agents are specialized agent instances spawned by the main agent to handle specific tasks. They enable parallelization, specialization, and isolation while keeping the main context clean.

Why Sub-Agents?

Sub-Agent Architecture

graph TD
    A[Main Agent] --> B[Task Decomposition]
    B --> C[Spawn Sub-Agent 1]
    B --> D[Spawn Sub-Agent 2]
    B --> E[Spawn Sub-Agent 3]
    C --> F[Sub-Agent 1 Context]
    D --> G[Sub-Agent 2 Context]
    E --> H[Sub-Agent 3 Context]
    F --> I[Results]
    G --> I
    H --> I
    I --> A[Main Agent Synthesizes]

    style A fill:#e1f5fe
    style C fill:#f3e5f5
    style D fill:#f3e5f5
    style E fill:#f3e5f5
    style I fill:#e8f5e9

When to Use Sub-Agents

Sub-Agent Configuration

interface SubAgentConfig {
  name: string;           // Purpose identifier
  description: string;    // When to use this sub-agent
  systemPrompt: string;   // Specialized instructions
  tools: string[];        // Allowed tools (restrictive)
  model?: string;         // Override model (cheaper/faster)
  maxTurns?: number;      // Limit iterations
  permissions?: PermissionProfile;
  context?: {
    includeFiles?: string[];
    includeMemory?: boolean;
  };
}

Built-in Sub-Agent Patterns

Spawning Sub-Agents

async def spawn_subagent(config: SubAgentConfig, task: string) -> SubAgentResult:
    # Create isolated session
    sub_session = await create_sub_session(parent_session_id)

    # Build context for sub-agent
    context = build_subagent_context(config, task)

    # Run sub-agent loop with restrictions
    result = await run_agent_loop(
        session=sub_session,
        system_prompt=config.systemPrompt,
        tools=filter_tools(config.tools),
        model=config.model or parent_model,
        max_turns=config.max_turns or 10,
        permissions=config.permissions
    )

    return SubAgentResult(
        summary=result.summary,
        findings=result.findings,
        files_changed=result.files_changed,
        success=result.success
    )

Communication Patterns

Fire and Forget

Main agent spawns and continues, doesn't wait for result.

await spawn_background_subagent(config, task)
# Continue with other work

Synchronous (Wait for Result)

Main agent waits for sub-agent to complete and uses results.

result = await spawn_subagent(config, task)
# Use result in main agent context

Parallel

Multiple sub-agents working simultaneously.

results = await asyncio.gather(
    spawn_subagent(explore_config, "find auth code"),
    spawn_subagent(test_config, "run related tests"),
)

Result Summarization

Sub-agents should return concise summaries to avoid bloating main context:

interface SubAgentResult {
  summary: string;        // Brief summary of what was done
  keyFindings: string[];  // Important discoveries
  filesModified: string[];
  filesRead: string[];
  recommendations?: string[];
  needsFollowUp: boolean;
  rawOutput?: string;     // Only if necessary
}

Context Passing

What to pass TO sub-agent:

• Specific task description
• Relevant file paths
• Relevant context from main session
• Constraints/requirements
• Tool restrictions

What NOT to pass:

• Full conversation history
• Unrelated files
• All tool results
• Personal preferences (unless relevant)

Best Practices

Design

1. Narrow scope - Give sub-agent a specific, well-defined task
2. Clear instructions - Include goal, constraints, and expected output
3. Minimal tools - Only tools needed for the task
4. Appropriate model - Use cheaper models for simple tasks
5. Set turn limits - Prevent runaway sub-agents

Execution

1. Summarize results - Main agent should get condensed results
2. Parallelize wisely - Only independent tasks in parallel
3. Handle failures - Sub-agent failures shouldn't crash main agent
4. Track costs - Monitor token usage across all sub-agents
5. Avoid deep nesting - Usually 1-2 levels max

Safety

1. Restrict permissions - Sub-agents often need fewer permissions
2. Isolate work - Consider using worktrees for code changes
3. Review changes - Main agent should review sub-agent changes
4. Limit scope - Don't let sub-agents modify unrelated files

Example: Explore Sub-Agent

name: explore
description: "Search and explore codebase to understand patterns"
systemPrompt: |
  You are an exploration specialist. Your job is to find and understand code.
  Be thorough but concise. Return a clear summary of findings.
  Don't make changes - only read and search.
tools:
  - read_file
  - glob
  - grep
  - list_dir
model: "fast-model"
maxTurns: 15
permissions:
  mode: "read-only"

Example: Implementation Sub-Agent

name: implement
description: "Implement a specific feature or fix"
systemPrompt: |
  You are an implementation specialist. Focus on the specific task.
  Follow existing code patterns. Make minimal, focused changes.
  Run tests if they exist for the modified code.
tools:
  - read_file
  - write_file
  - edit
  - grep
  - glob
  - bash
model: "balanced-model"
maxTurns: 30
permissions:
  mode: "interactive"

Debugging Sub-Agents

• Log sub-agent sessions separately - Easier to trace
• Show sub-agent status in UI - Keep user informed
• Allow inspection - View sub-agent's thinking/tool calls
• Track hierarchy - Know parent-child relationships

Related Notes

• Parallel Execution — Parallel tool execution
• Task Management — Task decomposition
• Permission System — Permissions
• Session Management — Sessions
• Agent Loop — Agent loop

Sources

• Claude Code sub-agents documentation
• OpenCode task/subagent patterns
• Anthropic multi-agent research
• LangGraph sub-graphs
• "Agentic Patterns" - sub-agent delegation