2026-06-27 21:39:35 +00:00
---
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
2026-06-30 20:26:02 +00:00
- tool/claude-code
2026-06-27 21:39:35 +00:00
scope: global
last_updated: 2026-06-27
2026-06-30 20:26:02 +00:00
last_reviewed: 2026-06-30
2026-06-27 21:39:35 +00:00
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–
│ Tool tax > benefit
│
├─ 4–
│ Can batch by type? ──► Yes: 1 agent handles all
│ No: 2–
│
├─ 11– –
│ 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 ×
| Batched specialists (5–
| 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–
**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–
**Rule**: Items are similar enough to batch if they share 2 of 3: input format, transformation logic, output format.
**Batch size**: 5–
### 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 × –
| 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–
| CLAUDE.md / project files | ~3–
| Agent prompt | ~1–
| **Minimum per agent** | ** ~20–
**20-item example**:
- Naive (1:1): 20 agents × **600K tokens**
- Batched (4 specialists × × **148K tokens** (75% reduction)
## Known Limitations
2026-06-30 20:26:02 +00:00
**Note:** Task tool behavior is version-sensitive and may change with tool updates. Verify tool capabilities in current Claude Code documentation before relying on the patterns below in production systems.
2026-06-27 21:39:35 +00:00
- 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
