Guide · Open source

How to use openai-agents-python: install, run agents and tips

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

openai-agents-python is the OpenAI Agents SDK, a Python library for building workflows where one or more LLM-powered agents work together. It is aimed at Python developers who want agents with instructions, tools, guardrails and the ability to hand tasks to other agents. After this guide you will be able to install the package, run a basic text agent and understand the sandbox, realtime and voice options.

OpenAI Agents SDKopenai/openai-agents-python · ★ 30.5k · MIT Install options & downloads

Quick start

1Check Python. Confirm you have Python 3.10 or newer installed.
2Create a virtual environment. Run python -m venv .venv and activate it.
3Install the package. Run pip install openai-agents inside the activated environment.
4Set your API key. Export OPENAI_API_KEY so the examples can call the model.
5Run a text agent. Create an Agent with instructions and call Runner.run_sync, then print result.final_output.
6Explore examples. Open the examples directory in the repository to see sandbox, realtime and voice code.

What you need before you install

The SDK requires Python 3.10 or newer. The examples in the README require an OpenAI API key, which is read from the OPENAI_API_KEY environment variable.

The SDK is provider-agnostic. The README says it supports the OpenAI Responses and Chat Completions APIs as well as 100+ other LLMs.

Python 3.10 or newer
An OpenAI API key set as OPENAI_API_KEY, or another supported LLM provider

Install openai-agents with pip or uv

Create a virtual environment, activate it, then install the package with pip. The activation command differs on Windows.

If you use uv, initialise a project and add the package instead.

For voice support, install the optional voice group: pip install 'openai-agents[voice]'
For Redis session support, install the optional redis group: pip install 'openai-agents[redis]'

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

# With uv
uv init
uv add openai-agents

Run your first text agent

Set OPENAI_API_KEY before running any example. A text Agent is the simplest option and fits workflows that do not need a persistent realtime connection or a sandbox workspace.

Runner.run_sync runs the agent and returns a result whose final_output holds the reply.

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)

Choose between text, sandbox, realtime and voice agents

The README lists four primary ways to run agents. Use a SandboxAgent when the agent must inspect files, run commands, apply patches or keep workspace state over longer tasks. Use a RealtimeAgent for low-latency, server-side voice and multimodal work over WebSocket. Use a VoicePipeline to turn audio into text, run an agent workflow and stream generated speech.

The README notes that the sandbox example uses UnixLocalSandboxClient, which is supported on macOS and Linux. On Windows it points to DockerSandboxClient with the openai-agents[docker] extra or a hosted sandbox client.

Text agent: standard request-and-reply workflows
Sandbox agent: file inspection, commands and patches (macOS and Linux example)
Realtime agent: voice and multimodal over WebSocket
Voice agent: speech-to-text, agent workflow, text-to-speech

Add tools, handoffs, guardrails and tracing

The README lists core concepts you can combine. Agents are configured with instructions, tools, guardrails and handoffs. Handoffs and agents as tools let one agent delegate specific tasks to another.

Tracing is built in, so you can view, debug and optimise agent runs. Sessions handle conversation history across runs, and Human in the loop mechanisms let people take part in runs. Check the documentation pages linked from the README for setup details.

Tools: functions, MCP and hosted tools
Guardrails: input and output validation checks
Handoffs and agents as tools: delegation to other agents
Sessions: automatic conversation history
Tracing: view and debug runs

What people use it for

Building a multi-step workflow where one agent hands a task to a specialist agent
Creating a voice assistant that turns speech into text, runs an agent and speaks the reply
Running an agent that inspects a repository or files inside a sandbox workspace
Debugging agent runs with built-in tracing to see what each step did

Frequently asked questions

Is openai-agents-python free to use?

The repository is released under the MIT licence, which is stated in the project metadata. Calls to OpenAI or other LLM providers are billed by those providers, and the examples require an API key.

What Python version do I need for openai-agents?

The README says Python 3.10 or newer is required. Install it in a virtual environment before running pip install openai-agents.

How do I install openai-agents with pip?

Create a virtual environment with python -m venv .venv, activate it, then run pip install openai-agents. Voice and Redis support are separate optional installs.

Do I need an OpenAI API key?

The examples require the OPENAI_API_KEY environment variable. The SDK also supports 100+ other LLMs, according to the README, but this repository's examples are written around that key.

Can I use openai-agents without writing code?

No. It is a code library with no graphical interface, so you use it by writing Python. If you want a JavaScript or TypeScript version, the README points to a separate repository.

How does openai-agents compare with LangGraph, CrewAI or AutoGen?

This guide does not benchmark them. The SDK is a lightweight Python framework for agents, tools, guardrails, handoffs and tracing. Compare the features you need in each project's documentation before choosing.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use openai-agents-python if you are a Python developer who wants agents with tools, handoffs, guardrails and built-in tracing, including voice options. Pick something else if you need a no-code tool, a non-Python stack, or you cannot use an OpenAI API key or another supported LLM provider.

Install options & downloads