What is OpenAI Swarm?
OpenAI Swarm is an experimental, open-source multi-agent framework released by OpenAI in late 2024. It is deliberately minimal — the entire framework is a single Python file — and exists primarily as an educational reference for building multi-agent systems using patterns that OpenAI considers important: agents that can hand off control to each other.
OpenAI explicitly describes Swarm as "educational" and not production-ready. However, its concepts — agents, tools, and handoffs — directly informed OpenAI's production Agents SDK released in early 2025. Understanding Swarm means understanding the mental model behind OpenAI's approach to agents.
Key features of OpenAI Swarm
Agents
Each agent has a name, system instructions, and a list of tools it can call. Agents are plain Python objects — no subclassing, no decorators, just configuration.
Handoffs
An agent can hand off the conversation to another agent by returning it as a tool result. Instead of a central router deciding who handles what, agents themselves decide when to pass control — keeping routing logic distributed and easy to reason about.
Context variables
A shared context dictionary persists across agent handoffs — agents can read and write shared state (user ID, order number, session data) without passing it through the conversation.
Stateless client loop
Swarm's client runs a simple loop: call the model, execute tools (or handoffs), repeat. There is no hidden state in the framework itself — what you see is what runs.
Native OpenAI function calling
Swarm uses OpenAI's standard function-calling API under the hood — tools are just Python functions with docstrings. No new abstractions to learn if you already know the OpenAI SDK.
Extremely readable codebase
The entire framework is about 300 lines of Python. Reading it is the best way to understand how a production-grade agent orchestration loop actually works internally.
How OpenAI Swarm works
A basic Swarm system looks like this:
from swarm import Swarm, Agent
client = Swarm()
def transfer_to_billing():
return billing_agent
triage = Agent(name="Triage", instructions="Route to billing or support.", tools=[transfer_to_billing])
billing_agent = Agent(name="Billing", instructions="Handle billing questions.")
response = client.run(agent=triage, messages=[{"role": "user", "content": "I have a billing issue"}])
print(response.messages[-1]["content"])The triage agent calls transfer_to_billing, which returns the billing agent object — Swarm recognises this as a handoff and continues the conversation with the billing agent.
Real-life use cases of OpenAI Swarm
Customer support routing
A triage agent classifies the issue and hands off to specialist agents for billing, technical, or account issues.
Sales pipelines
Qualify leads with a front-end agent, hand qualified prospects to a demo-booking agent, and pass closed deals to an onboarding agent.
Learning multi-agent architecture
Read and run the Swarm examples to understand agent orchestration before adopting a more complex framework.
Pros and cons of OpenAI Swarm
Pros
- + Extremely minimal — the whole thing is ~300 lines
- + Handoff pattern is elegant and easy to reason about
- + Great for learning multi-agent patterns
- + No new abstractions beyond standard OpenAI API
- + Free and open-source
Cons
- − Explicitly marked "experimental" by OpenAI — not production-supported
- − OpenAI-only (uses OpenAI's function calling API)
- − No built-in memory, observability, or persistence
- − Superseded by OpenAI's Agents SDK for production use
OpenAI Swarm pricing
| Component | Cost | Details |
|---|---|---|
| Framework | Free | Open-source, install with pip install git+https://github.com/openai/swarm |
| API usage | OpenAI rates | Standard OpenAI API token rates for each model call made by your agents |
Alternatives to OpenAI Swarm
- OpenAI Agents SDK — OpenAI's production-ready successor to Swarm concepts
- LangGraph — graph-based agent orchestration with cycles and persistence
- CrewAI — role-based multi-agent framework with structured task assignment
- Phidata / Agno — clean Python agents with memory and tool libraries
Tips for using OpenAI Swarm
No longer maintained — superseded by the OpenAI Agents SDK
OpenAI released the production Agents SDK in early 2025 as the official successor to Swarm. Swarm receives no bug fixes, security updates, or new features. Use it only as a learning reference.
Tool function docstrings and type annotations are required
Swarm parses tool functions using Python's inspect module. Parameter names and docstrings become the tool description sent to the model. Always annotate parameter types and write specific, descriptive docstrings.
Context variables must be JSON-serializable
Context variables passed between agents must be JSON-serializable — strings, numbers, lists, and dicts. Passing complex Python objects will cause silent serialization errors or unexpected type coercion.
Read the source code — the whole framework is ~300 lines
Reading Swarm is the fastest way to understand what every agent framework is abstracting over: the loop of calling the model, handling tool calls, executing handoffs, and returning control to the caller.
Key ideas Swarm teaches you
Agents are just instructions + tools: the system prompt and the function list define an agent's entire personality and capability
Handoffs are just tool calls: routing between agents is not magic — it is a function that returns another agent
Context is shared state: rather than stuffing everything into the conversation, use context variables for structured data
Loops are simple: call model → run tools → call model again — that is the entire agent loop
Who should use OpenAI Swarm?
- • Developers learning multi-agent architecture patterns for the first time
- • Engineers who want to understand what happens inside agent frameworks before adopting one
- • Teams prototyping agent-handoff patterns before moving to a production framework
Swarm's real value is conceptual — read it before adopting any agent framework and you will understand what every other framework is abstracting over. Then build production systems with Phidata or Dify for visual LLM app building.