Guide · Open source
How to use Swarm: install and run multi-agent handoffs in Python
Updated · written with AI from the project's own documentation and checked against our catalogue data
Swarm is an experimental, educational Python library from OpenAI for building systems where several AI agents, each with its own instructions and tools, pass a conversation between them. This guide shows you how to install it, write a two-agent handoff, and understand the run loop. It also explains why the README recommends the OpenAI Agents SDK for production work.
Swarmopenai/swarm · ★ 22.1k · MIT Install options & downloads Quick start
- 1Check Python version. Confirm you have Python 3.10 or newer, which the README requires.
- 2Install Swarm. Run pip install git+https://github.com/openai/swarm.git to install the library from GitHub.
- 3Define an Agent. Create Agent objects with a name and instructions, and add functions to the ones that should be able to hand off.
- 4Write a handoff function. Write a plain Python function that returns the target Agent; returning it hands the conversation over.
- 5Run the client. Create Swarm() and call client.run() with the starting agent and a messages list.
- 6Read the response. Print response.messages[-1]["content"] or inspect the returned agent and context_variables.
- 7Plan your next step. For production work, review the OpenAI Agents SDK, which the README recommends migrating to.
What Swarm is and who it is for
Swarm is built around two primitives: Agents and handoffs. An Agent encompasses instructions and tools, and can at any point choose to hand off a conversation to another Agent.
The project is described as educational, not as a production framework. It suits developers who want to learn how multi-agent handoffs work with a small codebase, and learners reading example code for function calling and agent routing.
- Good fit: learning handoffs, prototyping a triage or routing flow between a few specialized agents, comparing older patterns with the newer Agents SDK.
- Poor fit: production systems, or projects needing hosted conversation state or memory.
Install Swarm with pip
Swarm requires Python 3.10+. The README installs it directly from GitHub with pip. Use the HTTPS form unless you have SSH access set up for GitHub.
The README gives two equivalent commands: one over SSH and one over HTTPS.
pip install git+https://github.com/openai/swarm.gitCreate your first two agents and a handoff
Create a Swarm client, then define a function that returns another Agent. Returning an Agent from a function is how a handoff is expressed. Agent A receives the function in its functions list, so it can transfer the conversation to Agent B.
Agent B in the README example has only instructions and no tools. Its instruction tells it to only speak in Haikus, which makes it easy to see that the handoff happened.
- Import Swarm and Agent from the swarm package.
- Create the client with Swarm(). Swarm instantiates an OpenAI client internally.
- Pass the starting agent and a messages list to client.run().
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"])Understand the client.run() loop
client.run() is analogous to chat.completions.create() in the Chat Completions API. It takes messages and returns messages, and it saves no state between calls. It also handles function execution and handoffs, and can take several turns before returning to you.
The loop runs in this order: get a completion from the current Agent, execute tool calls and append results, switch Agent if necessary, update context variables if necessary, and return when there are no new function calls.
- max_turns limits how many conversational turns are allowed.
- execute_tools set to False stops execution and returns the tool_calls message when an Agent tries to call a function.
- context_variables passes a dictionary available to functions and Agent instructions.
- stream enables streaming responses; debug enables debug logging.
- The returned Response contains messages, the last agent, and context_variables.
Continue a conversation between calls
Because Swarm keeps no state, you carry it forward yourself. Pass the returned messages, the last agent and context variables, plus any new user message, into the next client.run() call.
The README notes that run_demo_loop in /swarm/repl/repl.py shows a full execution loop.
- Each returned message has a sender field showing which Agent produced it.
- Storing the conversation is your responsibility; Swarm does not do it for you.
Explore the examples folder
The repository includes examples you can read to see the patterns in practice. Each example has its own README.
- basic: setup, function calling, handoffs, and context variables.
- triage_agent: a basic triage step that hands off to the right agent.
- weather_agent: a simple function calling example.
- airline, support_bot and personal_shopper: larger multi-agent scenarios.
What people use it for
- Teaching yourself how a triage agent routes a customer to a billing or technical agent.
- Prototyping a two-agent flow where one agent gathers information and hands off to a specialist.
- Reading the airline or support_bot examples to see how several agents share a customer service flow.
- Comparing Swarm's handoff pattern with the OpenAI Agents SDK before choosing a library.
Frequently asked questions
Is Swarm production ready?
No. The README describes Swarm as experimental and educational, and says it is now replaced by the OpenAI Agents SDK. The README recommends migrating to the Agents SDK for all production use cases.
What Python version does Swarm need?
The README says Swarm requires Python 3.10 or newer.
How do I install openai/swarm?
Run pip install git+https://github.com/openai/swarm.git. The README also lists an SSH form, pip install git+ssh://git@github.com/openai/swarm.git.
Does Swarm store conversation history or memory?
No. Swarm is entirely powered by the Chat Completions API and is stateless between calls. You pass the messages, agent and context variables back in yourself on each run.
Is Swarm the same as the Assistants API?
No. The README says Swarm Agents are not related to Assistants in the Assistants API. The names are similar only for convenience.
What are alternatives to Swarm?
The source lists OpenAI Agents SDK, LangGraph, CrewAI and AutoGen as comparable projects. The Agents SDK is the one the README names as the production successor to Swarm.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Swarm is a good way to learn how agent handoffs and function calling fit together, because the codebase is small and the examples are readable. Do not use it for production, and do not choose it if you need hosted memory or stored conversation state; the OpenAI Agents SDK, which the README recommends, is the better place to start for those needs.
Install options & downloads