Swarm (Experimental, Educational)
A lightweight, ergonomic multi-agent orchestration framework focusing on agent coordination and handoffs.
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.
- 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.
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.
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 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"])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.