Why OpenAI replaced the experimental Swarm with the Agents SDK in 2025

OpenAI shipped Swarm in late 2024 as an experimental sample. It was deliberately tiny: an `Agent` was a system prompt plus tools plus a list of handoff targets, and the runtime was a small loop that translated a `transfer_to_x` tool call into a swap of the active agent. The pattern was elegant, the API was minimal, and the community immediately started building on it. The Agents SDK shipped in 2025 as the production successor. What survived is the core idea: handoff is a tool call, agents are peers with no central manager, and the API is still small enough to learn in an afternoon. The pattern proved out and they did not change it. What got fixed is everything Swarm deliberately omitted because it was sample code. Swarm had no first-class guardrails (input filtering and output validation were left to the user). It had no tracing surface (debugging was print statements and grep). Its handoff payloads were plain strings (no typed schemas, no validation). Streaming was barely supported. Evals had no framework support. The Agents SDK adds all of those. Guardrails are a first-class primitive that runs before and after agent calls. Tracing produces a structured event stream that integrates with observability tools. Handoff payloads can be typed with Pydantic schemas. Streaming works end to end. Evals have official harness support. The meta-lesson: 'sample code' and 'production framework' are different artefacts. Swarm proved the pattern; the Agents SDK is the productionisation. Both shipping was the right move; mixing them up would have meant either too-fragile production code or too-bloated sample code.

**The pattern survived; the production primitives were added.** OpenAI kept the four things Swarm got right and fixed the five things it deliberately left out. ### What survived The core pattern is unchanged. An `Agent` is a system prompt, a tool list, and a set of handoff targets. Handoff is a tool call (`transfer_to_research_agent`), the runtime intercepts it, swaps the active agent, and continues the loop. No central manager, no orchestrator role, peer agents that can directly hand off to each other. The API surface is still small enough to learn quickly. The proof of concept worked and the productionisation did not rewrite it. ### What got fixed Five primitives that Swarm omitted because it was sample code. **Guardrails.** First-class input filtering (before the agent runs) and output validation (after the agent returns). Swarm left this to the user, which meant every production deployment rolled its own. **Tracing.** Structured event stream for every agent call, every tool invocation, every handoff. Integrates with observability tools out of the box. Swarm had print statements. **Typed handoff payloads.** Pydantic schemas for the data passed at handoff time, with validation. Swarm passed plain strings. **Streaming.** Token-level streaming end to end, including across handoffs. Swarm had partial support that was not production-grade. **Evals.** Official harness for running eval sets against agents, including multi-agent trajectories. Swarm had no answer here. The Agents SDK also adds provider-agnostic adapters so the same agent code runs on OpenAI, Anthropic, and other supported backends. This is the lock-in mitigation that makes the SDK adoptable by teams that do not want to bet exclusively on OpenAI models. The broader lesson: 'sample code' and 'production framework' have different jobs. Swarm proved the pattern was worth productionising; the Agents SDK is the productionisation.