explaingit

openai/swarm

★ 21,508PythonAudience · developerComplexity · 2/5MaintainedLicenseSetup · moderate

TLDR

Educational Python framework for building systems where multiple AI agents coordinate and hand off tasks to each other based on what users need.

Mindmap

mindmap
  root((repo))
    What it does
      Multi-agent coordination
      Agent handoffs
      Task routing
    Key concepts
      Agents with instructions
      Function calling tools
      Stateless design
    Use cases
      Customer support flows
      Specialized agent routing
      Conversation handoffs
    Tech stack
      Python 3.10+
      OpenAI API
      Chat Completions

Things people build with this

USE CASE 1

Build customer support systems where a triage agent routes requests to specialized billing, technical, or refund agents.

USE CASE 2

Create multi-agent workflows where agents hand off conversations based on expertise or task type.

USE CASE 3

Prototype and learn how AI agents can coordinate with each other in a stateless, testable way.

Tech stack

PythonOpenAI API

Getting it running

Difficulty · moderate Time to first run · 30min

Requires OpenAI API key and valid credentials to run agent examples.

Use freely for any purpose including commercial, as long as you keep the copyright notice.

In plain English

Swarm is an experimental, educational Python framework from OpenAI for building systems where multiple AI agents coordinate with one another. An "agent" here means a configured instance of a language model, something with a set of instructions and a set of tools (functions it can call), and "multi-agent orchestration" means writing code that lets those agents hand off control to each other depending on what a user needs. The framework is built around two concepts: Agents and handoffs. You define agents by giving each one instructions and optionally some Python functions it can call. When one agent decides the conversation is better handled by a different agent, it performs a handoff, it returns a reference to the other agent, and Swarm automatically routes the conversation there. This makes it easy to build systems like a customer support flow where a general triage agent routes requests to specialized agents for billing, technical support, or refunds. Swarm is stateless, meaning it does not store conversation history between calls, you manage state yourself, which keeps it simple and testable. It runs on the client side using the standard OpenAI Chat Completions API under the hood. The README notes that Swarm has been superseded by the OpenAI Agents SDK, which is described as the production-ready version, and recommends migrating to that for any real-world use. Swarm remains available as an educational resource for understanding the concepts behind multi-agent coordination. It requires Python 3.10 or later and is installed directly from the GitHub repository using pip.

Copy-paste prompts

Prompt 1
Show me how to define two agents in Swarm and set up a handoff between them for a customer support scenario.
Prompt 2
How do I give a Swarm agent access to Python functions it can call, and what does the handoff syntax look like?
Prompt 3
Create a simple Swarm example with a general agent that routes to a billing specialist agent based on the user's question.
Prompt 4
Explain how Swarm's stateless design works and why I need to manage conversation history myself.
Open on GitHub → Explain another repo

Generated 2026-05-18 · Model: sonnet-4-6 · Verify against the repo before relying on details.