Table of Contents

OpenAI Swarm

OpenAI Swarm is an experimental, educational Python framework released by OpenAI for exploring lightweight multi-agent orchestration. Built around the core concepts of routines and handoffs, Swarm demonstrates how multiple specialized agents can coordinate to solve complex tasks through simple, composable patterns. While explicitly not intended for production use, its design patterns directly influenced the production-grade OpenAI Agents SDK released in 2025. The repository has accumulated significant community interest on GitHub (17,000+ stars).

Core Concepts

Swarm is built on two foundational ideas from the OpenAI orchestrating agents cookbook:

Routines

A routine is a set of natural language instructions combined with tools. It captures the idea of “a sequence of steps an agent should follow.” Routines are defined via the agent's instructions (system prompt) and functions (available tools). The agent follows the instructions, calling tools as needed.

Handoffs

A handoff occurs when one agent transfers control to another. This is implemented as a simple function that returns the target Agent object. The current agent decides to hand off based on its instructions and the conversation context. Handoffs enable dynamic task delegation between specialists.

Agent Definition

Swarm agents are lightweight Python objects with three key properties:

Agents use the OpenAI Chat Completions API with function calling. The LLM decides which functions to invoke based on the conversation.

The Run Loop

The client.run() method implements Swarm's core execution loop:

  1. Send the current message history to the active agent's LLM
  2. If the LLM returns a text response, return it to the caller
  3. If the LLM calls a function:
    • Execute the function locally
    • If the function returns an Agent, perform a handoff (switch active agent)
    • If the function returns a string/dict, append the result and loop back to step 1
  4. Continue until the LLM produces a final text response or max iterations reached

The entire loop runs client-side – there is no server component. Swarm is stateless between calls; all state is passed via message history and context variables.

Context Variables

Agents can share state through a context_variables dictionary:

How It Influenced the Agents SDK

Swarm served as a conceptual prototype for the production OpenAI Agents SDK (released March 2025):

Code Example

from swarm import Swarm, Agent
 
client = Swarm()
 
# Define handoff functions
def transfer_to_sales():
    "Transfer the conversation to the sales agent."
    return sales_agent
 
def transfer_to_support():
    "Transfer the conversation to the support agent."
    return support_agent
 
# Tool functions
def check_inventory(item: str):
    "Check if an item is in stock."
    inventory = {"laptop": 15, "phone": 42, "tablet": 0}
    count = inventory.get(item.lower(), 0)
    return f"{item}: {'In stock' if count > 0 else 'Out of stock'} ({count} units)"
 
def process_refund(order_id: str, context_variables: dict):
    "Process a refund for the given order."
    user = context_variables.get("user_name", "Unknown")
    return f"Refund processed for order {order_id} (customer: {user})"
 
# Define agents
triage_agent = Agent(
    name="Triage",
    instructions="You route customer queries. Send sales questions to Sales, support issues to Support.",
    functions=[transfer_to_sales, transfer_to_support],
)
 
sales_agent = Agent(
    name="Sales",
    instructions="You help customers with purchases and product availability.",
    functions=[check_inventory],
)
 
support_agent = Agent(
    name="Support",
    instructions="You handle returns, refunds, and technical issues.",
    functions=[process_refund],
)
 
# Run the multi-agent system
response = client.run(
    agent=triage_agent,
    messages=[{"role": "user", "content": "I need a refund for order #12345"}],
    context_variables={"user_name": "Alice"},
)
 
# Print the final response
print(response.messages[-1]["content"])
print(f"Final agent: {response.agent.name}")

Architecture Diagram

graph TD A["User Input"] --> B["Triage Agent"] B -->|handoff| C["Sales Agent"] B -->|handoff| D["Support Agent"] C --> E["check_inventory()"] D --> F["process_refund()"] G["Context Variables (shared state)"] -.-> B G -.-> C G -.-> D

Limitations

References

See Also