OpenAI Agents SDK: Complete Guide

Design Philosophy: Primitives First

OpenAI's approach to agent development is deliberately minimalist. Where Claude's SDK provides batteries-included tooling and Google's ADK offers enterprise workflow orchestration, the OpenAI Agents SDK gives you three building blocks and expects you to compose them into whatever architecture your application requires.

The three primitives are agents (an LLM paired with instructions and tools), handoffs (a mechanism for one agent to delegate work to another), and guardrails (validation layers that check agent inputs and outputs against safety and quality constraints). This simplicity is not a limitation but a design choice. It means the SDK imposes minimal opinions about how your agent system should be structured, which is valuable for teams with specific architectural requirements that do not fit neatly into a more opinionated framework.

Agents and Tool Calling

An agent in the OpenAI SDK is defined by its model, system instructions, and available tools. Tools are Python functions decorated with metadata that describes their purpose and input schema. When the model decides to call a tool, the SDK handles the function invocation, result formatting, and message threading automatically.

The SDK supports OpenAI's function calling format, which has become the most widely adopted tool calling standard in the industry since its introduction in 2023. This means existing tool definitions written for the OpenAI API work directly with the Agents SDK without modification. Third-party libraries and tool registries that target OpenAI's format are immediately compatible.

MCP support was added to enable interoperability with the broader tool ecosystem. The Agents Python SDK understands multiple MCP transports, allowing developers to reuse existing MCP servers or build custom ones. However, MCP integration is less deeply embedded than in Claude's SDK, where it is the primary tool integration mechanism.

Sandbox Execution

The April 2026 update introduced sandbox execution, a controlled environment where agents can inspect files, run commands, edit code, and perform other potentially dangerous operations without risking the host system's integrity. The sandbox provides a full Linux environment with configurable resource limits, network access controls, and filesystem isolation.

Sandboxing addresses one of the core challenges in agent development: letting the agent take real actions while maintaining safety guarantees. Without sandboxing, developers must either restrict agents to read-only operations (limiting their usefulness) or implement their own isolation layers (which is complex and error-prone). The SDK's built-in sandbox provides a middle ground where agents can be productive while remaining contained.

Each sandbox session is ephemeral by default, meaning the environment is destroyed when the agent finishes its task. Persistent sandboxes can be configured for long-running workflows where the agent needs to maintain state across multiple interactions.

Model-Native Harness

The model-native harness is the second major addition from April 2026. It moves tool dispatch, multi-step execution, and state persistence from application code into the model layer itself. In practical terms, this means the model manages its own execution loop rather than the SDK orchestrating it from outside.

The benefit is reduced complexity in application code. Developers no longer need to implement retry logic, tool call sequencing, or state management themselves. The model handles these concerns internally, making agent behavior more consistent and reducing the surface area for bugs in the orchestration layer.

The trade-off is less visibility and control over the execution process. With an external orchestration loop, developers can inspect and modify every step. With the model-native harness, some of this control is delegated to the model. For applications that require fine-grained control over the execution flow, the traditional orchestration approach is still available as an option.

Handoffs and Multi-Agent Patterns

Handoffs are the OpenAI SDK's mechanism for multi-agent coordination. When an agent encounters a subtask that would be better handled by a specialist, it can hand off the conversation to another agent with different instructions and tools. The receiving agent gets the relevant conversation context and continues the work.

Handoffs work well for linear delegation chains where one agent passes work to another in sequence. A customer service system might hand off from a triage agent to a billing specialist to a technical support agent based on the user's needs. Each agent in the chain has its own expertise and tool set.

For parallel coordination patterns (where multiple agents work simultaneously and merge their results), the handoff mechanism is less naturally suited. Developers typically implement parallel coordination in application code, using the SDK's agents as building blocks within a custom orchestration layer. The upcoming subagents feature will add more structured parent-child agent relationships to address this gap.

Guardrails

Guardrails are validation functions that check agent behavior against defined constraints. Input guardrails validate what the user sends to the agent. Output guardrails validate what the agent sends back. Tool guardrails validate tool call arguments before execution.

Guardrails can be as simple as keyword filters or as complex as secondary model evaluations. A common pattern is using a smaller, faster model to evaluate the primary agent's outputs for safety, accuracy, or policy compliance before they are returned to the user. This layered approach allows the primary agent to use a powerful but expensive model while the guardrail runs on a cheaper model optimized for classification.

Tracing and Observability

The SDK includes built-in tracing that captures every step of an agent's execution: model calls, tool invocations, handoffs, guardrail evaluations, and timing data. Traces can be visualized in OpenAI's dashboard or exported to third-party observability platforms.

Tracing integrates with OpenAI's evaluation, fine-tuning, and distillation pipeline. Agent traces can be used to identify performance bottlenecks, generate training data for model fine-tuning, and create distilled versions of agent workflows that run on smaller, cheaper models.

Voice Agent Support

A unique capability of the OpenAI Agents SDK is native voice agent support through GPT-Realtime-2. Developers can build agents that communicate through speech rather than text, with features including automatic interruption detection (the agent stops talking when the user starts), context management across spoken turns, and integration with the same tool calling and guardrail infrastructure used by text agents.

Voice agents open use cases that text-based agents cannot address, including phone-based customer service, hands-free assistants, accessibility applications, and real-time translation. No other major SDK provides comparable voice agent infrastructure.

Limitations

The SDK is primarily Python-focused. TypeScript support exists for the core agent loop but lags behind Python for the newer features like sandbox execution and the model-native harness. Teams building in TypeScript should evaluate whether the currently available features meet their needs or if they would benefit from a TypeScript-first SDK like Vercel's.

Like Claude's SDK, the OpenAI Agents SDK is vendor-locked to OpenAI models. The primitives-first design makes it relatively straightforward to abstract the model layer and swap in other providers, but doing so means losing access to the model-native harness, sandbox execution, and other features that depend on tight model integration.

Language and Ecosystem Support

The OpenAI Agents SDK is available on PyPI and supports Python 3.9 and later. The Python ecosystem around OpenAI is the largest of any AI provider, with thousands of community libraries, tutorials, integration examples, and production case studies available. This broad ecosystem means that most common agent patterns have been implemented and documented by someone in the community, reducing the time needed to solve routine problems.

TypeScript support covers the core agent loop and basic tool calling but does not yet include the newer features like sandbox execution and the model-native harness. OpenAI has stated that TypeScript parity is planned but has not committed to a timeline. For teams that need full feature coverage in TypeScript, the Vercel AI SDK (which uses OpenAI models through its provider-agnostic API) may be a better choice in the short term.

The SDK integrates with the broader OpenAI platform including the Assistants API, fine-tuning pipeline, and evaluation tools. Agent traces generated by the SDK can feed directly into fine-tuning workflows, creating a feedback loop where production agent behavior improves the underlying model over time.