OpenAI Agents SDK Guide 2026: Production Best Practices

What is the OpenAI Agents SDK in 2026?

In short

The OpenAI Agents SDK is OpenAI's official open-source (MIT-licensed) Python and TypeScript framework for building agents against OpenAI models. It evolved from the Swarm experiment, launched publicly in March 2025, and gained a sandbox + harness split on April 15, 2026 that made it production-viable for enterprise workloads.

The OpenAI Agents SDK is the lightweight Python (and TypeScript) framework OpenAI ships for building multi-agent workflows. It grew out of the Swarm experiment, went public in March 2025, and became the recommended path for any team building agents on OpenAI models in production. As of August 2026 the Python package is at 0.19.2, still pre-1.0, and has passed 28,300 GitHub stars and 4,400 forks.

The core primitives are small on purpose: Agent (the model, instructions, and tools), Runner (the loop that executes agents), Handoffs (transfer control between agents), Guardrails (parallel validation), Tracing (built-in observability), and Sessions (conversation persistence). Since April 15, 2026 there is a seventh: SandboxAgent, plus a nine-provider sandbox client matrix that lets the same agent run on a laptop, in Docker, or on Modal without code changes.

Alice Labs — an Anthropic Partner headquartered in Stockholm with 100+ production AI implementations since 2023 — uses the OpenAI Agents SDK as the default framework whenever a client is standardized on gpt-5.6-sol or gpt-realtime-2.1. For a broader tour of what else lives in this space, see our best AI agent frameworks guide for 2026.

OpenAI Agents SDK architecture: harness vs. sandbox separation

In short

The April 15, 2026 release split the SDK into a harness (control plane — agent loop, model calls, tool routing, handoffs, approvals, tracing) and a sandbox (execution plane — file ops, shell, dependency install, storage mounts, port exposure). The same Agent + Manifest can now target nine sandbox providers unchanged.

The single most important architectural change in the SDK's history landed on April 15, 2026. Before that release, sandbox-like execution was tangled with the agent loop: teams that wanted to move from a local prototype to a hosted sandbox had to rewrite control-flow code. After it, the SDK has two clean planes.

• Harness (control plane): owns the agent loop, model calls, tool routing, handoff logic, approvals, tracing, and recovery. It never touches the filesystem or shell directly.
• Sandbox (execution plane): owns file operations, command execution, dependency installation, storage mounts, and port exposure. It exposes a uniform interface via SandboxClient.

Karan Sharma, who leads the Agents SDK at OpenAI, described the change plainly: "This launch, at its core, is about taking our existing Agents SDK and making it so it's compatible with all of these sandbox providers." In practice, the same Agent and Manifest objects can target UnixLocal on a developer laptop, Docker in CI, and Modal in production — the only thing that changes is which client you construct.

The second-order effect is that credentials become runtime configuration, not prompt content. Env vars and mounts are declared on the Manifest and injected by the sandbox provider's native secret store — nothing about the agent instructions changes when you switch clouds. That is what makes the SDK usable inside EU AI Act and GDPR perimeters without a rewrite when data residency rules shift.

The nine OpenAI Agents SDK sandbox clients (UnixLocal, Docker, hosted)

In short

The SDK ships nine sandbox clients that share one Manifest + Capabilities API: two built-in (UnixLocalSandboxClient for dev, DockerSandboxClient for isolation) and seven hosted (Modal, E2B, Cloudflare, Daytona, Vercel, Blaxel, Runloop). Modal is the only provider with GPU sandboxes; E2B offers 900s timeouts on Firecracker microVMs; Daytona persists the filesystem across runs.

The value of the sandbox split is only real if the provider matrix is honest. As of August 2026 the OpenAI Agents SDK documents nine official sandbox clients, all speaking the same Manifest and Capabilities surface.

OpenAI Agents SDK sandbox client matrix

Because all nine clients honour the same Manifest and Capabilities API, you swap providers by changing one line. Modal's own benchmark documents the pattern in detail — see the Modal "Best Sandbox for the OpenAI Agents SDK" writeup for a like-for-like comparison of the hosted options.

Building your first SandboxAgent: Manifest, Capabilities, Runner

In short

A SandboxAgent is built from three objects: a Manifest describing the starting workspace contents, a Capabilities set defining what the agent can do inside the sandbox, and a SandboxRunConfig passed to the Runner. Paths are workspace-relative and the SDK blocks `..` traversal at the API layer.

The quickest way to internalise the harness/sandbox split is to build a minimal SandboxAgent. The imports come from agents.sandbox, and there are exactly three objects to understand.

