Agent Framework

Multi-AgentProduction-ReadyMIT

OpenAI Agents SDK

Q: How does the OpenAI Agents SDK differ from LangChain or CrewAI?

The Agents SDK is intentionally minimal and opinionated. It focuses on three core abstractions — Agents, Handoffs, and Guardrails — rather than providing a large toolkit for every possible integration. LangChain offers broader ecosystem coverage with hundreds of integrations, while CrewAI emphasizes role-based team collaboration. The Agents SDK prioritizes simplicity and first-party OpenAI model support.

Q: What are Handoffs in the Agents SDK?

Handoffs are a first-class concept that allows one agent to delegate a conversation to another agent. For example, a triage agent can hand off to a billing agent or a technical support agent based on the user's request. Handoffs preserve conversation context and allow specialized agents to handle specific domains without a single agent needing to know everything.

Q: What are Guardrails in the Agents SDK?

Guardrails are validation functions that run on agent inputs or outputs before they reach the user. Input guardrails can block prompt injection or off-topic requests, while output guardrails can filter sensitive information or enforce response formats. Guardrails run in parallel with agent execution for minimal latency impact and can trigger early termination when violations are detected.

Q: Does the OpenAI Agents SDK support non-OpenAI models?

Yes. While the SDK is optimized for OpenAI models, it supports any model provider that implements the OpenAI Chat Completions API format. This includes providers like Azure OpenAI, Anthropic (via compatibility layers), local models served through vLLM or Ollama, and any API that follows the OpenAI request and response schema.

Q: How does tracing work in the Agents SDK?

The SDK includes built-in tracing that records every agent invocation, tool call, handoff, and guardrail check in a structured trace. Traces can be viewed in the OpenAI Dashboard for debugging, exported to external observability platforms, or analyzed programmatically. Tracing is enabled by default and adds negligible overhead to agent execution.

by OpenAI · openai/openai-agents-python

The OpenAI Agents SDK is OpenAI's official Python framework for building multi-agent AI applications. It provides three core primitives — Agents with instructions and tools, Handoffs for delegating between specialized agents, and Guardrails for validating inputs and outputs — that compose into production-grade agentic workflows with built-in tracing and observability.

Evolved from the experimental Swarm framework, the Agents SDK is designed for real-world deployment. It supports structured outputs via Pydantic models, parallel tool execution, context propagation across agent handoffs, and integration with the OpenAI Dashboard for trace visualization. The SDK works with any OpenAI-compatible model provider, not just OpenAI's own models.

Core Primitives

Agents, Handoffs, Guardrails

<5min

Setup

pip install + API key

Python

Language

async-first design

MIT

License

open source

Quick Install

pip install openai-agents

Key Features

Agent Definition

Define agents with natural language instructions, a set of tools they can call, and optional handoff targets. Each agent is a self-contained unit with a clear purpose, model selection, and output type. Agents can be composed into complex workflows through handoffs and tool chaining.

Handoffs Between Agents

A first-class abstraction for delegating conversations between specialized agents. A triage agent can route to billing, support, or sales agents based on intent detection. Handoffs preserve full conversation context, ensuring smooth transitions without losing information.

Input & Output Guardrails

Validation functions that run in parallel with agent execution. Input guardrails catch prompt injection, off-topic requests, or policy violations before the agent processes them. Output guardrails filter sensitive data, enforce response formats, and verify factual accuracy before responding to users.

Built-in Tracing

Every agent invocation, tool call, handoff, and guardrail check is recorded in a structured trace. View traces in the OpenAI Dashboard, export to external observability tools, or analyze programmatically. Tracing is enabled by default with negligible performance overhead.

Structured Outputs

Define agent output schemas using Pydantic models for type-safe, validated responses. The SDK enforces output structure at the model level, ensuring agents return data in exactly the format your application expects — no manual parsing or validation needed.

Context Propagation

Pass typed context objects through the entire agent execution pipeline. Context is available to all tools, guardrails, and handoff targets, enabling shared state like user identity, session data, or feature flags without global variables or dependency injection.

Execution Brief

Use this page as a rollout checklist, not just reference text.

Suggest update

Tool Mapping Lens

Organize Tools by Workflow Phase

Catalog-oriented pages work best when users can map discovery, evaluation, and rollout in a clear path instead of reading an undifferentiated list.

Define the job-to-be-done first
Group tools by stage
Prioritize by adoption friction

Actionable Utility Module

Skill Implementation Board

Use this board for OpenAI Agents SDK before rollout. Capture inputs, apply one decision rule, execute the checklist, and log outcome.

Input: Objective

Deliver one measurable improvement with openai agents sdk multi-agent framework handoffs guardrails tracing production python

Input: Baseline Window

20-30 minutes

Input: Fallback Window

8-12 minutes

Decision Trigger	Action	Expected Output
Input: one workflow objective and release owner are defined	Run preview execution with fixed acceptance criteria.	Go or hold decision backed by repeatable evidence.
Input: output quality below baseline or retries increase	Limit scope, isolate root issue, and rerun controlled test.	One confirmed correction path before wider rollout.
Input: checks pass for two consecutive replay windows	Promote to broader traffic with fallback path active.	Stable rollout with low operational surprise.

Execution Steps

Record objective, owner, and stop condition.
Execute one controlled preview run.
Measure quality, latency, and correction burden.
Promote only when pass criteria are stable.

