## File: README.md # Swarm (experimental, educational) > [!IMPORTANT] > Swarm is now replaced by the [OpenAI Agents SDK](https://github.com/openai/openai-agents-python), 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+ ```shell pip install git+ssh://git@github.com/openai/swarm.git ``` or ```shell pip install git+https://github.com/openai/swarm.git ``` ## Usage ```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"]) ``` ``` 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: `Agent`s 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). ```python 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`](https://platform.openai.com/docs/api-reference/chat/create#chat-create-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 of a full execution loop in `/swarm/repl/repl.py`.) #### `Response` Fields | Field | Type | Description | | --------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **messages** | `List` | A list of message objects generated during the conversation. Very similar to [Chat Completions `messages`](https://platform.openai.com/docs/api-reference/chat/create#chat-create-messages), but with a `sender` field indicating which `Agent` the message originated from. | | **agent** | `Agent` | The last agent to handle a message. | | **context_variables** | `dict` | The same as the input variables, plus any changes. | ## Agents An `Agent` simply encapsulates a set of `instructions` with a set of `functions` (plus some additional settings below), and has the capability to hand off execution to another `Agent`. While it's tempting to personify an `Agent` as "someone who does X", it can also be used to represent a very specific workflow or step defined by a set of `instructions` and `functions` (e.g. a set of steps, a complex retrieval, single step of data transformation, etc). This allows `Agent`s to be composed into a network of "agents", "workflows", and "tasks", all represented by the same primitive. ## `Agent` Fields | Field | Type | Description | Default | | ---------------- | ------------------------ | ----------------------------------------------------------------------------- | ---------------------------- | | **name** | `str` | The name of the agent. | `"Agent"` | | **model** | `str` | The model to be used by the agent. | `"gpt-4o"` | | **instructions** | `str` or `func() -> str` | Instructions for the agent, can be a string or a callable returning a string. | `"You are a helpful agent."` | | **functions** | `List` | A list of functions that the agent can call. | `[]` | | **tool_choice** | `str` | The tool choice for the agent, if any. | `None` | ### Instructions `Agent` `instructions` are directly converted into the `system` prompt of a conversation (as the first message). Only the `instructions` of the active `Agent` will be present at any given time (e.g. if there is an `Agent` handoff, the `system` prompt will change, but the chat history will not.) ```python agent = Agent( instructions="You are a helpful agent." ) ``` The `instructions` can either be a regular `str`, or a function that returns a `str`. The function can optionally receive a `context_variables` parameter, which will be populated by the `context_variables` passed into `client.run()`. ```python def instructions(context_variables): user_name = context_variables["user_name"] return f"Help the user, {user_name}, do whatever they want." agent = Agent( instructions=instructions ) response = client.run( agent=agent, messages=[{"role":"user", "content": "Hi!"}], context_variables={"user_name":"John"} ) print(response.messages[-1]["content"]) ``` ``` Hi John, how can I assist you today? ``` ## Functions - Swarm `Agent`s can call python functions directly. - Function should usually return a `str` (values will be attempted to be cast as a `str`). - If a function returns an `Agent`, execution will be transferred to that `Agent`. - If a function defines a `context_variables` parameter, it will be populated by the `context_variables` passed into `client.run()`. ```python def greet(context_variables, language): user_name = context_variables["user_name"] greeting = "Hola" if language.lower() == "spanish" else "Hello" print(f"{greeting}, {user_name}!") return "Done" agent = Agent( functions=[greet] ) client.run( agent=agent, messages=[{"role": "user", "content": "Usa greet() por favor."}], context_variables={"user_name": "John"} ) ``` ``` Hola, John! ``` - If an `Agent` function call has an error (missing function, wrong argument, error) an error response will be appended to the chat so the `Agent` can recover gracefully. - If multiple functions are called by the `Agent`, they will be executed in that order. ### Handoffs and Updating Context Variables An `Agent` can hand off to another `Agent` by returning it in a `function`. ```python sales_agent = Agent(name="Sales Agent") def transfer_to_sales(): return sales_agent agent = Agent(functions=[transfer_to_sales]) response = client.run(agent, [{"role":"user", "content":"Transfer me to sales."}]) print(response.agent.name) ``` ``` Sales Agent ``` It can also update the `context_variables` by returning a more complete `Result` object. This can also contain a `value` and an `agent`, in case you want a single function to return a value, update the agent, and update the context variables (or any subset of the three). ```python sales_agent = Agent(name="Sales Agent") def talk_to_sales(): print("Hello, World!") return Result( value="Done", agent=sales_agent, context_variables={"department": "sales"} ) agent = Agent(functions=[talk_to_sales]) response = client.run( agent=agent, messages=[{"role": "user", "content": "Transfer me to sales"}], context_variables={"user_name": "John"} ) print(response.agent.name) print(response.context_variables) ``` ``` Sales Agent {'department': 'sales', 'user_name': 'John'} ``` > [!NOTE] > If an `Agent` calls multiple functions to hand-off to an `Agent`, only the last handoff function will be used. ### Function Schemas Swarm automatically converts functions into a JSON Schema that is passed into Chat Completions `tools`. - Docstrings are turned into the function `description`. - Parameters without default values are set to `required`. - Type hints are mapped to the parameter's `type` (and default to `string`). - Per-parameter descriptions are not explicitly supported, but should work similarly if just added in the docstring. (In the future docstring argument parsing may be added.) ```python def greet(name, age: int, location: str = "New York"): """Greets the user. Make sure to get their name and age before calling. Args: name: Name of the user. age: Age of the user. location: Best place on earth. """ print(f"Hello {name}, glad you are {age} in {location}!") ``` ```javascript { "type": "function", "function": { "name": "greet", "description": "Greets the user. Make sure to get their name and age before calling.\n\nArgs:\n name: Name of the user.\n age: Age of the user.\n location: Best place on earth.", "parameters": { "type": "object", "properties": { "name": {"type": "string"}, "age": {"type": "integer"}, "location": {"type": "string"} }, "required": ["name", "age"] } } } ``` ## Streaming ```python stream = client.run(agent, messages, stream=True) for chunk in stream: print(chunk) ``` Uses the same events as [Chat Completions API streaming](https://platform.openai.com/docs/api-reference/streaming). See `process_and_print_streaming_response` in `/swarm/repl/repl.py` as an example. Two new event types have been added: - `{"delim":"start"}` and `{"delim":"end"}`, to signal each time an `Agent` handles a single message (response or function call). This helps identify switches between `Agent`s. - `{"response": Response}` will return a `Response` object at the end of a stream with the aggregated (complete) response, for convenience. # Evaluations Evaluations are crucial to any project, and we encourage developers to bring their own eval suites to test the performance of their swarms. For reference, we have some examples for how to eval swarm in the `airline`, `weather_agent` and `triage_agent` quickstart examples. See the READMEs for more details. # Utils Use the `run_demo_loop` to test out your swarm! This will run a REPL on your command line. Supports streaming. ```python from swarm.repl import run_demo_loop ... run_demo_loop(agent, stream=True) ``` # Core Contributors - Ilan Bigio - [ibigio](https://github.com/ibigio) - James Hills - [jhills20](https://github.com/jhills20) - Shyamal Anadkat - [shyamal-anadkat](https://github.com/shyamal-anadkat) - Charu Jaiswal - [charuj](https://github.com/charuj) - Colin Jarvis - [colin-openai](https://github.com/colin-openai) - Katia Gil Guzman - [katia-openai](https://github.com/katia-openai) --- ## File: examples/airline/README.md # Airline customer service This example demonstrates a multi-agent setup for handling different customer service requests in an airline context using the Swarm framework. The agents can triage requests, handle flight modifications, cancellations, and lost baggage cases. This example uses the helper function `run_demo_loop`, which allows us to create an interactive Swarm session. ## Agents 1. **Triage Agent**: Determines the type of request and transfers to the appropriate agent. 2. **Flight Modification Agent**: Handles requests related to flight modifications, further triaging them into: - **Flight Cancel Agent**: Manages flight cancellation requests. - **Flight Change Agent**: Manages flight change requests. 3. **Lost Baggage Agent**: Handles lost baggage inquiries. ## Setup Once you have installed dependencies and Swarm, run the example using: ```shell python3 main.py ``` ## Evaluations > [!NOTE] > These evals are intended to be examples to demonstrate functionality, but will have to be updated and catered to your particular use case. For this example, we run function evals, where we input a conversation, and the expected function call ('None' if no function call is expected). The evaluation cases are stored in `eval/eval_cases/` subfolder. ```json [ { "conversation": [ { "role": "user", "content": "My bag was not delivered!" } ], "function": "transfer_to_lost_baggage" }, { "conversation": [ { "role": "user", "content": "I had some turbulence on my flight" } ], "function": "None" } ] ``` The script 'function_evals.py' will run the evals. Make sure to set `n` to the number of times you want to run each particular eval. To run the script from the root airline folder, execute: ```bash cd evals python3 function_evals.py ``` The results of these evaluations will be stored in `evals/eval_results/` --- ## File: examples/basic/README.md # Swarm basic This folder contains basic examples demonstrating core Swarm capabilities. These examples show the simplest implementations of Swarm, with one input message, and a corresponding output. The `simple_loop_no_helpers` has a while loop to demonstrate how to create an interactive Swarm session. ### Examples 1. **agent_handoff.py** - Demonstrates how to transfer a conversation from one agent to another. - **Usage**: Transfers Spanish-speaking users from an English agent to a Spanish agent. 2. **bare_minimum.py** - A bare minimum example showing the basic setup of an agent. - **Usage**: Sets up an agent that responds to a simple user message. 3. **context_variables.py** - Shows how to use context variables within an agent. - **Usage**: Uses context variables to greet a user by name and print account details. 4. **function_calling.py** - Demonstrates how to define and call functions from an agent. - **Usage**: Sets up an agent that can respond with weather information for a given location. 5. **simple_loop_no_helpers.py** - An example of a simple interaction loop without using helper functions. - **Usage**: Sets up a loop where the user can continuously interact with the agent, printing the conversation. ## Running the Examples To run any of the examples, use the following command: ```shell python3 .py ``` --- ## File: examples/personal_shopper/README.md # Personal shopper This Swarm is a personal shopping agent that can help with making sales and refunding orders. This example uses the helper function `run_demo_loop`, which allows us to create an interactive Swarm session. In this example, we also use a Sqlite3 database with customer information and transaction data. ## Overview The personal shopper example includes three main agents to handle various customer service requests: 1. **Triage Agent**: Determines the type of request and transfers to the appropriate agent. 2. **Refund Agent**: Manages customer refunds, requiring both user ID and item ID to initiate a refund. 3. **Sales Agent**: Handles actions related to placing orders, requiring both user ID and product ID to complete a purchase. ## Setup Once you have installed dependencies and Swarm, run the example using: ```shell python3 main.py ``` --- ## File: examples/support_bot/README.md # Support bot This example is a customer service bot which includes a user interface agent and a help center agent with several tools. This example uses the helper function `run_demo_loop`, which allows us to create an interactive Swarm session. ## Overview The support bot consists of two main agents: 1. **User Interface Agent**: Handles initial user interactions and directs them to the help center agent based on their needs. 2. **Help Center Agent**: Provides detailed help and support using various tools and integrated with a Qdrant VectorDB for documentation retrieval. ## Setup To start the support bot: 1. Ensure Docker is installed and running on your system. 2. Install the necessary additional libraries: ```shell make install ``` 3. Initialize docker ```shell docker-compose up -d ``` 4. Prepare the vector DB: ```shell make prep ``` 5. Run the main scripy: ```shell make run ``` --- ## File: examples/triage_agent/README.md # Triage agent This example is a Swarm containing a triage agent, which takes in user inputs and chooses whether to respond directly, or triage the request to a sales or refunds agent. ## Setup To run the triage agent Swarm: 1. Run ```shell python3 run.py ``` ## Evals > [!NOTE] > These evals are intended to be examples to demonstrate functionality, but will have to be updated and catered to your particular use case. This example uses `Pytest` to run eval unit tests. We have two tests in the `evals.py` file, one which tests if we call the correct triage function when expected, and one which assesses if a conversation is 'successful', as defined in our prompt in `evals.py`. To run the evals, run ```shell pytest evals.py ``` --- ## File: examples/weather_agent/README.md # Weather agent This example is a weather agent demonstrating function calling with a single agent. The agent has tools to get the weather of a particular city, and send an email. ## Setup To run the weather agent Swarm: 1. Run ```shell python3 run.py ``` ## Evals > [!NOTE] > These evals are intended to be examples to demonstrate functionality, but will have to be updated and catered to your particular use case. This example uses `Pytest` to run eval unit tests. We have two tests in the `evals.py` file, one which tests if we call the `get_weather` function when expected, and one which assesses if we properly do NOT call the `get_weather` function when we shouldn't have a tool call. To run the evals, run ```shell pytest evals.py ```