Swarm (Experimental, Educational)
A lightweight, ergonomic multi-agent orchestration framework focusing on agent coordination and handoffs.
- Source repo
- openai/swarm
- Stars
- ★ 22k
- Last updated
- 6mo ago
- License
- MIT
- Primary language
- Python
- FA score
- 51/100 · Major gaps
At a glance
- How it runs
- Works with
- Platform-specificOpenAI API
- Cost
- Free software; you pay for model usage
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- Developers learning to build multi-agent orchestration with function calling and handoffs.
- Not a fit if
- Teams needing a production-ready, maintained framework; this is deprecated
- Teams that must use non-OpenAI or local models
- Developers who need built-in session state and memory management
- Source review
- 51/100 · Major gaps 3 safety controls not found
What does this agent do, and when should you use it?
Swarm is an experimental, educational framework maintained by the OpenAI Solutions team that demonstrates how to build lightweight, highly controllable multi-agent orchestration systems. It is built on two primitive abstractions: Agent and handoffs. An Agent encapsulates instructions and tools, and can hand off a conversation to another Agent at any point. Swarm runs entirely on the client and is stateless between calls, powered entirely by the Chat Completions API. It provides a client.run() method to execute tool calls, handle agent switches, update context variables, and supports streaming responses. The project is deprecated in favor of the OpenAI Agents SDK for production use.
Swarm centers on the Swarm client and Agent class. The client.run() method takes an initial agent and messages, then loops over: getting a completion from the current agent, executing tool calls, switching agents if needed, and updating context variables. Agents can be defined with instructions and functions. Functions can be plain Python functions, and if they return an Agent, execution transfers to that Agent. Swarm automatically converts functions into JSON Schema for Chat Completions tools. It also supports updating context variables via a Result object, streaming via the stream=True parameter, and a demo REPL loop.
- Developers learning to build multi-agent orchestration with function calling and handoffs.
- Scenarios requiring many independent capabilities or instructions that are hard to encode in a single prompt.
- Building customer service bots, such as the airline support example with multiple specialized agents.
- Developers needing a lightweight, testable orchestration layer without fully-hosted threads.
- Educational or prototyping purposes to demonstrate agent transfer and tool invocation.
How do you install or deploy this agent?
Requires Python 3.10+. Install from GitHub with:
pip install git+ssh://[email protected]/openai/swarm.gitor with HTTPS:
pip install git+https://github.com/openai/swarm.gitHow do you use this agent?
Set your OpenAI API key. Then instantiate Swarm client, define agents with instructions and functions, and call client.run with the initial agent and messages. Example:
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"])What are this agent's strengths and limitations?
- Lightweight and stateless, using only the Chat Completions API, making it easy to integrate and test.
- Simple abstractions of Agent and handoffs allow flexible composition of workflows and agent networks.
- Supports streaming and a demo REPL for quick testing and debugging.
- Maintained by the OpenAI team with rich examples covering airline support, weather, and shopping agents.
- Experimental and deprecated; replaced by the OpenAI Agents SDK for production use.
- Locked into OpenAI's API; cannot be used with other model providers.
- Limited documentation and no built-in state management; developers handle session state.
- Requires git and Python 3.10+, and API usage may incur costs.
- Function schema generation may be incomplete, e.g., no per-parameter descriptions.
How does this agent compare with similar options?
Swarm is distinct from OpenAI's Assistants API, which offers fully-hosted threads and built-in memory management. Swarm runs entirely on the client, is stateless, and resembles the Chat Completions API. Officially, production users are advised to migrate to the OpenAI Agents SDK.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Swarm (Experimental, Educational) This agent | 51 · Major gaps | Library / SDKFree + model costs | ★ 22k | 6mo ago | Python | OpenAI API |
| Langroid | 70 · Some gaps | Library / SDKFree + model costs | ★ 4.1k | today | Python | Claude Code · OpenAI API |
| CaveAgent | 62 · Some gaps | Library / SDKFree + model costs | ★ 204 | 1mo ago | Python | OpenAI API · Claude API |
| Agent Craft | 49 · Major gaps | CLIFree + model costs | ★ 516 | 3d ago | Python | OpenAI API |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows: Repository published by official OpenAI organization, MIT license, SECURITY.md provides security policy link. Code allows injectable OpenAI client for mocking, but defaults to real API key, no least privilege or user confirmation. Data flow transparency limited; context_variables and messages documented, but sensitive data handling not addressed. Dependency security: pyproject.toml only lists setuptools, no version pinning, supply chain risk. External effects: tool functions can execute arbitrary Python, but risks not emphasized. Rollback not mentioned. Source attribution clear with contributors listed. Deductions: lack of user confirmation, sensitive data handling, rollback, and dependency pinning.
Evidence shows: Code structure consistent, README matches code examples. Depends on OpenAI Python SDK without version specification, may affect availability. Error handling: docs mention function call errors append error message, but no detailed format. Deductions: dependency version not fixed, error message details insufficient.
Evidence shows: README clearly targets developers, provides multiple example scenarios (basic, triage_agent, weather_agent, etc.). Capability boundaries clear, states Swarm is educational, not for production. Trigger precision: function calling and handoff mechanisms clear. Environment fit: requires Python 3.10+, supports streaming. Deductions: no major flaws, but lacks detailed environment configuration guide.
Evidence shows: README well-structured with install, usage, documentation, examples. Install instructions provided via pip. Naming stable, Agent and Swarm classes consistent. Examples abundant. Known limitations explicit, notes Swarm replaced by Agents SDK. License MIT. Versioning: no CHANGELOG, but README mentions replacement. Maintenance responsibility clear, maintained by OpenAI team. Deductions: missing version changelog.
Evidence shows: Output usability high, returns Response object with messages, agent, context variables. Marginal value high, provides lightweight multi-agent orchestration. Cost-benefit: free open source, but requires OpenAI API key. Deductions: none significant.
Evidence shows: README claims consistent with code examples, traceable. Cross-source corroboration limited, relies on single repository. Fact-inference separation: docs clearly distinguish experimental vs production-ready. Deductions: lack of external verification.
- Not found in source: confirmation before actingTurn on (or add) a confirmation step before it acts, and try it in a sandbox or test environment before real data.
- Not found in source: sensitive-data handlingUse dedicated, low-privilege, revocable API keys — never production credentials — and keep secrets out of logs.
- Not found in source: rollback or recovery pathBack up first, or work on a git branch or snapshot, so its changes can be undone.
- This framework is experimental and not for production; official recommendation is to migrate to Agents SDK.
- Tool functions can execute arbitrary code; carefully design permissions and input validation.
- Dependencies are not version-pinned, posing supply chain risk.
- No user confirmation mechanism; implement for sensitive operations.