from agents import Agent, Runner
from agents.sandbox import (
    Manifest,
    File,
    LocalDir,
    Capabilities,
    SandboxAgent,
    SandboxRunConfig,
)
from agents.sandbox.clients import UnixLocalSandboxClient

manifest = Manifest(
    entries=[
        LocalDir(local_path="./repo", sandbox_path="repo"),
        File(sandbox_path="notes.md", content="# Working notes\n"),
    ],
    environment={"PROJECT_NAME": "alice-demo"},
)

capabilities = Capabilities.default()  # filesystem + shell + compaction

agent = SandboxAgent(
    name="repo_reviewer",
    model="gpt-5.6-sol",
    instructions="You review the repo at ./repo and log findings in notes.md.",
    capabilities=capabilities,
)

client = UnixLocalSandboxClient()

result = Runner.run_sync(
    agent,
    input="Summarize the repo structure and flag any TODOs in notes.md.",
    run_config=SandboxRunConfig(sandbox_client=client, manifest=manifest),
)
print(result.final_output)

The Manifest describes the fresh contents of the sandbox workspace. Entries include File (inline content), Dir (empty directory), LocalDir (a local path materialised into the sandbox), GitRepo (a checkout), and cloud mounts for S3, GCS, R2, and Azure Blob. Paths must be workspace-relative — the SDK rejects .. traversal at the API layer.

Capabilities control what the agent can do inside the sandbox. Capabilities.default() includes the filesystem toolset (apply_patch, view_image), the shell toolset, and compaction. Skills (lazy-loaded task playbooks) and Memory (cross-run key/value storage) are opt-in.

SandboxRunConfig is what the Runner needs to actually execute: the client to talk to, and the manifest to hydrate the workspace. Swapping UnixLocalSandboxClient for DockerSandboxClient or a hosted client is a one-line change — everything above it is portable.

OpenAI agent framework tool patterns: functions, MCP, hosted, agents-as-tools

In short

The OpenAI agent framework has four tool patterns: @tool-decorated Python functions (auto-schema from type hints), MCP servers, hosted tools (web_search, code_interpreter, file_search served by OpenAI), and agents-as-tools for manager patterns. The `tool_use_behavior` parameter controls whether tool output ends the run or feeds back to the model.

Tool calling is where the gpt agent framework earns its keep. The SDK deliberately keeps the surface small: one decorator, one protocol, one built-in family, and one composition pattern.

1. Function tools. Decorate a Python function with @tool and the SDK generates the JSON schema from your type hints and docstring:

from agents import Agent, tool

@tool
def get_order(order_id: str) -> dict:
    """Look up an order by its ID and return status + line items."""
    return {"id": order_id, "status": "shipped", "items": [...]}

agent = Agent(
    name="order_lookup",
    model="gpt-5.6-sol",
    tools=[get_order],
    instructions="Look up orders when asked.",
)

2. MCP servers. The SDK ships a built-in MCP client. Any MCP server — local stdio or remote HTTP — is registered on the Agent identically to a function tool and appears to the model with the same shape. This is how Alice Labs wires shared internal capabilities (auth, feature flags, entitlement checks) into agents without duplicating tool code.

3. Hosted tools. OpenAI serves web_search, code_interpreter, and file_search from its own infrastructure. Import them from agents.tools and add them to the Agent — no server to run, billed through the Responses API.

4. Agents-as-tools. Any Agent can be exposed to another Agent as a callable tool via agent.as_tool(). This is how you build a Manager pattern where a coordinator agent delegates to specialist agents in parallel while keeping orchestration control (see the next section for how this differs from a handoff).

The tool_use_behavior parameter on the Agent decides what happens when a tool returns. The default ("run_llm_again") feeds the result back to the model for the next turn. Setting it to "stop_on_first_tool" ends the run immediately — useful when the tool result is the final answer, saving one full LLM call per invocation.

Handoffs vs. subagents: multi-agent orchestration in OpenAI Agents SDK

In short

The SDK offers three distinct multi-agent patterns. Handoff transfers full conversation control from agent A to agent B and the caller drops out. Manager (agents-as-tools) calls agent B inline and keeps the caller in charge. Subagents (April 2026 preview) run isolated parallel sub-runs with their own context window and report results back. Pick by who needs to stay in charge and whether the work is sequential or parallel.

"Multi-agent" is a container word. The OpenAI Agents SDK has three concrete mechanisms, and picking the wrong one is a common source of leaked context and surprise bills.

Handoff vs. agents-as-tools vs. subagents

