DOCSEARCHbyAlgolia
Submit Docs

OpenAI Swarm

repository·main·Indexed 12 days ago

https://github.com/openai/swarm

An experimental, educational framework for multi-agent orchestration focusing on lightweight, controllable, and testable agent coordination. It utilizes two primary primitives: Agents, which encapsulate instructions and tools, and handoffs, which allow agents to transfer conversations to other agents. Swarm is stateless and runs primarily on the client side, using client.run() to manage completions, tool calls, and context variables.

Tokens
5.4K
Snippets
21
Records
25
Agent score
97%

What's inside Swarm

  1. Core Swarm capabilities in basic examples

    main

    The basic examples in Swarm demonstrate several fundamental patterns for building multi-agent systems:

    • Agent Handoffs: Transferring a conversation from one agent to another (e.g., transferring a user from an English-speaking agent to a Spanish-speaking agent).
    • Bare Minimum Setup: The simplest possible configuration of an Agent to respond to a single user message.
    • Context Variables: Using variables within an agent's context to maintain state or user-specific data (e.g., greeting a user by name or accessing account details).
    • Function Calling: Defining and allowing agents to execute Python functions (e.g., an agent retrieving weather information for a specific location).
    • Interactive Loops: Implementing a manual interaction loop (using a while loop) to create a continuous, multi-turn conversation session without using high-level helper functions.

  2. How the Personal Shopper agent swarm works

    main

    The Personal Shopper swarm uses a multi-agent architecture to route customer service requests. It consists of three specialized agents:

    1. Triage Agent: Acts as the entry point. It analyzes the user's request to determine the intent and transfers the conversation to the correct specialized agent.
    2. Refund Agent: Handles refund requests. To successfully process a refund, this agent requires both a user ID and an item ID.
    3. Sales Agent: Manages order placement. To complete a purchase, this agent requires both a user ID and a product ID.

    This pattern demonstrates how to use a Triage agent to orchestrate handoffs between specialized agents in a Swarm.

  3. Use Python functions with Swarm Agents

    main

    Swarm Agents can call Python functions directly. These functions are automatically converted into JSON Schemas for use as tools in Chat Completions.

    Key behaviors:

    • Return Values: Functions should ideally return a str. Other types will be cast to str.
    • Context Variables: If a function includes a context_variables parameter, it will be automatically populated with the context_variables passed into client.run().
    • Error Handling: If a function call fails (missing function, wrong arguments, or runtime error), an error response is appended to the chat so the Agent can attempt to recover.
    • Execution Order: If an agent calls multiple functions, they are executed in the order they were called.

    Function Schema Mapping:

    • Description: Derived from the function's docstring.
    • Required Parameters: Parameters without default values are marked as required in the schema.
    • Types: Type hints are mapped to JSON Schema types (e.g., int to integer). If no hint is provided, it defaults to string.
    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"}
)

  4. Understand the Support Bot architecture

    main

    The support bot demonstration uses a multi-agent pattern to handle customer service tasks:

    • User Interface Agent: Acts as the entry point for user interactions. Its primary responsibility is to triage requests and direct users to the appropriate specialized agent (e.g., the Help Center Agent).
    • Help Center Agent: A specialized agent designed for detailed support. It utilizes various tools and is integrated with a Qdrant VectorDB to retrieve relevant documentation for answering user queries.

  5. Understand the Airline Customer Service agent hierarchy

    main

    This example uses a hierarchical agent structure to manage customer service workflows:

    1. Triage Agent: The entry point. It determines the request type and uses transfers to hand off to specialized agents.
    2. Flight Modification Agent: A specialized agent that further triages requests into:
      • Flight Cancel Agent: Handles cancellations.
      • Flight Change Agent: Handles flight changes.
    3. Lost Baggage Agent: Handles inquiries regarding lost luggage.

  6. Perform Agent handoffs and update context variables

    main

    You can implement agent handoffs and state management using two methods:

    1. Simple Handoff

    An Agent can hand off control to another Agent by simply returning the target Agent instance from a function.

    2. Advanced Handoff with Result

    To perform a handoff while simultaneously returning a value and updating context_variables, return a Result object. This is useful for a single function to perform multiple side effects.

    Note: If an Agent calls multiple functions that perform handoffs, only the last handoff function will be used.

    Result object fields:

    • value: The return value for the function call.
    • agent: The new Agent to hand off to.
    • context_variables: A dictionary of variables to update or add to the existing context.
    sales_agent = Agent(name="Sales Agent")

def talk_to_sales():
   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"}
)
# response.agent.name will be 'Sales Agent'
# response.context_variables will be {'department': 'sales', 'user_name': 'John'}

  7. How Swarm agents and handoffs work

    main

    Swarm is a lightweight orchestration framework based on two primitives: Agents and handoffs.

    • An Agent encapsulates instructions and tools (functions).
    • A handoff occurs when an agent uses a function to return a different Agent object, transferring the conversation to that agent.

    Important Note: Swarm agents are stateless. They are powered by the Chat Completions API and do not store state between calls. Unlike the Assistants API, Swarm runs almost entirely on the client side. You must manage state by passing the messages and context_variables from a Response back into the next client.run() call to continue a conversation.

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

  8. Run the Triage Agent example

    main

    The Triage Agent example demonstrates a Swarm where a central triage agent receives user input and decides whether to handle the request directly or hand it off to specialized agents (e.g., a sales agent or a refunds agent).

    To execute the triage agent Swarm, run the following command from the example directory:

    python3 run.py

  10. Install Swarm

    main

    Swarm requires Python 3.10+. You can install it directly from GitHub using pip via SSH or HTTPS.

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

    or

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

  11. Run the Personal Shopper example

    main

    The Personal Shopper example demonstrates an interactive Swarm session using a run_demo_loop helper function. This agentic system manages sales and refunds using a SQLite3 database for customer and transaction data.

    To run this example, ensure you have installed the necessary dependencies and Swarm, then execute:

    python3 main.py

  12. Run evaluations for the Triage Agent

    main

    The Triage Agent example includes unit tests using pytest to validate agent behavior. These evaluations check:

    1. If the correct triage function is called based on the input.
    2. If a conversation is considered 'successful' according to the logic defined in evals.py.

    Note: These evaluations are examples and should be customized for your specific use case.

    To run the evaluations, use:

    pytest evals.py