# OpenAI Agents SDK for Python: a lightweight framework for multi-agent workflows

> The openai-agents package gives Python developers agents, handoffs, guardrails and tracing in one install. Here is what the code actually does, where it stops, and how to judge whether it fits.

**openai/openai-agents-python** — Project brief: A lightweight, powerful framework for multi-agent workflows. On Windows, use DockerSandboxClient with the openai-agents[docker] extra or a hosted sandbox client instead; see Sandbox clients for setup details.

- Repository: https://github.com/openai/openai-agents-python
- Website: https://openai.github.io/openai-agents-python/
- Stars: 29,523 · Forks: 4,763
- Language: Python
- License: MIT
- Published: 2026-08-04 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/openai-openai-agents-python

## What openai-agents solves, and who it is written for

Multi-agent code usually starts the same way. One script calls a model, then grows a second script that calls a second model, then a router that decides which one runs, then a retry layer, then somewhere to store the conversation. None of that is the part you wanted to build. openai-agents is the package that assumes those parts already exist and gives them names.

The README lists the vocabulary directly: agents, sandbox agents, realtime agents, voice agents, agents as tools and handoffs, tools, guardrails, human in the loop, sessions, and tracing. Each of those is a concept in the SDK rather than a pattern you reimplement. An agent is an LLM configured with instructions, tools, guardrails and handoffs. A handoff is delegation to another agent for a specific task. A session is automatic conversation history across runs. Tracing is built-in tracking of agent runs.

The audience is narrower than the description suggests. This is a Python library for developers who already write Python, install packages with pip or uv, and are comfortable reading a docstring. It requires Python 3.10 or newer. It is provider-agnostic according to the README, which states support for the OpenAI Responses and Chat Completions APIs plus more than 100 other LLMs. The litellm and any-llm extras in pyproject.toml are the mechanism behind that claim, and they are optional installs, not the default.

If your problem is a single prompt with a single response, this package is more machinery than you need. Its value shows up when one agent has to hand work to another, when a check has to run before an answer is returned, or when you need to see what happened across a run.

## How the SDK is put together: Runner, agents, handoffs and sessions

The control flow in every example runs through Runner. You construct an Agent with a name and instructions, then call Runner.run_sync with that agent and a string. The result object exposes final_output. That is the whole of the basic loop, and the README's haiku example prints the model's text from it.

Around that core, the pieces compose rather than nest. An agent is a configuration object: instructions, tools, guardrails, handoffs. Tools let an agent take actions, and the README groups them as functions, MCP, and hosted tools. Guardrails are configurable safety checks for input and output validation, which means they run at the boundary of a run rather than inside your business logic. Handoffs and agents-as-tools are two ways to delegate, and the difference matters: a handoff transfers the conversation to another agent, while agents-as-tools lets one agent call another and keep control.

Sessions handle history. Without one, each Runner call starts from whatever you pass in. With one, conversation history is managed across runs automatically. The package ships a redis extra for Redis-backed sessions and a sqlalchemy extra for SQLAlchemy with asyncpg, so persistence is a choice you install rather than a default you inherit.

Tracing is on the same footing. The README describes it as built-in tracking of agent runs for viewing, debugging and optimizing workflows, and there is a viz extra that pulls in graphviz for visual output. The repository also carries a Makefile target that reads a released API contract and a prospective contract check, which is a sign the project treats its public surface as something to pin and verify between releases.

The four run modes are separate code paths, not variations of one. A text Agent is for workflows that do not need a persistent realtime connection or a sandbox workspace. A SandboxAgent is for work that inspects files, runs commands, applies patches, or preserves workspace state over longer tasks. A RealtimeAgent runs server-side voice and multimodal sessions over WebSocket. A VoicePipeline chains speech-to-text, an agent workflow, and text-to-speech.

## Installing openai-agents and running a first agent

The README requires Python 3.10 or newer. The recommended path is a virtual environment, then a pip install of the package. Two commands, and the second one is the only name you need to remember.

```bash
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install openai-agents
```

If you already use uv, the README offers the equivalent in two steps. The package name is the same in both cases.

```bash
uv init
uv add openai-agents
```

Optional features are extras on the same package. Voice support and Redis session support are the two the README names explicitly, and both appear in pyproject.toml as optional-dependencies groups.

