SecondBrain/reference/agent-orchestration-patterns.md

---
type: reference
subtype: pattern/framework
title: Agent Orchestration Patterns
summary: Principles and decision framework for coordinating multiple AI subagents without exhausting the main context window. Answers "when to delegate and how to structure it."
tags:
  - type/reference
  - domain/ai-agents
  - domain/orchestration
scope: global
last_updated: 2026-06-27
related:
  - reference/agent-orchestration-cookbook
---

# Agent Orchestration Patterns

**Purpose**: When should you spawn agents vs. use tools directly, and how do you structure multi-agent work to keep token costs under control?

## Core Principle

Agents are **disposable contexts**: each subprocess starts fresh, does its work, writes output to files, then disappears. Only the minimal return value lands in the main conversation. Heavy file reading happens in agent context — never in main context.

## Decision Framework

```
How many items?
  │
  ├─ 1–3 ──────────────────────► Direct tools only
  │                               Tool tax > benefit
  │
  ├─ 4–10 ─────────────────────► Single specialist agent
  │         Can batch by type? ──► Yes: 1 agent handles all
  │                               No:  2–3 typed agents
  │
  ├─ 11–30 ────────────────────► 2–4 specialist agents
  │   Speed critical? ─────────► Parallel specialists
  │   Cost critical?  ─────────► Sequential specialists
  │
  └─ 30+ ──────────────────────► Specialists + phase rotation
      └─ Re-evaluate: is agent pattern right here?
```

### Parallelism vs. Cost Tradeoff

| Approach | Relative Cost | Speed | Best When |
|---|---|---|---|
| 1 agent per item | Very high (N × tool tax) | Fast | Never — this is an anti-pattern |
| Batched specialists (5–8/agent) | Low | Medium | Default choice |
| Sequential specialist | Lowest | Slow | Cost-critical, interruptible tasks |
| Parallel specialists | Medium | Fast | Speed-critical, failures must isolate |

## The Patterns

### 1. Disposable Context
**When**: Any time you need to read N files and process them.
**Why**: Each agent's file reads vanish when the agent finishes; only the return value (200–400 tokens) stays in main context.
**Anti-example**: Main conversation reads 20 files → context grows to 100K+ tokens and never shrinks.

### 2. Minimal Prompt, File-Specified Paths
**When**: Always.
**Why**: Agents read what they need; do not pre-load them with full project context.
**Rule**: Prompt = task description + paths + decision criteria + return schema. No more.

```
Update {component} with Alpine.js.
- Source: {jsx_path}
- Target: {erb_path}
- Audit:  {audit_path}
Decision: clear→update, ambiguous→skip+note, no-op→skip
Return: {"status": "updated|skipped|ambiguous", "changes": [...]}
```

### 3. State via Files, Not Memory
**When**: Agents need to share data or pass results forward.
**Why**: Agents cannot communicate directly; files are the coordination bus.
**Pattern**: Each agent writes `reports/{item}.md`; a consolidation agent reads `reports/*.md`.

### 4. Single-Message Parallel Spawn
**When**: You want agents to run concurrently.
**Why**: Multiple Task tool calls in one message → parallel. Separate messages → sequential.
**Rule**: Prepare all agent prompts, then issue all Task calls in a single message.

### 5. Batch by Similarity (2-of-3 Rule)
**When**: Deciding how to group items across specialists.
**Why**: Similar items share setup cost; the "tool tax" (~20–25K tokens) is paid once per agent.
**Rule**: Items are similar enough to batch if they share 2 of 3: input format, transformation logic, output format.
**Batch size**: 5–8 items per specialist (avoids rate limits; keeps per-agent context manageable).

### 6. Four-Phase Structure
**When**: Any multi-item orchestration task.

| Phase | Who | What | Returns |
|---|---|---|---|
| Inventory | Agent (haiku) | Discovery only — no file reading | JSON item list |
| Processing | Specialist agents (sonnet) | Read, transform, write reports | Minimal JSON status |
| Consolidation | Agent (sonnet) | Read all reports, generate summary | Executive summary |
| Cleanup | Main conversation (direct tools) | `rm`, `mv` | — |

## Model Selection

| Task | Model |
|---|---|
| Inventory, file discovery | haiku |
| Simple transforms, mechanical | haiku |
| Analysis, code generation | sonnet (default) |
| Architecture decisions | sonnet |

## Anti-Patterns

| Anti-Pattern | Problem | Fix |
|---|---|---|
| 1 agent per item | N × tool tax; 20 items = 550K tokens | Batch 5–8 items per specialist |
| Main reads all files | Context grows monotonically; no recovery | Delegate reads to agents |
| Over-sharing context in prompt | Wasted tokens on unused info | Paths + instructions only |
| Verbose agent responses | Bloats main context with detail | Return JSON status; write detail to files |
| Skip consolidation phase | User must parse N raw responses | Always run a summary agent |
| Silent failure on error | Items silently lost | Log errors, continue batch, report in summary |

## Error Handling Rules

1. Let other agents in the batch **complete** — don't abort on one failure.
2. Return structured error: `{"item": "X", "status": "error", "error": "reason"}`.
3. Consolidation agent treats missing reports as errors.
4. Report failures in summary; let the user decide on retry.
5. Design for **idempotency** — re-running a specialist should be safe (check-before-modify).

## Context Budget Reference

| Component | Tokens |
|---|---|
| System tools (fixed overhead) | ~15–20K |
| CLAUDE.md / project files | ~3–5K |
| Agent prompt | ~1–2K |
| **Minimum per agent** | **~20–25K** |

**20-item example**:
- Naive (1:1): 20 agents × 30K = **600K tokens**
- Batched (4 specialists × 5 items): 4 × 37K = **148K tokens** (75% reduction)

## Known Limitations

- Task tool does **not** return agent IDs programmatically (visible in UI only).
- No API to list active/completed agents.
- `resume` parameter requires manual ID tracking — not suitable for automated orchestration.
- **Workaround**: track progress via manifest files; design for idempotency.

## Related

- [[reference/agent-orchestration-cookbook]] — concrete walkthroughs, token budgets, error recovery patterns