openai /
openai-agents-python
Python framework for building agents that use tools, hand off tasks, and run in sandboxes
- 30.2k stars
- 438 stars since 3 Oct
- Python
- Updated today
- Some experience
- AI agents
Building an agent usually means wiring a model to tools, keeping conversation history, checking inputs and outputs, and passing work between specialists. This SDK packages those pieces. You define an Agent with instructions and tools, then run it with a Runner.
Agents can call functions, MCP servers and hosted tools. They can hand work to other agents, or use another agent as a tool. Guardrails check input and output, human-in-the-loop steps let a person step in, and sessions keep history between runs. Tracing records each run so you can view and debug it.
Beyond text agents, there are sandbox agents that work inside a container (inspect files, run commands, apply patches), realtime agents for low-latency voice over WebSocket, and a voice pipeline that chains speech-to-text, an agent and text-to-speech. The README says it supports the OpenAI Responses and Chat Completions APIs plus 100+ other LLMs. A JavaScript/TypeScript version lives in a separate repo.
What it does
Agents, tools and handoffs
Configure an agent with instructions and tools (functions, MCP, hosted tools). Delegate to other agents through handoffs or by using them as tools.
Guardrails and human in the loop
Add configurable input and output checks, and built-in ways to involve a person during an agent run.
Sessions and tracing
Conversation history is managed automatically across runs. Built-in tracing lets you view and debug each run.
Sandbox agents
A SandboxAgent works in a container workspace to inspect files, run commands and apply patches over longer tasks. Unix local and Docker clients are mentioned.
Realtime and voice agents
RealtimeAgent handles voice and multimodal sessions over WebSocket. VoicePipeline turns audio into text, runs an agent, and streams speech back.
What you could build
- Build a customer-support assistant that hands questions off to specialist agents.
- Create a coding helper that inspects a git repo and runs commands in a sandbox.
- Add input and output guardrails to an LLM app before it reaches users.
- Prototype a voice assistant using the realtime or voice pipeline.
- Trace and debug multi-step agent runs to see where a workflow goes wrong.
Get started
Use Python 3.10 or newer, create a virtual environment and install the package. Set the OPENAI_API_KEY environment variable, then run the short Agent and Runner example from the README. Optional extras exist for voice and Redis sessions.
python -m venv .venvsource .venv/bin/activate # On Windows: .venv\Scripts\activatepip install openai-agentsCommands are copied from the project's README. Read it on GitHub for the full setup.
More in AI agents
openclaw
Self-hosted AI assistant that answers in your chat apps and runs on your own machine
hermes-agent
Self-hosted AI agent that keeps skills and memory, and chats via terminal or Telegram
TradingAgents
A team of LLM agents that debate and decide on stock trades, for research
paperclip
A Node.js server and React dashboard for running a team of AI agents like a company
autoresearch
Let an AI agent edit a small LLM training script overnight and keep what improves it
ruflo
Agent harness adding swarms, memory and plugins around Claude Code and Codex
OpenManus
Open-source general AI agent that runs tasks from your terminal with your own LLM key
multica
A shared board where you assign issues to AI coding agents like teammates
openhuman
Rust agent harness with a desktop app, terminal client and embeddable library
buzz
Self-hostable team workspace where people and AI agents share channels on a Nostr relay