OpenAI Swarm

Type: full-code · Vendor: OpenAI · Language: Python · License: MIT · Status: deprecated · Status in practice: deprecated · First released: 2024-10-10 · Successor: OpenAI Agents SDK

Links: homepage docs repo

Explore an ergonomic, minimal model of multi-agent orchestration where agents are functions, control transfer is just returning another Agent from a tool, and a single client.run() drives the whole loop.

Description. OpenAI Swarm is an MIT-licensed educational framework (not for production) from the OpenAI Solution team. Its API has two primitives: an Agent (name, model, instructions, functions, tool_choice) and a handoff that happens when a function returns another Agent. context_variables flow through every call and can be updated via a Result return. The library is no longer recommended for new code; the README states 'Swarm is now replaced by the OpenAI Agents SDK, which is a production-ready evolution of Swarm. We recommend migrating to the Agents SDK for all production use cases.'

Agent loop shape. Single client.run() loop, analogous to chat.completions.create(). On each turn the current Agent is called, any tool functions execute; if a function returns an Agent, the runner swaps current_agent and continues; if it returns a Result, context_variables update. The loop terminates when the agent produces a plain message with no further handoff or tool call.

Primary use cases

studying minimal multi-agent orchestration as a teaching reference
small experimental routines where agents transfer control by returning each other
porting designs into the OpenAI Agents SDK

flowchart TD CALLER[Caller] --> RUN[client.run<br/>messages + context_variables + current_agent] RUN --> AGENT[current_agent<br/>name + model + instructions + functions] AGENT --> LLM[LLM call] LLM --> DEC{output} DEC -- plain message --> OUT[Final response] DEC -- function call --> FN[Run function] FN -- returns str --> RUN FN -- returns Agent --> SWAP[Swap current_agent] SWAP --> RUN FN -- returns Result --> CTX[Update context_variables] CTX --> RUN

Key concepts

Agent → tool-use (docs) — Bundle of name, model, instructions (string or callable), functions, tool_choice. The unit of behaviour.
Handoff via function return → handoff (docs) — Returning another Agent from a function transfers control to that Agent for the next turn.
context_variables (docs) — Dict-shaped state passed into instructions and functions; persists across handoffs and can be updated via a Result return.
client.run() (docs) — Single-entry runner that drives the loop, analogous to chat.completions.create.

OpenAI Swarm

Neighbourhood

Alternatives & relatives

Listed as alternative by (3)

References

Provenance