# OpenAI Agents SDK

> Source: https://aiwiki.ai/wiki/openai_agents_sdk
> Updated: 2026-06-21
> Categories: AI Agents, Developer Tools, OpenAI
> From AI Wiki (https://aiwiki.ai), a free encyclopedia of artificial intelligence. Quote with attribution.

The **OpenAI Agents SDK** is an open-source, lightweight framework developed by [OpenAI](/wiki/openai) for building [multi-agent systems](/wiki/multi_agent_system) and [agentic workflows](/wiki/agentic_workflow), built around four core primitives: agents, handoffs, guardrails, and tracing. Released on March 11, 2025 under the MIT license, it is the production-ready successor to [OpenAI Swarm](/wiki/openai_swarm), an experimental educational framework that OpenAI introduced in October 2024.[^1][^7] The SDK provides a Python-first (and later TypeScript) toolkit for orchestrating [AI agents](/wiki/ai_agents) that can use tools, hand off tasks to other agents, validate inputs and outputs through guardrails, and be monitored through built-in tracing. OpenAI designed it with "enough features to be worth using, but few enough primitives to make it quick to learn."[^2] It is hosted on GitHub, where it has accumulated 26,400+ stars and 4,000+ forks as of May 2026.[^3]

The SDK underwent its most significant overhaul on April 15, 2026 with the "Next Evolution of the Agents SDK" release, which introduced native sandbox execution, a long-horizon harness, a subagent primitive (beta), and a planned code mode. These additions reposition the SDK from a multi-agent orchestrator into a complete agent infrastructure stack capable of running Codex-style coding agents on real codebases.[^21][^22][^23]

## When was the OpenAI Agents SDK released?

### OpenAI Swarm (October 2024)

In October 2024, OpenAI quietly released Swarm, an experimental, educational framework for multi-agent orchestration. Swarm was built on top of [OpenAI](/wiki/openai)'s Chat Completions API and introduced two core abstractions: **routines** (sets of instructions and tools for an agent) and **handoffs** (the ability for one agent to transfer a conversation to another agent). OpenAI explicitly described Swarm as a research and educational tool rather than a production-ready product. Shyamal Anadkat, a researcher at OpenAI, said at the time: "Think of it more like a cookbook. It's experimental code for building simple agents. It's not meant for production and won't be maintained by us."[^7][^8]

Despite its experimental status, Swarm attracted significant developer attention. It demonstrated that [multi-agent systems](/wiki/multi_agent_system) could be built with minimal abstraction, an idea that influenced the broader [AI agent](/wiki/ai_agents) framework ecosystem.

### Launch of the Agents SDK (March 2025)

On March 11, 2025, OpenAI released the Agents SDK as part of a broader announcement that also introduced the Responses API, built-in tools for web search, file search, and [computer use](/wiki/computer_use), and observability tracing.[^1][^9][^10] The Agents SDK replaced Swarm with a production-grade framework, retaining Swarm's core philosophy of lightweight, ergonomic multi-agent orchestration while adding the reliability, tooling, and features needed for real-world deployment.

The initial release was Python-only (package name: `openai-agents`), with a TypeScript/JavaScript version following in June 2025.[^6] Both SDKs support the same core primitives: agents, handoffs, guardrails, and tracing.

### AgentKit and DevDay (October 2025)

At OpenAI's DevDay on October 6, 2025, the company announced **AgentKit**, a higher-level toolkit built on top of the Agents SDK.[^4] While the Agents SDK provides foundational, open-source primitives for building agents, AgentKit adds enterprise-oriented features:

- **Agent Builder**: a visual drag-and-drop canvas for composing multi-agent workflows, with support for preview runs, inline evaluation configuration, and full versioning.
- **ChatKit**: embeddable UI components for shipping agent experiences inside an application.
- **Connector Registry**: an admin-controlled directory for securely connecting agents to internal tools and third-party systems.
- **Evals for Agents**: step-by-step trace grading, datasets for assessing individual agent components, automated prompt optimization, and the ability to run evaluations on external models.

To demonstrate ease of use, an OpenAI engineer built an entire AI workflow and two AI agents live on stage in under eight minutes during the DevDay keynote.[^4] The Agents SDK and AgentKit are complementary: the SDK handles low-level orchestration, while AgentKit provides the tooling to ship and iterate on agents faster in production environments.

### The next evolution (April 2026)

On April 15, 2026, OpenAI shipped what it described as the "next evolution" of the Agents SDK, an update intended to address the two largest enterprise blockers reported by SDK users: safety and complexity in long-horizon work.[^21][^22] Karan Sharma of OpenAI's product team summarized the launch as "taking our existing Agents SDK and making it so it's compatible with all of these sandbox providers."[^22]

The release introduced four new capability areas:

| Capability | Status (April 2026) | Purpose |
|---|---|---|
| **Native sandbox execution** | GA (Python) | Run agent-generated code in isolated, controlled environments |
| **Model-native harness** | GA (Python) | Configurable memory and orchestration for long-horizon work on frontier models |
| **Subagents** | Beta, Python first | Runtime primitive for spawning specialized child agents |
| **Code mode** | Planned (Python and TypeScript) | Codex-style code generation and execution as a first-class agent capability |

TypeScript support for the new harness, sandbox, code mode, and subagent primitives is planned for a later release without a public timeline.[^21][^23] All four capabilities are available to every SDK customer through the standard OpenAI API at standard pricing, with no premium tier or enterprise gate on the core features.[^22]

### Current status (May 2026)

As of May 12, 2026, the Python SDK is at version **0.17.2**, with frequent patch releases since the April overhaul.[^15][^25] The TypeScript SDK (`@openai/agents`) reached version 0.11.4 over the same period.[^26] The SDK is one of the three most widely adopted open-source agent frameworks alongside [LangChain](/wiki/langchain) / LangGraph and [CrewAI](/wiki/crewai), and OpenAI has positioned it (together with AgentKit and the Responses API) as the long-term successor to the Assistants API, which is scheduled for deprecation in mid-2026.[^5]

## How is the OpenAI Agents SDK designed?

The OpenAI Agents SDK is built around two guiding principles that OpenAI states directly in its documentation. The first is "enough features to be worth using, but few enough primitives to make it quick to learn"; the second is that the SDK "works great out of the box, but you can customize exactly what happens."[^2] In practice these translate to:

1. **Minimalism with power.** The framework uses few abstractions so developers can learn and start building quickly. Orchestration is handled through plain Python (or TypeScript) code rather than domain-specific configuration languages.
2. **Opinionated defaults with flexibility.** Sensible defaults allow developers to get started immediately, while nearly every component can be customized or replaced for advanced use cases.

The SDK operates through an **agent loop**: a central execution cycle managed by the `Runner` class. When an agent is run, the loop repeatedly calls the [language model](/wiki/large_language_model), executes any requested [tool calls](/wiki/tool_use), processes handoffs to other agents, and checks guardrails until the agent produces a final output. The loop terminates when the LLM produces text output of the expected type without requesting further tool calls.

Since v0.16.0 (May 2026), the implicit default model is `gpt-5.4-mini` (replacing `gpt-4.1`), with GPT-5-family defaults including `reasoning.effort="none"` and `verbosity="low"`.[^25] Applications that did not pin a model will pick up the new defaults on upgrade.

## What are the core primitives of the OpenAI Agents SDK?

The original Agents SDK was organized around four core primitives: **agents**, **handoffs**, **guardrails**, and **tracing**. The April 2026 release added **sandbox agents** and **subagents** as additional first-class primitives, with **code mode** planned.[^11][^12][^13][^21]

### Agents

Agents are the fundamental building blocks. Each agent is an [LLM](/wiki/large_language_model) configured with instructions, tools, and optional runtime behaviors such as handoffs, guardrails, and structured outputs.

| Property | Required | Description |
|---|---|---|
| `name` | Yes | A human-readable identifier for the agent |
| `instructions` | Yes | System prompt (static string or dynamic callback function) |
| `model` | No | Which LLM to use (defaults to a configured OpenAI model, currently `gpt-5.4-mini`) |
| `tools` | No | List of tools the agent can invoke |
| `handoffs` | No | List of agents this agent can delegate to |
| `output_type` | No | Pydantic model, dataclass, or TypedDict for structured output |
| `model_settings` | No | Temperature, top_p, reasoning effort, retry settings, and other model parameters |
| `input_guardrails` | No | Guardrails to validate user input |
| `output_guardrails` | No | Guardrails to validate agent output |

A minimal agent example in Python:

```python
from agents import Agent, Runner

agent = Agent(
    name="Assistant",
    instructions="You are a helpful assistant."
)
result = Runner.run_sync(agent, "Write a haiku about recursion.")
print(result.final_output)
```

Agents support two multi-agent patterns:

- **Manager pattern:** A central agent invokes sub-agents as tools, retaining overall control of the conversation.
- **Handoff pattern:** Peer agents delegate to specialists who take over the conversation entirely.

Agents also have lifecycle hooks (`on_agent_start`, `on_agent_end`, `on_llm_start`, `on_tool_end`, `on_handoff`) that allow developers to observe and react to events during execution. The `clone()` method allows creating agent variants with modified properties.

### Handoffs

Handoffs allow one agent to delegate a task to another agent. They are the primary mechanism for building [multi-agent systems](/wiki/multi_agent_system) where different agents specialize in different domains. Internally, handoffs are represented as tools exposed to the LLM. For example, if there is a handoff to an agent named "Refund Agent," the model sees a tool called `transfer_to_refund_agent`.[^11]

Handoffs accept several configuration options:

| Option | Description |
|---|---|
| `agent` | The target agent to hand off to |
| `tool_name_override` | Custom name for the handoff tool |
| `tool_description_override` | Custom description for the handoff tool |
| `on_handoff` | Callback function executed during the handoff |
| `input_type` | Pydantic schema for structured metadata the model must provide |
| `input_filter` | Modifies conversation history passed to the next agent |
| `is_enabled` | Boolean or function controlling whether the handoff is available |

A triage agent that can hand off to specialized agents:

```python
from agents import Agent, handoff

billing_agent = Agent(name="Billing agent", instructions="Handle billing questions.")
refund_agent = Agent(name="Refund agent", instructions="Process refund requests.")

triage_agent = Agent(
    name="Triage agent",
    instructions="Route customer queries to the right specialist.",
    handoffs=[billing_agent, handoff(refund_agent)]
)
```

The `input_type` parameter allows the model to pass structured metadata during a handoff. This is useful for passing small pieces of information like the reason for escalation, the customer's language, or a priority level. Input filters (available through `agents.extensions.handoff_filters`) can modify or trim conversation history before passing it to the next agent, which is important for managing context length in long conversations.

Handoffs remain within a single run. Input guardrails only apply to the first agent in the chain, and output guardrails only apply to the final agent. Starting in v0.6.0, handoff history is packaged into a single assistant message, and v0.7.0 disabled nested handoff history by default to keep transcripts compact.[^15]

### Subagents

**Subagents**, introduced in beta with the April 2026 release, formalize a pattern that many teams had been building by hand on top of handoffs. Instead of writing a custom orchestration loop and message bus, developers declare a parent agent that can spawn specialized child agents for sub-tasks: a planning agent that delegates research to a specialized searcher, hands code changes to an editor agent, passes tests to a verifier, and synthesizes the result.[^21][^24] The runtime manages parallel execution, message routing, and result aggregation. OpenAI's stated motivation is that this pattern "consistently outperforms monolithic agents on long-horizon tasks." Subagents launched in Python first, with TypeScript support planned.

Subagents differ from handoffs in two ways. First, control returns to the parent after the subagent finishes, rather than the conversation transferring permanently. Second, subagents can be invoked in parallel, whereas handoffs are sequential by design.

### Guardrails

Guardrails provide input and output validation to constrain agent behavior and prevent unsafe or malformed responses.[^12] The SDK supports three types of guardrails:

**Input guardrails** validate user input before or during agent execution. By default, they run in parallel with the agent (for lower latency), but can be configured to run in blocking mode (completing before the agent starts). When an input guardrail detects a violation, it triggers a tripwire that raises an `InputGuardrailTripwireTriggered` exception and halts execution.

**Output guardrails** validate the final output of an agent. They always run after the agent completes and apply only to the last agent in a handoff chain. They follow the same tripwire mechanism as input guardrails. Since v0.15.0, model refusals surface explicitly as `ModelRefusalError` rather than as empty text, and applications must register `model_refusal` run error handlers to manage refusals without exceptions.[^25]

**Tool guardrails** wrap [function tool](/wiki/function_calling) invocations. Input tool guardrails run before the tool executes and can skip the call or reject the output. Output tool guardrails run after execution and can replace results or trigger tripwires.

Example of an input guardrail:

```python
from agents import Agent, GuardrailFunctionOutput, input_guardrail, Runner

@input_guardrail
async def math_homework_guardrail(ctx, agent, input):
    result = await Runner.run(guardrail_agent, input, context=ctx.context)
    return GuardrailFunctionOutput(
        output_info=result.final_output,
        tripwire_triggered=result.final_output.is_math_homework
    )

agent = Agent(
    name="Support Agent",
    instructions="Help customers with their questions.",
    input_guardrails=[math_homework_guardrail]
)
```

### Tracing

The SDK includes built-in tracing that automatically records events during an agent run.[^13] Traces capture [LLM](/wiki/large_language_model) generations, [tool calls](/wiki/tool_use), handoffs, guardrail evaluations, speech-to-text transcriptions, sandbox executions, and custom events.

Tracing is enabled by default. Each `Runner.run()` invocation is wrapped in a trace named "Agent workflow" by default. Traces contain spans, which represent individual operations with timestamps and parent relationships. Span types include agent, generation, function, guardrail, handoff, sandbox, and custom.

Traces are displayed in the OpenAI Traces dashboard, where developers can debug, visualize, and monitor workflows during development and in production. The tracing system also supports sensitive data controls: generation and function spans can optionally exclude LLM inputs/outputs and function call details.

The tracing system integrates with over 20 third-party observability platforms, including Weights & Biases, Arize Phoenix, MLflow, Langfuse, and LangSmith. Non-OpenAI models can use a free OpenAI API key for dashboard access through `set_tracing_export_api_key()`.

Tracing can be disabled globally via the environment variable `OPENAI_AGENTS_DISABLE_TRACING=1`, programmatically with `set_tracing_disabled(True)`, or per-run using `RunConfig.tracing_disabled`.

### Sandbox agents and the harness

The April 2026 release introduced **Sandbox Agents**, a beta SDK surface that gives the standard `Agent` and `Runner` flow a persistent, isolated workspace.[^21][^23][^24] A sandbox agent can inspect files, run shell commands, edit repositories, apply patches, generate artifacts, take snapshots, and resume work across runs. The sandbox primitive is paired with what OpenAI calls a **model-native harness**: configurable memory, sandbox-aware orchestration, Codex-style filesystem tools, and standardized integrations with the primitives now common in frontier coding agents.[^21]

The sandbox layer is built around a **Manifest** abstraction that describes the agent's workspace in a portable way: the container image, environment variables, mounted local files and directories, exposed tools, output directories, and access policies. The Manifest is paired with an `AGENTS.md` markdown file at the repo root that defines conventions, test commands, restricted zones, and custom instructions for the agent.[^24]

Sandbox agents support multiple execution backends, all selectable through a uniform interface:

| Backend | Type | Use case |
|---|---|---|
| `UnixLocalSandboxClient` | Local Unix process | Fast local development without containers |
| `DockerSandboxClient` | Local Docker container | Container isolation on a developer machine |
| `BlaxelSandboxClient` | Hosted | Long-running enterprise agents |
| `CloudflareSandboxClient` | Hosted | Edge sandbox execution |
| `DaytonaSandboxClient` | Hosted | Low cold-start latency |
| `E2BSandboxClient` | Hosted | Iterative Python with shared state |
| `ModalSandboxClient` | Hosted | GPU and high-compute workloads |
| `RunloopSandboxClient` | Hosted | Production agent sandboxes |
| `VercelSandboxClient` | Hosted | Bursty, I/O-heavy serverless workloads |

The seven hosted providers (Blaxel, Cloudflare, Daytona, E2B, Modal, Runloop, and Vercel) are available as optional install extras.[^21][^23] Developers can also bring their own sandbox implementation by implementing the SandboxClient interface. Workspaces can mount files from object storage providers including AWS S3, Google Cloud Storage, Azure Blob Storage, and Cloudflare R2.[^24]

Since v0.17.0, local sandbox source materialization keeps `LocalFile.src` and `LocalDir.src` artifacts inside the materialization `base_dir` unless an application explicitly grants outside-access through a `SandboxPathGrant` on the manifest. This change tightens the default security boundary for trusted host files copied into the sandbox.[^25]

A new **`apply_patch`** filesystem tool is built into the harness. Rather than asking the model to write a full file (which costs tokens and risks unintended regressions), the model produces a minimal diff that the SDK applies atomically through a robust parser, an approach popularized by [Claude Code](/wiki/claude_code).[^24]

### Code mode (planned)

**Code mode**, announced alongside the April 2026 release and not yet shipped, will give agents specialized code execution and generation abilities as a first-class capability, rather than a tool layered on top of a generic agent.[^21][^24] OpenAI's stated goal is a Codex-style autonomous developer experience built directly into the SDK. The feature is planned for both Python and TypeScript, but no public ship date has been announced.

## Tools

Agents in the SDK can use several types of tools:[^14]

| Tool type | Description |
|---|---|
| `FunctionTool` | Any Python function wrapped with the `@function_tool` decorator; schemas are auto-generated from type hints |
| `WebSearchTool` | Built-in hosted tool for web search (OpenAI models only) |
| `FileSearchTool` | Built-in hosted tool for searching uploaded documents (OpenAI models only) |
| `ComputerTool` | Built-in tool for interacting with computer interfaces (GA since v0.11.0) |
| `CodeInterpreterTool` | Hosted tool for executing code in a sandboxed environment |
| `ImageGenerationTool` | Hosted tool for generating images |
| `HostedMCPTool` | Tools hosted on external MCP servers |
| `LocalShellTool` | OpenAI-hosted container execution for shell commands |
| `apply_patch` | Diff-based filesystem editing tool (sandbox harness) |

Function tools are the most common custom tool type. The `@function_tool` decorator automatically generates a JSON schema from the function's type hints and docstring:

```python
from agents import Agent, function_tool

@function_tool
def get_weather(city: str) -> str:
    """Returns weather info for the specified city."""
    return f"The weather in {city} is sunny."

agent = Agent(
    name="Weather Agent",
    instructions="Provide weather information.",
    tools=[get_weather]
)
```

Since v0.8.0, synchronous function tools run on worker threads to avoid blocking the event loop, and MCP tool failure handling is configurable.[^15] v0.16.0 added tool execution concurrency controls and optional server-prefixed naming for MCP tools to prevent name collisions.[^25]

### Model Context Protocol (MCP)

The SDK has first-class support for the [Model Context Protocol](/wiki/model_context_protocol) (MCP) for connecting agents to external tool providers. Three types of MCP server implementations are supported: hosted MCP server tools, Streamable HTTP MCP servers (local or remote), and Stdio MCP servers. Since v0.16.1, the SDK validates MCP `require_approval` policies before invoking sensitive tools, and v0.13.0 added resource-management methods for managing MCP-hosted assets.[^15][^25]

## Running agents

The `Runner` class provides three methods for executing agents:

| Method | Description |
|---|---|
| `Runner.run()` | Asynchronous execution; returns a `RunResult` when complete |
| `Runner.run_sync()` | Synchronous wrapper around `Runner.run()` for simpler scripts |
| `Runner.run_streamed()` | Streams events in real time; returns a `RunResultStreaming` |

The agent loop works as follows:

1. The agent is invoked with the given input.
2. If the LLM produces a final output (text matching the agent's `output_type` with no tool calls), the loop terminates.
3. If the LLM requests a handoff, the loop continues with the new agent.
4. If the LLM requests tool calls, the tools are executed and results are fed back to the LLM. The loop repeats.

Streaming mode (`Runner.run_streamed()`) emits `StreamEvent` objects in real time. Two event types are available: `RawResponsesStreamEvent` (raw events from the LLM in OpenAI Responses API format, such as `response.output_text.delta`) and `RunItemStreamEvent` (higher-level events like `tool_called`, `tool_output`, and `message_output_created`). Since v0.16.0, the SDK supports a `max_turns=None` option to disable the run's turn limit, which is useful for long-horizon sandbox agents.[^25]

## Sessions and memory

The Agents SDK provides a `Session` object for managing conversation context across multiple runs.[^20] Sessions are important because [AI agents](/wiki/ai_agents) often operate in long-running, multi-turn interactions where carrying too much context forward leads to distraction and increased costs, while preserving too little causes the agent to lose coherence.

Sessions support context management techniques including trimming (removing older messages) and compression (summarizing prior conversation). Persistence backends include in-memory (default), SQLite (via `AsyncSQLiteSession`), MongoDB, and Redis (the `[redis]` extra), allowing production deployments to share session state across instances.[^25] v0.16.1 fixed session history restoration after a compaction failure, and v0.17.1 addressed corrupt item handling and MongoDB metadata timestamps.

## Human-in-the-loop

The SDK supports human-in-the-loop approval mechanisms that allow developers to pause tool execution, serialize and store agent state, approve or reject specific tool calls, and resume the agent run. Tools can be configured to require approval by setting a `needsApproval` option to `true` or to an async function that returns a boolean.

When a tool invocation requires approval, the SDK pauses the run and returns pending approvals in an interruptions array. Developers can approve or reject each pending item, optionally setting sticky decisions (`alwaysApprove` or `alwaysReject`) that persist for the rest of the run.

## Voice and realtime agents

The SDK supports building voice agents through the `RealtimeAgent` class, which integrates with [OpenAI](/wiki/openai)'s Realtime API. The default Realtime model is `gpt-realtime-2` as of v0.17.0 (May 2026), replacing the prior `gpt-realtime-1.5` default introduced in v0.13.0.[^25] Voice agents support low-latency speech-to-speech interactions with automatic interruption detection, context management, guardrails, and handoffs between agents.

The TypeScript SDK automatically selects the appropriate transport: WebRTC for browser environments and WebSockets for server-side applications. Voice agents support the same core primitives (tools, handoffs, guardrails) as text-based agents. v0.5.0 added SIP protocol support for `RealtimeRunner`, enabling integration with telephony providers for phone-based agents.[^15]

## Is the OpenAI Agents SDK model-agnostic?

While the SDK is developed by [OpenAI](/wiki/openai) and works best with OpenAI models (through both the Responses API and Chat Completions API), it is designed to be provider-agnostic. The SDK supports over 100 alternative [language models](/wiki/large_language_model) through LiteLLM integration, including models from [Anthropic](/wiki/anthropic) ([Claude](/wiki/claude)), [Google](/wiki/google_deepmind) ([Gemini](/wiki/gemini)), [DeepSeek](/wiki/deepseek), Meta (Llama), Mistral, and others.[^3]

There are limitations when using non-OpenAI providers. Hosted tools (web search, file search, code interpreter) are only available with OpenAI models. Tracing dashboard integration may require additional configuration. Not all SDK features work identically across providers.

## Installation and requirements

The SDK requires Python 3.10 or newer (Python 3.9 was dropped in v0.9.0; Python 3.14 compatibility was added in v0.5.0) and is installed via pip or uv:[^15]

```bash
pip install openai-agents
```

Optional extras include:

| Extra | Purpose |
|---|---|
| `[voice]` | Voice and realtime agent support |
| `[redis]` | Redis-backed session persistence |
| `[blaxel]`, `[cloudflare]`, `[daytona]`, `[e2b]`, `[modal]`, `[runloop]`, `[vercel]` | Hosted sandbox provider clients |

The SDK depends on the OpenAI Python package version 2.x (since v0.4.0); the older 1.x is no longer supported. An `OPENAI_API_KEY` environment variable must be set for use with OpenAI models.

The TypeScript version is available as a separate package, `@openai/agents`, on npm. The latest TypeScript release as of May 2026 is v0.11.4.[^26]

## How does the OpenAI Agents SDK compare to LangGraph and CrewAI?

The OpenAI Agents SDK competes with several other [AI agent](/wiki/ai_agents) frameworks. Each takes a different approach to agent orchestration.[^17][^18]

| Feature | OpenAI Agents SDK | [LangChain](/wiki/langchain) / LangGraph | [CrewAI](/wiki/crewai) | [Claude Agent SDK](/wiki/claude_agent_sdk) |
|---|---|---|---|---|
| Primary abstraction | Handoffs, sandboxes, subagents | Graph-based state machines | Role-based crews | Hooks and subagents |
| Model support | OpenAI-first, 100+ via LiteLLM | Model-agnostic from the start | Model-agnostic | Claude-first |
| Learning curve | Low (minimal abstractions) | Moderate to high | Low to moderate | Low to moderate |
| Multi-agent pattern | Handoff-based delegation, subagents | Graph-based control flow | Role-based collaboration | Hierarchical subagents |
| Built-in tracing | Yes (OpenAI dashboard) | Via LangSmith | Via third-party tools | Via Anthropic console |
| Voice agent support | Yes (RealtimeAgent) | No native support | No native support | No native support |
| Native sandbox execution | Yes (7 hosted providers + Docker + Unix) | Via integrations | Via integrations | Via integrations |
| MCP support | Yes (first-class) | Yes (via integrations) | Yes (first-class) | Yes (first-class) |
| Hosted tools | Web search, file search, code interpreter, computer use, image generation | No hosted tools | No hosted tools | No hosted tools |
| GitHub stars (May 2026) | 26,400+ | 47,000+ (LangChain core) | 44,000+ | Newer, growing |
| License | MIT | MIT | MIT | MIT |

**When to choose OpenAI Agents SDK:** Best for teams already using OpenAI models who want minimal abstractions, built-in hosted tools, voice agent support, native sandbox execution with seven hosted providers, and a fast path from prototype to production. The April 2026 sandbox and harness features make it especially competitive for coding agents and long-horizon work.

**When to choose LangGraph:** Best for complex, stateful workflows that require graph-based control flow, built-in checkpointing, and model-agnostic design. Has the largest ecosystem and community.

**When to choose CrewAI:** Best for role-based multi-agent collaboration where agents need distinct personalities and skillsets. Fastest growing for multi-agent use cases.

**When to choose Claude Agent SDK:** Best for deep [Anthropic](/wiki/anthropic) [Claude](/wiki/claude) integration, hooks-based behavioral control, and leveraging the MCP tool ecosystem with local-first design.

## What is the OpenAI Agents SDK used for?

The OpenAI Agents SDK has been adopted across a range of applications:[^1][^16][^19]

- **Customer support automation:** OpenAI provides an official demo with specialized agents for triage, flight information, booking and cancellation, seat assignment, FAQ, and refunds. Klarna built a support agent using OpenAI tools that handles two-thirds of all customer tickets.
- **Sales and prospecting:** Clay used OpenAI agent tools to build a sales agent that contributed to 10x growth.
- **Cryptocurrency and finance:** Coinbase used the Agents SDK to prototype and deploy agents that interact with crypto wallets and on-chain activities.
- **Enterprise search and knowledge:** Box integrated the Agents SDK with web search to enable enterprises to query and extract insights from unstructured data.
- **Research and deep analysis:** The SDK supports multi-step research workflows where agents gather information, analyze data, and produce structured reports.
- **Voice interfaces:** The RealtimeAgent feature enables spoken customer service, voice assistants, and interactive voice response systems through speech-to-speech models.
- **Coding agents (April 2026 onward):** The sandbox-and-harness layer supports Codex-style autonomous coding agents that inspect repositories, run commands, edit files via `apply_patch`, and verify changes inside isolated environments.
- **Agentic commerce:** The Agents SDK is the reference implementation for OpenAI's side of the **Agentic Commerce Protocol** (ACP), co-developed with Stripe. ACP lets ChatGPT users buy directly from Etsy and (rolling out) over a million Shopify merchants such as Glossier, Vuori, Spanx, and SKIMS through agent-initiated checkouts using Stripe Shared Payment Tokens.[^27]

## How does the OpenAI Agents SDK relate to the Responses API?

The OpenAI Agents SDK is designed to work with the Responses API, which OpenAI released on the same day (March 11, 2025).[^1] The Responses API combines the simplicity of the Chat Completions API with the tool-use capabilities of the Assistants API, providing first-party support for web search, file search, and [computer use](/wiki/computer_use) as built-in tools. OpenAI framed the API as foundational for agents: "With a single Responses API call, developers will be able to solve increasingly complex tasks using multiple tools and model turns."[^9]

The Responses API is the server-side API that provides built-in tools and model access, while the Agents SDK is the client-side library that orchestrates multi-agent workflows on top of it. The SDK also works with the Chat Completions API for backwards compatibility.

OpenAI has announced plans to deprecate the Assistants API, with a target sunset date in mid-2026, directing developers to migrate to the Responses API and Agents SDK.[^5]

## Version history

Selected releases from the OpenAI Agents SDK (Python):[^15][^25]

| Version | Date (approx.) | Notable changes |
|---|---|---|
| 0.1.0 | mid-2025 | Initial release; added `run_context` and `agent` parameters to MCP server tool listing |
| 0.2.0 | 2025 | `Agent` replaced with `AgentBase` in type signatures |
| 0.3.0 | 2025 | Migrated to `gpt-realtime` model GA version |
| 0.4.0 | 2025 | Dropped support for openai package v1.x; v2.x required |
| 0.5.0 | 2025 | Added SIP protocol support for `RealtimeRunner`; Python 3.14 compatibility |
| 0.6.0 | 2025 | Handoff history packaged into a single assistant message |
| 0.7.0 | 2025 | Nested handoff history disabled by default; default reasoning effort for GPT-5.x changed |
| 0.8.0 | late 2025 | Synchronous function tools run on worker threads; configurable MCP tool failure handling |
| 0.9.0 | late 2025 | Dropped Python 3.9 support; narrowed type hint for `Agent.as_tool()` |
| 0.10.0 | early 2026 | WebSocket transport for Responses API; new streaming examples |
| 0.11.0 | early 2026 | Tool search support with namespaces; `ComputerTool` reached GA |
| 0.12.0 | early 2026 | Retry settings for model API calls via `ModelSettings` |
| 0.13.0 | March 2026 | Default Realtime model updated to `gpt-realtime-1.5`; MCP resource management methods |
| 0.14.0 | April 15, 2026 | **Sandbox Agents (beta)**: workspace manifests, sandbox clients (Unix, Docker, 7 hosted providers), snapshots, resume support |
| 0.15.0 | April 2026 | Model refusals surface as `ModelRefusalError` instead of empty text |
| 0.16.0 | May 7, 2026 | Default model switched to `gpt-5.4-mini`; `max_turns=None` option; tool execution concurrency; server-prefixed MCP tool naming |
| 0.16.1 | May 7, 2026 | Stabilized chat completions stream output indexing; MCP `require_approval` validation; session restoration after compaction |
| 0.17.0 | May 8, 2026 | Default RealtimeAgent model is `gpt-realtime-2`; sandbox source materialization constrained to base dir; Responses context-management fixes |
| 0.17.1 | May 11, 2026 | Sandbox archive extraction limits; git repo subpath validation; MongoDB and corrupt-item session fixes |
| 0.17.2 | May 12, 2026 | OpenAI Conversations reasoning persistence; realtime auto-response and tracing shutdown fixes |

## See also

- [Agent Builder (OpenAI AgentKit)](/wiki/agent_builder)
- [AI agents](/wiki/ai_agents)
- [Multi-agent system](/wiki/multi_agent_system)
- [OpenAI](/wiki/openai)
- [OpenAI Swarm](/wiki/openai_swarm)
- [Function calling](/wiki/function_calling)
- [Tool use](/wiki/tool_use)
- [Model Context Protocol](/wiki/model_context_protocol)
- [LangChain](/wiki/langchain)
- [CrewAI](/wiki/crewai)
- [Claude Agent SDK](/wiki/claude_agent_sdk)
- [Agentic workflow](/wiki/agentic_workflow)
- [Computer use](/wiki/computer_use)
- [Codex](/wiki/codex)

## References

[^1]: OpenAI. "New tools for building agents." OpenAI Blog, March 11, 2025. https://openai.com/index/new-tools-for-building-agents/
[^2]: OpenAI. "OpenAI Agents SDK Documentation." https://openai.github.io/openai-agents-python/
[^3]: OpenAI. "openai/openai-agents-python." GitHub. https://github.com/openai/openai-agents-python
[^4]: OpenAI. "Introducing AgentKit." OpenAI Blog, October 6, 2025. https://openai.com/index/introducing-agentkit/
[^5]: OpenAI. "OpenAI for Developers in 2025." https://developers.openai.com/blog/openai-for-developers-2025/
[^6]: OpenAI. "Updates to building agents: Typescript Agents SDK, a new RealtimeAgent feature for voice agents, Traces for Realtime, and speech-to-speech improvements." OpenAI Developer Community, June 2025. https://community.openai.com/t/updates-to-building-agents-typescript-agents-sdk-a-new-realtimeagent-feature-for-voice-agents-traces-for-realtime-and-speech-to-speech-improvements/1277152
[^7]: OpenAI. "openai/swarm: Educational framework exploring ergonomic, lightweight multi-agent orchestration." GitHub. https://github.com/openai/swarm
[^8]: Sergiu Nisioi. "OpenAI Releases Swarm: An Experimental Open-Source Framework for Multi-Agent Orchestration." InfoQ, October 2024. https://www.infoq.com/news/2024/10/openai-swarm-orchestration/
[^9]: Sean Michael Kerner. "OpenAI Launches New API, SDK, and Tools to Develop Custom Agents." InfoQ, March 2025. https://www.infoq.com/news/2025/03/openai-responses-api-agents-sdk/
[^10]: Carl Franzen. "OpenAI unveils Responses API, open source Agents SDK, letting developers build their own Deep Research and Operator." VentureBeat, March 2025. https://venturebeat.com/programming-development/openai-unveils-responses-api-open-source-agents-sdk-letting-developers-build-their-own-deep-research-and-operator/
[^11]: OpenAI. "Handoffs - OpenAI Agents SDK." https://openai.github.io/openai-agents-python/handoffs/
[^12]: OpenAI. "Guardrails - OpenAI Agents SDK." https://openai.github.io/openai-agents-python/guardrails/
[^13]: OpenAI. "Tracing - OpenAI Agents SDK." https://openai.github.io/openai-agents-python/tracing/
[^14]: OpenAI. "Tools - OpenAI Agents SDK." https://openai.github.io/openai-agents-python/tools/
[^15]: OpenAI. "Release process/changelog - OpenAI Agents SDK." https://openai.github.io/openai-agents-python/release/
[^16]: Mem0. "OpenAI Agents SDK Review (December 2025)." https://mem0.ai/blog/openai-agents-sdk-review
[^17]: Langfuse. "Comparing Open-Source AI Agent Frameworks." March 2025. https://langfuse.com/blog/2025-03-19-ai-agent-comparison
[^18]: Composio. "OpenAI Agents SDK vs LangGraph vs Autogen vs CrewAI." https://composio.dev/blog/openai-agents-sdk-vs-langgraph-vs-autogen-vs-crewai
[^19]: OpenAI. "A practical guide to building agents." https://cdn.openai.com/business-guides-and-resources/a-practical-guide-to-building-agents.pdf
[^20]: OpenAI. "Context Engineering - Short-Term Memory Management with Sessions from OpenAI Agents SDK." OpenAI Cookbook. https://cookbook.openai.com/examples/agents_sdk/session_memory
[^21]: OpenAI. "The next evolution of the Agents SDK." OpenAI Blog, April 15, 2026. https://openai.com/index/the-next-evolution-of-the-agents-sdk/
[^22]: TechCrunch. "OpenAI updates its Agents SDK to help enterprises build safer, more capable agents." April 15, 2026. https://techcrunch.com/2026/04/15/openai-updates-its-agents-sdk-to-help-enterprises-build-safer-more-capable-agents/
[^23]: Help Net Security. "OpenAI updates Agents SDK, adds sandbox for safer code execution." April 16, 2026. https://www.helpnetsecurity.com/2026/04/16/openai-agents-sdk-harness-and-sandbox-update/
[^24]: Idlen. "OpenAI Agents SDK: Native Sandbox, Codex Harness, apply_patch, 7 Providers." April 2026. https://www.idlen.io/news/openai-agents-sdk-sandbox-harness-codex-filesystem-tools-april-2026
[^25]: OpenAI. "Releases - openai/openai-agents-python." GitHub. https://github.com/openai/openai-agents-python/releases
[^26]: OpenAI. "Releases - openai/openai-agents-js." GitHub. https://github.com/openai/openai-agents-js/releases
[^27]: OpenAI. "Buy it in ChatGPT: Instant Checkout and the Agentic Commerce Protocol." OpenAI Blog. https://openai.com/index/buy-it-in-chatgpt/