What Are Sub-Agents?

A sub-agent is an agent spawned by another agent to handle a specific subtask:

Main Agent (orchestrator)
  ├── Sub-Agent 1: "Research this topic"
  ├── Sub-Agent 2: "Write tests for this code"
  └── Sub-Agent 3: "Review the implementation"

Why sub-agents?

• Each sub-agent can use a different model (cheap for research, expensive for coding)
• Sub-agents run in parallel — faster than sequential execution
• Each sub-agent has a focused context window — no context pollution
• Failure in one sub-agent doesn't crash the others

The Orchestrator Pattern

The most common multi-agent architecture:

User Request
     ↓
┌──────────────┐
│ Orchestrator │  Plans and delegates
│ (Tier 3-4)   │  Uses a mid-tier model
└──────┬───────┘
       │
  ┌────┼────┬────────┐
  ↓    ↓    ↓        ↓
┌────┐┌────┐┌────┐┌──────┐
│ R1 ││ R2 ││ R3 ││ R4   │  Specialist agents
│T5  ││T1  ││T5  ││T3    │  Each uses optimal tier
└────┘└────┘└────┘└──────┘
  ↓    ↓    ↓        ↓
  └────┴────┴────────┘
       ↓
┌──────────────┐
│ Orchestrator │  Combines results
│ (Tier 3-4)   │
└──────────────┘
       ↓
   Final Response

Cost optimization: The orchestrator uses a Tier 3-4 model for planning. Only the sub-agent that needs deep reasoning uses a Tier 1 model. Simple sub-tasks use Tier 5-6.

Sub-Agents in Practice

OpenCode implements sub-agents with its agent system:

## AGENTS.md — Sub-agent definitions

### Research Agent
- Model: gpt-4o-mini (fast, cheap)
- Tools: web search, file read
- Task: gather information, summarize findings
- Output: structured research brief

### Implementation Agent
- Model: claude-sonnet-4 (strong coding)
- Tools: file read/write, terminal
- Task: write code based on research brief
- Output: working implementation with tests

### Review Agent
- Model: claude-opus-4.6 (thorough analysis)
- Tools: file read, terminal (run tests)
- Task: review implementation, find issues
- Output: approval or list of changes needed

The key insight: Each agent has its own system prompt, tool set, and model — optimized for its specific role.

Self-Improving Agent Systems

The most advanced pattern: agents that make themselves better.

The improvement loop:

1. Agent performs a task
2. Agent evaluates its own performance
3. Agent identifies what went wrong or could be better
4. Agent updates its own instructions (AGENTS.md, prompts)
5. Next task uses the improved instructions
6. Repeat

Practical example:

Session 1:
  Agent writes a function with a bug
  Tests catch the bug
  Agent fixes it

Session 2 (self-improvement):
  Agent reviews Session 1 logs
  Discovers: "I often forget null checks on optional fields"
  Updates AGENTS.md: "Always add null checks for optional parameters"

Session 3:
  Agent writes a function WITH null checks from the start
  Tests pass on first try

Building a Self-Improving System

A practical implementation:

Step 1: Log everything

// After each agent session, save a retrospective
const retro = {
  task: "Add user search endpoint",
  attempts: 3,
  errors: [
    "Missing null check on query parameter",
    "Forgot to add route to index.js"
  ],
  fix_patterns: [
    "Always validate query parameters",
    "Always register new routes in index.js"
  ],
  timestamp: new Date().toISOString()
};
await fs.writeFile('agent-retros/session-42.json', JSON.stringify(retro));

Step 2: Periodically synthesize learnings

Prompt: "Review the last 20 agent retrospectives.
Identify the top 5 recurring mistakes. For each, write
a concise rule that would prevent it. Update AGENTS.md
with these rules in the Pitfalls section."

Step 3: Verify improvement Track error rates over time. If a specific error type drops after adding a rule, the system is genuinely improving.

Multi-Agent Communication

How agents talk to each other:

Direct passing (simplest):

result_1 = await research_agent.run(task);
result_2 = await coding_agent.run(task, result_1);
result_3 = await review_agent.run(result_2);

Message queue (scalable):

Research Agent → publishes findings to queue
Coding Agent  → subscribes to findings, publishes code
Review Agent  → subscribes to code, publishes reviews

Shared workspace (file-based):

All agents read/write to a shared directory:
  workspace/
    research.md    ← Research agent writes
    implementation/ ← Coding agent writes
    review.md      ← Review agent writes
    plan.md        ← Orchestrator reads all, updates plan

The shared workspace pattern is the simplest and most debuggable. You can inspect every file to understand what each agent produced.

When NOT to Use Sub-Agents

Sub-agents add complexity. Use them only when the benefit justifies it:

Use sub-agents when:

• Different subtasks need different models
• Subtasks can run in parallel for speed
• Each subtask is complex enough to fill a context window
• You need different tool sets per subtask

Don't use sub-agents when:

• A single agent with the right model can handle the full task
• The overhead of orchestration exceeds the time saved
• The task is sequential and each step depends on the previous one
• You're adding complexity for the sake of architecture

The cost of sub-agents:

• Each agent invocation has latency overhead (2-5 seconds)
• Orchestrator tokens add up (planning, combining results)
• Debugging multi-agent failures is harder than single-agent
• More moving parts = more failure modes

Start with one agent. Split into sub-agents only when you hit a clear limitation that sub-agents solve.

---quiz question: What is the main advantage of using sub-agents with different model tiers? options:

• { text: "Sub-agents are always faster than single agents", correct: false }
• { text: "Each sub-agent can use the optimal model for its specific task, reducing cost while maintaining quality", correct: true }
• { text: "Sub-agents don't need system prompts", correct: false } feedback: Sub-agents allow cost optimization by matching each subtask to its ideal model — a cheap Tier 5-6 model for research, an expensive Tier 1 for complex reasoning, and a mid-tier for everything else.

---quiz question: How do self-improving agent systems work? options:

• { text: "They automatically retrain the underlying LLM", correct: false }
• { text: "They log mistakes, identify patterns, and update their own instructions (AGENTS.md) to prevent recurring errors", correct: true }
• { text: "They download updates from the internet", correct: false } feedback: Self-improving systems log their errors, analyze patterns, and update their instruction files (like AGENTS.md) so that future sessions benefit from past mistakes — creating a virtuous improvement cycle.

---quiz question: When should you NOT use sub-agents? options:

• { text: "When different subtasks need different models", correct: false }
• { text: "When a single agent can handle the full task and the overhead of orchestration would exceed the time saved", correct: true }
• { text: "When working with open-source models", correct: false } feedback: Sub-agents add latency, token costs, and debugging complexity. Only use them when a single agent hits clear limitations — like needing different models, parallel execution, or isolated context windows for different subtasks.