====== 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 [[https://cookbook.openai.com/examples/orchestrating_agents|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:

  * **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 Run Loop =====

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

  - Send the current message history to the active agent's LLM
  - If the LLM returns a text response, return it to the caller
  - 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
  - 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:

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

===== How It Influenced the Agents SDK =====

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)

===== Code Example =====

<code python>
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}")
</code>

===== Architecture Diagram =====

<mermaid>
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
</mermaid>

===== Limitations =====

  * **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

===== References =====

  * [[https://github.com/openai/swarm|OpenAI Swarm GitHub Repository]]
  * [[https://cookbook.openai.com/examples/orchestrating_agents|OpenAI Cookbook: Orchestrating Agents]]
  * [[https://venturebeat.com/ai/openais-swarm-ai-agent-framework-routines-and-handoffs|VentureBeat: OpenAI Swarm Framework]]
  * [[https://www.infoq.com/news/2024/10/openai-swarm-orchestration/|InfoQ: OpenAI Releases Swarm]]

===== See Also =====

  * [[autogen_studio|AutoGen Studio]] -- Microsoft's visual multi-agent workflow builder
  * [[composio|Composio]] -- Tool integration platform for agents
  * [[e2b|E2B]] -- Sandboxed code execution for agent workflows
  * [[browser_use|Browser-Use]] -- AI browser automation for agents