Skip to main content

OpenAI Agents SDK Guide (2026) | Build Production AI Agents with the OpenAI Agents SDK

Introduction​

OpenAI's Agents SDK is a lightweight, production-ready framework for building AI agents that can use tools, hand off tasks to other agents, apply guardrails, keep workflow state, and expose traces for debugging. Released in 2025 as the production successor to OpenAI's earlier Swarm prototype, the SDK has quickly become one of the most popular agent frameworks, with approximately 22,000 GitHub stars as of 2026.

The OpenAI Agents SDK occupies a specific niche in the agent framework landscape: production-grade single-agent loops with handoffs. Where CrewAI is role-based and LangGraph is graph-based, the OpenAI Agents SDK is the OpenAI-native production framework for ReAct-style loops with delegation.

This guide explains what the OpenAI Agents SDK is, how its architecture works, what core concepts it provides, and how to use it for building production AI agents. It also covers the SDK's relationship to the broader OpenAI ecosystem, practical workflows, comparisons with other frameworks, and guidance for choosing the right tools for your project.

What Is the OpenAI Agents SDK?​

The OpenAI Agents SDK is an open-source MIT-licensed Python and TypeScript framework from OpenAI for building agent applications. It is a lightweight yet powerful framework for building multi-agent workflows, and it is provider-agnostic, supporting the OpenAI Responses and Chat Completions APIs, as well as 100+ other LLMs from other providers.

The Evolution from Swarm​

The SDK is the production successor to Swarm, an experimental prototype OpenAI released in October 2024. Swarm demonstrated the conceptual model of agents with handoffs but lacked tracing, guardrails, and production guarantees. The OpenAI Agents SDK brought the same conceptual model plus the production primitives teams needed: built-in tracing, input and output guardrails, structured outputs, sessions, and a clear runner abstraction.

A Code-First Framework​

The OpenAI Agents SDK is a code-first framework. It is best suited for developers building multi-step agent workflows, not for teams looking for a purely visual no-code agent builder. It is closer to an agent runtime and orchestration framework for developers.

Core Primitives​

The SDK is built around a small, opinionated set of primitives:

PrimitivePurpose
AgentAn LLM configured with instructions, tools, guardrails, and handoffs
HandoffDelegation to another agent
GuardrailAn input or output validator
RunnerThe execution loop
SessionA persistent conversation
ToolsFunctions, MCP servers, and hosted tools
TracingBuilt-in tracking of agent runs

Why the OpenAI Agents SDK Exists​

The Agent Framework Wars​

The 2024 agent framework wars produced a long list of frameworks with overlapping primitives and confusing APIs. The OpenAI Agents SDK landed with a small, opinionated surface: agents, handoffs, guardrails, runner, session. The simplicity is the value proposition.

First-Party Tracing​

OpenAI shipped first-party tracing with the SDK. The default Traces dashboard renders agent runs as nested span trees with model calls, tool calls, and handoff transitions visible at a glance. For teams that already pay for OpenAI, the trace surface is included—no separate observability vendor required. For teams that prefer their own backend, the SDK accepts a custom trace processor.

The Responses API​

The Responses API gave OpenAI's newest features a coherent path into agent applications: Reasoning models with deep thinking, the Computer Use tool, the File Search built-in tool, the Web Search built-in tool. The SDK is the recommended way to use these features.

OpenAI Agents SDK Architecture​

The OpenAI Agents SDK provides a clean separation between the agent harness and the compute environment. The architecture is organized around a small set of core components that work together to orchestrate agent workflows.

Architecture Overview​

User Input
    ↓
┌─────────────────────────────────────────────────────┐
│                    Runner                           │
│  ┌─────────────────────────────────────────────┐   │
│  │                   Agent                     │   │
│  │  ┌───────────┐  ┌───────────┐  ┌─────────┐ │   │
│  │  │ Model     │  │ Tools     │  │ Handoffs│ │   │
│  │  │ +         │  │ +         │  │ +       │ │   │
│  │  │Instructions│ │ Guardrails│  │Sessions │ │   │
│  │  └───────────┘  └───────────┘  └─────────┘ │   │
│  └─────────────────────────────────────────────┘   │
│                       ↓                            │
│  ┌─────────────────────────────────────────────┐   │
│  │                Tracing                      │   │
│  └─────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────┘
    ↓