```bash
pip install 'openai-agents[voice]'
pip install 'openai-agents[redis]'
```

Before running anything, set the OPENAI_API_KEY environment variable. The README states this as a requirement for all four of its run examples. Then the smallest useful program is an agent plus a Runner call. The output is the model's final text, which the README illustrates with a haiku about recursion.

```python
from agents import Agent, Runner

agent = Agent(name="Assistant", instructions="You are a helpful assistant")

result = Runner.run_sync(agent, "Write a haiku about recursion in programming.")
print(result.final_output)
```

One practical note for notebook users: the repository includes examples/basic/hello_world_jupyter.ipynb, and the README points to it separately from the script example. If you run the snippet above in Jupyter and see nothing, that file is the version written for the notebook event loop.

## Sandbox agents and the Windows problem

A SandboxAgent is the mode for tasks that need a workspace rather than a conversation. The README describes it as an agent preconfigured to work with a container to perform work over long time horizons, and the example uses it to inspect a repository and summarize the README.

The example imports Manifest, SandboxAgent and SandboxRunConfig from agents.sandbox, GitRepo from agents.sandbox.entries, and UnixLocalSandboxClient from agents.sandbox.sandboxes. The manifest declares entries, here a git repository pinned to a ref. The run passes a RunConfig alongside the agent and the prompt.

```python
from agents import Runner
from agents.run import RunConfig
from agents.sandbox import Manifest, SandboxAgent, SandboxRunConfig
from agents.sandbox.entries import GitRepo
from agents.sandbox.sandboxes import UnixLocalSandboxClient

agent = SandboxAgent(
    name="Workspace Assistant",
    instructions="Inspect the sandbox workspace before answering.",
    default_manifest=Manifest(entries={"repo": GitRepo(repo="openai/openai-agents-python", ref="main")}),
)
```

This is where the platform boundary sits, and the README is direct about it. UnixLocalSandboxClient is supported on macOS and Linux. On Windows, the guidance is to use DockerSandboxClient with the openai-agents[docker] extra, or a hosted sandbox client, and to consult the sandbox clients documentation for setup. That is a real constraint, not a footnote. If your team develops on Windows and expects the same local sandbox behaviour as your CI runners, the local client is not the path.

The second thing to watch is the manifest. A GitRepo entry clones a repository into the workspace, which means the agent's reach is defined by what you put in entries. The README example is scoped to one repo at one ref. Broadening that is your decision, and the documentation for sandbox clients is where the details live.

## Where openai-agents is the wrong tool

The framework assumes a model call is the unit of work. If your workflow is mostly deterministic data transformation with one classification step at the end, wrapping it in an agent adds a layer without removing any code.

The provider-agnostic claim deserves scrutiny before you rely on it. The README states support for 100+ LLMs, and pyproject.toml carries litellm and any-llm as optional extras with their own version floors and, in the any-llm case, a Python 3.11 minimum. The core dependency is openai>=3.0.0,<4. So the default path is the OpenAI client, and the multi-provider path is an install you add and a compatibility surface someone has to keep working. If your plan depends on a non-OpenAI model, test that route early rather than after the architecture is set.

Realtime and voice are separate run modes with separate extras. Realtime depends on websockets, and voice adds numpy. Neither is part of a base install. A team that installs openai-agents and then discovers it needs voice support has a second install step and a different execution model to learn.

Finally, consider the shape of the abstraction. Handoffs move a conversation from one agent to another. If your mental model is a directed graph where you control every edge and every state transition, you will spend time mapping that model onto handoffs and agents-as-tools. The SDK gives you delegation; it does not give you a graph editor.

## How it compares with PydanticAI and LangGraph

The two comparisons people search for most are PydanticAI and LangGraph, and the difference is mostly about where control lives.

PydanticAI is built around Pydantic, and openai-agents depends on pydantic>=2.12.2 itself, so the two share a validation foundation. The distinction is emphasis. PydanticAI's identity is type-safe model interaction with Pydantic at the centre. openai-agents puts orchestration at the centre: handoffs, agents-as-tools, guardrails, sessions and tracing are first-class concepts in the README's own list. If you want typed model outputs and a thin call layer, the former framing fits better. If you want a documented set of delegation and safety primitives, openai-agents is the more direct match.

