226 lines
6.4 KiB
Markdown
226 lines
6.4 KiB
Markdown
---
|
||
type: reference
|
||
subtype: cookbook
|
||
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
|
||
scope: global
|
||
last_updated: 2026-06-27
|
||
related:
|
||
- reference/agent-orchestration-patterns
|
||
---
|
||
|
||
# Agent Orchestration Cookbook
|
||
|
||
**Purpose**: Concrete examples, prompt templates, and gotchas for implementing the patterns in [[reference/agent-orchestration-patterns]].
|
||
|
||
## 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
|
||
|
||
| Term | Definition |
|
||
|---|---|
|
||
| Tool Tax | Fixed ~20–25K token overhead per agent before any work is done |
|
||
| Specialist | An agent that processes multiple similar items, paying tool tax once |
|
||
| Batch | Group of agents spawned in parallel (5–8 max to respect rate limits) |
|
||
| Manifest | JSON file tracking completed/pending/failed items for recovery |
|
||
| Flattened | Orchestration where agents are peers at one level, not nested |
|
||
| Idempotent | Safe to re-run — check-before-modify prevents double-processing |
|
||
|
||
---
|
||
|
||
## Related
|
||
|
||
- [[reference/agent-orchestration-patterns]] — decision framework, core principles, anti-patterns table
|