Handoffs are the SDK's oldest multi-agent primitive and appear in the trace UI as a single tree — you can click through the whole conversation across every specialist that touched it. The receiving agent inherits the full message history, which is exactly what you want for a "please transfer me to billing" interaction and exactly what you do not want when the receiving agent should reason from a clean slate.

The Manager pattern (agents-as-tools) is the right default when the caller needs to decide what to do with the sub-agent's output. Alice Labs uses it for parallel research: a coordinator asks three specialist agents different questions concurrently and synthesises the answers into a final response.

Subagents, previewed alongside the sandbox/harness split on April 15, 2026, close the gap for parallel work where each unit should have its own context window. They report structured results back to the parent, which keeps the parent's context lean even when the sub-runs are chatty.

OpenAI TypeScript SDK: parity status as of August 2026

In short

openai-agents-js has 3,100+ GitHub stars and is at parity with the Python package on Agent, Runner, Handoffs, Guardrails, Tracing, Sessions, and MCP. The April 2026 sandbox + harness update landed Python-first; TypeScript parity is planned with no announced GA date. For sandbox-heavy work today, Alice Labs recommends running Python behind a TypeScript API gateway.

The openai typescript sdk question is the second-most-common one Alice Labs gets from Next.js and Cloudflare Workers teams. The honest August 2026 answer has two parts.

What's at parity. The openai-agents-js package (3,100+ GitHub stars, MIT-licensed, still pre-1.0) matches the Python package on all core primitives: Agent, Runner, Handoffs, Guardrails, Tracing, Sessions, and MCP. If your agents are conversational, tool-using, and don't need a full shell, the TypeScript SDK is production-appropriate today.

What's not at parity. The April 15, 2026 sandbox and harness architecture landed Python-first. As of August 2026 OpenAI has said TypeScript parity for SandboxAgent, the nine sandbox clients, and subagents is planned but has not announced a GA date. The TypeScript package's own release notes say "planned for a future release" without a milestone.

Alice Labs field pattern. When a client's surrounding app is Next.js, Deno, Cloudflare Workers, or Vercel — and the agent needs no sandbox — we build in TypeScript. When the agent needs a sandbox today, we build the agent in Python and call it from a thin TypeScript API gateway (a single POST endpoint that streams SSE). The TS app stays unchanged; the Python service runs on Modal or E2B behind it.

Guardrails, tracing, and sessions: production hardening

In short

The SDK ships three production-hardening primitives. Input and output guardrails run in parallel with the agent and can raise a tripwire to halt the run. The built-in tracing UI at platform.openai.com/traces visualises the full agent tree, tool calls, and handoffs. Sessions auto-persist conversation state (Redis backend supported). Hooks and Runner.run streaming complete the production surface.

Every production openai agents deployment Alice Labs has shipped has the same four things wired up before it goes live.

Guardrails. input_guardrails inspect the user input before the agent runs; output_guardrails inspect the final response. Either can raise a tripwire that halts the run — a fail-fast pattern designed for PII detection, prompt-injection screening, and policy enforcement. They run in parallel with the main agent, so latency impact is negligible unless the guardrail itself is slow.

Tracing. Every Runner invocation produces a trace visible at platform.openai.com/traces. The full agent tree — every model call, every tool call, every handoff — is timestamped and inspectable. Handoffs across specialist agents appear as a single tree, which is the single most useful debugging affordance in the SDK. Alice Labs exports traces to Datadog and OpenTelemetry via the tracing hook so they land in the same observability stack as the rest of the client's services.

Sessions. Passing a Session to the Runner auto-persists conversation state across invocations. The default backend is in-memory; install openai-agents[redis] to persist across processes and pods. Session IDs should map to your application's user or thread identifiers so audit trails are queryable by business record.

Hooks and streaming. The Runner exposes hooks (on_agent_start, on_tool_end, on_handoff, and others) that make cost accounting and metrics trivial. Runner.run supports streaming for user-facing latency, human-in-the-loop pauses via approvals, and resumable RunState so a killed process can pick up where it left off.

For a deeper look at how these primitives compare across frameworks, see our best AI agent frameworks guide for 2026.

Deploying OpenAI Agents to production: patterns Alice Labs uses

In short

Alice Labs' default production pattern for OpenAI Agents: deploy the harness behind FastAPI or Next.js Route Handlers, keep the sandbox client swappable via env var, run UnixLocal in CI and Modal or E2B in production, wire tracing to Datadog or OpenTelemetry, and enforce budget caps with max_turns plus a cost hook.

The openai agents production checklist is short, and every item has bitten at least one Alice Labs project when it was skipped.