Final Output

Component Layers​

  1. Input Layer: User request enters the system
  2. Runner Layer: Orchestrates the agent loop, manages state, and handles streaming
  3. Agent Layer: The core unit containing model, instructions, tools, and runtime behavior
  4. Tool Layer: Functions, MCP servers, and hosted tools that agents can call
  5. Orchestration Layer: Handoffs and agent-as-tool patterns for multi-agent workflows
  6. Guardrail Layer: Input and output validation
  7. Tracing Layer: Built-in observability and debugging

Core Concepts​

Agents​

An agent is the core unit of an SDK-based workflow. It packages a model, instructions, and optional runtime behavior such as tools, guardrails, MCP servers, handoffs, and structured outputs.

Key agent properties:

PropertyPurpose
nameHuman-readable identity in traces
instructionsThe job, constraints, and style for that agent
modelChoosing the model and tuning behavior
toolsCapabilities the agent can call directly
handoffsDelegating to another agent
handoffDescriptionHinting when another agent should delegate here
outputTypeReturning structured output instead of plain text
guardrailsValidation, blocking, and review flows

Best practice: Start with one focused agent. Define the smallest agent that can own a clear task. Add more agents only when you need separate ownership, different instructions, different tool surfaces, or different approval policies.

Tool Calling​

Tools let agents take actions. The SDK supports three primary tool types:

Tool TypeDescription
Custom toolsPython functions you define and register as tools
Managed toolsBuilt-in, hosted tools provided by OpenAI (Code Interpreter, Web Search, File Search)
MCP serversModel Context Protocol servers for external capabilities

Tool configuration example:

const getWeather = tool({
  name: "get_weather",
  description: "Return the weather for a given city.",
  parameters: z.object({ city: z.string() }),
  async execute({ city }) {
    return `The weather in ${city} is sunny.`;
  },
});

const agent = new Agent({
  name: "Weather bot",
  instructions: "You are a helpful weather bot.",
  model: "gpt-5.6",
  tools: [getWeather],
});

Handoffs​

Handoffs are a specialized tool call used by the Agents SDK for transferring control between agents. They are the clearest fit when a specialist should own the next response rather than merely helping behind the scenes.

Two orchestration patterns:

PatternWhen to UseWhat Happens
HandoffsA specialist should take over the conversationControl moves to the specialist agent
Agents as toolsA manager should stay in controlThe manager keeps ownership of the reply

Handoff example:

const billingAgent = new Agent({ name: "Billing agent" });
const refundAgent = new Agent({ name: "Refund agent" });
const triageAgent = Agent.create({
  name: "Triage agent",
  handoffs: [billingAgent, handoff(refundAgent)],
});

When to add specialists: Add specialists only when they materially improve capability isolation, policy isolation, prompt clarity, or trace legibility. Splitting too early creates more prompts, more traces, and more approval surfaces without necessarily making the workflow better.

Guardrails​

Guardrails are configurable safety checks for input and output validation. They can run in parallel to the agent or block execution until they complete.

Types of guardrails:

Use CaseStart With
Block disallowed user requests before the main model runsInput guardrails
Validate or redact the final output before it leaves the systemOutput guardrails
Check arguments or results around a function tool callTool guardrails
Pause before side effects like cancellations, edits, shell commandsHuman-in-the-loop approvals

Key behaviors:

  • Input guardrails run only for the first agent in the chain
  • Output guardrails run only for the agent that produces the final output
  • Guardrails can run in parallel (for speed) or block execution (for safety)

Input guardrail example:

const agent = new Agent({
  name: "Customer support",
  inputGuardrails: [{
    name: "Math homework guardrail",
    runInParallel: false,
    async execute({ input, context }) {
      const result = await run(guardrailAgent, input, { context });
      return {
        outputInfo: result.finalOutput,
        tripwireTriggered: result.finalOutput?.isMathHomework === true,
      };
    },
  }],
});

