## Multi-Agent Pattern Selection Guide

### Decision flow
```
Task has parallelizable subtasks?
├─ Yes → Supervisor / Fan-out workers
└─ No → Sequential handoffs?
         ├─ Yes → Peer-to-peer / Swarm
         └─ No → Single agent + tools (KISS)
```

### Pattern fit matrix

| Pattern | Parallel | Sequential | Dynamic routing | Best for |
|---------|----------|-----------|-----------------|----------|
| Supervisor-worker | ✓ | Partial | ✓ | Decomposable tasks, specialists |
| Hierarchical | ✓ | ✓ | ✓ | Large organizations, deep trees |
| Swarm / peer-to-peer | ✗ | ✓ | ✗ | Handoff chains, known sequences |
| Blackboard | ✓ | ✓ | ✓ | Unstructured, emergent |
| Agent-as-tool | Depends | ✓ | ✗ | Explicit pipelines, graph workflows |

### Production guardrails (non-negotiable)

| Guardrail | Why |
|-----------|-----|
| Max steps per run | Prevents infinite loops |
| Max tokens per run | Controls API spend |
| Max wall-clock time | Bounding latency |
| Idempotent tool calls | Retries don't double-charge |
| Trace/replay ID | Multi-agent debugging without this is impossible |

### The "don't over-engineer" rule
Most production tasks don't need multi-agent. Justify by:
- Real role separation (different tools/knowledge per agent)
- Measurable parallelism win (not theoretical)
- An eval set that shows multi-agent beats single-agent

If a single well-designed agent + 10 tools can do the job, it will be:
- Cheaper (fewer model calls)
- Faster (less coordination overhead)
- More debuggable (fewer failure points)

### Common failure modes

| Pattern | Failure |
|---------|---------|
| Supervisor | Bottleneck for parallel work |
| Swarm | Drift into contradictory outputs |
| Any multi-agent | Runaway loops without step caps |
| Any multi-agent | Nondeterministic LLM-driven control flow |
| Any multi-agent | Agents duplicating work (overlapping roles) |