On 10 October 2024, OpenAI published a GitHub repository called Swarm with an unusual warning in large letters: do not use in production. That phrase, repeated in the README and in the examples, is not polite humility: it is a statement of intent. Swarm does not aim to compete with CrewAI, LangGraph, or its own Assistants API. It is an open laboratory where the OpenAI team shows, in fewer than five hundred lines of Python, how they themselves think about agent coordination.

Key takeaways

  • Swarm reduces the multi-agent vocabulary to two concepts: agents and handoffs.

  • Routing emerges from the model, not from an explicit graph or centralised planner.

  • Its fewer than 500 lines of Python make the design fully readable and the code adaptable.

  • It is not a production solution: it lacks persistent state, retries, observability, and robust error handling.

  • The philosophical bet is that coordination does not need heavy infrastructure if the models are capable enough.

Why an experimental framework, and why now

Multi-agent frameworks have been accumulating abstractions for over a year. CrewAI talks about crews, tasks, and processes. LangGraph models state machines with explicit nodes, edges, and checkpointers. Each layer solves real problems but also imposes an ontology the developer must learn before writing the first useful line.

Swarm responds in the opposite direction: reduce the vocabulary to two ideas and see how far that gets you.

The two ideas are agents and handoffs. An agent is a configuration with instructions and functions. A handoff is a function that returns another agent. When the model decides to call that function, control passes to the returned agent and the next conversation round occurs under its instructions.

No explicit graph, no state machine, no planner. Routing emerges from the fact that models, given well-named functions, know when to call them.

This is a philosophical bet: coordination between agents does not need heavy infrastructure if the underlying models are capable enough. With GPT-4o as the engine, OpenAI is saying it prefers trusting model reasoning over framework scaffolding.

Swarm’s structure

Swarm’s core code fits in a single file. The client manages the conversation loop: sends the message to the model, receives the response, executes tool calls, and repeats. The only addition over the standard chat API is the Agent Python object and the handoff logic:

from swarm import Swarm, Agent

client = Swarm()

support = Agent(
    name="Support",
    instructions="Resolve technical problems. If the issue is about billing, transfer to Billing.",
)

billing = Agent(
    name="Billing",
    instructions="Handle questions about invoices and payments.",
)

def transfer_to_billing():
    return billing

support.functions = [transfer_to_billing]

response = client.run(
    agent=support,
    messages=[{"role": "user", "content": "I have an incorrect charge"}],
)

When the support model decides to transfer, it calls transfer_to_billing(), Swarm receives the returned agent, and continues the conversation under billing‘s instructions. That is the entire framework.

Differences from CrewAI and LangGraph

The three approaches reflect different philosophies about where coordination intelligence should live.

CrewAI externalises coordination into a Manager Agent that distributes tasks. This is the model closest to a traditional organisational hierarchy: useful when roles are stable and tasks well-defined, but adds an extra LLM call layer for every routing decision.

LangGraph models flow as a directed graph with explicit nodes and edges. The advantage is predictability and visual debugging of the flow; the disadvantage is that you must design the graph upfront, which is not always possible for dynamic flows.

Swarm eliminates both layers and trusts that the base model, with clear instructions and well-named functions, will make routing decisions at each turn. It is more fragile (a less capable model may make incorrect handoff decisions), but also more transparent and easier to reason about.

The OpenAI Assistants API already covers production cases with persistent state and managed threads. Swarm exists in the conceptual space, not to replace it.

Patterns emerging from Swarm

Although Swarm is experimental, its examples show three patterns:

  • Triage agent: an initial agent that analyses the request and transfers to the right specialist. The simplest pattern and the one that works best with less powerful models.

  • Escalation chain: agents in a chain where each can escalate to the next when the issue exceeds its competence, similar to a support ticket system.

  • Simulated parallel agents: one agent per aspect of the request and a synthesiser agent combining the responses.

The limit of all these patterns is the same: without persistent state between sessions, without automatic retries, without integrated observability, they are proof-of-concept demonstrations, not production systems. For production multi-agent systems with trace observability, the Assistants API or mature frameworks like LangGraph are the appropriate choice.

Real value of Swarm

Swarm’s real value is not the framework itself: it is the code. Reading the five hundred lines of implementation is one of the best ways to understand what an agent framework actually does under its abstractions: manage message history, execute tool calls, handle the conversation loop. Once you read the code, the "mystery" of how more complex frameworks work reduces considerably.

It also opens a conversation about whether current framework complexity is justified. For many use cases, Swarm’s answer: "trust the model and give it good functions". For others, the persistent state, retries, and observability of LangGraph or CrewAI are not optional. Swarm’s merit is forcing that conversation with code rather than arguments.

Conclusion

Swarm is an executable paper, not a production framework. Its most valuable contribution is demonstrating that coordination between agents can be surprisingly simple when the base model is capable. Most of the complexity in current frameworks exists either to compensate for model fragility or to add features Swarm deliberately omits. For teams that want to understand how multi-agent systems work before adopting a framework, reading Swarm’s code is the best starting point.

Frequently asked questions

Can I use OpenAI's Swarm in production?

No, and the repository itself says so in large letters, repeated in the README and the examples. Swarm lacks persistent state between sessions, automatic retries, integrated observability and robust error handling, so its patterns are proof-of-concept demonstrations. For production multi-agent systems with trace observability, OpenAI's Assistants API, which already offers persistent state and managed threads, or mature frameworks like LangGraph are the appropriate choice.

How does a handoff work in Swarm, and how does it differ from LangGraph or CrewAI?

A handoff is a Python function that returns another Agent object; when the model decides to call it, control passes to the returned agent and the next conversation round runs under its instructions. There is no explicit graph, state machine or planner: routing emerges from the model. LangGraph instead requires designing a directed graph with nodes and edges upfront, and CrewAI externalises coordination into a Manager Agent that adds an extra LLM call for every routing decision.

What do I gain from reading Swarm's code if I am not going to use it?

An understanding of what an agent framework actually does beneath its abstractions. The core code fits in a single file, fewer than five hundred lines of Python: it manages message history, executes tool calls and repeats the conversation loop. Once you read it, more complex frameworks stop looking opaque. Much of their complexity exists to compensate for model fragility, or to add the state, retries and observability Swarm deliberately omits.