OpenAI Swarm

What Swarm Was#

Swarm was published by OpenAI's Solutions team in October 2024 as an educational repository. The README was explicit: not for production, not for backwards compatibility, here to teach two patterns — routines (an agent following a procedure step by step) and handoffs (one agent transferring control to another).

Despite the disclaimer it became widely cited because the codebase was small enough to read in an afternoon and showed something most frameworks obscured: how to build multi-agent systems without a centralised orchestrator. The handoff pattern, where Agent A calls a tool that returns Agent B, made the control flow legible at the message level.

The Handoff Pattern#

In Swarm, a handoff is just a tool whose return value is another `Agent`. When the model calls that tool, the Swarm runtime swaps the active agent for the one returned and continues the conversation under the new agent's instructions and tool set. The message history is preserved, so context flows naturally; the system prompt and available tools change.

This made common customer-service patterns trivial to express: a triage agent inspects the user query and hands off to a billing, technical, or sales agent. Each downstream agent can itself hand back to triage or to another specialist. The runtime is a few hundred lines of Python.

from swarm import Agent

def transfer_to_billing():
    return billing_agent

triage = Agent(
    name="Triage",
    instructions="Decide if the user needs billing or technical help.",
    functions=[transfer_to_billing, transfer_to_technical],
)

billing_agent = Agent(
    name="Billing",
    instructions="Handle invoicing and refund queries.",
)

Why It Was Deprecated#

Swarm shipped without three things production systems need: tracing, guardrails, and async execution. OpenAI replaced it in late 2024 with the OpenAI Agents SDK, which keeps the handoff and routine model but adds first-class tracing (visible in the OpenAI dashboard), input/output guardrails, structured outputs via Pydantic, full async support, and a richer set of tool types including computer-use tools.

The Agents SDK is now the recommended production path inside OpenAI's ecosystem. Swarm's repository remains available for educational purposes and continues to be a useful reference, but new projects should start with the Agents SDK.

Lessons That Persisted#

• Handoffs as tool calls — a clean way to model multi-agent control flow without a separate orchestration layer, now copied by CrewAI's Swarm pattern and AutoGen's selector mode.
• Routines as instructions — a procedural prompt that the agent reads as steps to follow, useful for compliance-style workflows where deviation from the script is unacceptable.
• Minimal runtime — Swarm demonstrated that a usable agent framework fits in a few hundred lines, a useful counterweight to the sprawl of larger frameworks.

Status in 2026#

Swarm is read, not run. If you are designing a multi-agent system on OpenAI models, use the Agents SDK. If you are designing one provider-neutrally, use LangGraph, AutoGen, or CrewAI. If you are studying agent design patterns, Swarm remains one of the clearest worked examples available.