Human-in-the-Loop​

Human-in-the-loop approvals pause the run so a person or policy can approve or reject a sensitive action. The model can still decide that an action is needed, but the run pauses until you approve or reject it.

Approval example:

const cancelOrder = tool({
  name: "cancel_order",
  description: "Cancel a customer order.",
  parameters: z.object({ orderId: z.number() }),
  needsApproval: true,
  async execute({ orderId }) {
    return `Cancelled order ${orderId}`;
  },
});

Sessions​

Sessions provide automatic conversation history management across agent runs. They enable agents to maintain context across multiple turns and interactions.

Tracing​

Tracing is a built-in tracking of agent runs, allowing you to view, debug, and optimize your workflows. The default Traces dashboard renders agent runs as nested span trees with model calls, tool calls, and handoff transitions visible at a glance.

Sandbox Agents​

Sandbox agents are preconfigured to work with a container to perform work over long time horizons. OpenAI's April 2026 update specifically framed this as a way for agents to handle longer-horizon tasks inside controlled sandbox environments.

How the OpenAI Agents SDK Works​

The Execution Flow​

1. User Request
       ↓
2. Runner Initializes
       ↓
3. Agent Processes Request
   - Applies input guardrails
   - Calls model with instructions and tools
       ↓
4. Model Reasons and Decides
   - May call tools
   - May hand off to another agent
       ↓
5. Tool Execution (if applicable)
   - Functions, MCP servers, or hosted tools
   - May require human approval
       ↓
6. Handoff (if applicable)
   - Control transfers to specialist agent
       ↓
7. Response Generation
   - Applies output guardrails
   - Returns structured or unstructured output
       ↓
8. Tracing Records the Run
       ↓
9. Final Output Returned

Running Agents​

The SDK supports three primary ways to run agents:

  1. Standard run: One agent, one turn
  2. Multi-turn run: Agent with session state
  3. Sandbox run: Agent in a containerized environment

Parallel Execution​

The SDK supports parallel agent execution using Python asyncio, enabling you to "fan out" multiple specialized agents at the same time and then "fan in" their outputs to a final "meta" agent.

Parallel execution example:

responses = await asyncio.gather(
    *(run_agent(agent, review_text) for agent in parallel_agents)
)
labeled_summaries = [
    f"### {resp.last_agent.name}\n{resp.final_output}"
    for resp in responses
]
collected_summaries = "\n".join(labeled_summaries)
final_summary = await run_agent(meta_agent, collected_summaries)

Key Features​

Agent Orchestration​

The SDK manages the full agent lifecycle: model calls, tool execution, handoffs, guardrails, and sessions. The Runner handles the execution loop, managing turns, tools, safety measures, handoffs, and sessions.

Native Tool Calling​

The SDK provides native support for three tool types:

  • Custom Python functions registered as tools
  • Managed tools hosted by OpenAI (Code Interpreter, Web Search, File Search)
  • MCP servers for external capabilities

Multi-Agent Workflows​

The SDK supports two primary patterns for multi-agent collaboration:

PatternUse Case
HandoffsSpecialists take over the conversation for their domain
Agents as toolsA manager stays in control and calls specialists as bounded capabilities

Safety & Guardrails​

The SDK provides configurable safety checks:

  • Input guardrails for user requests
  • Output guardrails for final responses
  • Tool guardrails for function arguments and results
  • Human-in-the-loop approvals for sensitive actions

Structured Outputs​

Agents can return structured output using Zod schemas (TypeScript) or Pydantic models (Python):

const calendarEvent = z.object({
  name: z.string(),
  date: z.string(),
  participants: z.array(z.string()),
});

const agent = new Agent({
  name: "Calendar extractor",
  instructions: "Extract calendar events from text.",
  outputType: calendarEvent,
});

Observability​

Built-in tracing provides:

  • Nested span trees of agent runs
  • Model calls, tool calls, and handoff transitions
  • Debugging and optimization visibility

