The swarm agent pattern organises multiple agents as peers that hand tasks between themselves based on which agent is best suited to handle the current step. Unlike the supervisor pattern, there is no central coordinator — each agent makes its own routing decisions, passing the task to the most appropriate next agent when the current step is outside its specialisation. The concept was formalised by OpenAI’s Swarm library (released 2024) but the underlying idea has appeared in multi-agent systems long before that. Swarm architectures are powerful for dynamic task routing but introduce complexity in coordination and failure handling that requires careful design.
How Swarm Differs from Supervisor
The key distinction between swarm and supervisor patterns is where routing intelligence lives. In a supervisor system, one central agent holds the overall task context and decides which worker handles each step. In a swarm, the routing is distributed: each agent decides, based on the current task state, whether it should handle the next step or hand off to a different agent. The agent currently holding the task has full authority to route — there is no manager to approve the handoff. This decentralisation means swarm systems scale more naturally as you add agents (new agents simply register their capabilities and become routing targets) and are more resilient to individual agent failures (if one agent is unavailable, the task routes around it). The cost is coherence: without a central view of the overall task, it is harder to maintain strategic consistency across many handoffs.
OpenAI Swarm: The Reference Implementation
OpenAI’s Swarm library (available on GitHub) provides a lightweight reference implementation of the swarm pattern. Its core abstractions are Agent (a model with instructions and a set of tools) and Handoff (a special tool that transfers control to another agent). When an agent calls a handoff tool, the current agent’s context is passed to the receiving agent, which continues the conversation from that point. The library is intentionally minimal — it is an educational reference rather than a production framework — but it clearly illustrates the routing mechanics. The key concept is that handoff decisions are made by agents based on their instructions: each agent’s instructions include a description of when to hand off to each other agent, and the model follows these instructions to make routing decisions.
When Swarm Is the Right Choice
The swarm pattern works best when three conditions hold: the system has many distinct specialisations (enough that a central supervisor would become unwieldy), the task routing is highly dynamic and content-dependent (which specialist handles the next step depends on what the previous step discovered), and the overall task has no strong sequential dependencies that require a central view to manage (the agents can each see enough context to make good local routing decisions). Classic examples: a customer service system where a general agent routes to billing, technical support, or account management based on the customer’s issue — the routing is content-driven and each specialist has clear authority in their domain. A multi-lingual support system where agents specialised in different languages hand off based on detected language. A research assistant where general research hands off to domain specialists (legal, medical, financial) when the query requires specific expertise.
Figure 1 — Swarm vs supervisor: routing intelligence location
Designing Agent Handoff Conditions
The quality of a swarm system is largely determined by how clearly each agent’s handoff conditions are specified. Each agent needs to know: under what conditions should it handle the task itself, under what conditions should it hand off, and to which agent? These conditions are typically specified in the agent’s system prompt instructions. Well-designed handoff instructions are precise and non-overlapping: “Hand off to the billing agent when the user’s question involves invoice amounts, payment methods, or subscription changes. Handle all other account questions directly.” Poorly designed handoffs — vague, overlapping, or missing conditions — cause agents to make inconsistent routing decisions, resulting in tasks that get passed to the wrong agent, tasks that loop between agents without resolution, or tasks that no agent claims.
The Handoff Loop Problem
The most common failure mode in swarm architectures is the handoff loop: agent A hands off to agent B, agent B determines it cannot handle the task and hands off back to agent A (or to agent C, which hands off back to A). This loop continues indefinitely, consuming tokens and making no progress. Prevention requires two mechanisms: explicit loop detection (track which agents have already handled a task and reject re-handoffs to the same agent within one task session) and escalation paths (when a task has been handed off more than N times without resolution, escalate to a designated fallback agent or return a graceful failure). OpenAI’s Swarm library does not implement loop detection by default — it is something production systems need to add explicitly.
Context Preservation Across Handoffs
When a task is handed off between agents, context must travel with it. The receiving agent needs to understand not just the current request but the history of what has been tried and what was discovered by previous agents. In OpenAI’s Swarm, the conversation history is automatically passed to the receiving agent, which ensures continuity. In custom implementations, context preservation needs to be explicit: attach a structured summary of prior agent actions to the handoff, so the receiving agent does not duplicate work or miss relevant context. For long task chains with many handoffs, the accumulated context can grow large — implement summarisation to compress older history while preserving the most relevant facts for the current agent.
Swarm vs Supervisor: Choosing
The practical choice between swarm and supervisor comes down to task characteristics. If the task has a clear overall strategy that benefits from a central view — complex software engineering, multi-phase research with dependent steps — the supervisor pattern’s centralised control is worth its overhead. If the task is primarily about routing requests to the right specialist with no strong strategic dependencies between steps — customer service, support routing, language-specific handling — the swarm’s distributed model is more natural and scales better. Many real systems start as supervisor architectures and adopt swarm-like elements as they grow: adding direct agent-to-agent handoffs in cases where routing through the supervisor adds unnecessary latency. The two patterns are not mutually exclusive and can coexist within the same system.
The swarm pattern is a powerful architecture for systems where routing decisions are distributed, specialisations are many, and adding new agents should not require rewriting a central coordinator. It shines in customer-facing applications where dynamic content-based routing is the primary architectural challenge. Its failure modes — handoff loops, context loss, inconsistent routing decisions — are manageable with explicit loop detection, clear handoff conditions, and careful context preservation. For teams building their first multi-agent system, starting with a supervisor pattern is usually simpler; consider migrating to swarm elements as the number of specialists grows beyond what a central supervisor can manage cleanly.
Testing Swarm Routing Logic
Swarm systems are harder to test than supervisor systems because there is no central routing function to unit-test — routing decisions are embedded in each agent’s LLM call. The practical testing approach is scenario-based: for each type of task the system handles, verify that the task reaches the correct agent through the routing chain. Create a test case for each handoff condition: inputs that should route to agent A, inputs that should route to agent B, inputs near the boundary between two agents’ scopes. Run these scenarios against the full swarm, trace the routing path, and flag cases where the task reached the wrong agent or looped. Scenario tests catch both incorrect handoff conditions (the model routes incorrectly because the instructions are ambiguous) and missing handoff conditions (a task type no agent claims). Run these tests after any change to agent instructions, since instruction changes can silently alter routing behaviour in ways that only surface in production if not caught by tests.
Observability in Swarm Systems
Observability is more important in swarm systems than in supervisor systems, because failures are harder to diagnose without a trace. When a swarm fails — the task ends without resolution, or the wrong agent handles the final step — diagnosing the root cause requires reading the full handoff sequence: which agent first received the task, what it decided, which agent it handed off to, what that agent decided, and so on. Build explicit logging into every handoff: log the outgoing agent, the incoming agent, the reason for the handoff (which condition triggered it), and the context state at the time of handoff. This trace makes it immediately clear whether a failure was caused by a wrong routing decision, a missing handoff condition, a loop, or a context loss during handoff. Without this trace, debugging swarm failures in production is extremely time-consuming.