multi-agent-patterns

Choose between three patterns: Supervisor for controlled delegation with a central orchestrator, Swarm for peer-to-peer handoffs without a single point of failure, and Hierarchical for large projects needing strategy, planning, and execution layers. Match the pattern to your coordination needs, not organizational metaphors.

Supervisor gives workflow control and easy human-in-the-loop but risks becoming a bottleneck and distorting sub-agent responses. Swarm has no single failure point and suits breadth-first exploration, but coordination complexity grows with agent count. Use forward_message to let supervisors pass responses directly.

Avoid multi-agent designs when the task fits within a single agent's context window with no parallelism benefit. A single agent with good tools outperforms a poorly coordinated multi-agent system; only scale out when context isolation or parallel execution provides measurable benefit.

Common failures include supervisor bottlenecks, coordination overhead, divergence, and error propagation. Mitigate with explicit handoff protocols, goal boundaries with convergence checks, TTL limits on agent loops, output validation, and retry logic with circuit breakers.

A single agent chat costs 1x tokens, a single agent with tools about 4x, and a multi-agent system roughly 15x. The multiplier is bounded, and quality plus parallelism gains typically exceed the cost on non-trivial tasks.

Pass bounded task instructions to sub-agents instead of full conversation history, and use the file system as shared memory to prevent context bloat. Full-context delegation is only appropriate for genuinely complex tasks where isolation matters less.