OpenAI Swarm review: a clear handoff lesson, not a production framework in 2026
OpenAI Swarm is a small Python framework created to explore multi-agent orchestration through two primitives: agents and handoffs. Its README now labels the project experimental and educational, says it has been replaced by the OpenAI Agents SDK, and recommends migrating every production use case. That statement should appear before any feature list: Swarm is useful source code and a teaching pattern, not OpenAI's current production recommendation.
The repository is not marked archived on GitHub. The latest commit we verified was 15 April 2026, pinning pre-commit hooks to immutable revisions. That is a maintenance/supply-chain change, not a new runtime release. The repository has no formal GitHub Releases and installation still points to the Git repository. “Not archived” therefore does not overturn the explicit replacement notice.
Swarm remains worth studying because the implementation is unusually legible. A routine is essentially instructions plus functions. A handoff occurs when a function returns another Agent. Context variables let application data influence instructions and functions, while the client loop sends Chat Completions, executes tool calls, merges context updates and optionally changes the active agent. This compactness makes behavior inspectable—and exposes how much production infrastructure is missing.
Status in 2026
| Question | Verified answer on 20 Aug 2026 | Practical decision |
|---|---|---|
| Official positioning | Experimental, educational; replaced by OpenAI Agents SDK | Do not start a new production system on Swarm |
| GitHub archived flag | False | Repository visibility is not production endorsement |
| Latest verified commit | 6af0b4c, 15 Apr 2026; pre-commit pinning | Maintenance activity, not a feature release |
| Formal releases | No GitHub Releases | Pin a commit for any reproducible experiment |
| License | MIT | Open source, while APIs/models have separate terms |
| Runtime/API | Python 3.10+; Chat Completions; client-side stateless loop | Application must persist messages and state |
| Current successor | OpenAI Agents SDK | Adds maintained handoffs, sessions/state, guardrails and tracing |
What Swarm actually teaches
| Primitive | Swarm behavior | Boundary to test |
|---|---|---|
| Agent | Name, instructions, functions, optional model/tool choice | A prompt persona is not a security principal |
| Routine | Instructions plus the tools available for one focused job | Instructions are probabilistic, not workflow constraints |
| Function/tool | Python callable exposed through a schema | Arguments need authorization and side-effect controls |
| Handoff | A function returns another Agent, which becomes active | Cycles, wrong routing and context disclosure are possible |
| context_variables | Mutable dictionary available to instructions/functions | It is not durable session storage or automatic LLM context |
| Result | A tool can return value, new agent and context updates | Merge and serialization semantics belong to the app |
| Client.run | Repeated model/tool calls until completion or max turns | One process loop; no queue, checkpoint or distributed lease |
| Streaming | Yields delimiters and response chunks | Reconnect and exactly-once tool execution are not supplied |
A runnable handoff experiment
Build one bounded experiment: a triage agent routes either to sales or refunds; sales may only query a read-only catalog, while refund can only prepare—not execute—a refund. Pass customer_id, locale and verified order ownership in context_variables. Make transfer functions return the destination agent, log source/destination/reason, and cap max_turns at five. Use a fake provider or sandboxed tools first. The experiment demonstrates routing without granting the model real financial authority.
Test routines independently before testing the network. Give triage a labeled set of billing, sales, ambiguous and adversarial requests; measure destination and unnecessary handoffs. For each specialist, remove all tools it does not need and test its refusal outside scope. Then exercise A→B→A cycles, parallel tool calls, malformed arguments, a tool exception, an attempted cross-tenant lookup and prompt injection embedded in an order note. The expected result must include safe failure, not merely a fluent answer.
Context variables are local application data, not a secret channel and not automatic conversation memory. A dynamic instruction may insert their values into the model prompt, and a function may return updates. Classify each key as model-visible or code-only, never let the model select tenant identity, and avoid placing long-lived credentials in a mutable dictionary. Persist the authoritative state in a database with versioning; reconstruct the minimal context for each run.
Migration and evaluation workflow
- Pin the Swarm Git commit, Python environment and model configuration; never depend on an unpinned Git install.
- Draw every agent, outgoing handoff, tool, context key and terminal state; flag cycles and privilege increases.
- Create a redacted golden set with routing labels, specialist answers, refusals, tool results and expected safe failures.
- Run Swarm in a sandbox with fake/read-only tools, max_turns, timeouts and a deterministic side-effect ledger.
- Record active agent, handoff source/destination/reason, model request, tool call ID, arguments hash, result and usage.
- Build the same workflow in OpenAI Agents SDK using handoffs or agents-as-tools and typed RunContextWrapper.
- Add session/run-state strategy, approvals, tool guardrails, server authorization, idempotency and sensitive trace policy.
- Shadow both implementations on the same inputs; compare routing, answer quality, tool success, turns, latency and cost.
- Canary with read-only traffic, then narrowly scoped writes requiring approval; rehearse timeout, crash and rollback.
- Retire the Swarm dependency after parity and safety gates pass, while retaining tests and the explicit handoff graph.
What to measure
| Metric | Method | Why |
|---|---|---|
| Handoff accuracy | Labeled destination and confusion matrix | A fluent specialist is useless after wrong routing |
| Cycle rate | Repeated agent-edge sequences per run | Multi-agent loops burn tokens without progress |
| Tool authorization | Allowed/denied tests by user, tenant and resource | Schema validity is not permission |
| Side-effect integrity | Idempotency and duplicate simulation | Retries can repeat financial or messaging actions |
| Answer quality | Task rubric and evidence checks | Routing success does not guarantee correct work |
| Turns and usage | Requests/tokens by agent and handoff | A network can hide cost amplification |
| Latency | p50/p95 total and per tool/model step | Handoffs add serial calls |
| Recovery | Crash, timeout, approval pause and resume tests | Swarm itself offers no durable checkpoint |
| Trace privacy | Sensitive-field detection in exported events | Observability can become a data leak |
Migration starts with behavior, not class names. Inventory Swarm agents, instructions, functions, transfer edges, context keys, model settings, maximum turns, streaming events and external side effects. Draw the actual handoff graph and mark cycles, terminal agents and privilege changes. Capture redacted transcripts and tool traces for a golden set. Pin the Swarm commit and model snapshot long enough to establish a baseline before moving to the Agents SDK.
Map Agent to the maintained SDK's Agent, transfer functions to handoffs or a customized handoff(), and context variables to typed RunContextWrapper data. Use a handoff when the specialist should take over the user-facing conversation; use Agent.as_tool() when a manager should retain control. Choose exactly one conversation-memory strategy—session, to_input_list(), or OpenAI-managed continuation—to avoid duplicate history.
Add production controls during migration rather than recreating Swarm. Tools can require approval, timeouts and input/output guardrails; runs can preserve state for interruption and resumption; tracing records generations, tools, handoffs and guardrails. Tracing is enabled by default in the Agents SDK and may contain sensitive inputs/outputs, so configure redaction or disable it where policy requires. A guardrail library still does not replace server-side authorization.
Security, state and operational limits
| Risk | Minimum control | Why Swarm alone is insufficient |
|---|---|---|
| Wrong handoff | Allowlisted edges, descriptions, labeled eval and human route | Routing is model-selected |
| Privilege escalation | Separate tool sets and server-side authorization | Active agent is not a trusted identity |
| Infinite loop | max_turns, cycle detector, progress invariant | Agents can return one another repeatedly |
| Duplicate action | Idempotency key and transaction ledger | Client loop lacks exactly-once semantics |
| Lost state | Database/session and versioned resume token | Chat Completions loop is stateless across calls |
| Prompt injection | Data/instruction separation, output validation, destination limits | Tool content re-enters model context |
| Secret leakage | Code-only context, redaction and least privilege | Dynamic instructions can expose context values |
| Silent failure | Structured traces, usage and alerts | No built-in production observability |
Swarm versus current alternatives
| Option | Choose it when | Compared with Swarm |
|---|---|---|
| OpenAI Agents SDK | You want the official maintained evolution with OpenAI models | Handoffs plus sessions/state, approvals, guardrails and tracing |
| LangGraph | Durable checkpoints, explicit graphs, interrupts and provider flexibility dominate | More engineering; stronger state/control model |
| AutoGen AgentChat/Core | Event-driven or distributed multi-agent teams and message protocols matter | Broader runtime and team patterns; more conceptual surface |
| CrewAI | Role-based crews plus business flows and fast templates suit the team | More opinionated composition and ecosystem |
| Single agent + tools | One model can route tools without conversation takeover | Simpler evaluation, context and cost; often the best baseline |
| Deterministic workflow | Known sequence, auditability and exact state transitions matter | Less autonomous, much easier to reason about |
| Swarm | Learning the minimal routine/handoff loop | Small and inspectable, officially superseded for production |
Swarm has no built-in durable state, scheduler, distributed execution, authentication, tenant isolation, retry ledger, cost budget or production trace store. A process crash between a side effect and its tool result can produce ambiguity on retry. Use idempotency keys tied to business operations, transactional outboxes for consequential actions, tool-specific timeouts, per-user rate limits, maximum turns and a human escalation state. Detect repeated active-agent sequences rather than relying only on a global turn ceiling.
Prompt injection becomes more dangerous when a handoff changes the available tools. Treat all user text, retrieved records and tool outputs as untrusted. Do not allow a document to choose an agent by returning a transfer instruction. Authorize at the tool boundary using server-derived identity, validate target account and amount, restrict network destinations, minimize credentials and require approval for irreversible actions. Log the policy decision separately from model reasoning.
Editorial judgment: Swarm is still one of the best tiny codebases for understanding the handoff idea. Its lack of machinery is pedagogically valuable because developers can see the loop. The same lack makes it a poor foundation for new production work, especially when the official maintainer supplies a successor. Read it, reproduce a small experiment, then migrate the pattern—not the dependency—to the Agents SDK or another runtime chosen for your durability and provider requirements.
Frequently asked questions
Is OpenAI Swarm production-ready?
No. Its own README calls it experimental and educational, says the Agents SDK replaced it, and recommends migration for all production use cases.
Is the repository archived?
GitHub's archived flag was false on 20 August 2026. That does not cancel the official replacement notice.
Is Swarm still maintained?
A maintenance commit was visible in April 2026, but there are no formal releases. Activity is not the same as an actively evolved production framework.
What is a handoff?
A tool-like transfer that changes the active agent. In Swarm it occurs when a function returns another Agent.
Are context_variables conversation memory?
No. They are application data passed through a run. The application must persist authoritative conversation and business state.
Can Swarm work with non-OpenAI models?
Its implementation is built around an OpenAI-compatible client/Chat Completions pattern. Compatibility layers may work, but are not a reason to choose a superseded project.
What replaces Swarm?
OpenAI recommends the OpenAI Agents SDK, which preserves lightweight agent and handoff concepts while adding maintained production-oriented features.
Do Agents SDK guardrails replace authorization?
No. Guardrails can validate or block stages; server-side identity, tenant and resource authorization remain mandatory.
Should every workflow use multiple agents?
No. Start with one agent and tools or a deterministic workflow. Add handoffs only when distinct instructions/tool scopes and direct specialist conversation improve measured outcomes.
How should I migrate?
Freeze a baseline, map the handoff graph and context, recreate it with typed SDK primitives, add controls, shadow, canary and remove Swarm after parity.
Sources
- Official Swarm repository
- Swarm README: replacement notice
- Swarm source: core loop
- Swarm commits
- Swarm releases
- Swarm MIT license
- OpenAI Agents SDK quickstart
- Agents SDK handoffs
- Agents SDK context
- Agents SDK guardrails
- Agents SDK running and state
- Agents SDK tracing
- LangGraph overview
- AutoGen AgentChat
- AutoGen handoff pattern
- CrewAI documentation
Independent review dated 20 August 2026. Repository flags, commits and successor APIs can change; verify the official README and current Agents SDK before implementation.
