151 lines
6.3 KiB
Markdown
151 lines
6.3 KiB
Markdown
---
|
||
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
|