LangGraph takes the graph position. Nodes and edges, with explicit state passed between them. That is a closer fit when you need to inspect and control the topology of a workflow, or when the same step must be reachable from several paths. openai-agents does not present a graph as its core abstraction; it presents agents that delegate. The trade-off is legibility. A graph is easier to draw and reason about statically. A handoff chain is easier to write and read as code, but the set of possible transitions is less obvious from the source.

There is also the vendor dimension. openai-agents is published by OpenAI, and the README's provider-agnostic claim is implemented through optional extras rather than being the default dependency. LangGraph and PydanticAI are not tied to OpenAI in the same way. For a team that wants maximum distance from a single model vendor, that is worth weighing against the convenience of the built-in tracing and session handling.

## Maintenance, licence and the cost of keeping up

The repository is not archived, and the last push was on 2026-08-19. Releases in the same window include v0.22.0 on 2026-08-19, v0.21.1 on 2026-08-16, and v0.21.0 on 2026-08-15, while pyproject.toml declares version 0.22.2. Three releases in four days is a fast cadence, and it is the main upgrade cost you should plan for.

The project treats API stability as something to measure. The Makefile has targets that generate and check a released API contract for a given version, plus a prospective contract check that runs integration tests against it. That is a stronger signal than a changelog, because it implies the public surface is diffed between releases. It does not mean the surface never changes; it means changes are visible if you run the check.

Dependencies are pinned with floors and ceilings, including security floors for transitive packages such as httpx2, pyjwt, python-multipart, starlette and urllib3, and a protobuf exclusion noted in the optional voice group. In practice that means a fresh install can pull a newer transitive dependency than your last one, and a lockfile is the only way to keep two environments identical.

The licence is MIT, declared in pyproject.toml and present as a LICENSE file at the repository root. MIT is permissive: it allows commercial use, modification and redistribution with the licence text retained. It says nothing about the terms of the model APIs you call, which are governed separately, and it offers no warranty. That is the standard reading, not legal advice; get counsel if your organisation has rules about which licences it accepts.

## Conclusion

Adopt openai-agents if you are building Python agent workflows and want handoffs, guardrails, sessions and tracing behind one import, and if your runtime is macOS or Linux when you plan to use the local sandbox. Skip it if you need a Windows-native sandbox path, or if you would rather assemble a graph of nodes and edges than delegate between agents. Before committing, verify four things: that Python 3.10 or newer is available, that the optional extras you need are named in pyproject.toml, that your model provider is reachable through the Responses or Chat Completions APIs, and whether your workflow depends on UnixLocalSandboxClient, which the README limits to macOS and Linux.

## FAQ

### Is the OpenAI Agents SDK free?

The package is released under the MIT licence, so the code itself can be used, modified and redistributed at no cost. The model calls you make from it are billed by whichever provider serves them, and the README requires an OPENAI_API_KEY before running its examples.

### How do I install openai-agents in Python?

The README requires Python 3.10 or newer and shows two routes: create a virtual environment and run pip install openai-agents, or, with uv, run uv init then uv add openai-agents. Optional features such as voice and Redis sessions install as extras on the same package name.

### Which is better for me, the OpenAI Agents SDK or PydanticAI?

Both build on Pydantic, and openai-agents depends on pydantic>=2.12.2. The split is emphasis: openai-agents documents orchestration primitives such as handoffs, agents-as-tools, guardrails, sessions and tracing, while PydanticAI centres on type-safe model interaction. Choose based on whether you need delegation primitives or typed model calls.

### How does openai-agents compare with LangGraph?

LangGraph models a workflow as a graph of nodes and edges with explicit state, while openai-agents models it as agents that delegate through handoffs and agents-as-tools. A graph is easier to inspect statically; a handoff chain reads more directly as code but makes the set of possible transitions less obvious.

### How does openai-agents compare with LangChain?

LangChain is a broader framework of integrations and chains, while openai-agents is a narrower SDK whose README lists agents, handoffs, guardrails, sessions and tracing as its core concepts. The repository does not document a LangChain integration, so the two are separate stacks rather than layers of one.

## Sources

- [Official documentation](https://openai.github.io/openai-agents-python/)
- [Official README](https://github.com/openai/openai-agents-python#readme)
- [Project repository](https://github.com/openai/openai-agents-python)
- [Release notes](https://github.com/openai/openai-agents-python/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/openai-openai-agents-python