6.3 KiB

Raw Permalink Blame History

type

subtype

title

summary

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

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

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

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)

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:

{
  "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:

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.

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

6.3 KiB Raw Permalink Blame History Unescape Escape