# OpenAI Agents SDK [PyPI](https://pypi.org/project/openai-agents/) The OpenAI Agents SDK is a lightweight yet powerful framework for building multi-agent workflows. It is provider-agnostic, supporting the OpenAI Responses and Chat Completions APIs, as well as 100+ other LLMs. > [!NOTE] > Looking for the JavaScript/TypeScript version? Check out [Agents SDK JS/TS](https://github.com/openai/openai-agents-js). ### Core concepts: 1. [**Agents**](https://openai.github.io/openai-agents-python/agents): LLMs configured with instructions, tools, guardrails, and handoffs 1. [**Sandbox agents**](https://openai.github.io/openai-agents-python/sandbox_agents): Agents preconfigured to work with a container to perform work over long time horizons. 1. [**Realtime agents**](https://openai.github.io/openai-agents-python/realtime/quickstart/): Build powerful voice agents with `gpt-realtime-2.1` and full agent features 1. [**Voice agents**](https://openai.github.io/openai-agents-python/voice/quickstart/): Build voice pipelines that combine speech-to-text, an agent workflow, and text-to-speech 1. **[Agents as tools](https://openai.github.io/openai-agents-python/tools/#agents-as-tools) / [Handoffs](https://openai.github.io/openai-agents-python/handoffs/)**: Delegating to other agents for specific tasks 1. [**Tools**](https://openai.github.io/openai-agents-python/tools/): Various Tools let agents take actions (functions, MCP, hosted tools) 1. [**Guardrails**](https://openai.github.io/openai-agents-python/guardrails/): Configurable safety checks for input and output validation 1. [**Human in the loop**](https://openai.github.io/openai-agents-python/human_in_the_loop/): Built-in mechanisms for involving humans across agent runs 1. [**Sessions**](https://openai.github.io/openai-agents-python/sessions/): Automatic conversation history management across agent runs 1. [**Tracing**](https://openai.github.io/openai-agents-python/tracing/): Built-in tracking of agent runs, allowing you to view, debug and optimize your workflows Explore the [examples](https://github.com/openai/openai-agents-python/tree/main/examples) directory to see the SDK in action, and read our [documentation](https://openai.github.io/openai-agents-python/) for more details. ## Get started To get started, set up your Python environment (Python 3.10 or newer required), and then install OpenAI Agents SDK package. ### venv ```bash python -m venv .venv source .venv/bin/activate # On Windows: .venv\Scripts\activate pip install openai-agents ``` For voice support, install with the optional `voice` group: `pip install 'openai-agents[voice]'`. For Redis session support, install with the optional `redis` group: `pip install 'openai-agents[redis]'`. ### uv If you're familiar with [uv](https://docs.astral.sh/uv/), installing the package would be even easier: ```bash uv init uv add openai-agents ``` For voice support, install with the optional `voice` group: `uv add 'openai-agents[voice]'`. For Redis session support, install with the optional `redis` group: `uv add 'openai-agents[redis]'`. ## Run your first agents The SDK supports four primary ways to run agents. Set the `OPENAI_API_KEY` environment variable before running any of these examples. ### Run a text agent Use a text `Agent` for workflows that do not need a persistent realtime connection or a sandbox workspace. ```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) # Code within the code, # Functions calling themselves, # Infinite loop's dance. ``` (_For Jupyter notebook users, see [hello_world_jupyter.ipynb](https://github.com/openai/openai-agents-python/blob/main/examples/basic/hello_world_jupyter.ipynb)_) ### Run a sandbox agent Use a [`SandboxAgent`](https://openai.github.io/openai-agents-python/sandbox_agents) when the agent needs to inspect files, run commands, apply patches, or preserve workspace state across longer tasks. This example uses `UnixLocalSandboxClient`, which is supported on macOS and Linux. On Windows, use `DockerSandboxClient` with the `openai-agents[docker]` extra or a hosted sandbox client instead; see [Sandbox clients](https://openai.github.io/openai-agents-python/sandbox/clients/) for setup details. ```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")} ), ) result = Runner.run_sync( agent, "Inspect the repo README and summarize what this project does.", run_config=RunConfig(sandbox=SandboxRunConfig(client=UnixLocalSandboxClient())), ) print(result.final_output) ``` ### Run a realtime agent Use a [`RealtimeAgent`](https://openai.github.io/openai-agents-python/realtime/quickstart/) for low-latency, server-side voice and multimodal experiences over WebSocket. ```python import asyncio from agents.realtime import RealtimeAgent, RealtimeRunner async def main() -> None: agent = RealtimeAgent( name="Assistant", instructions="You are a helpful voice assistant. Keep responses short." ) runner = RealtimeRunner(starting_agent=agent) session = await runner.run() async with session: await session.send_message("Say hello in one short sentence.") async for event in session: if event.type == "audio": # Forward or play event.audio.data. pass elif event.type == "history_added": print(event.item) elif event.type == "agent_end": break if __name__ == "__main__": asyncio.run(main()) ``` ### Run a voice agent Use a [`VoicePipeline`](https://openai.github.io/openai-agents-python/voice/quickstart/) to turn audio into text, run an agent workflow, and stream generated speech. ```python import asyncio import numpy as np from agents import Agent from agents.voice import AudioInput, SingleAgentVoiceWorkflow, VoicePipeline async def main() -> None: agent = Agent(name="Assistant", instructions="You are a helpful voice assistant.") pipeline = VoicePipeline(workflow=SingleAgentVoiceWorkflow(agent)) audio_input = AudioInput(buffer=np.zeros(24000 * 3, dtype=np.int16)) result = await pipeline.run(audio_input) async for event in result.stream(): if event.type == "voice_stream_event_audio": # Forward or play event.data. pass if __name__ == "__main__": asyncio.run(main()) ``` Explore the [examples](https://github.com/openai/openai-agents-python/tree/main/examples) directory to see the SDK in action, and read our [documentation](https://openai.github.io/openai-agents-python/) for more details. ## Contributing Please share bug reports and feature requests through [GitHub issues](https://github.com/openai/openai-agents-python/issues). Pull requests are limited to repository collaborators; we do not accept pull requests from non-collaborators. See [CONTRIBUTING.md](https://github.com/openai/openai-agents-python/blob/main/CONTRIBUTING.md) for the contribution policy and development guide. For security vulnerabilities, follow [SECURITY.md](https://github.com/openai/openai-agents-python/blob/main/SECURITY.md). ## Acknowledgements We'd like to acknowledge the excellent work of the open-source community, especially: - [Pydantic](https://docs.pydantic.dev/latest/) - [Requests](https://github.com/psf/requests) - [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) - [Griffe](https://github.com/mkdocstrings/griffe) This library has these optional dependencies: - [websockets](https://github.com/python-websockets/websockets) - [SQLAlchemy](https://github.com/sqlalchemy/sqlalchemy) - [any-llm](https://github.com/mozilla-ai/any-llm) and [LiteLLM](https://github.com/BerriAI/litellm) We also rely on the following tools to manage the project: - [uv](https://github.com/astral-sh/uv) and [ruff](https://github.com/astral-sh/ruff) - [mypy](https://github.com/python/mypy) and [Pyright](https://github.com/microsoft/pyright) - [pytest](https://github.com/pytest-dev/pytest) and [Coverage.py](https://github.com/coveragepy/coveragepy) - [MkDocs](https://github.com/squidfunk/mkdocs-material) We're committed to continuing to build the Agents SDK as an open source framework so others in the community can expand on our approach. --- Attribution added by YourAIKit. It is not part of the upstream file. - Source: https://github.com/openai/openai-agents-python - Credit: OpenAI - Upstream copy: openai/openai-agents-python at commit 0dc4cf152bff1f50bdc0e41f28808563406545b2, README.md - Copyright: Copyright (c) 2025 OpenAI - License: MIT. Full text: https://youraikit.com/licenses/openai-openai-agents-python-root/LICENSE - Changes: YourAIKit removed 2 embedded images (badges, logos, or pictures); a linked image keeps its link as text. - The full upstream license text (LICENSE) follows. License (LICENSE): ```text MIT License Copyright (c) 2025 OpenAI Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ```