6.6 KiB

Raw Blame History

type

subtype

title

summary

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

Let other agents in the batch complete — don't abort on one failure.
Return structured error: {"item": "X", "status": "error", "error": "reason"}.
Consolidation agent treats missing reports as errors.
Report failures in summary; let the user decide on retry.
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

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.

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.

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

6.6 KiB Raw Blame History Unescape Escape