Sessions​

Automatic conversation history management across agent runs enables:

  • Multi-turn conversations
  • Persistent context
  • Stateful workflows

Sandbox Agents​

Containerized execution for long-running tasks enables:

  • File inspection and manipulation
  • Command execution
  • Controlled compute environments

Realtime Voice Agents​

The SDK supports building powerful voice agents with gpt-realtime-2.1 and full agent features.

Provider-Agnostic​

The SDK supports the OpenAI Responses and Chat Completions APIs, as well as 100+ other LLMs. This means you can use non-OpenAI models (including Hugging Face models) with the same agent framework.

Common Workflows​

Customer Support Agent​

A support triage agent that classifies issues, looks up account data, and escalates complex cases.

Customer Request
       ↓
Triage Agent
  - Input guardrail: Block inappropriate requests
  - Routes to appropriate specialist
       ↓
Billing Agent / Technical Agent / Refund Agent
  - Each with specialized tools and instructions
  - May require human approval for sensitive actions
       ↓
Final Response

Research Assistant​

An agent that searches internal documents, summarizes findings, and hands off legal or finance-specific tasks to specialist agents.

User Question
       ↓
Research Agent
  - Uses File Search tool
  - Summarizes findings
       ↓
Specialist Handoff (if needed)
  - Legal Agent for policy questions
  - Finance Agent for budget questions
       ↓
Final Synthesis

Parallel Analysis​

Fanning out multiple specialized agents at the same time and then fanning in their outputs to a final meta-agent.

Content Input
       ↓
┌──────────────┬──────────────┬──────────────┐
│ Features     │ Pros/Cons    │ Sentiment    │
│ Agent        │ Agent        │ Agent        │
└──────────────┴──────────────┴──────────────┘
       ↓              ↓              ↓
        └──────────────┴──────────────┘
                       ↓
              Meta Agent (Combines)
                       ↓
              Executive Summary

Enterprise Assistant​

An enterprise agent that accesses internal knowledge bases, business systems, and provides responses to employees.

Employee Query
       ↓
Enterprise Agent
  - Input guardrail: Validate query
  - Uses File Search for internal docs
  - Calls MCP servers for business systems
       ↓
Response with Citations

Enterprise Use Cases​

AI Customer Support​

Automate tier-1 support with agents that can classify issues, access knowledge bases, and escalate complex cases. Handoffs enable routing to billing, technical, or refund specialists.

Internal Knowledge Assistants​

Enterprise employees can query internal documentation, policies, and knowledge bases through conversational agents with RAG capabilities.

Software Engineering Automation​

Agents that can inspect files, run commands, and work in controlled sandbox environments for code review, testing, and automation.

Business Process Automation​

Agents that review incoming requests, prepare suggested actions, and route work through approval workflows.

Semantic search across internal documents, emails, and data sources using agents with File Search and MCP integrations.

AI Research Assistants​

Agents that search, analyze, and synthesize information across multiple sources with handoffs to specialist agents for domain-specific tasks.

Advantages​

1. Official OpenAI Framework​

The SDK is OpenAI's official production framework for agents, making it the natural choice for OpenAI-first stacks.

2. Lightweight and Simple​

The SDK has a small, opinionated surface with very few abstractions. The simplicity is the value proposition.

3. Native Tool Calling​

First-class support for custom tools, managed tools (Code Interpreter, Web Search, File Search), and MCP servers.

4. Multi-Agent Support​

Two patterns for multi-agent workflows: handoffs and agents as tools. Both are built into the SDK.

5. Built-in Guardrails​

Configurable safety checks for input validation, output validation, and tool behavior.

6. First-Party Tracing​

Included observability with no separate vendor required. Traces dashboard renders agent runs with model calls, tool calls, and handoff transitions.

7. Provider-Agnostic​

Supports 100+ LLMs beyond OpenAI, including Hugging Face models.

8. Sandbox Support​

Containerized execution for long-running tasks and controlled compute environments.

9. Sessions​

