# OpenAI Swarm: features, protocols, quickstart

## TL;DR

OpenAI Swarm is an experimental, educational Python library from OpenAI's Solutions team that routes a conversation between agents through handoff functions on top of Chat Completions. A notice at the top of its README says it is replaced by the OpenAI Agents SDK. It suits people studying handoff patterns, not new production builds.

## Key facts

| Field | Value |
| --- | --- |
| Type | Framework |
| Languages / SDKs | Python |
| License | MIT |
| Pricing model | Open source, free |
| Orchestration pattern | Handoff |
| GitHub stars | 22,025 (as of 2026-10-01) |
| GitHub forks | 2,341 |
| Last push | 2026-04-15 |
| Latest release | No release published |
| Repository | [openai/swarm](https://github.com/openai/swarm) |
| Documentation | [github.com](https://github.com/openai/swarm#documentation) |
| Last verified | 2026-09-30 |

## Key features

- Two primitives only: an Agent (instructions plus Python functions) and a handoff, which happens when a function returns another Agent. ([source](https://github.com/openai/swarm#handoffs-and-updating-context-variables))
- client.run() loops: get a completion, run tool calls, switch agent if needed, update context, and return once no function is called; max_turns and model_override limit or redirect it. ([source](https://github.com/openai/swarm#clientrun))
- A context_variables dict is passed to instructions and functions; a Result object can return a value, a new agent and context updates at once. ([source](https://github.com/openai/swarm#handoffs-and-updating-context-variables))
- Python function signatures and docstrings are turned into JSON Schema tool definitions automatically. ([source](https://github.com/openai/swarm#function-schemas))
- Streaming adds start/end delimiter events so a client can see when the active agent changes. ([source](https://github.com/openai/swarm#streaming))
- run_demo_loop starts a command-line REPL, with streaming, for trying an agent network by hand. ([source](https://github.com/openai/swarm#utils))
- Example apps cover triage routing, an airline customer-service setup, a support bot and a personal shopper. ([source](https://github.com/openai/swarm#examples))

## Architecture and orchestration pattern

Pattern: Handoff.

Swarm is a thin loop around the Chat Completions API. `Swarm()` wraps an OpenAI client, and `client.run(agent, messages)` repeatedly asks the active agent for a completion, executes any function calls in order, appends their results, and returns when the model stops calling functions or `max_turns` is reached.

Multi-agent behaviour comes only from handoffs: a function that returns an `Agent` makes that agent active. The active agent's `instructions` become the system prompt, while the chat history carries over unchanged. There is no planner, graph or supervisor object; the network is whatever set of transfer functions you write.

Nothing is stored between calls. `run()` returns a `Response` with the new messages, the last active agent and the updated `context_variables`, and the caller passes them back in to continue. Memory, persistence and retrieval are left to the application.

### Human in the loop

The README documents one control point: calling `client.run(..., execute_tools=False)` stops the loop and returns the pending `tool_calls` message instead of running the function, so application code or a person can inspect it before continuing. Because `run()` is stateless and returns all messages, the caller decides when to add a user turn and resume. `run_demo_loop` gives a command-line REPL for manual testing. No approval UI or interrupt API beyond this is documented.

## Protocols

| Protocol | Support | Evidence | Note |
| --- | --- | --- | --- |
| MCP | Unknown (checked 2026-09-30) | — | README has no MCP mention; GitHub code search for mcp in openai/swarm returned no results. |
| A2A | Unknown (checked 2026-09-30) | — | README has no A2A mention; code search for a2a matched only unrelated strings in a log file and a pre-commit config. |
| AG-UI | Unknown (checked 2026-09-30) | — | README and code search for ag-ui returned nothing, and Swarm is not in the AG-UI README integration list. |

## Best for

- Learning how handoff-based routing between agents works from a very small codebase.
- Reading the design that the README says the OpenAI Agents SDK evolved from before migrating.
- Throwaway prototypes of triage-style routing, following the triage and airline examples.
- Experiments where every piece of state should be passed explicitly on each call.

## Not for

- New production systems; the README recommends migrating to the OpenAI Agents SDK for all production use.
- Apps that need built-in memory, persistence or server-side threads.
- Teams that need tagged releases, a PyPI package or an SDK in another language.

## Quickstart

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

Install not yet verified by this site.

```python
from swarm import Swarm, Agent

client = Swarm()  # wraps an OpenAI client; reads OPENAI_API_KEY

refunds = Agent(name="Refunds", instructions="Handle refund requests briefly and politely.")

def transfer_to_refunds():
    """Hand the conversation to the refunds agent."""
    return refunds

triage = Agent(
    name="Triage",
    instructions="Send refund questions to the refunds agent; answer anything else yourself.",
    functions=[transfer_to_refunds],
)

resp = client.run(agent=triage, messages=[{"role": "user", "content": "I want my money back."}])
print(resp.agent.name, "->", resp.messages[-1]["content"])
```

### Common pitfalls

- Requires Python 3.10+.
- The README installs from GitHub (`git+https` or `git+ssh`); there are no tagged releases.
- `Swarm()` creates an OpenAI client, so `OPENAI_API_KEY` must be set; the `Agent` default model is `gpt-4o`.
- Runs are stateless: pass `response.messages`, `response.agent` and `response.context_variables` into the next `run()` to continue a conversation.
- If an agent calls several handoff functions in one turn, only the last handoff is used.
- `setup.cfg` lists pytest, pre-commit, numpy and instructor as install requirements, so they are installed alongside the library.

Official quickstart: https://github.com/openai/swarm#install

## Pros

- Very small concept surface: agents, functions, handoffs and context variables are the whole API. ([source](https://github.com/openai/swarm#overview))
- Handoffs are ordinary Python functions that return an Agent, so routing logic is easy to read and unit-test. ([source](https://github.com/openai/swarm#handoffs-and-updating-context-variables))
- execute_tools=False lets the caller stop before any function runs and inspect the pending call. ([source](https://github.com/openai/swarm#clientrun))
- Ships worked examples, including customer-service setups with evaluation scripts. ([source](https://github.com/openai/swarm#evaluations))

## Cons

- Superseded: the notice at the top of the README says Swarm is replaced by the OpenAI Agents SDK and recommends migrating for all production use cases. ([source](https://github.com/openai/swarm/blob/main/README.md?plain=1#L5-L8))
- Code changes stopped in October 2024; later commits only point to the Agents SDK (March 2025) and pin pre-commit hooks (April 2026). ([source](https://github.com/openai/swarm/commits/main))
- No tagged releases; installation is straight from the GitHub repository. ([source](https://github.com/openai/swarm/releases))
- Stateless by design, with no built-in memory or persistence between runs. ([source](https://github.com/openai/swarm#overview))
- Built on an OpenAI client and the Chat Completions API rather than a provider-neutral model layer. ([source](https://github.com/openai/swarm#running-swarm))

## Alternatives

- [OpenAI Agents SDK (Python)](https://multiagentguide.top/tools/openai-agents-sdk.md)
- [OpenAI Agents SDK (JavaScript/TypeScript)](https://multiagentguide.top/tools/openai-agents-js.md)
- [Agent Squad](https://multiagentguide.top/tools/agent-squad.md)
- [AG2](https://multiagentguide.top/tools/ag2.md)

## FAQ

### Is OpenAI Swarm still maintained?

No active development is visible. The notice at the top of the README (lines 5-8) says Swarm is replaced by the OpenAI Agents SDK and recommends migrating for production; code changes stopped in October 2024.

### How is Swarm different from the OpenAI Agents SDK?

Swarm is labelled experimental and educational, keeps no state between calls, and has no releases. The README names the Agents SDK as its replacement for production use and says the OpenAI team will actively maintain it.

### Does Swarm support MCP?

No MCP, A2A or AG-UI support was found in the README or code. Tools are plain Python functions converted to JSON Schema.

### Is Swarm free?

The library is MIT licensed with no paid tier. It calls OpenAI models through the Chat Completions API, which is billed by OpenAI.

### What language does Swarm use?

Python 3.10 or newer, installed from the GitHub repository.

## Sources

- [Swarm GitHub repository (README)](https://github.com/openai/swarm)
- [README: documentation section](https://github.com/openai/swarm#documentation)
- [README: notice that Swarm is replaced by the OpenAI Agents SDK (lines 5-8)](https://github.com/openai/swarm/blob/main/README.md?plain=1#L5-L8)
- [README: install](https://github.com/openai/swarm#install)
- [README: overview](https://github.com/openai/swarm#overview)
- [README: examples](https://github.com/openai/swarm#examples)
- [README: running Swarm](https://github.com/openai/swarm#running-swarm)
- [README: client.run()](https://github.com/openai/swarm#clientrun)
- [README: handoffs and context variables](https://github.com/openai/swarm#handoffs-and-updating-context-variables)
- [README: function schemas](https://github.com/openai/swarm#function-schemas)
- [README: streaming](https://github.com/openai/swarm#streaming)
- [README: evaluations](https://github.com/openai/swarm#evaluations)
- [README: utils (run_demo_loop)](https://github.com/openai/swarm#utils)
- [setup.cfg (install requirements)](https://github.com/openai/swarm/blob/main/setup.cfg)
- [Commit history](https://github.com/openai/swarm/commits/main)
- [Releases (none published)](https://github.com/openai/swarm/releases)
- [OpenAI Agents SDK repository (named replacement)](https://github.com/openai/openai-agents-python)

## Unknown fields

protocols.mcp, protocols.a2a and protocols.agui are unknown: the README does not mention any of them; GitHub code search in openai/swarm found no MCP or AG-UI code and only unrelated 'a2a' strings in a log file and a pre-commit config; Swarm is not in the AG-UI README integration list. The project has no homepage, so homepage is null.

Corrections or removal requests: support@multiagentguide.top

---

Data as of 2026-10-01. Not affiliated with listed projects. HTML version: https://multiagentguide.top/tools/openai-swarm