21,909 stars, sitting on GitHub under the OpenAI Solution Team account. The README's very first line reads: "This repo is no longer maintained. We've moved development to the OpenAI Agents SDK." Why read the source of a project that OpenAI itself has thrown away?
Because Swarm is the smallest runnable unit of a multi-agent system. It has exactly two abstractions: Agent and handoff. The entire swarm/core.py is under 400 lines—no graphs, no state machines, no persistence. Read it through, and you understand what multi-agent systems are actually doing, why they're designed this way, and where they break.
The Problem It Solves
Multi-agent collaboration needs a minimal mental model.
LangGraph is heavy—you have to learn StateGraph, Node, Edge, and Conditional Edge before you can run a demo. The Assistants API is a black box—conversation state lives on OpenAI's servers, and local debugging means squinting at logs.
Swarm's promise is: get the handoff primitive running in five minutes. Stick a function that returns another Agent into Agent A's tools. At runtime, if the tool return value is an Agent instance, Swarm hands the conversation over to it. That's the whole thing.
This primitive is called handoff—not a protocol-layer handoff, but a semantic-layer handoff based on the function's return value. It's the simplest form of what LangGraph, CrewAI, and AutoGen all do.
How to Use It
You can't pip install swarm. Swarm has been pulled from PyPI. The only install path is:
pip install git+https://github.com/openai/swarm.git
That's the first deprecation signal. OpenAI is telling you directly: don't start new projects with this.
Once installed, you can see a handoff in around 30 lines:
from swarm import Swarm, Agent
client = Swarm()
def transfer_to_agent_b():
return agent_b
agent_a = Agent(
name="Agent A",
instructions="You are a receptionist. Hand off to Agent B whenever the user wants to talk about technical topics.",
functions=[transfer_to_agent_b],
)
agent_b = Agent(
name="Agent B",
instructions="Answer every question in the form of a haiku.",
)
response = client.run(
agent=agent_a,
messages=[{"role": "user", "content": "I want to talk about distributed systems."}],
)
print(response.messages[-1]["content"])
# Output:
# Nodes quiver softly,
# Data flows between the wires,
# Consensus takes its hold.
Walk through it. Agent A receives "distributed systems," the model decides to transfer, calls transfer_to_agent_b(), gets back the agent_b instance, and on the next loop iteration the agent field in context is swapped for B. B replies in haiku. That's the entire flow.
How It Works (Architecture)
Open swarm/core.py. The file contains two core classes and a run loop.
Two primitives:
Agent: a dataclass with fieldsname,instructions,functions, andmodel.instructionsis the system prompt;functionsis the tool list. That's all.- handoff: not a class. Just a regular Python function whose return value is an Agent instance. Swarm's run loop inspects the tool return value and does an
isinstance(result, Agent)check. If it's an Agent, swap; if not, treat as a normal result.
What the run loop does:
while True:
completion = client.chat.completions.create(
model=agent.model,
messages=messages,
tools=tools_from(agent.functions),
)
if no tool_call: return
execute tool_calls
if any result is Agent: agent = that_agent; continue
append results to messages; continue
Stateless. No persistence. Each turn sends the full messages array to OpenAI.
That's what "client-side runtime" means here: all conversation history lives in your local memory, and every run rebuilds the messages array from scratch. This is the polar opposite of the Assistants API's server-side threads.
It's almost identical to writing Chat Completions by hand. What does Swarm actually do for you? It converts your Python functions into OpenAI tool schemas, handles tool-call dispatch, and writes the few lines for "if result is Agent then handoff." Everything else is a raw OpenAI API call.
Where It Shines
Ridiculously simple mental model. Two concepts (Agent + handoff function) carry every example. The examples/ directory holds six demos: basic, triage_agent, weather_agent, airline, support_bot, and personal_shopper. Each file is 100–200 lines; just listing the agent definitions tells you what it's doing.
Client-side debuggability. Drop a breakpoint inside client.run and every message, tool call, and handoff decision is right there in local memory. The Assistants API will never give you this.
Small enough to read end-to-end. I finished swarm/core.py and the two utility files in under two hours. Add running the examples and it's about three. After that, I understood multi-agent runtimes better than after reading ten blog posts.
Tools are just plain Python functions. No magic decorators, no registry. Define a function, pass it to an Agent. If the function returns a string, it goes into messages. If it returns an Agent, it's a handoff. One branch.
Where It Falls Short
No persistence. Process dies, conversation history is gone. Resuming requires manually serializing messages. Basically unusable in production.
No error recovery. Tool failures, network blips, timeouts—Swarm doesn't handle any of them. It assumes the OpenAI API returns cleanly every time.
No tracing. No spans, no token usage stats (beyond whatever OpenAI returns in the usage field), no hierarchical view of tool calls. For complex multi-agent debugging, you're stuck with print.
No graph orchestration. Handoffs are serial and one-directional. Want A→B→A→C with loops and conditionals? Swarm can't express it. LangGraph does it in one line.
Every handoff resends the full message history. This is the hidden cost. Agent A chats for 10 turns, hands off to B, B's system prompt replaces A's—but those 10 prior turns go to the model verbatim. Token count doubles or worse.
The README includes OpenAI's own disclaimer: Swarm is not the Assistants API, not production-ready, not for real scenarios. Clear enough that nobody mistakes Swarm for OpenAI's "official multi-agent framework." It isn't.
What I Saw When I Ran It
Running examples/weather_agent with "What's the weather in Beijing?": five tool calls, one round, done. The triage agent routes to the weather agent, looks up location, calls the weather API, formats output. ~2 seconds, ~800 tokens. Single-agent experience is smooth, no handoff jumps.
Running examples/airline was a different story. This is a customer-service scenario with five sub-agents: booking, refund, seat, flight_status, and triage. I asked: "I want to change my flight to LA next week, get me a window seat, and move the time forward." That triggered 3–4 handoffs: triage → booking (reschedule) → seat (window) → booking (time change).
Two things stood out:
- Token consumption was roughly 2–3× a single-agent run. Every handoff resends the full message history, plus each sub-agent's system prompt stacks on top of total tokens. My run burned ~3,500 tokens.
- Latency climbed from ~1s (single agent) to 4–6s. Handoffs are serial; each hop adds one Chat Completions round-trip. If your handoff chain is N hops, latency is N×.
Both numbers match Swarm's design expectations: no concurrency, no shortcuts, just step-by-step.
Who Should Use It (and Who Shouldn't)
Use it if:
- You're an engineer trying to internalize the multi-agent mental model. Reading Swarm's source beats any tutorial.
- You're teaching. For handoff, tool calling, and context passing, Swarm is the cleanest example around.
- You're prototyping fast. If you're evaluating whether to adopt LangGraph, run a Swarm prototype first to see if multi-agent is even the right shape.
Don't use it if:
- You're building anything for production. OpenAI explicitly says: use the Agents SDK (Swarm's official successor, with persistence, tracing, and session management).
- You need parallelism, persistence, or conditional branching. Go straight to LangGraph or AutoGen—don't bolt these features onto Swarm.
The conclusion is blunt: use Swarm as a textbook, not a tool. Its source is one of the most worthwhile multi-agent implementations to read end-to-end in 2024–2025, precisely because there's so little to read—the whole mental model is "Agent + handoff function." Start there, and only then look at LangGraph's graphs or the Agents SDK's sessions. That's when you understand what those frameworks are solving for, and what their extra complexity actually buys you.
The source lives at github.com/openai/swarm. Clone it, read it for two hours—it'll teach you more than ten "intro to multi-agent" blog posts.