Why OpenAI replaced the experimental Swarm with the Agents SDK

Flashcard·Easy·4.0 · 0·~30s·Asked atInfosys Tcs

Attempt it

They kept the core idea: handoff as a tool call, peer agents with no central manager, a tiny API. That model proved out in Swarm and the community workflows built on it.

They fixed the missing production primitives. Swarm had no first-class guardrails (input or output checks were ad-hoc), no tracing surface, no structured handoff payloads with typed schemas, no streaming support worth shipping, and no clear answer for evals. The Agents SDK adds all of those plus official LLM-provider-agnostic adapters, so the same agent code runs on OpenAI, Anthropic, or other supported backends. 'Sample code' and 'production framework' are different artefacts; Swarm proved the pattern and the Agents SDK is the productionisation.

Your answer

OpenAI shipped Swarm in late 2024 as an experimental sample. It was deliberately tiny: an `Agent` was a system prompt, tools and a list of handoff targets. A small loop turned a `transfer_to_x` tool call into a swap of the active agent. The Agents SDK shipped in 2025 as the production successor. The core idea survived: handoff is a tool call, agents are peers with no central manager, and the API is still small enough to learn in an afternoon. What got fixed is everything Swarm omitted because it was sample code. Swarm had no first-class guardrails (they were left to the user) and no tracing surface (debugging was print statements and grep). It had no typed handoff schemas: handoffs returned an Agent from a function with untyped context variables. Streaming was barely supported, and evals had no framework support. The Agents SDK adds all of those. Guardrails check agent input and output. Tracing produces a structured event stream for observability tools. Handoff payloads can be typed with Pydantic schemas. Streaming works end to end. Traces feed OpenAI's evaluation tools. 'Sample code' and 'production framework' are different artefacts. Swarm proved the pattern; the Agents SDK is the productionisation.

**The pattern survived; the production primitives were added.** OpenAI kept the four things Swarm got right and fixed the five things it left out. ### What survived 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: peer agents hand off directly. The API surface is still small enough to learn quickly. ### What got fixed Five primitives that Swarm omitted because it was sample code. **Guardrails.** First-class input checks (in parallel with the agent by default, or before it in blocking mode) and output validation (after the agent returns). Swarm left this to the user. **Tracing.** Structured event stream for every agent call, tool invocation and handoff. Integrates with observability tools out of the box. Swarm had print statements. **Typed handoff payloads.** Pydantic schemas, with validation, for handoff data. Swarm handed off by returning an Agent from a function, with untyped context variables. **Streaming.** Token-level streaming end to end, including across handoffs. Swarm's support was partial. **Evals.** Traces feed OpenAI's evaluation tools, so multi-agent trajectories can be graded. 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 lowers lock-in to OpenAI models. 'Sample code' and 'production framework' have different jobs. Swarm proved the pattern was worth productionising; the Agents SDK is the productionisation.

TL;DR

The Agents SDK keeps Swarm's handoff as tool call pattern and small API, and adds the production primitives Swarm omitted: guardrails, tracing, typed payloads, streaming, evals, and provider-agnostic adapters.

Memory aid

Easy to grasp

Imagine a chef shares a viral recipe card that shows a brilliant new way to braise lamb. Cooks everywhere try it and love the technique. But the recipe card has no notes about how long it lasts in the fridge, how to scale it for fifty guests, or what to do if the lamb is too tough. A few months later the chef publishes a proper cookbook with the same recipe plus all the production details: storage, scaling, troubleshooting, substitutions. The technique is identical; the cookbook just adds everything you need to actually run a kitchen on it. Swarm was the recipe card; the Agents SDK is the cookbook.

Key concepts

Multi-agent systems Agents LLM frameworks

Concept explanation~2 min read

Everything you need to truly understand this topic: intuition, mechanics, step by step explanation, code, formulas, and worked example. Click to expand.

When OpenAI released Swarm in October 2024, the README opened with a deliberate disclaimer: 'an educational framework exploring ergonomic, lightweight multi-agent orchestration.' That was not modesty. It was a central design choice that shaped what Swarm did and did not include. About five months later, in March 2025, the production successor (the Agents SDK) shipped. The difference between the two artefacts is the cleanest available case study of how a framework matures from prototype to production.

What survived from Swarm

Four things from Swarm carried forward into the Agents SDK essentially unchanged.

Handoff as a tool call

The core primitive. An agent that wants to transfer control to another agent emits a tool call (transfer_to_research_agent(brief)). The runtime intercepts the call, swaps the active agent, and continues the loop. There is no separate handoff API; handoff lives in the model's native action space alongside every other tool.

This was the idea Swarm was built to demonstrate, and the community workflows that grew up around it (and the parallel adoption in LangGraph's swarm prebuilt) proved that the pattern was durable. The Agents SDK kept it because there was no reason to change it.

Peer agents with no central manager

Swarm has no orchestrator role. Every agent is a peer; control flows by direct handoff. This is the architectural opposite of AutoGen's GroupChat or LangGraph's create_supervisor. The Agents SDK keeps peer handoff and also offers agents as tools, where a manager agent calls specialists as tools.

Tiny API surface

Swarm's entire surface was an Agent class, a run function, and a handful of helpers. The Agents SDK is larger because production primitives have real surface area, but it is still small relative to LangGraph or AutoGen. The minimalism was part of Swarm's appeal and the Agents SDK preserves it as much as the production scope allows.

The mental model

The simplicity of the mental model: an agent is a prompt plus tools plus handoff targets. Read the docs in an hour, build a working prototype the same afternoon. This learnability was Swarm's main selling point and the Agents SDK keeps it.

What got fixed (the five production primitives)

Provider-agnostic adapters and what they unlock

The sample code versus production framework lesson

Situations where this technique stops working.

2–4 min · Everything important, quickly.

Capability	Swarm (2024)	Agents SDK (2025)
Handoff as tool call	Yes	Yes
Peer agents, no central manager	Yes	Yes
Tiny API surface	Yes	Yes (still small)
First-class guardrails	No	Yes
Structured tracing	No	Yes
Typed handoff payloads	No	Yes
End to end streaming	Partial	Yes
Eval support (traces feed OpenAI evals)	No	Yes
Provider-agnostic adapters	No	Yes

Real products, models, and research that use this idea.

OpenAI's Swarm repository on GitHub still exists but is explicitly marked as superseded by the Agents SDK; the README points users to the new framework.
OpenAI calls the Agents SDK a production-ready evolution of Swarm and recommends migrating to it for all production use cases.

What an interviewer would ask next. Try answering before peeking at the approach.

QHow does the Agents SDK handoff primitive differ from LangGraph's create_swarm prebuilt?

Both implement handoff as tool call with peer agents. The Agents SDK is more minimal and provider-agnostic; LangGraph's swarm sits on top of the same state-graph machinery as create_supervisor, which gives you checkpointing and time-travel for free at the cost of a heavier underlying model.

2 more follow-ups an interviewer would ask next. Sign in to reveal them.

Red flags & common mistakes

The phrases that signal junior thinking. Click to expand.

Most common mistake

Thinking the difference between Swarm and the Agents SDK is the handoff pattern. The pattern survives unchanged; what changed is everything around it that production needs.

60 second bullets to scan on the way to the call.

What survived from Swarm (pattern, peer topology, small API)
The five primitives the Agents SDK adds (guardrails, tracing, schemas, streaming, evals)

Primary sources. Browse if you want the original framing.