multi-agent-patterns

Choose a supervisor when tasks have clear decomposition and human oversight matters; choose a swarm when requirements emerge dynamically and rigid planning is counterproductive. Supervisors centralize control but risk bottlenecks, while swarms eliminate single points of failure at the cost of harder convergence.

Implement handoffs by having agent nodes return a next_agent field in the graph state and wiring edges between agent nodes in a StateGraph. The references file shows a full swarm example with triage, research, analysis, and writing agents transferring control through explicit handoff edges.

Use multiple agents when a single context window cannot hold all task-relevant information, when subtasks run in parallel, or when subtasks need different tools and system prompts. If a single agent with a longer context suffices, multi-agent coordination overhead is not justified.

Multi-agent runs cost roughly 15x a single-agent baseline because of coordination messages, retries, and consensus rounds on top of per-agent work. Budget for this multiplier and measure against a single-agent baseline before assuming extra agents help.

Validate each agent's output before passing it downstream, add retry logic with circuit breakers, and consider a verification agent for critical outputs. The included AgentFailureHandler class implements exponential backoff retries and automatic rerouting after repeated failures.

Simple majority voting treats hallucinations from weak agents as equal to strong reasoning and encourages sycophantic agreement. Use confidence-weighted voting or structured debate protocols with explicit adversarial roles instead.