openai/swarm

openai/swarm

Description: Educational framework exploring ergonomic, lightweight multi-agent orchestration. Managed by OpenAI Solution team.

Language: Python

License: MIT

Stars: 21610

Forks: 2303

Open issues: 31

Created: 2024-02-22T20:53:54Z

Pushed: 2026-04-15T17:10:28Z

Default branch: main

Fork: no

Archived: no

README: 

Swarm (experimental, educational)

> [!IMPORTANT] > Swarm is now replaced by the OpenAI Agents SDK, which is a production-ready evolution of Swarm. The Agents SDK features key improvements and will be actively maintained by the OpenAI team. > > We recommend migrating to the Agents SDK for all production use cases.

Install

Requires Python 3.10+

pip install git+ssh://git@github.com/openai/swarm.git

or

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

Usage

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"])

Hope glimmers brightly,
New paths converge gracefully,
What can I assist?

Table of Contents

• [Overview](#overview)
• [Examples](#examples)
• [Documentation](#documentation)
• [Running Swarm](#running-swarm)
• [Agents](#agents)
• [Functions](#functions)
• [Streaming](#streaming)
• [Evaluations](#evaluations)
• [Utils](#utils)

Overview

Swarm focuses on making agent coordination and execution lightweight, highly controllable, and easily testable.

It accomplishes this through two primitive abstractions: Agents and handoffs. An Agent encompasses instructions and tools, and can at any point choose to hand off a conversation to another Agent.

These primitives are powerful enough to express rich dynamics between tools and networks of agents, allowing you to build scalable, real-world solutions while avoiding a steep learning curve.

> [!NOTE] > Swarm Agents are not related to Assistants in the Assistants API. They are named similarly for convenience, but are otherwise completely unrelated. Swarm is entirely powered by the Chat Completions API and is hence stateless between calls.

Why Swarm

Swarm explores patterns that are lightweight, scalable, and highly customizable by design. Approaches similar to Swarm are best suited for situations dealing with a large number of independent capabilities and instructions that are difficult to encode into a single prompt.

The Assistants API is a great option for developers looking for fully-hosted threads and built in memory management and retrieval. However, Swarm is an educational resource for developers curious to learn about multi-agent orchestration. Swarm runs (almost) entirely on the client and, much like the Chat Completions API, does not store state between calls.

Examples

Check out /examples for inspiration! Learn more about each one in its README.

• [basic](examples/basic): Simple examples of fundamentals like setup, function calling, handoffs, and context variables
• [triage_agent](examples/triage_agent): Simple example of setting up a basic triage step to hand off to the right agent
• [weather_agent](examples/weather_agent): Simple example of function calling
• [airline](examples/airline): A multi-agent setup for handling different customer service requests in an airline context.
• [support_bot](examples/support_bot): A customer service bot which includes a user interface agent and a help center agent with several tools
• [personal_shopper](examples/personal_shopper): A personal shopping agent that can help with making sales and refunding orders

Documentation


Running Swarm

Start by instantiating a Swarm client (which internally just instantiates an OpenAI client).

from swarm import Swarm

client = Swarm()

client.run()

Swarm's run() function is analogous to the chat.completions.create() function in the Chat Completions API – it takes messages and returns messages and saves no state between calls. Importantly, however, it also handles Agent function execution, hand-offs, context variable references, and can take multiple turns before returning to the user.

At its core, Swarm's client.run() implements the following loop:

1. Get a completion from the current Agent 2. Execute tool calls and append results 3. Switch Agent if necessary 4. Update context variables, if necessary 5. If no new function calls, return

Arguments

| Argument | Type | Description | Default | | --------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------- | | agent | Agent | The (initial) agent to be called. | (required) | | messages | List | A list of message objects, identical to Chat Completions `messages` | (required) | | context_variables | dict | A dictionary of additional context variables, available to functions and Agent instructions | {} | | max_turns | int | The maximum number of conversational turns allowed | float("inf") | | model_override | str | An optional string to override the model being used by an Agent | None | | execute_tools | bool | If False, interrupt execution and immediately returns tool_calls message when an Agent tries to call a function | True | | stream | bool | If True, enables streaming responses | False | | debug | bool | If True, enables debug logging | False |

Once client.run() is finished (after potentially multiple calls to agents and tools) it will return a Response containing all the relevant updated state. Specifically, the new messages, the last Agent to be called, and the most up-to-date context_variables. You can pass these values (plus new user messages) in to your next execution of client.run() to continue the interaction where it left off – much like chat.completions.create(). (The run_demo_loop function implements an example…