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).

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

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.

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.

Swarm agents are lightweight Python objects with three key properties:

• name – Identifier for the agent
• instructions – System prompt defining the agent's role and behavior
• functions – List of Python functions the agent can call (tools + handoff functions)

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

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.

Agents can share state through a context_variables dictionary:

• Passed to client.run() at invocation
• Accessible by any function via a context_variables parameter
• Persisted across handoffs within a single run
• Useful for session data (user ID, preferences, accumulated results)

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

• Routines evolved into structured agent workflows with persistence
• Handoffs became first-class primitives with reliability guarantees
• Context variables expanded into managed state with storage backends
• Function calling matured into the standardized tool-use protocol
• The lightweight, composable philosophy carried forward while adding production features (error recovery, rate limiting, distributed execution)

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

  +----------------+
  |  User Input    |
  +-------+--------+
          |
  +-------v--------+    handoff     +----------------+
  |   Triage       |--------------->|    Sales        |
  |   Agent        |                |    Agent        |
  |                |    handoff     | +------------+  |
  |  functions:    |--------+      | |check_      |  |
  |  - to_sales    |        |      | |inventory   |  |
  |  - to_support  |        |      | +------------+  |
  +----------------+        |      +----------------+
                            |
                   +--------v-------+
                   |   Support      |
                   |   Agent        |
                   | +------------+ |
                   | |process_    | |
                   | |refund      | |
                   | +------------+ |
                   +----------------+

          +---------------------+
          |  Context Variables  |
          |  (shared state)     |
          |  {"user_name":...}  |
          +---------------------+

• Educational Only – Not intended for production use; no official support or maintenance
• No Persistence – Stateless between runs; all state must be passed explicitly
• No Error Recovery – No built-in retries, fallbacks, or circuit breakers
• Single-Machine – Client-side execution only; no distributed scaling
• OpenAI-Only – Tied to OpenAI models; third-party LLMs require custom wrappers
• Infinite Loop Risk – Poor handoff logic can cause circular agent delegation
• No Streaming UI – Basic streaming support; complex UIs need manual implementation

• OpenAI Swarm GitHub Repository
• OpenAI Cookbook: Orchestrating Agents
• VentureBeat: OpenAI Swarm Framework
• InfoQ: OpenAI Releases Swarm

• AutoGen Studio – Microsoft's visual multi-agent workflow builder
• Composio – Tool integration platform for agents
• E2B – Sandboxed code execution for agent workflows
• Browser-Use – AI browser automation for agents