SecondBrain/reference/agent-orchestration-cookbook.md

---
type: reference
subtype: pattern/framework
title: Agent Orchestration Cookbook
summary: Concrete implementation examples for multi-agent orchestration — prompt templates, token budgets, error recovery, and common gotchas. Companion to the patterns hub.
tags:
  - type/reference
  - domain/ai-agents
  - domain/orchestration
  - tool/claude-code
scope: global
last_updated: 2026-06-27
last_reviewed: 2026-06-30
related:
  - reference/agent-orchestration-patterns
---

# Agent Orchestration Cookbook

**Purpose**: Concrete examples, prompt templates, and gotchas for implementing the patterns in [[reference/agent-orchestration-patterns]].

**Note:** Tool behavior (especially the Task tool) is version-sensitive and may change with Claude Code updates. Verify agent capabilities against current Claude Code documentation before adapting these examples to production systems.

## Phase Templates

### Phase 1 — Inventory Agent Prompt

```markdown
Discover all [items] matching [criteria].

Use filesystem commands only (ls, find, glob) — do NOT read file contents.

Return JSON:
{
  "items": [
    {
      "name": "[identifier]",
      "source_path": "...",
      "target_path": "...",
      "output_path": "reports/[name].md"
    }
  ],
  "count": N
}
```

Key constraint: **no file reading** in inventory. Just paths. Keeps agent context small (~200 token return).

### Phase 2 — Specialist Agent Prompt

```markdown
Process these [N] [item type]: [name1, name2, ...]

For each item:
1. Read source: {source_path}
2. Read target: {target_path}
3. [Transform / analyze / validate]
4. Write audit to: {output_path}

Decision criteria:
- Clear action needed → execute → status: "updated"
- No change needed → skip → status: "skipped"
- Ambiguous / risky → don't modify → status: "ambiguous" + reason

Return JSON array:
[{"name": "...", "status": "updated|skipped|ambiguous", "changes": [...], "reason": "..."}]
```

Spawn all specialist agents **in a single message** for parallel execution.

### Phase 3 — Consolidation Agent Prompt

```markdown
Read all reports in [output_dir]/*.md
Treat missing reports as errors.

Generate:
## Summary
- Total: X | Updated: Y | Skipped: Z | Ambiguous: W | Errors: E

## Needs Review
[For each ambiguous item: name + reason + options]

## Errors
[For each error: name + what failed]

## Cleanup
[List temp files ready for removal after user approval]
```

### Phase 4 — Cleanup (Main Conversation)

Run directly — no agent needed. Simple bash: `rm -rf reports/[task]/`

---

## Token Budget Examples

### 12-Item Migration (3 Specialists)

| Phase | Main Context Δ | Agent Contexts |
|---|---|---|
| Inventory | +200 tokens | ~25K (1 agent) |
| Processing (3 × 4 items) | +600 tokens (3 × 200) | ~90K (3 × 30K) |
| Consolidation | +300 tokens | ~27K (reads 12 reports) |
| Cleanup | +100 tokens | 0 |
| **Total main** | **~1,200 tokens** | — |
| **Total agents** | — | **~142K tokens** |

Naive (main reads 12 components directly): ~60K+ tokens in main, no isolation.

### Batching Math

```
Tool tax per agent: ~20–25K tokens (fixed)
Work per item:      ~5K tokens (variable)

20 items, 1:1:      20 × (25K + 5K) = 600K tokens
20 items, batched:   4 × (25K + 25K) = 200K tokens   ← 67% savings
```

The "2-of-3 similarity rule" for grouping: items share input format + transformation + output format → batch together.

---

## Error Recovery Patterns

### Resilient Batch (Pseudocode)

```python
results = []
for agent in batch:
    result = await agent.complete()
    if result.ok:
        results.append(result.data)
    else:
        results.append({
            "item": agent.item,
            "status": "error",
            "error": result.error_message
        })
# All results — success and failure — go to consolidation
```

### Manifest-Based Recovery

For long-running or interruptible orchestrations, write a manifest after each batch:

```json
{
  "task": "migration",
  "started": "2026-06-27T10:00:00Z",
  "batches": [
    {"id": 1, "status": "complete", "items": ["a", "b", "c"]},
    {"id": 2, "status": "in_progress", "items": ["d", "e"]}
  ],
  "pending": ["f", "g", "h"]
}
```

Recovery agent reads manifest → skips completed → resumes from `in_progress`.

### Idempotent Processing

Add a check-before-modify guard in every specialist prompt:

```markdown
Before modifying {target_path}:
1. Check if transformation already applied (e.g., look for marker X).
2. If already present → skip → status: "already_done"
3. If not present → proceed.
```

Safe to re-run without double-processing.

---

## Common Gotchas

| Gotcha | Symptom | Fix |
|---|---|---|
| Agent IDs not returned programmatically | Can't resume from code | Use manifest files for continuity instead of `resume` |
| Rate limits with large parallel batches | API errors mid-batch | Cap parallel agents at 5–8; batch sequentially |
| Verbose agent responses bloating main context | Main context grows despite delegation | Enforce JSON-only return; write prose to files |
| Inventory agent reads files "to check" | Inventory takes 10× longer | Explicitly prohibit file reading in inventory prompt |
| Ambiguous items silently skipped | Work lost, no trace | Require `status: "ambiguous"` + `reason` field in return schema |
| Re-running overwrites completed work | Duplicate or corrupted output | Add idempotency check (see above) |

---

## Structural Variations

### When to Use Sequential vs. Parallel Specialists

| Condition | Pattern |
|---|---|
| Items have dependencies (A must finish before B) | Sequential |
| Cost is the primary constraint | Sequential |
| Items are independent; speed matters | Parallel |
| Failures must be isolated from each other | Parallel |

### Nesting Depth

Keep agents **flat** — peers, not hierarchies. Nested agents (agent spawns agent spawns agent) compound overhead and complicate error tracing. The only valid hierarchy is: main → specialists → (optional) consolidator.

### When Not to Use Agents

- Task requires fewer than 3 tool calls → use tools directly.
- Single file read + simple edit → use tools directly.
- Items depend heavily on shared mutable state → agents are the wrong primitive.

---

**Glossary terms** are defined in the companion patterns note: [[reference/agent-orchestration-patterns]].

---

## Related

- [[reference/agent-orchestration-patterns]] — decision framework, core principles, anti-patterns table