OpenAI Agents SDK: Swarm's Production Successor
What it is: OpenAI's own lightweight framework for building multi-agent systems — agents, tools, handoffs between agents, and guardrails, in a small primitive-based API. It's the production-oriented rewrite of Swarm, OpenAI's earlier experimental multi-agent library that was explicitly marked "not for production" and mostly served as a design pattern reference.
Quick answer: If you're already deep in the OpenAI ecosystem and want a small, official, low-abstraction way to run an agent with tools and hand off between specialized sub-agents, the Agents SDK is a lighter option than LangGraph or CrewAI. If you need multi-provider flexibility or explicit graph checkpoints, look elsewhere first.
Why it matters for data work
Data pipelines often need a router: one step decides "is this a schema question, a data-quality question, or a straight SQL request?" and hands off to a specialized agent for each. The SDK's handoff primitive models exactly this — a triage agent that can pass the conversation, with full context, to a narrower agent built and tested for one job — without you hand-rolling the routing logic.
Install & configure
Install the SDK from PyPI:
pip install openai-agentsSet OPENAI_API_KEY in your environment, define an Agent with instructions and a list of tools (plain Python functions), and call Runner.run(agent, input). Tools are registered with type-annotated function signatures, and the SDK generates the tool schema for you rather than requiring hand-written JSON schema.
Agents SDK or LangGraph/CrewAI — which fits?
Pick the Agents SDK when your stack is already OpenAI-centric and you want the smallest official abstraction — fewer concepts to learn than LangGraph's graph model, and no dependency on a third-party orchestration vendor. Pick LangGraph when you need durable checkpoints, mid-run human approval, or heavy branching logic that benefits from being modeled explicitly as a graph rather than a chain of handoffs. Pick CrewAI when the "team of role-based agents" mental model matches how your organization already thinks about the task. The Agents SDK sits between these: more structured than a bare API loop, less ceremonious than a full graph framework.
How do I keep it safe?
Every tool you register is a function the model can call with arguments it generates — treat tool definitions the same way you'd treat any user-facing API endpoint. Use the SDK's guardrail hooks to validate inputs and outputs before a tool call executes or a response returns, scope database credentials passed into tools to read-only access where the agent shouldn't be writing, and log every tool call and handoff so a bad run is reconstructable after the fact.
Troubleshooting
Most early issues come from tool schemas or missing credentials rather than the framework itself.
- Tool call fails with a schema error: the SDK infers the JSON schema from your function's type hints — make sure every parameter is annotated, including optional ones.
- Handoff doesn't preserve context: confirm you're returning the handoff object from the agent's logic rather than just describing the handoff in the instructions text.
- Authentication errors: confirm
OPENAI_API_KEYis set in the process environment the SDK actually runs in, not just your shell. - Unexpected model behavior after an update: pin the SDK and model version together in requirements, since default model behavior can shift between releases.
Author & links
Author: OpenAI
Repo: github.com/openai/openai-agents-python
License: MIT
Related skills
Compare against LangGraph for explicit graph control, or LangChain for its wider integration catalog. For durable, long-running agent execution across process restarts, see Temporal for AI workflows.
← Back to Agent Frameworks