Repository files navigation

Requires Python 3.10+

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

or

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

fromswarmimportSwarm,Agentclient=Swarm()deftransfer_to_agent_b():returnagent_bagent_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?

• Overview
• Examples
• Documentation
  • Running Swarm
  • Agents
  • Functions
  • Streaming
• Evaluations
• Utils

Swarm focuses on making agentcoordination andexecution lightweight, highly controllable, and easily testable.

It accomplishes this through two primitive abstractions:Agents andhandoffs. AnAgent encompassesinstructions andtools, and can at any point choose to hand off a conversation to anotherAgent.

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.

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.

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

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

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

fromswarmimportSwarmclient=Swarm()

Swarm'srun() function is analogous to thechat.completions.create() function in the Chat Completions API – it takesmessages and returnsmessages 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'sclient.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

Onceclient.run() is finished (after potentially multiple calls to agents and tools) it will return aResponse containing all the relevant updated state. Specifically, the newmessages, the lastAgent to be called, and the most up-to-datecontext_variables. You can pass these values (plus new user messages) in to your next execution ofclient.run() to continue the interaction where it left off – much likechat.completions.create(). (Therun_demo_loop function implements an example of a full execution loop in/swarm/repl/repl.py.)

AnAgent simply encapsulates a set ofinstructions with a set offunctions (plus some additional settings below), and has the capability to hand off execution to anotherAgent.

While it's tempting to personify anAgent as "someone who does X", it can also be used to represent a very specific workflow or step defined by a set ofinstructions andfunctions (e.g. a set of steps, a complex retrieval, single step of data transformation, etc). This allowsAgents to be composed into a network of "agents", "workflows", and "tasks", all represented by the same primitive.

Agentinstructions are directly converted into thesystem prompt of a conversation (as the first message). Only theinstructions of the activeAgent will be present at any given time (e.g. if there is anAgent handoff, thesystem prompt will change, but the chat history will not.)

agent=Agent(instructions="You are a helpful agent.")

Theinstructions can either be a regularstr, or a function that returns astr. The function can optionally receive acontext_variables parameter, which will be populated by thecontext_variables passed intoclient.run().

definstructions(context_variables):user_name=context_variables["user_name"]returnf"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?

• SwarmAgents can call python functions directly.
• Function should usually return astr (values will be attempted to be cast as astr).
• If a function returns anAgent, execution will be transferred to thatAgent.
• If a function defines acontext_variables parameter, it will be populated by thecontext_variables passed intoclient.run().

defgreet(context_variables,language):user_name=context_variables["user_name"]greeting="Hola"iflanguage.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 anAgent function call has an error (missing function, wrong argument, error) an error response will be appended to the chat so theAgent can recover gracefully.
• If multiple functions are called by theAgent, they will be executed in that order.

AnAgent can hand off to anotherAgent by returning it in afunction.

sales_agent=Agent(name="Sales Agent")deftransfer_to_sales():returnsales_agentagent=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 thecontext_variables by returning a more completeResult object. This can also contain avalue and anagent, 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).

sales_agent=Agent(name="Sales Agent")deftalk_to_sales():print("Hello, World!")returnResult(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'}

Swarm automatically converts functions into a JSON Schema that is passed into Chat Completionstools.

• Docstrings are turned into the functiondescription.
• Parameters without default values are set torequired.
• Type hints are mapped to the parameter'stype (and default tostring).
• 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.)

defgreet(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}!")

{"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"]}}}

stream=client.run(agent,messages,stream=True)forchunkinstream:print(chunk)

Uses the same events asChat Completions API streaming. Seeprocess_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 anAgent handles a single message (response or function call). This helps identify switches betweenAgents.
• {"response": Response} will return aResponse object at the end of a stream with the aggregated (complete) response, for convenience.

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 theairline,weather_agent andtriage_agent quickstart examples. See the READMEs for more details.

Use therun_demo_loop to test out your swarm! This will run a REPL on your command line. Supports streaming.

fromswarm.replimportrun_demo_loop...run_demo_loop(agent,stream=True)

• Ilan Bigio -ibigio
• James Hills -jhills20
• Shyamal Anadkat -shyamal-anadkat
• Charu Jaiswal -charuj
• Colin Jarvis -colin-openai
• Katia Gil Guzman -katia-openai