OpenAI Swarm landed on GitHub in October 2024 as an "educational" multi-agent framework. It was small (under 1000 lines of Python), opinionated about routines and handoffs, and intentionally not a product. By early 2025 it had picked up more than 20k stars, mostly from engineers using it for real workloads despite the experimental label.
In March 2025, OpenAI shipped the Agents SDK as the production successor. The Swarm repo now redirects users there. If you wrote code against Swarm in 2024 or 2025, you have a decision to make in 2026: keep your demo working as-is, migrate to the Agents SDK, or jump to a different framework entirely.
This guide covers what Swarm did, what changed, and how to pick the right successor for your stack. For the broader landscape, see our roundup of the best AI agent frameworks.
TL;DR
- Status: Swarm is officially deprecated. The README points users to the OpenAI Agents SDK for all production use cases.
- Replacement: openai-agents-python and the TypeScript counterpart. Same handoff model, plus guardrails, tracing, and Responses API support.
- Migration cost: Low if you used Swarm's core abstractions (Agent, function tools, handoffs). Higher if you leaned on Swarm internals.
- When Swarm is still fine: internal demos, teaching material, throwaway prototypes that already work.
- When to migrate now: anything customer-facing, anything you need to debug in production, anything that needs guardrails or evals.
What Swarm actually did
Swarm modeled an agent as a Python object with three things: an instructions string, a list of callable tools, and the ability to return another Agent from a tool call. That last bit is the "handoff": instead of routing through a central planner, an agent decides on its own to pass control to a peer.
The minimal example looked like this:
from swarm import Swarm, Agent
client = Swarm()
def transfer_to_billing():
return billing_agent
triage_agent = Agent(
name="Triage",
instructions="Decide if the request is billing or technical.",
functions=[transfer_to_billing],
)
billing_agent = Agent(
name="Billing",
instructions="Handle billing questions. Be direct.",
)
response = client.run(
agent=triage_agent,
messages=[{"role": "user", "content": "My invoice looks wrong."}],
)
print(response.messages[-1]["content"])That was the whole framework, roughly. No persistent state, no streaming abstractions, no built-in tracing, no guardrails. The point was to demonstrate the routines-and-handoffs pattern, not to ship it.
Engineers liked it precisely because it was small. You could read every line in an afternoon. But "small and educational" became "small and unmaintained" pretty quickly, and OpenAI never intended it as a long-term home.
What happened in 2025: the Agents SDK
In March 2025 OpenAI released the Agents SDK as a production-grade evolution of Swarm. The mental model is the same: agents have instructions, tools, and can hand off to peers. What's new:
- Built-in tracing. Every run produces a structured trace you can inspect in the OpenAI dashboard or export via OpenTelemetry. This was the biggest gap in Swarm: when your agent did something weird, you had no way to see why.
- Guardrails. Pre- and post-tool callbacks for input validation, output checking, content filtering, cost ceilings. You can implement these as plain Python callables.
- Responses API native. The SDK targets the Responses API by default, which means built-in support for file search, web search, computer use, and code interpreter as first-class tools.
- TypeScript parity. OpenAI shipped
@openai/agentsalongside the Python SDK. Same primitives, same handoff model. - Active maintenance. This is the big one. Issues get triaged, releases ship monthly, and the SDK tracks new model capabilities (GPT-5.5 reasoning controls, structured outputs, parallel tool calls).
The migration path is direct. Pseudocode for the same triage example on the Agents SDK:
from agents import Agent, Runner
billing_agent = Agent(
name="Billing",
instructions="Handle billing questions. Be direct.",
)
triage_agent = Agent(
name="Triage",
instructions="Route to the right specialist.",
handoffs=[billing_agent],
)
result = await Runner.run(
triage_agent,
input="My invoice looks wrong.",
)
print(result.final_output)The shape is recognizable. Handoffs moved from a function-return convention to an explicit handoffs parameter. The runner is async-first. Everything else maps one-to-one.
When Swarm is still fine to use
Three cases where leaving Swarm running makes sense:
- Internal demos that already work. If you built a workshop or teaching artifact on Swarm in 2024 and it still runs, there's no urgency. The repo will keep installing.
- Pinned Python environments. Swarm's last release works against the OpenAI Python SDK from 2024. If you've pinned versions and don't need new model support, you can stay there.
- Reading the source to learn agents. Swarm is genuinely the best 500-line introduction to multi-agent orchestration that exists. Clone it, read it, then build on something else.
For literally any other case (production, customer-facing, anything you'd debug with a trace), migrate.
When to migrate to the Agents SDK
Migrate now if any of these apply:
- You need tracing into production agent runs. Swarm has none built in.
- You want to use GPT-5.5 or newer model capabilities (reasoning effort controls, Responses API tools).
- You need guardrails: cost limits, content filters, schema validation on tool inputs.
- You want TypeScript on the same primitives, not a separate framework.
- You care about long-term support. Swarm is frozen; the Agents SDK is on a monthly cadence.
The migration itself is mostly mechanical:
| Swarm | Agents SDK |
|---|---|
Agent(name, instructions, functions=[...]) | Agent(name, instructions, tools=[...]) |
Return Agent from a function | handoffs=[other_agent] parameter |
client.run(agent, messages) | Runner.run(agent, input) |
| Manual print debugging | Built-in tracing dashboard + OTel export |
| No guardrails | input_guardrails, output_guardrails |
Most apps can migrate in a few hours. The handoff semantics are identical, which is the part that takes the longest to reason about.
Swarm vs LangGraph vs CrewAI vs Claude Agent SDK
Picking a successor isn't automatic. The Agents SDK is the obvious choice for OpenAI-centric stacks, but the broader market has four serious contenders in 2026:
OpenAI Agents SDK
Best for: teams already on OpenAI / Azure OpenAI, want the cleanest handoff model, want native Responses API tools (file search, web search, computer use).
Watch out for: OpenAI-flavored opinions. You can use other providers through LiteLLM, but the SDK is shaped around the Responses API.
LangGraph
Best for: complex stateful workflows, graphs with cycles, human-in-the-loop checkpoints, anything where "agent" is the wrong abstraction and "stateful workflow with LLM nodes" is closer.
Watch out for: heavier conceptual load. You're modeling a state graph, not a conversation. For simple handoffs, this is overkill. See our LangChain vs LangGraph breakdown.
CrewAI
Best for: role-based multi-agent systems where you want to declaratively describe "a researcher, a writer, an editor" and let the framework orchestrate. Heavy in agentic content workflows.
Watch out for: lower control over execution flow. Great for crews of agents working a brief; awkward when you need precise routing logic.
Claude Agent SDK
Best for: teams centered on Claude (Anthropic). Tighter coupling to Claude's tool-use, computer-use, and extended-thinking features. Strong for coding agents specifically.
Watch out for: less abstraction over multi-provider use. If you need to swap between Claude and GPT for the same agent, you're not getting that for free.
What about tracing across all of these?
Whichever framework you land on, the operational story is the same: you need traces, evals, and a gateway in front of provider APIs. Frameworks compete on developer ergonomics; observability platforms cover the production surface area.
Respan instruments all four frameworks above through OpenTelemetry. Your Agents SDK trace, your LangGraph run, your CrewAI crew, and your Claude Agent SDK execution all land in the same trace viewer with the same span model. That makes the framework choice less load-bearing than it looks: you can migrate later without losing observability continuity. See LLM tracing for the deeper treatment.
A practical migration recipe
If you're sitting on a Swarm app in production right now, here's the order of operations:
- Inventory your agents. List every
Agent(...)definition and every function that returns another agent. - Pin a working baseline. Tag your current Swarm commit. Snapshot test the behavior on a representative set of inputs.
- Set up tracing first. Before changing any code, instrument your existing Swarm runs with OpenTelemetry (Respan, Braintrust, or vendor of choice). Get a baseline trace.
- Migrate one agent at a time. Convert your simplest agent first. Run the snapshot tests. Compare new traces against the baseline.
- Convert handoffs last. The handoff semantics are the part most likely to subtly drift. Test multi-agent flows end-to-end with eval prompts.
- Add guardrails. This is the upgrade you couldn't do in Swarm. Start with a cost ceiling and an input schema check on user-facing agents.
Most teams ship the migration in under a week.
FAQ
Is OpenAI Swarm officially deprecated? Yes. The Swarm README explicitly recommends migrating to the OpenAI Agents SDK for production use. Swarm remains available as an educational reference but does not receive active maintenance.
Will my existing Swarm code keep running? Yes, for now. The package is on PyPI and the OpenAI Python SDK still accepts the calls Swarm makes. There's no hard cutoff, but new model features won't appear in Swarm.
Is the Agents SDK a drop-in replacement? Conceptually, yes. Mechanically, no. The class names, method signatures, and handoff API are different. The migration is a few hours of focused work, not a rewrite.
Can I use the Agents SDK with non-OpenAI models? Yes, via LiteLLM or a gateway like Respan that exposes an OpenAI-compatible interface. You won't get Responses API tools (web search, file search, computer use) on non-OpenAI providers, but the agent loop works.
Should I skip the Agents SDK and go straight to LangGraph? Only if your workload is genuinely a stateful graph, not a conversation with handoffs. For most teams the Agents SDK is the smaller cognitive load and the closer match to what Swarm code already expresses.
Does the Agents SDK have built-in tracing? Yes. Runs produce structured traces visible in the OpenAI dashboard, and you can export to any OpenTelemetry-compatible backend including Respan.
What about TypeScript / Node?
@openai/agents is the TypeScript port. Same primitives. If you're on a JS stack, this is the cleanest path off Swarm.