# openai/swarm: a teaching framework for multi-agent handoffs, now superseded by the Agents SDK

> Swarm is a small Python library from OpenAI that shows how agents and handoffs can coordinate a conversation without server-side state. It is educational, and the README now points production users to the OpenAI Agents SDK instead.

**openai/swarm** — Educational framework exploring ergonomic, lightweight multi-agent orchestration. Managed by OpenAI Solution team.

- Repository: https://github.com/openai/swarm
- Stars: 22,025 · Forks: 2,341
- Language: Python
- License: MIT
- Published: 2026-09-21 · Updated: 2026-09-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/openai-swarm

## What openai/swarm actually solves, and for whom

A single prompt stops working once a task needs many independent capabilities and instruction sets that do not fit in one context. Swarm's answer is to split that prompt into several Agent objects and let one agent hand the conversation to another when the work changes shape. The README frames the target audience plainly: it is an educational resource for developers curious about multi-agent orchestration, and it says approaches like Swarm suit situations with a large number of independent capabilities and instructions that are difficult to encode into a single prompt.

That framing matters when you decide whether to read the code. This is not a runtime you deploy and forget. It is a reference implementation of two primitives, Agent and handoff, written to be small enough to read in one sitting. The repository is Python, MIT licensed, and the last push was on 2026-04-15. The README opens with an important note: Swarm is now replaced by the OpenAI Agents SDK, described there as a production-ready evolution, and the project recommends migrating for all production use cases. Treat the codebase as a study object, not as a dependency you plan to keep for years.

## Agents, handoffs and the run loop

An Agent carries instructions and functions. A handoff is just a function that returns another Agent, and the loop notices the return value and switches the active agent. There is no separate handoff class to learn, which is the most interesting design choice in the project: the transfer mechanism reuses ordinary tool calling rather than adding a new protocol.

client.run() is documented as analogous to chat.completions.create(): it takes messages and returns messages, and saves no state between calls. The README describes the loop as five steps. Get a completion from the current Agent. Execute tool calls and append results. Switch Agent if necessary. Update context variables if necessary. If there are no new function calls, return. The result is a Response holding the updated messages, the last Agent called, and the current context_variables, which you pass back in along with new user messages to continue the interaction.

The arguments table is where the practical controls live. max_turns defaults to float("inf"), so a runaway loop has no built-in ceiling unless you set one. execute_tools can be set to False to interrupt execution and return the tool_calls message immediately, which is the documented hook for inspecting or approving a call before it runs. model_override swaps the model per run, and stream enables streaming responses. The README also states that Swarm Agents are unrelated to Assistants in the Assistants API, despite the similar naming, and that the library runs entirely on the Chat Completions API.

## Installing openai/swarm and a first handoff

The README requires Python 3.10 or higher and gives two install commands, both from the git repository rather than a package index. Pick the HTTPS form unless you already have SSH keys configured for GitHub.

```bash
pip install git+https://github.com/openai/swarm.git
```

After that, the README's usage example is the shortest way to see a handoff happen. Agent A has a function that returns agent_b, and Agent B is told to speak only in Haikus. When the user asks to talk to agent B, the model calls the transfer function, the loop sees an Agent returned, and the next completion comes from agent B.

```python
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 helpful agent.",
    functions=[transfer_to_agent_b],
)

agent_b = Agent(
    name="Agent B",
    instructions="Only speak in Haikus.",
)

response = client.run(
    agent=agent_a,
    messages=[{"role": "user", "content": "I want to talk to agent B."}],
)

print(response.messages[-1]["content"])
```

The README shows the expected output as a haiku about hope and new paths. If you get a normal prose answer instead, the handoff did not fire, and the first thing to check is whether your transfer function is listed in the agent's functions argument. Instantiating Swarm() also creates an OpenAI client internally, so the usual API key environment variable for that client has to be present before the call succeeds.

## Where Swarm stops being the right tool

The largest limitation is stated by the project itself. The README says Swarm is replaced by the OpenAI Agents SDK and recommends migrating for all production use cases. If you are choosing a dependency today for something that will run in front of customers, the project's own guidance points away from itself.

