AI

OpenAI Swarm: Lightweight Multi-Agent Orchestration Framework with 21k+ GitHub Stars

Tosin Akinosho

— 4 min read

OpenAI Swarm is an educational framework for building lightweight, scalable multi-agent systems that prioritize ergonomic design and ease of testing. With 21.3k GitHub stars and active community engagement, Swarm represents OpenAI's approach to agent coordination through simple primitives: agents and handoffs. Unlike heavyweight orchestration frameworks, Swarm runs almost entirely on the client side, making it ideal for developers exploring multi-agent patterns without complex infrastructure.

What is OpenAI Swarm?

OpenAI Swarm is an experimental, educational framework that explores patterns for multi-agent coordination and execution. Created by the OpenAI Solution team, Swarm focuses on making agent orchestration lightweight, highly controllable, and easily testable. The framework is powered entirely by the Chat Completions API, meaning it's stateless between calls—similar to how the Chat Completions API itself works.

Swarm accomplishes multi-agent coordination through two core primitives: Agents and handoffs. An Agent encapsulates instructions and tools, and can at any point choose to hand off a conversation to another Agent. These simple abstractions are powerful enough to express rich dynamics between tools and networks of agents, allowing developers to build scalable, real-world solutions without a steep learning curve.

It's important to note that Swarm Agents are completely unrelated to Assistants in the Assistants API—they're named similarly for convenience but operate on entirely different principles. Swarm is stateless and client-side, while Assistants are hosted and maintain state between calls.

Core Features and Architecture

Agent-Based Design: Each Agent encapsulates a set of instructions (system prompt) and a set of functions (tools). Agents can be simple (representing a single workflow step) or complex (representing a full persona). The framework treats both equally, allowing flexible composition of "agents," "workflows," and "tasks" using the same primitive.

Handoff Mechanism: Agents can hand off execution to other Agents by returning them from function calls. This enables dynamic routing and multi-turn conversations where different agents take control based on context. Handoffs are explicit and controllable, making agent transitions transparent and debuggable.

Function Calling: Swarm automatically converts Python functions into JSON Schema for the Chat Completions API. Docstrings become function descriptions, type hints map to parameter types, and parameters without defaults are marked required. Functions can return strings (appended to chat), Agents (triggering handoffs), or Result objects (combining value, agent, and context updates).

Context Variables: Beyond messages, Swarm supports context variables—a dictionary of additional state available to functions and Agent instructions. Functions can receive and modify context variables, enabling stateful workflows without storing state in the API. This is particularly useful for tracking user information, session state, or workflow progress.

Streaming Support: Swarm supports streaming responses using the same events as Chat Completions API streaming, plus two new event types: `{"delim":"start"}` and `{"delim":"end"}` to signal Agent handoffs, and `{"response": Response}` to return the complete aggregated response at stream end.

Execution Loop: Swarm's `client.run()` implements a simple but powerful loop: get a completion from the current Agent, execute tool calls, switch Agents if necessary, update context variables, and repeat until no new function calls are made. This loop is transparent and controllable, with options for max turns, model override, and debug logging.

Get free AI agent insights weekly

Join our community of builders exploring the latest in AI agents, frameworks, and automation tools.

Join Free

Getting Started

Installation: Swarm requires Python 3.10+ and can be installed via pip:

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

Basic Example: Here's a minimal example showing agent creation and handoff:

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

The response will show Agent B responding in haiku format, demonstrating successful handoff and instruction switching.

Real-World Use Cases

Customer Service Triage: A triage agent receives customer inquiries and routes them to specialized agents (billing, technical support, sales). Each agent has specific instructions and tools relevant to their domain. The triage agent can hand off based on intent classification, and specialized agents can escalate back if needed.

Multi-Step Workflows: Complex processes like airline customer service (booking, cancellations, refunds) can be decomposed into agent-based steps. Each step is an Agent with specific instructions and tools. Context variables track booking details, customer info, and transaction state across handoffs.

Research and Analysis: A research coordinator agent can hand off to specialized agents for data gathering, analysis, and report generation. Each agent focuses on its specific task, with context variables accumulating findings. The coordinator can orchestrate multiple rounds of research and synthesis.

Interactive Simulations: Swarm's stateless design makes it ideal for simulations where multiple agents interact. Each turn, agents can hand off based on conversation flow, with context variables tracking simulation state. This enables everything from customer service simulations to creative writing collaborations.

How It Compares

vs. Assistants API: Assistants provide hosted threads with built-in memory and retrieval, ideal for persistent, stateful interactions. Swarm is stateless and client-side, offering more control and lower latency but requiring developers to manage state. Assistants are better for long-running conversations; Swarm is better for orchestrated workflows.

vs. LangChain Agents: LangChain provides a comprehensive ecosystem with memory, retrieval, and many integrations. Swarm is intentionally minimal, focusing purely on agent coordination. LangChain is more feature-rich; Swarm is more lightweight and easier to understand.

vs. AutoGen: AutoGen (from Microsoft) focuses on multi-agent conversations with rich interaction patterns. Swarm emphasizes explicit control and testability. AutoGen is more autonomous; Swarm is more deterministic and controllable.

What's Next

OpenAI has announced that Swarm is being evolved into the OpenAI Agents SDK, a production-ready framework with key improvements and active maintenance from the OpenAI team. The Agents SDK will build on Swarm's core concepts while adding production features. For new projects, OpenAI recommends starting with the Agents SDK, though Swarm remains valuable for learning and experimentation.

The multi-agent space is rapidly evolving, with frameworks increasingly focusing on ergonomic design and developer experience. Swarm's emphasis on simplicity and testability has influenced the broader ecosystem, and its successor (the Agents SDK) will likely set new standards for production multi-agent systems.

Sources

Read more