1. Serve the harness behind a stable HTTP surface. FastAPI on the Python side, Next.js Route Handlers on the TypeScript side. The agent is a library, not a service — put the service boundary at the request/response layer.
2. Make the SandboxClient env-driven. Construct UnixLocalSandboxClient, DockerSandboxClient, or a hosted client based on APP_ENV. This is what makes "runs on my laptop, runs on Modal in prod" a one-line switch instead of a refactor.
3. Rate-limit at the harness layer. OpenAI's tier-4 limits are almost always the bottleneck, not the sandbox. Enforce a per-tenant token bucket in the harness before the model call — not inside individual tools.
4. Cap runs with max_turns and a cost hook. Pair a hard turn limit on the Runner with an on_agent_end hook that sums token counts across the trace. If the sum crosses a threshold, kill the run and return a friendly failure.
5. Export traces where your on-call already lives. The Datadog and OpenTelemetry exporters are documented in the tracing docs. Do not build a new dashboard — plug into whatever your platform team already pages against.

For a broader deployment checklist that includes infrastructure, security, and compliance controls beyond the SDK itself, see our EU AI Act compliance checklist for 2026.

OpenAI Agents SDK vs LangGraph vs Claude Agent SDK: when to choose which

In short

Pick the OpenAI Agents SDK when the client is OpenAI-standardized, the agent-loop complexity is low, and you need a hosted sandbox plus subagents out of the box. Pick LangGraph for state-machine control across any model. Pick the Claude Agent SDK for repo and filesystem work on Claude. Pick the Microsoft Agent Framework for Azure-native .NET or Python enterprise shops.

None of these frameworks is universally better. The right pick depends on which model the client is committed to, how much explicit control you need over the agent loop, and where the surrounding platform already lives.

Framework selection matrix

The Alice Labs decision rule across 100+ implementations: pick the OpenAI Agents SDK when the client is OpenAI-standardized, agent-loop complexity is low, and hosted sandbox plus subagents matter. Pick LangGraph when the loop needs explicit branches, retries, or checkpoints across any model. Pick the Claude Agent SDK when the work is repo-shaped on Claude. Pick Microsoft Agent Framework when the client's platform team has already standardised on Azure.

For head-to-head technical comparisons that go deeper than this table, see the Turion.ai LangGraph vs OpenAI vs Claude Agent SDK writeup and our best AI agent frameworks guide for 2026.

Cost and rate-limit realities of OpenAI Agents SDK in production

In short

Two cost lines matter: OpenAI model tokens (with tier-4 rate limits usually the bottleneck) and sandbox session hours ($0.10–$0.40/hour on Modal or E2B). Handoffs multiply token usage because each handoff re-sends conversation context. A Manager pattern with gpt-5-nano workers cuts run cost 40–70% versus running every step on the reasoning-tier model.

The unit economics of an OpenAI Agents SDK deployment have two independent variables. Model cost is driven by tokens across the whole trace — including every handoff. Sandbox cost is driven by session-hours on the hosted provider.

Model cost. The examples in the OpenAI docs use gpt-5.6-sol as the default sandbox model and gpt-5-nano as the cheap tool-caller. Alice Labs mirrors this: reasoning-tier for the coordinator, nano tier for tool-heavy workers. Across a set of production migrations we tracked in the first half of 2026, switching from all-reasoning-tier to a coordinator-plus-nano-worker Manager pattern cut end-to-end run cost by 40–70% with no measurable degradation on the client's eval set.

Handoff cost. Every handoff re-sends the full conversation context to the receiving agent. In a five-handoff support flow, the transcript is billed six times. The compaction capability trims context automatically once configurable thresholds are crossed — turn it on before adding a fourth handoff, or switch that leg to a subagent with a fresh context window.

Sandbox cost. Modal and E2B are typically $0.10–$0.40 per session-hour depending on tier and GPU. Set an idle timeout on the sandbox client so orphaned sessions do not accrue overnight. Modal's memory-snapshot cold starts make the "spin up a fresh sandbox per request" pattern viable at scale — you do not need to reuse long-lived sandboxes to keep latency low.

Rate limits. OpenAI's Responses API tier-4 rate limits are almost always the ceiling in high-fan-out workloads, not the sandbox provider. Enforce token budgeting at the harness layer, and use a queue in front of the harness for any burst-heavy workload.

Voice, realtime, and multimodal agents

In short

