OpenAI Agents SDK Documentation (Python)
by OpenAI
OpenAI's own agent framework, documented down to handoffs, guardrails and tracing.
Overview
The OpenAI Agents SDK is a lightweight, provider-agnostic Python framework for multi-agent workflows, described in its own documentation as 'a production-ready upgrade of our previous experimentation for agents, Swarm'. Its design principle is stated explicitly: enough features to be worth using, but few enough primitives to make it quick to learn. Three of those primitives carry most of the weight. Agents are LLMs configured with instructions and tools; Handoffs let one agent delegate to another; Guardrails validate inputs and outputs and can halt a run before it does damage. Around them the documentation covers sessions for automatic conversation-history management, tracing for viewing and debugging runs, tool types spanning plain Python functions, hosted tools and MCP servers, and human-in-the-loop interruption. Beyond text agents it documents sandbox agents that perform long-horizon work in isolated container workspaces, realtime agents built on gpt-realtime-2.1, and voice pipelines that chain speech-to-text, an agent workflow and text-to-speech. The site is split into a quickstart, configuration, conceptual guides per component, and a full API reference generated from the source. Installation is a single pip install openai-agents, and Python 3.10 or newer is required. The SDK is MIT licensed with roughly 28,500 GitHub stars, and although it is OpenAI's, it supports the Responses and Chat Completions API shapes plus more than a hundred other models.
At a Glance
- Topic
- Agentic
- Level
- Intermediate
- Format
- Documentation
- Cost
- Free
- Duration
- ~3-4 hours for the quickstart plus the core guides; a reference thereafter
- Provider
- OpenAI
- Hands-on
- Yes — code/exercises
- Certificate
- None
What You’ll Learn
- ✓Define agents with instructions, tools, output types and model settings
- ✓Delegate work between agents using handoffs instead of hand-rolled routing
- ✓Enforce input and output guardrails that can stop a run early
- ✓Persist conversation history with sessions rather than hand-managed message lists
- ✓Attach MCP servers, hosted tools and plain Python functions as agent tools
- ✓Read and debug agent runs through the SDK's built-in tracing views
- ✓Build realtime voice agents and speech-to-text to text-to-speech pipelines
- ✓Run long-horizon tasks inside isolated sandbox container workspaces
Highlights
- •Written by the team that shipped Swarm, and explicit about what changed and why
- •Small primitive surface: the conceptual section is readable in a single afternoon
- •Tracing is built in rather than bolted on, making multi-agent debugging tractable
- •Provider-agnostic, documented against Responses, Chat Completions and 100+ other models
- •MIT licensed with ~28.5k stars and an API reference generated from the shipping source
Who It’s For
Best For
- ✓Python engineers building their first multi-agent system
- ✓Teams wanting handoffs and guardrails without adopting a large orchestration framework
- ✓Developers wiring MCP servers into an agent runtime
- ✓Anyone migrating an experimental Swarm prototype to something supported
Prerequisites
- •Python 3.10 or newer and comfort with async Python
- •An OpenAI API key, or another supported model provider
- •Basic familiarity with LLM tool and function calling
FAQ
What is OpenAI Agents SDK Documentation (Python)?
The official documentation for OpenAI's Python Agents SDK, the production successor to the experimental Swarm project. It documents a deliberately small primitive set of agents, handoffs, guardrails, sessions and tracing, plus sandbox agents, realtime voice agents, MCP server integration and human-in-the-loop patterns, with an API reference for every component and a runnable quickstart.
Is OpenAI Agents SDK Documentation (Python) free?
OpenAI Agents SDK Documentation (Python) is free to access.
What level is OpenAI Agents SDK Documentation (Python) for?
OpenAI Agents SDK Documentation (Python) is aimed at a intermediate audience. Recommended background: Python 3.10 or newer and comfort with async Python, An OpenAI API key, or another supported model provider, Basic familiarity with LLM tool and function calling.
How long does OpenAI Agents SDK Documentation (Python) take?
Expect roughly ~3-4 hours for the quickstart plus the core guides; a reference thereafter. Most learners work through it at their own pace.
What will I learn from OpenAI Agents SDK Documentation (Python)?
You'll learn: Define agents with instructions, tools, output types and model settings; Delegate work between agents using handoffs instead of hand-rolled routing; Enforce input and output guardrails that can stop a run early; Persist conversation history with sessions rather than hand-managed message lists; Attach MCP servers, hosted tools and plain Python functions as agent tools; Read and debug agent runs through the SDK's built-in tracing views; Build realtime voice agents and speech-to-text to text-to-speech pipelines; Run long-horizon tasks inside isolated sandbox container workspaces.
Topics
Sources
This page was written from 3 sources, 2 on domains other than openai.github.io.