The second limitation is the stateless design. Swarm stores nothing between calls, so every turn requires you to resend the full message list and any context_variables. That is fine for a demo and workable for a service that persists conversation state in your own database, but it means memory management is your problem, not the library's. The README contrasts this with the Assistants API, which it calls a great option for developers who want fully hosted threads with built-in memory and retrieval.

Two smaller edges are worth knowing. max_turns defaults to infinity, so an agent that keeps handing off or calling tools will keep going until something else stops it. And the README documents no rollback, no retry policy and no persistence layer, so recovery behaviour after a failed tool call is left to the application. None of this is a defect in a teaching framework. It is a defect in a framework you picked for the wrong job.

## Swarm versus the OpenAI Agents SDK

The real alternative named in the README is the OpenAI Agents SDK, at openai/openai-agents-python. The difference in approach is not cosmetic. Swarm is a client-side loop over Chat Completions with two primitives and no state; the README describes the Agents SDK as a production-ready evolution of Swarm with key improvements, maintained by the OpenAI team.

If you are learning the pattern, Swarm is the smaller text to read, which is exactly why it exists. If you are shipping, the migration question answers itself: the same concepts of agents and handoffs appear in the successor, but the successor is the one the project says will be maintained. A second alternative is the Assistants API, which the README positions for developers who want hosted threads plus built-in memory and retrieval, the opposite trade-off from Swarm's stateless client-side design. Choosing between those two is a choice about who owns conversation state, and Swarm takes the position that you do.

## Maintenance, licence and upgrade cost

The repository is not archived, and the last push was on 2026-04-15. No versioned release is documented, and the README's install instructions point at the git repository rather than a package index, so pinning is on you: a git URL installs whatever the default branch holds at that moment. The pyproject.toml in the repository declares setuptools as the build backend and nothing else, which tells you the packaging is minimal.

The licence is MIT, which permits commercial use and modification, but this is not legal advice and you should read LICENSE yourself. The upgrade cost is the part people underestimate. Because Swarm is positioned as superseded, any investment in it is a cost you will likely pay again when moving to the Agents SDK. The README's own recommendation is to migrate for production use cases, so the honest accounting is that Swarm is a learning expense, and the cheaper path is to learn the pattern here and build on the successor.

## Conclusion

Adopt openai/swarm if you want to read and run a compact example of agent handoffs, or to teach the pattern to a team that already knows the Chat Completions API. Do not adopt it for a production system: the README states it is replaced by the OpenAI Agents SDK and recommends migrating for all production use cases. Before you build anything on it, verify that your Python is 3.10 or newer, that you can install from the git URL because no versioned release is documented, and that you accept losing state between calls, since Swarm stores nothing server-side and you must resend messages and context_variables yourself.

## FAQ

### How do I install openai/swarm?

The README requires Python 3.10 or higher and gives two commands, pip install git+https://github.com/openai/swarm.git or the SSH form pip install git+ssh://git@github.com/openai/swarm.git. Both install from the git repository rather than a package index.

### How do I use openai/swarm?

You instantiate a Swarm client, define one or more Agent objects with instructions and functions, and call client.run() with an agent and a messages list. A handoff is a function that returns another Agent, and the run loop switches agents when it sees that return value.

### Is openai/swarm still maintained?

The repository is not archived and the last push was on 2026-04-15, but the README states that Swarm is now replaced by the OpenAI Agents SDK and recommends migrating to it for all production use cases.

### Does openai/swarm store conversation state between calls?

No. The README says Swarm is entirely powered by the Chat Completions API and is stateless between calls, and that client.run() saves no state. You continue a conversation by passing the returned messages, the last Agent and the updated context_variables back into the next call.

### What are the alternatives to openai/swarm?

The README names the OpenAI Agents SDK as the production-ready successor and recommends migrating to it. It also describes the Assistants API as a good option for developers who want fully hosted threads with built-in memory and retrieval.

## Sources

- [Issues](https://github.com/openai/swarm/issues)
- [License: MIT](https://github.com/openai/swarm/blob/main/LICENSE)
- [openai/swarm on GitHub](https://github.com/openai/swarm)
- [README](https://github.com/openai/swarm/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/openai-swarm