What is the OpenAI Agents SDK?
The OpenAI Agents SDK is OpenAI's open-source, MIT-licensed Python and TypeScript framework for building agents from a few primitives: agents, tools, handoffs, guardrails, sessions and tracing, running inside a team's own application.
Checked
The Agents SDK replaced Swarm, OpenAI's earlier experiment with handoffs between agents, and is the middle option in OpenAI's own three-way choice. The Agents API, in public beta since 10 September 2026, runs agents on a managed Codex harness with OpenAI saving progress. The Responses API is for calling models directly and building everything else. The SDK runs in the team's application, so the team controls deployment, storage, approvals and runtime integration.
The SDK matters more now that OpenAI is retiring other parts of its stack. The Assistants API shut down on 26 August 2026, and Agent Builder and the Evals platform shut down on 30 November 2026. OpenAI points teams to the Agents SDK, the Agents API or the Responses API instead.
How it works
A Runner takes an agent (instructions, a model and tools) and loops: call the model, run any tool calls, feed results back, and stop when the agent returns a final output. Everything else is composition of a few primitives.
Handoffs and agents as tools
A handoff passes control of the conversation to another agent. An agent used as a tool runs a subtask and returns, so the calling agent keeps control.
Guardrails and human-in-the-loop
Input and output checks that can stop a run, and built-in ways to pause for a person before a step goes ahead.
Sessions
Automatic conversation history across runs, with a Redis option among the extras.
Tracing
Every run is traced by default, with model calls, tool calls, handoffs and guardrails recorded for debugging.
Sandbox, realtime and voice agents
Agents preset to work inside a container for long tasks, low-latency realtime agents over WebSocket, and voice pipelines that chain speech-to-text, the agent and text-to-speech.
Version and status, checked 1 November 2026
Versions
Python openai-agents 0.24.0 (15 October 2026) and JavaScript @openai/agents 0.21.0 (20 October 2026). The first Python release, 0.0.1, was on 4 March 2025, and the SDK is still pre-1.0. Python 3.10 or later is required.
Adoption
30,428 GitHub stars on the Python repo and 3,956 on the JavaScript repo, and 4.45M PyPI downloads in the week to 1 November 2026.
Models
OpenAI's Responses and Chat Completions APIs natively. Other providers run through Any-LLM and LiteLLM adapters, which OpenAI's docs describe as beta integrations whose behaviour varies by provider.
When to pick it, and when not to
Pick it for
Teams on OpenAI models that want a thin, code-first framework with handoffs, guardrails and tracing included, and voice or realtime agents, where the SDK has dedicated primitives.
Pick the Agents API instead when
The job is a long-running task the team would rather not host, and a managed Codex harness with saved sessions fits.
Pick the Responses API instead when
The agent is simple enough that a framework adds more than it saves, or the team needs full control of every request.
Look elsewhere when
Several model vendors must work equally well, or the workflow needs durable checkpoints and explicit branching. A model-neutral graph runtime such as LangGraph fits that job more directly.
Migrating from Agent Builder
Teams with Agent Builder workflows have until 30 November 2026. The Agents SDK is the code-first landing point for those flows.
Gotchas from production
Traces go to OpenAI by default
Tracing is on by default and exports to OpenAI's Traces dashboard. It is unavailable to organisations under Zero Data Retention. Disable it with OPENAI_AGENTS_DISABLE_TRACING=1, or add a processor that sends spans to the team's own observability stack.
A 401 with no OpenAI key
Running only non-OpenAI models still tries to upload traces, which fails with a tracing 401 until tracing is disabled or a separate key is set for trace export.
Some tools are Responses-only
Tool search, tool namespaces, deferred loading and programmatic tool calling are rejected on Chat Completions and non-Responses backends, and Responses-only fields such as previous_response_id are dropped silently unless strict feature validation is on.
Adapters vary by provider
Usage metrics may be missing through LiteLLM unless include_usage is set, and providers without JSON schema support can return invalid structured output. OpenAI's docs say to validate the exact backend before deploying.
Pre-1.0 churn
Minor releases can change APIs. Pin the version and run the eval suite on every upgrade.
How Motiontic approaches it
Motiontic's engineers are vendor-neutral. They run a short spike on the client's real task before committing to a framework or store, keep prompts, tool definitions and evals outside the framework so a later switch is a refactor rather than a rewrite, and hand the eval suite to the client's team so the next tooling decision can be measured rather than argued.
OpenAI Agents SDK and its nearest alternatives, checked 1 November 2026
| OpenAI Agents SDK | OpenAI Agents API | Claude Agent SDK | Google ADK | |
|---|---|---|---|---|
| Where it runs | In the team's application | On OpenAI, managed Codex harness | In the team's process, bundles a binary | In the team's process or on Google Cloud |
| State | Team storage, SDK sessions or Responses state | Saved sessions, turns and items on OpenAI | Sessions that resume or fork | Sessions and graph state |
| Integration effort (vendor's own rating) | Medium | Low | Not rated | Not rated |
| Models | OpenAI; others via beta adapters | OpenAI | Claude | Gemini, plus adapters for others |
| Licence | MIT | Hosted service | Anthropic Commercial Terms | Apache-2.0 |
| Latest version | 0.24.0 Python (15 Oct 2026) | Public beta since 10 Sep 2026 | 0.2.176 Python (31 Oct 2026) | 2.13.0 Python (23 Oct 2026) |
| PyPI downloads, week to 1 Nov 2026 | 4.45M | n/a | 8.09M | 2.45M |
Common questions
Is the OpenAI Agents SDK free?
The SDK is open source under the MIT licence. Teams pay for the model calls and any hosted tools it uses.
Can the OpenAI Agents SDK use Claude, Gemini or local models?
Yes, through the Any-LLM and LiteLLM adapters, which OpenAI describes as beta integrations whose behaviour varies by provider. Responses-only tools are not available on those backends.
What is the difference between the Agents SDK and the Agents API?
The SDK runs inside the team's application and the team manages state and deployment. The Agents API, in public beta since 10 September 2026, runs agents on OpenAI's managed Codex harness and saves their progress.
Did the Agents SDK replace Swarm?
Yes. Swarm's README states that it has been replaced by the OpenAI Agents SDK.
How is tracing turned off in the OpenAI Agents SDK?
Set the environment variable OPENAI_AGENTS_DISABLE_TRACING=1, call set_tracing_disabled(True), or set tracing_disabled on a single run's RunConfig.
Related
Claude Agent SDK
Claude Code's harness as a library: the same loop, tools and context management, in a team's own process.
Agent handoff
One agent passes the conversation to another, which carries on from there.
AI guardrails
Checks on what goes into a model, what comes out, and what an agent is allowed to do.
Claude Agent SDK vs LangGraph
Claude Code's harness as a library compared with a model-neutral graph runtime.
AI agent development
Agents that do real work for users, with the evals, traces and guardrails to keep them in production.
Sources
- GitHub, openai/openai-agents-python (30,428 stars, 1 Nov 2026)
- PyPI, openai-agents (0.24.0, 15 Oct 2026)
- OpenAI docs, Agents (Agents API vs Agents SDK vs Responses API)
- OpenAI Agents SDK docs, Tracing
- OpenAI Agents SDK docs, Models (non-OpenAI adapters)
- OpenAI deprecations (Agent Builder and Evals shut down 2026-11-30)
- OpenAI API changelog (Agents API beta 2026-09-10)
- OpenAI Swarm README (replaced by the Agents SDK)
Running agents that have to hold up?
Describe the agent, the systems it touches and what it must never get wrong. The first call is with a lab engineer, who will say plainly whether it is ready for production, and whether Motiontic is the right team.