OpenAI Agents SDK
A Python framework for tool-using, observable multi-agent workflows.
- Source repo
- openai/openai-agents-python
- Stars
- ★ 31k
- Last updated
- 1d ago
- License
- MIT
- Primary language
- Python
- FA score
- 64/100 · Some gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformOpenAI API
- Cost
- Free software; you pay for model usage
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- A Python backend team decomposing a task among specialized agents through handoffs or agents as tools.
- Not a fit if
- Windows developers wanting UnixLocalSandboxClient sandboxing directly
- End users wanting a finished assistant rather than building their own agents
- Source review
- 64/100 · Some gaps
What does this agent do, and when should you use it?
OpenAI Agents SDK is a Python framework for building multi-agent workflows, not a finished end-user assistant. Developers define an Agent, SandboxAgent, or RealtimeAgent with instructions, tools, guardrails, and handoffs, then execute work through Runner. It supports the OpenAI Responses and Chat Completions APIs as well as more than 100 other LLMs. The framework includes function, MCP, and hosted tools; input and output guardrails; human-in-the-loop mechanisms; sessions; and tracing. SandboxAgent can inspect files, run commands, apply patches, and preserve workspace state through a sandbox, while RealtimeAgent targets low-latency voice and multimodal experiences over WebSocket.
A developer creates an Agent, SandboxAgent, or RealtimeAgent and configures its name, instructions, and optionally tools, guardrails, and handoffs. Runner.run_sync executes text or sandbox work and returns result.final_output; the sandbox example supplies a repository through Manifest and GitRepo, then runs it with SandboxRunConfig and UnixLocalSandboxClient so the agent can inspect the workspace, execute commands, and apply patches. RealtimeRunner starts a RealtimeAgent session, where an application can call session.send_message and consume audio, history_added, and agent_end events. The SDK also manages conversation history across runs and records agent runs for viewing, debugging, and workflow optimization.
- A Python backend team decomposing a task among specialized agents through handoffs or agents as tools.
- A macOS or Linux development-automation workflow where an agent must inspect a Git workspace, run commands, and apply patches.
- An application that needs to connect function, MCP, or hosted tools to agent actions while validating inputs and outputs with guardrails.
- A product team preserving conversation history across runs and using tracing to investigate or optimize an agent workflow.
- A developer building a low-latency voice or multimodal interaction that uses RealtimeAgent and RealtimeRunner over WebSocket.
How do you install or deploy this agent?
Python 3.10 or newer is required. Create an environment and install:
python -m venv .venv
source .venv/bin/activate
pip install openai-agentsOr with uv:
uv init
uv add openai-agentsFor voice support, install with pip install 'openai-agents[voice]'. For Redis sessions, install with pip install 'openai-agents[redis]'. Set OPENAI_API_KEY before running the provided examples.
How do you use this agent?
Minimal text agent:
from agents import Agent, Runneragent = 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)For voice, use RealtimeAgent and RealtimeRunner from agents.realtime, then call await session.send_message(...). For workspace work, use SandboxAgent; the documented UnixLocalSandboxClient example works on macOS and Linux. On Windows, use DockerSandboxClient with openai-agents[docker], or a hosted sandbox client.
What are this agent's strengths and limitations?
- One Python framework covers text, sandbox, and realtime agent execution models.
- It explicitly supports OpenAI's Responses and Chat Completions APIs alongside more than 100 other LLMs.
- It includes workflow primitives for handoffs, agents as tools, function/MCP/hosted tools, guardrails, human involvement, sessions, and tracing.
- SandboxAgent supports longer-running workspace tasks through manifests and sandbox clients that can inspect files, run commands, and apply patches.
- The examples require OPENAI_API_KEY; although the SDK states it supports other LLMs, the supplied material does not document their configuration.
- UnixLocalSandboxClient is limited to macOS and Linux; Windows requires DockerSandboxClient, the docker extra, or a hosted sandbox client.
- Voice support, Redis sessions, and Docker sandboxing each require their corresponding optional dependency group.
- The supplied material does not specify pricing, a production deployment topology, adaptation steps for other LLMs, or service-availability commitments.
How does this agent compare with similar options?
For JavaScript or TypeScript projects, the repository points to a separate Agents SDK JS/TS project; this repository is the Python version.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| OpenAI Agents SDK This agent | 64 · Some gaps | Library / SDKFree + model costs | ★ 31k | 1d ago | Python | OpenAI API |
| Composio | 51 · Major gaps | Library / SDKFree + model costs | ★ 31k | today | TypeScript | Claude Code · OpenAI API · Claude API |
| Promptise Foundry | 44 · Major gaps | Library / SDKFree + model costs | ★ 894 | 3d ago | Python | Claude.ai · OpenAI API · Claude API |
| TanStack AI | 76 · Some gaps | Library / SDKFree + model costs | ★ 3.3k | 1d ago | TypeScript | OpenAI API · Claude API |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows: framework provides sandbox agents, human-in-the-loop mechanisms, input/output validation (guardrails), session management, and configurable permissions (e.g., sandbox path grants). Dependencies have version ranges and lock files (uv.lock) and dependency groups. External effects: sandbox agents restrict filesystem access, but no explicit rollback mechanism. Deductions: rollback not explicit, dependency security audit not evident in static files.
Evidence shows: codebase has strict type checking (mypy strict), linting (ruff), and test configuration (pytest), and test files exist. Dependencies have version ranges but no availability guarantee. Failure messages: tests and code provide error messages, but not systematic. Deductions: dependency availability not guaranteed, failure message completeness not fully assessed.
Evidence shows: README describes multiple use cases (text, sandbox, realtime, voice agents) and provides examples. Capability boundaries defined via tools, guardrails, and sandbox mechanisms. Trigger precision: agent instructions and tool definitions are clear. Environment fit: supports multiple Python versions and OS, with optional dependencies. Deductions: known limitations not explicitly listed.
Evidence shows: README provides clear information architecture, detailed install notes, stable naming (version number explicit), rich examples, MIT license, versioning via pyproject.toml and CHANGELOG (not provided), maintenance responsibility by OpenAI. Deductions: known limitations not explicitly listed, CHANGELOG not provided.
Evidence shows: output usability high, multiple run modes (sync, async, streaming), high marginal value (multi-agent workflows, sandbox, realtime), cost-benefit reasonable (open source, MIT). Deductions: none.
Evidence shows: README claims consistent with code and docs, supported by tests and examples, facts and inferences clearly separated. Deductions: none.
- Static review cannot verify actual runtime behavior; all scores based on source code and documentation.
- Dependency security audit not evident in static files; recommend checking for dependency vulnerabilities.
- Rollback mechanism not explicit; recommend reviewing documentation or code for recovery strategies.
- Known limitations not listed in README; may affect user expectations.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
Install the preview Use standard CPython 3.10–3.14 in a virtual environment. These wheels include the native runtime; no Rust toolchain or source build is needed. This preview is distributed through GitHub Releases, not PyPI. Run the command for your platform: Linux x86_64 (glibc 2.39 or newer) ```sh python -m pip install "https://github.com/openai/openai-agents-python/releases/download/v0.24.0-alpha.6/openai_agents-0.24.0a6-cp310-abi3-manylinux_2_39_x86_64.whl" ``` macOS 11 or newer on Apple Silicon ```sh …View on GitHub ↗ -
Release notes excerpt
[0.24.0](https://github.com/openai/openai-agents-python/compare/v0.23.1...v0.24.0) (2026-10-15) Features * expose MCP annotations on converted tools ([#5356](https://github.com/openai/openai-agents-python/issues/5356)) ([75813f8](https://github.com/openai/openai-agents-python/commit/75813f83997b249e5f4b53cccaff0d8a03aa179f)) * support run-wide tool exception formatting ([#5326](https://github.com/openai/openai-agents-python/issues/5326)) ([8fd9a7c](https://github.com/openai/openai-agents-python/commit/8fd9a7cd19a4c495c438d39c83fb03ea3fb5a7e0)) Bug Fixes …View on GitHub ↗ -
Release notes excerpt
[0.23.1](https://github.com/openai/openai-agents-python/compare/v0.23.0...v0.23.1) (2026-10-02) Bug Fixes * restore release tests and refresh required readiness check ([#5278](https://github.com/openai/openai-agents-python/issues/5278)) ([730deb4](https://github.com/openai/openai-agents-python/commit/730deb419c0a2e9e5ebd739499744e4a6bf89ed1)) <!-- agents-release-review:start --> Release readiness review (v0.23.0 -> TARGET 0a5a08b21cd44808d73e8a9e732212dd33b3690d) This is a release readiness report done by $final-release-review skill. Diff …View on GitHub ↗