Automatic conversation history management across agent runs.

10. Production-Ready​

The SDK is the production-ready upgrade of OpenAI's previous experimentation for agents.

Limitations​

1. Primarily Optimized for OpenAI​

While provider-agnostic, the SDK is most deeply integrated with OpenAI's ecosystem and the Responses API.

2. Requires Thoughtful Workflow Design​

The SDK is a code-first framework that requires deliberate design of agents, tools, and handoffs.

3. External Memory Implementation​

Long-term memory is not built in—it requires external storage implementation.

4. Model API Costs​

All agent runs consume tokens and incur API costs. Multi-agent workflows can increase costs significantly.

5. Production Monitoring Remains Essential​

While tracing is built in, production monitoring, alerting, and evaluation require additional tooling.

6. Not Every Application Needs Multiple Agents​

For simple tasks, a direct API call may be more appropriate than an agent framework.

7. Learning Curve​

Understanding handoffs, guardrails, and agent orchestration requires time and practice.

8. Limited Visual Tooling​

The SDK is code-first—it does not provide a visual no-code agent builder.

Pricing Overview​

The OpenAI Agents SDK itself is open-source and free (MIT-licensed). However, using the SDK incurs costs for:

API Usage Costs​

  • Token consumption: Every agent run consumes tokens for prompts, completions, and tool calls
  • Model selection: More capable models (GPT-5.6, o-series) cost more per token
  • Managed tools: Tools like Code Interpreter and Web Search may have additional usage costs

Infrastructure Considerations​

  • Compute: Sandbox agents may require container infrastructure
  • Storage: Sessions and traces may require storage
  • Observability: Custom trace processors may require infrastructure

Note: For current pricing, always refer to the official OpenAI pricing page.

OpenAI Agents SDK vs Other Agent Frameworks​

Framework Comparison​

FrameworkPrimary FocusBest ForKey Differentiator
OpenAI Agents SDKProduction-grade single-agent loops with handoffsOpenAI-first stacksNative tool calling, first-party tracing
LangGraphGraph-based state machinesComplex stateful workflowsCheckpoints, cyclic workflows, human-in-the-loop
CrewAIRole-based multi-agent crewsRole-based pipelinesClean mental model of collaboration
AutoGenConversational multi-agentMulti-agent debate and consensus⚠️ Maintenance mode
Google ADKGoogle-stack agent runtimeGCP-native teamsVertex AI integration

OpenAI Agents SDK vs LangGraph​

AspectOpenAI Agents SDKLangGraph
ArchitectureLightweight, minimal boilerplateGraph-based orchestration
State ManagementSession-basedCheckpoint-based with time travel
Workflow ControlHandoffs and agents as toolsExplicit graph reasoning
Learning CurveLowerSteeper
Best ForStructured runtime with handoffs and tracingComplex state machines, cyclic workflows

When to Use Each​

Use the OpenAI Agents SDK when:

  • You want a structured runtime with handoffs, guardrails, tracing, and tool calling out of the box
  • You're building on the OpenAI ecosystem
  • You need a lightweight, minimal-boilerplate framework

Use LangGraph when:

  • You need complex state machines with checkpoints
  • You need cyclic workflows and explicit graph reasoning
  • You're already in the LangChain ecosystem

Use CrewAI when:

  • You want role-based multi-agent pipelines
  • You need rapid prototyping with a clean mental model

Who Should Use the OpenAI Agents SDK?​

AI Engineers​

The SDK provides a production-ready framework for building agent applications with minimal boilerplate.

Backend Developers​

The code-first approach integrates naturally with existing backend systems and workflows.

AI Startups​

The lightweight framework and built-in tracing enable rapid development and iteration.

Enterprise Teams​

The SDK's guardrails, human-in-the-loop approvals, and tracing support enterprise compliance and observability requirements.

Software Architects​

The SDK's simple primitives make it easy to design and communicate agent architectures.

Platform Engineers​

The provider-agnostic design and MCP support enable building flexible agent platforms.

Best Practices​

1. Start with One Focused Agent​

