OpenAI Agents SDK

OpenAI Agents SDK 是一个轻量级但功能强大的框架，用于构建多智能体工作流。它与提供商无关，支持 OpenAI 的 Responses 和 Chat Completions API，以及 100 多种其他大语言模型。

[!NOTE] 您在寻找 JavaScript/TypeScript 版本吗？请查看 Agents SDK JS/TS。

核心概念：

1. 智能体：配置了指令、工具、安全约束和交接机制的大语言模型
2. 作为工具的智能体 / 交接：将特定任务委托给其他智能体
3. 工具：各种工具使智能体能够执行操作（函数、MCP、托管工具）
4. 安全约束：可配置的安全检查，用于输入和输出验证
5. 人类参与环节：内置机制，可在智能体运行过程中引入人工干预
6. 会话：自动管理跨智能体运行的对话历史
7. 追踪：内置的智能体运行跟踪功能，允许您查看、调试和优化工作流
8. 实时智能体：使用 gpt-realtime-1.5 和完整智能体功能构建强大的语音智能体

浏览 examples 目录，了解 SDK 的实际应用；更多详细信息请参阅我们的 文档。

开始使用

要开始使用，请设置您的 Python 环境（需 Python 3.10 或更高版本），然后安装 OpenAI Agents SDK 包。

venv

python -m venv .venv
source .venv/bin/activate  # 在 Windows 上：.venv\Scripts\activate
pip install openai-agents

如需语音支持，请使用可选的 voice 组进行安装：pip install 'openai-agents[voice]'。如需 Redis 会话支持，请使用可选的 redis 组进行安装：pip install 'openai-agents[redis]'。

uv

如果您熟悉 uv，安装该包将更加简单：

uv init
uv add openai-agents

如需语音支持，请使用可选的 voice 组进行安装：uv add 'openai-agents[voice]'。如需 Redis 会话支持，请使用可选的 redis 组进行安装：uv add 'openai-agents[redis]'。

运行您的第一个智能体

from agents import Agent, Runner

agent = Agent(name="Assistant", instructions="您是一位乐于助人的助手")

result = Runner.run_sync(agent, "写一首关于编程中递归的俳句。")
print(result.final_output)

# 代码之中藏代码，
# 函数自调自身时，
# 无限循环舞翩跹。

（运行此代码时，请确保已设置 OPENAI_API_KEY 环境变量）

（对于 Jupyter Notebook 用户，请参阅 hello_world_jupyter.ipynb）

浏览 examples 目录，了解 SDK 的实际应用；更多详细信息请参阅我们的 文档。

致谢

我们谨向开源社区的杰出工作表示感谢，特别是：

• Pydantic
• Requests
• MCP Python SDK
• Griffe

本库具有以下可选依赖项：

• websockets
• SQLAlchemy
• any-llm 和 LiteLLM

我们还依靠以下工具来管理项目：

• uv 和 ruff
• mypy 和 Pyright
• pytest 和 Coverage.py
• MkDocs

我们致力于继续将 Agents SDK 打造成一个开源框架，以便社区中的其他人能够在此基础上进一步发展。

OpenAI Agents SDK 快速上手指南

OpenAI Agents SDK 是一个轻量级但功能强大的框架，用于构建多智能体（Multi-Agent）工作流。它不依赖特定提供商，支持 OpenAI Responses 和 Chat Completions API，以及 100+ 其他大语言模型。

环境准备

• 操作系统：Linux、macOS 或 Windows
• Python 版本：Python 3.10 或更高版本
• API 密钥：需准备 OPENAI_API_KEY 环境变量

安装步骤

你可以选择使用标准的 venv 或现代化的 uv 工具进行安装。

方式一：使用 venv（标准方案）

python -m venv .venv
source .venv/bin/activate  # Windows 用户请使用：.venv\Scripts\activate

# 基础安装
pip install openai-agents

# 可选：安装语音支持
pip install 'openai-agents[voice]'

# 可选：安装 Redis 会话支持
pip install 'openai-agents[redis]'

国内加速建议：如果下载速度较慢，可使用清华或阿里镜像源： pip install -i https://pypi.tuna.tsinghua.edu.cn/simple openai-agents

方式二：使用 uv（推荐方案）

如果你已安装 uv，安装过程将更加简洁高效：

uv init
uv add openai-agents

# 可选：安装语音支持
uv add 'openai-agents[voice]'

# 可选：安装 Redis 会话支持
uv add 'openai-agents[redis]'

基本使用

以下是最简单的单智能体运行示例。确保在运行前已设置环境变量 OPENAI_API_KEY。

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.

Jupyter 用户注意：请参考官方仓库中的 hello_world_jupyter.ipynb 示例。

更多高级功能（如智能体移交、工具调用、护栏机制等）请查阅 官方文档 或浏览 examples 目录。