The SDK exposes RealtimeAgent (WebSocket transport with gpt-realtime-2.1) for low-latency voice, a voice pipeline that composes STT + Agent + TTS behind a single Runner, and screenshot-driven GUI automation via `view_image` in the sandbox capabilities. Install `openai-agents[voice]` to pull in the sounddevice and numpy dependencies.

Voice and realtime are first-class in the SDK, and they compose with everything above — the same guardrails, tracing, sessions, and sandbox story applies.

RealtimeAgent uses a WebSocket transport talking to gpt-realtime-2.1. Latency is measured in hundreds of milliseconds, which is why it powers most of the low-latency voice deployments Alice Labs sees in Nordic customer-service pilots. Handoffs across specialist RealtimeAgents preserve audio session state, so a caller can be routed to a billing specialist without losing the conversation.

Voice pipeline. For teams that want to bring their own STT or TTS — common in EU deployments where data residency rules push STT to an on-prem provider — the SDK exposes a pipeline that composes STT + Agent + TTS as a single Runner. The Agent portion stays identical to a text-only Agent, which is what makes swapping in a new STT provider a config change.

Multimodal via sandbox. Sandbox agents can invoke view_image on screenshots for GUI automation flows. Combined with the shell and filesystem capabilities, this is the primitive most enterprise RPA-style agents use.

Install the extra with pip install openai-agents[voice] — this pulls in sounddevice and numpy so local dev works without extra wiring.

Security and credential handling in sandboxed OpenAI agents

In short

Never place secrets in prompts, instructions, or generated artifacts. Use `Manifest.environment` for startup env vars; hosted providers have native secret stores. Treat the sandbox as semi-trusted — review artifacts before promoting them outside the workspace. Path traversal (`..`) is blocked at the SDK layer. For EU deployments, choose an EU-region hosted sandbox provider.

Sandboxed agents change the security posture in one important way: the agent can now write files, install packages, and run commands. Everything below is non-negotiable in an Alice Labs enterprise engagement.

• Never place secrets in prompts, instructions, or generated artifacts. The agent can and will echo them into the workspace. Treat any secret that lands inside the sandbox as compromised.
• Use Manifest.environment for startup env vars. Hosted providers (Modal, E2B, Cloudflare) have native secret stores that inject values at runtime. Reference them from the Manifest — do not inline them.
• Treat the sandbox as semi-trusted. A prompt-injected agent can produce hostile artifacts. Review any artifact — commit, patch, exported document — before promoting it outside the workspace. Do not auto-deploy sandbox output.
• Path traversal is blocked at the SDK layer. The SDK rejects .. in Manifest paths and tool arguments, but do not rely on this alone — validate paths in your own tools too.
• Data residency is a provider choice. For EU AI Act and GDPR deployments, pick a hosted sandbox provider with EU regions (Modal EU, Cloudflare EU) and pin the region on the client. Data never leaves the perimeter.

For the full EU AI Act view including risk classification and technical controls, see our EU AI Act compliance checklist for 2026.

OpenAI Agents SDK roadmap and the 1.0 question

In short

Both Python and TypeScript packages are still pre-1.0 as of August 2026. The April 15, 2026 sandbox + harness release plus subagents and code-mode preview landed Python-first. TypeScript sandbox/harness parity, code-mode GA, and a stable 1.0 API are the three outstanding milestones. Build against the stable Agent + Runner + tool surface; defer sandbox-heavy TypeScript builds until parity ships.

The OpenAI Agents SDK is production-viable today for the majority of enterprise workloads — Alice Labs runs it in production for Nordic clients right now. But it is still pre-1.0, and expectation-setting matters.

• Cadence. Weekly releases, minor version bumps roughly monthly. The Python package is at 0.19.2 as of August 1, 2026, and the TypeScript package tracks a similar cadence.
• The three open milestones. TypeScript sandbox/harness parity, code-mode general availability, and a stable 1.0 API surface. OpenAI has not committed public GA dates for any of them.
• What's stable. The Agent class, the Runner loop, the @tool decorator, and MCP support have been API-stable for months. Build against these primitives first and add newer surfaces (subagents, code mode) once they hit GA.
• What to defer. Sandbox-heavy TypeScript builds. The TS package covers the core primitives well, but the sandbox story is Python-first and will be for at least the next several releases based on the current cadence.

The practical version-management pattern: pin exact versions in requirements.txt and package.json, upgrade in staging on a weekly cadence, and gate promotion on the client's eval set. This is what makes running a pre-1.0 SDK in production a solved problem rather than a running risk.

For the broader framework landscape and where the OpenAI Agents SDK fits alongside LangGraph, CrewAI, and the Claude Agent SDK, see our best AI agent frameworks guide for 2026.