Define the smallest agent that can own a clear task. Add more agents only when you need separate ownership, different instructions, different tool surfaces, or different approval policies.

2. Add Specialists Only When the Contract Changes​

Add specialists only when they materially improve capability isolation, policy isolation, prompt clarity, or trace legibility.

3. Keep Handoff Descriptions Short and Concrete​

Make it clear when another agent should delegate to this specialist.

4. Use Structured Outputs​

Return typed data rather than free-form prose when downstream code needs structured data.

5. Design Safe Guardrails​

  • Use input guardrails to block disallowed requests before the main model runs
  • Use output guardrails to validate final output before it leaves the system
  • Use human-in-the-loop approvals for sensitive actions like cancellations or shell commands

6. Use Parallel Execution When Appropriate​

"Fan out" multiple specialized agents at the same time and "fan in" their outputs to a final meta-agent to reduce latency.

7. Log and Monitor All Tool Calls​

Tracing is built in—use it to debug and optimize workflows.

8. Choose the Right Orchestration Pattern​

  • Use handoffs when a specialist should take over the conversation
  • Use agents as tools when a manager should stay in control and call specialists as bounded capabilities

9. Validate Before and After​

Use guardrails both before and after agent execution to ensure safe, reliable behavior.

10. Combine with RAG​

For applications requiring external knowledge, combine the SDK with retrieval-augmented generation using the File Search tool.

Frequently Asked Questions​

What is the OpenAI Agents SDK?​

The OpenAI Agents SDK is an open-source MIT-licensed Python and TypeScript framework from OpenAI for building agent applications. It provides a lightweight, production-ready framework for building AI agents that can use tools, hand off tasks to other agents, apply guardrails, and keep workflow state.

Is the OpenAI Agents SDK open source?​

Yes. The SDK is open-source under the MIT license.

Does the SDK support Tool Calling?​

Yes. The SDK supports custom Python functions, managed tools (Code Interpreter, Web Search, File Search), and MCP servers.

What are Handoffs?​

Handoffs are a specialized tool call used by the Agents SDK for transferring control between agents. They are the clearest fit when a specialist should own the next response.

What are Guardrails?​

Guardrails are configurable safety checks for input and output validation. They can run in parallel to the agent or block execution until they complete.

Can it build multi-agent systems?​

Yes. The SDK supports two primary patterns for multi-agent collaboration: handoffs (specialists take over the conversation) and agents as tools (a manager stays in control).

How does it compare with LangGraph?​

The OpenAI Agents SDK is a lightweight, minimal-boilerplate framework. LangGraph is a graph-based orchestration framework for complex state machines and cyclic workflows. Choose the SDK for structured runtime with handoffs and tracing; choose LangGraph for complex state machines.

Is it suitable for enterprise applications?​

Yes. The SDK includes guardrails, human-in-the-loop approvals, tracing, and sessions—all supporting enterprise compliance and observability requirements.

Conclusion​

The OpenAI Agents SDK has established itself as one of the leading frameworks for building production AI agents. With approximately 22,000 GitHub stars and growing adoption across startups and enterprises, it offers a lightweight, production-ready foundation for agent applications.

The SDK's key strengths—lightweight simplicity, native tool calling, multi-agent support, built-in guardrails, first-party tracing, and provider-agnostic design—make it particularly well-suited for OpenAI-first stacks and teams that need a structured runtime with handoffs and tracing out of the box.

The framework's primitives are small and clearly named: Agent, Handoff, Guardrail, Runner, Session, Tools, and Tracing. The simplicity is the value proposition.

The most effective approach combines the SDK's agent orchestration with:

  • RAG for external knowledge (via File Search or MCP)
  • Guardrails for safety and compliance
  • Human-in-the-loop approvals for sensitive actions
  • Tracing for observability and debugging
  • Parallel execution for latency reduction

Whether you're building a customer support agent, a research assistant, an enterprise knowledge system, or a complex multi-agent workflow, the OpenAI Agents SDK provides the framework, tools, and production infrastructure needed to succeed.