85 agentic tools audited for security incidents · Talk to the lab →
MotionticBook a call
Tool explainer

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 and its nearest alternatives, checked 1 November 2026
OpenAI Agents SDKOpenAI Agents APIClaude Agent SDKGoogle ADK
Where it runsIn the team's applicationOn OpenAI, managed Codex harnessIn the team's process, bundles a binaryIn the team's process or on Google Cloud
StateTeam storage, SDK sessions or Responses stateSaved sessions, turns and items on OpenAISessions that resume or forkSessions and graph state
Integration effort (vendor's own rating)MediumLowNot ratedNot rated
ModelsOpenAI; others via beta adaptersOpenAIClaudeGemini, plus adapters for others
LicenceMITHosted serviceAnthropic Commercial TermsApache-2.0
Latest version0.24.0 Python (15 Oct 2026)Public beta since 10 Sep 20260.2.176 Python (31 Oct 2026)2.13.0 Python (23 Oct 2026)
PyPI downloads, week to 1 Nov 20264.45Mn/a8.09M2.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.

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.