OpenAI Swarm — Lightweight Multi-Agent Orchestration

What it is

OpenAI Swarm is an educational multi-agent framework that demonstrates lightweight patterns for orchestrating multiple AI agents. It provides ergonomic agent handoffs, tool calling, and context variables with minimal abstraction over the Chat Completions API. The framework is intentionally simple: agents are functions, handoffs are return values, and context is a shared dictionary.

This tool is for developers learning multi-agent patterns and teams building proof-of-concept agent systems. OpenAI positions it as educational rather than production-grade.

How it saves time or tokens

Swarm strips multi-agent orchestration to its essentials. Instead of complex frameworks with dozens of concepts, Swarm has three: agents, handoffs, and context variables. This makes it fast to prototype and easy to understand. The minimal abstraction means you control exactly what goes to the API, avoiding hidden token costs from framework overhead.

How to use

1. Install Swarm from the OpenAI GitHub repository.
2. Define agents as objects with instructions and functions.
3. Define handoff functions that return other agents.
4. Run the swarm client to orchestrate.

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

Example

from swarm import Swarm, Agent

client = Swarm()

def transfer_to_sales():
    return sales_agent

def transfer_to_support():
    return support_agent

triage_agent = Agent(
    name='Triage',
    instructions='Route the user to the right department.',
    functions=[transfer_to_sales, transfer_to_support]
)

sales_agent = Agent(
    name='Sales',
    instructions='Help the user with pricing and purchases.'
)

support_agent = Agent(
    name='Support',
    instructions='Help the user with technical issues.'
)

response = client.run(
    agent=triage_agent,
    messages=[{'role': 'user', 'content': 'My account is locked'}]
)

print(response.messages[-1]['content'])
# Support agent handles the locked account issue

Related on TokRepo

• Multi-agent frameworks — Swarm deep-dive
• AI agent tools — More agent orchestration tools

Common pitfalls

• Swarm is educational and experimental. OpenAI does not recommend it for production workloads without significant hardening.
• It only works with OpenAI models. There is no built-in support for Anthropic, Google, or local models.
• Agent handoffs lose conversation history by default. Implement context passing explicitly if you need agents to share full conversation state.
• Error handling is minimal. Production systems need retry logic, timeout handling, and fallback strategies.
• The framework has no built-in persistence. Agent state is lost between runs unless you implement storage yourself.
• Review the official documentation before deploying to production to ensure compatibility with your specific environment and requirements.
• Start with default settings and customize incrementally. Changing too many configuration options at once makes debugging harder.