Output Template

tool=openai agents sdk multi-agent framework handoffs guardrails tracing production python
objective=
preview_result=pass|fail
primary_metric=
next_step=rollout|patch|hold

Share execution feedback

What Is OpenAI Agents SDK?

The OpenAI Agents SDK is OpenAI's official Python framework for building multi-agent AI applications. It provides a minimal set of carefully designed primitives — Agents, Handoffs, and Guardrails — that compose into sophisticated agent workflows. Rather than offering a sprawling toolkit, the SDK focuses on getting the core abstractions right and letting developers build on top of them.

The SDK evolved from Swarm, OpenAI's experimental multi-agent research project released in late 2024. While Swarm demonstrated the viability of lightweight agent orchestration, the Agents SDK is engineered for production deployment with proper error handling, async execution, structured outputs, and comprehensive tracing. It represents OpenAI's opinionated answer to how multi-agent systems should be built.

What sets the Agents SDK apart from frameworks like LangChain or CrewAI is its deliberate simplicity. An Agent is defined with instructions (a system prompt), tools (Python functions), and optionally handoff targets (other agents). This small surface area makes it easy to reason about agent behavior, debug issues, and maintain systems over time. There are no complex chain configurations or workflow DAGs to manage.

The SDK integrates deeply with the OpenAI platform. Traces are viewable in the OpenAI Dashboard alongside API usage and fine-tuning data. Structured outputs leverage OpenAI's native JSON mode for reliable schema enforcement. And while it works with any OpenAI-compatible provider, it is optimized for OpenAI models with features like parallel tool calling and function calling that map directly to SDK primitives.

How to Calculate Better Results with openai agents sdk multi-agent framework handoffs guardrails tracing production python

Install the SDK using pip: run pip install openai-agents in your Python environment. The package requires Python 3.9 or later and depends on the OpenAI Python SDK and Pydantic. Set your OPENAI_API_KEY environment variable to authenticate with the OpenAI API, or configure a custom model provider for non-OpenAI models.

Define your first agent with instructions, tools, and an output type. Create a Python function decorated as a tool, instantiate an Agent with a name, instructions string, and the tool list, then call Runner.run() with a user message. The SDK handles the conversation loop, tool execution, and response generation automatically.

Add a second agent and connect them with a handoff. For example, create a triage agent that analyzes user intent and hands off to either a billing agent or a support agent. The triage agent's handoff targets are defined as a list of Agent instances. When the triage agent decides to hand off, the SDK transfers the full conversation context to the target agent seamlessly.

Add guardrails to protect your agents in production. Define an input guardrail function that checks for prompt injection patterns and an output guardrail that verifies the response does not contain sensitive data. Attach them to your agents — guardrails run in parallel with agent execution for minimal latency. Enable tracing and view the execution flow in the OpenAI Dashboard to debug and optimize your multi-agent system.

Treat this page as a decision map. Build a shortlist fast, then run a focused second pass for security, ownership, and operational fit.

When a team keeps one shared selection rubric, tool adoption speeds up because evaluators stop debating criteria every time a new option appears.

Worked Examples

Building a customer support triage system

You need a support system that routes customer inquiries to specialized agents for billing, technical issues, and general questions
Define three specialized agents: billing_agent with access to Stripe tools and refund policies, tech_agent with access to documentation search and log analysis, and general_agent for FAQ responses
Create a triage_agent with instructions to classify incoming requests and hand off to the appropriate specialist, with handoff targets set to all three specialized agents
Add an input guardrail to the triage agent that detects and blocks prompt injection attempts, jailbreak patterns, and requests for information outside the support domain
Add an output guardrail to all agents that redacts credit card numbers, SSNs, and internal system identifiers from responses before they reach the customer
Deploy the system with tracing enabled, monitor handoff accuracy in the OpenAI Dashboard, and iterate on agent instructions based on trace analysis

Outcome: A production customer support system with intelligent routing, domain-specialized agents, safety guardrails, and full observability — built with under 200 lines of Python using the Agents SDK.

Research agent with structured output and tool chain

You need an agent that researches a topic, gathers data from multiple sources, and produces a structured research report
Define a Pydantic model for the output: ResearchReport with fields for title, summary, key_findings (list), sources (list), and confidence_score (float)
Create a research agent with tools for web search, document retrieval, and data extraction, with the output type set to ResearchReport
Add a fact-checking guardrail that validates claims in the report against the retrieved sources, flagging unsupported assertions
The agent receives a research query, uses its tools to gather information from multiple sources, synthesizes findings, and returns a typed ResearchReport object
The structured output is validated by Pydantic, checked by the guardrail, and returned as a Python object that your application can process directly without parsing

Outcome: A research pipeline that produces structured, fact-checked reports with source citations, type-safe outputs, and automated quality validation — leveraging the SDK's structured output and guardrail primitives.

Frequently Asked Questions

What is the OpenAI Agents SDK?

The OpenAI Agents SDK is OpenAI's official Python framework for building multi-agent AI applications. It provides primitives for defining agents with instructions and tools, orchestrating handoffs between agents, enforcing guardrails on inputs and outputs, and tracing execution for debugging. It is the successor to the experimental Swarm framework, redesigned for production use.

How does the OpenAI Agents SDK differ from LangChain or CrewAI?