OpenAI Agents SDK

OpenAI Agents SDK 快速入门

OpenAI 官方出品 —— provider-agnostic 的多 Agent 框架，2025 年的「Agents 入门首选」。

这是什么？适合谁？

OpenAI Agents SDK 是 OpenAI 官方在 2025 年开源的多 Agent 工作流框架，定位「a lightweight yet powerful framework for multi-agent workflows」。GitHub 28.1K+ stars（截至 2026-07），MIT 开源，当前活跃迭代（2026-07 仍有提交）。

它最大的特点是 provider-agnostic——虽然名字带「OpenAI」，但实际上通过 LiteLLM / any-llm 支持 100+ LLMs，包括 Anthropic Claude、Google Gemini、DeepSeek、Anthropic、xAI Grok、HuggingFace Inference Providers 等。所以你不会因为用了这个 SDK 就被锁死在 OpenAI。

核心能力矩阵（9 大特性）：

1. Agents — 配置 instructions + tools + guardrails + handoffs 的 LLM 单元。
2. Sandbox Agents — 在容器里长期跑任务的 Agent（适合代码编辑、文件处理等长时任务）。
3. Agents as Tools / Handoffs — Agent 间委派（一个 Agent 把任务「转交」给另一个）。
4. Tools — 自定义函数、MCP、Hosted Tools（OpenAI 内置工具）。
5. Guardrails — 输入/输出校验（防 prompt injection、敏感信息）。
6. Human in the Loop — 关键节点暂停等人确认。
7. Sessions — 自动跨 run 的会话历史管理（SQLite / Redis / SQLAlchemy）。
8. Tracing — 内置 trace，可视化每个 Agent run、tool call、handoff。
9. Realtime Agents — 基于 gpt-realtime-2.1 的语音 Agent（WebSocket，低延迟）。

适合谁？一是已经在用 OpenAI API、想升级到多 Agent 工作流的开发者；二是想用 OpenAI 官方工具链（Hosted Tools、Tracing UI）但又不想被 OpenAI 锁死的团队（provider-agnostic）；三是做语音 Agent 的开发者（RealtimeAgent 是 2025-2026 的杀器）。不适合：完全不想写 Python 的用户（这是纯 Python SDK）；也不适合企业级多租户部署（Agno AgentOS 这类有 RBAC 的 runtime 更合适）。

准备工作

1. Python 3.10 及以上：访问 python.org 下载安装。
2. 包管理器：pip 或 uv（官方推荐 uv，更快）。
3. 模型 API Key：默认 OpenAI API Key（OPENAI_API_KEY）；接其他模型需要相应 Key（ANTHROPIC_API_KEY、GEMINI_API_KEY 等）。
4. （可选）Docker：跑 Sandbox Agents 在 Windows 上需要 Docker；macOS/Linux 可以用 UnixLocalSandboxClient。

3 步快速上手

第 1 步：安装

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

可选 extras：

• 语音支持：pip install 'openai-agents[voice]'
• Redis sessions：pip install 'openai-agents[redis]'
• Docker sandbox：pip install 'openai-agents[docker]'

第 2 步：创建 Agent

新建 hello_agent.py：

import asyncio
from agents import Agent, Runner

agent = Agent(
    name="助手",
    instructions="你是一个有帮助的中文助手，回答简洁。",
)

async def main():
    result = await Runner.run(agent, "写一首关于秋天的五言绝句。")
    print(result.final_output)

asyncio.run(main())

跑通后 Agent 会调用 OpenAI Responses API（默认 gpt-4o）输出五言绝句。Runner.run() 是 async 接口；想同步跑用 Runner.run_sync(agent, "...")。

第 3 步：添加工具 + Handoff

import asyncio
from agents import Agent, Runner, function_tool

@function_tool
def get_weather(city: str) -> str:
    """查询指定城市的天气"""
    return f"{city}：晴天 25°C，湿度 45%"

weather_agent = Agent(
    name="天气助手",
    instructions="帮用户查天气，使用 get_weather 工具。",
    tools=[get_weather],
)

# 主 Agent 通过 handoff 把问题路由到 weather_agent
triage_agent = Agent(
    name="总助手",
    instructions="用户问天气时交给天气助手。",
    handoffs=[weather_agent],
)

async def main():
    result = await Runner.run(triage_agent, "北京今天天气怎么样？")
    print(result.final_output)

asyncio.run(main())

handoffs=[weather_agent] 让 triage_agent 自动判断什么时候把对话「转交」给 weather_agent，这是多 Agent 协作的核心机制。

常见踩坑

踩坑 1：AuthenticationError: No API key provided

• 症状：运行 Agent 时报 openai.AuthenticationError: No API key provided，即使已设置环境变量仍然报错
• 原因：SDK 优先从 OPENAI_API_KEY 环境变量读取，但未正确 export（Windows PowerShell 用 $env: 而非 export），或 .env 文件未被加载
• 解决：Linux/macOS 用 export OPENAI_API_KEY=sk-...；Windows PowerShell 用 $env:OPENAI_API_KEY="sk-..."；推荐用 python-dotenv 配合 .env 文件；确认 key 有对应的模型访问权限
• 参考：GitHub Issue #636（Human-In-The-Loop 架构讨论——API Key 配置是最基础的踩坑）

踩坑 2：多 Agent Handoff 死循环不退出

• 症状：Agent A 把对话转交给 B，B 又转回给 A，反复循环直到超时
• 原因：handoff 没有终止条件——模型判断「不确定」时倾向于转交而非直接回答，形成 A → B → A 环路
• 解决：Runner.run(agent, msg, max_turns=10) 强制截断；在 instructions 中明确写「如果不知道答案直接说不知道，不要再转交」；为每个 Agent 设置清晰的职责边界
• 参考：GitHub Issue #1156（Tool Call Results not appearing 讨论中涉及 handoff 流程控制）

踩坑 3：Windows 上 UnixLocalSandboxClient 不可用

• 症状：from agents.sandbox import UnixLocalSandboxClient 报错或运行时报 POSIX 相关错误
• 原因：UnixLocalSandboxClient 依赖 Unix 域套接字（POSIX 特定），Windows 不支持
• 解决：安装 pip install "openai-agents[docker]" extra，使用 DockerSandboxClient；CI/CD 流水线也用 Docker（macOS/Linux 可继续用 UnixLocalSandboxClient）
• 参考：GitHub Issue #2868（Per-tool authorization middleware——sandbox 相关设计讨论）

踩坑 4：Realtime Agent WebSocket 连接频繁断开

• 症状：Realtime Agent 运行时 WebSocket 连接周期性断开，Agent 响应中断
• 原因：NAT / 代理 / 防火墙对 WebSocket 长连接有超时限制（通常 60 秒无活动即断开）；默认无心跳保活
• 解决：在 RealtimeRunner 中设置合理的 ping 间隔（ping_interval=15 秒）；生产环境用托管 WebSocket 服务（Cloudflare Durable Objects 或 ngrok）；或在重连逻辑中实现指数退避
• 参考：GitHub Issue #636（Realtime Agent 稳定性是社区关注的高优先级问题）

踩坑 5：@function_tool 装饰器未生效（Agent 不调用工具）

• 症状：定义了 @function_tool 函数并传入 tools=[]，但 Agent 从未调用它
• 原因：@function_tool 装饰器必须从 agents 导入（from agents import function_tool）；工具函数必须有 docstring（模型通过 docstring 理解工具用途）；传参格式不对
• 解决：确保 from agents import function_tool；docstring 包含「用途、参数、返回」三要素（如 """获取指定城市的天气。Args: city: 城市名。Returns: 天气描述。"""）；检查 Agent(tools=[my_tool]) 的传参是否列表而非单个函数
• 参考：GitHub Issue #1397（GPT-5 tool call 兼容性讨论——工具定义规范是排查重点）

踩坑 6：Tracing UI 打不开/不显示

• 症状：运行 Agent 后去 https://platform.openai.com/traces 看追踪，但页面空白或提示「No traces found」
• 原因：Traces 默认写入本地 SQLite 文件（trace.db），未发送到 OpenAI 云端；或 tracing.disabled = True 被其他代码关闭了 tracing
• 解决：本地 tracing 通过 openai-trace ui 命令启动本地 UI 查看；要发送到 OpenAI Dashboard 需在构造 Runner 时传 trace_exporters 参数；确认 tracing.disabled 为 False（默认为 False）
• 参考：GitHub Issue #2970（Pre-execution validation for tool calls——tracing 调试相关讨论）

踩坑 7：中文 prompt 报 UnicodeDecodeError

• 症状：在 Windows 终端运行 Agent 代码，中文 prompt 或输出报 UnicodeDecodeError: 'gbk' codec
• 原因：Windows 控制台默认 GBK 编码，Python 的 stdin/stdout 无法正确处理 Unicode
• 解决：set PYTHONIOENCODING=utf-8 切换编码；或将输出重定向到文件 python hello_agent.py > out.txt（文件用 UTF-8）；推荐在 VS Code 终端中运行（默认 UTF-8）
• 参考：GitHub Issue #1156（Tool Call Results not appearing——编码问题在多语言环境下被多次提及）

踩坑 8：Sandbox Agent 找不到入口文件

• 症状：Sandbox Agent 启动后报 FileNotFoundError 或提示找不到项目文件
• 原因：SandboxAgent 的 Manifest 必须显式声明容器内的入口文件（如 entries={"repo": GitRepo(repo="...", ref="main")}），未声明时 sandbox 不知道从哪里开始读
• 解决：在 SandboxAgent(default_manifest=Manifest(entries={"repo": GitRepo(repo="https://github.com/owner/repo", ref="main")})) 中明确声明仓库和分支；如果需要本地文件，用 Manifest(entries={"src": LocalFile(path="./my_project")})
• 参考：GitHub Issue #2868（Per-tool authorization 讨论中涉及 sandbox 文件系统配置）

初级用法

• 单 Agent：上面示例就是——Agent(name=..., instructions=...) + Runner.run(agent, "...")。
• @function_tool 自定义工具：用 @function_tool 装饰 Python 函数，docstring 自动作为工具描述传给 LLM。
• Handoff（Agent 转交）：一个 Agent 的 handoffs=[other_agent] 字段让模型判断何时把对话交给其他 Agent。
• Agents as Tools：把 Agent 当成 tool 给主 Agent 调用（区别于 handoff：tool 是「调用并拿结果」，handoff 是「完全转交对话」）。
• Sessions：自动管理多轮对话历史，Runner.run(agent, "msg", session=session_obj)。
• Guardrails：输入/输出校验函数，模型响应不通过规则就抛异常（防 prompt injection）。
• Hosted Tools：OpenAI 内置工具（WebSearchTool、CodeInterpreterTool 等）直接 from agents.tools import hosted_tool。

高级玩法

• Sandbox Agents：SandboxAgent(default_manifest=Manifest(entries={"repo": GitRepo(...)}))，在隔离容器里跑 Agent，适合长时编码任务（自动 inspect / patch 文件）。
• Realtime Agents：RealtimeAgent(name=..., instructions=...) + RealtimeRunner，基于 WebSocket 做语音/多模态 Agent，用 gpt-realtime-2.1 模型。
• MCP 工具：通过 MCPServerStdio 或 MCPServerSse 接入任意 MCP Server 的工具。
• Tracing + 自定义 processor：内置 TracingProcessor 抽象，可以把 trace 发到 Langfuse / Arize Phoenix 等可观测平台。
• Sessions 持久化：SQLiteSession / RedisSession / 自定义 SQLAlchemySession，跨 run 保留对话历史。
• Multi-agent 编排模式：
  • Manager 模式：主 Agent 用 tools=[agent_a.as_tool(), agent_b.as_tool()] 调用子 Agent。
  • Handoff 模式：主 Agent 用 handoffs=[agent_a, agent_b]，把控制权完全转交。
• Human in the Loop：Agent(..., interrupt_on={"send_email": True}) 让关键工具调用前暂停等用户确认。
• 任意 LLM 路由：通过 litellm 或 any-llm 切到 Claude / Gemini / DeepSeek，模型切换不影响 Agent 代码。

小技巧

1. 先用 gpt-4o-mini 试水：便宜（$0.15/M input）、快、中文好。跑通后再换 gpt-4.1 或 gpt-5 提质量。
2. 用 max_turns 兜底：handoff 容易出死循环，Runner.run(agent, msg, max_turns=10) 强制截断。
3. docstring 是 Agent 的说明书：自定义 tool 不写 docstring = Agent 不知道怎么调用。包含「用途、参数、返回、调用场景」。
4. Realtime Agent 用托管 WebSocket：本地 WebSocket 在 NAT 后容易断。生产用 Cloudflare Durable Objects / ngrok / OpenAI 自家的 Realtime API endpoint。
5. Tracing 默认开：调试时 tracing.disabled = False（默认就是开），跑完去 https://platform.openai.com/traces 看完整链路。
6. provider-agnostic 不是免费的：用 Claude / Gemini 时 tool call schema 跟 OpenAI 略有差异，复杂 tool 可能需要改写 docstring 适配。
7. Sandbox 在 macOS/Linux 才能用 UnixLocalSandboxClient：Windows 必须 Docker，CI/CD 流水线里跑 Sandbox Agent 也用 Docker。

进阶学习建议

如果你想从「能跑通 SDK」走到「能在产品里用 SDK」，按这条路径走最快：

1. 先看 examples/basic：官方维护的 30+ 完整示例，覆盖 hello world → handoffs → tools → sessions → guardrails。
2. 跑 examples/agent_patterns：看 Manager vs Handoff 两种多 Agent 编排的实际写法。
3. 接 MCP：把 Agent 接到 GitHub MCP / Filesystem MCP，立刻获得 10+ 个新工具。
4. Sandbox Agents：如果做编码助手方向（Cursor / Devin 替代品），SandboxAgent + GitRepo entry 是核心组件。
5. Realtime Agents：做语音助手方向（替代 Vapi / Retell），RealtimeAgent + WebSocket 是 2025-2026 的热门方向。
6. 生产化：Sessions 持久化 + Tracing → Langfuse + Guardrails + Human in the loop。

可以对比阅读的几个相关项目：Anthropic Claude Agent SDK、Google ADK、smolagents。

FAQ

Q1: OpenAI Agents SDK 是免费的吗？

A1: 软件 MIT 开源免费。运行成本 = 模型 API 调用费：OpenAI 模型按 token 计费（gpt-4o-mini 约 $0.15/M input，gpt-4.1 约 $2/M input，gpt-realtime 语音更贵）。接其他模型按对应厂商价格（Claude Sonnet 约 $3/M input、Gemini 2.5 Flash 有免费额度）。本地 LLM 0 边际成本。

Q2: 跟 LangGraph 有什么区别？

A2: LangGraph 是「图编排」（节点 + 边 + 状态机），更偏通用工作流；OpenAI Agents SDK 是「Agent 优先」——Agent、Handoff、Hosted Tools 都是一等公民。LangGraph 生态更广（LangSmith 调试、企业用户多），OpenAI Agents SDK 跟 OpenAI 平台集成更深（Hosted Tools、Tracing UI、Realtime API）。两者可以混用——在 LangGraph 的节点里跑 OpenAI Agents SDK Agent。

Q3: 必须用 OpenAI 模型吗？

A3: 不是。SDK 通过 litellm / any-llm 支持 100+ LLMs（Anthropic Claude、Google Gemini、xAI Grok、DeepSeek、Mistral、HuggingFace Inference Providers 等）。在 Agent 配置里指定 model="claude-sonnet-4-..." 即可切换模型（需要相应 extra 包和 API Key）。

Q4: 跟 LangChain Agent 比呢？

A4: LangChain Agent 偏「工具链 + 生态」——Retriever、Memory、OutputParser 一应俱全；OpenAI Agents SDK 偏「多 Agent 协作 + Tracing + 实时语音」——Handoffs、RealtimeAgent、Hosted Tools 是 LangChain 没有的。如果你的场景是「多 Agent 路由 + 语音/多模态」，选 OpenAI Agents SDK；如果你的场景是「复杂 RAG + 文档处理」，选 LangChain。

Q5: Sandbox Agents 和普通 Agent 有什么区别？

A5: 普通 Agent（Agent）是「一次性问答」，每轮调用完就结束；Sandbox Agent（SandboxAgent）在容器里跑，可以跨多次调用持续修改文件、检查状态——适合「帮我重构这个 repo」「帮我修这个 bug」这种长时编码任务。Sandbox 跑在 Docker 里（Windows）或 Unix 容器（macOS/Linux）。

参考链接

• OpenAI Agents SDK GitHub
• OpenAI Agents SDK 文档
• OpenAI Agents SDK Examples
• OpenAI Tracing Dashboard
• OpenAI Responses API 文档

免责声明

本文涉及的 GitHub stars 数、版本号、价格等信息基于公开资料整理（截至 2026-07），实际数据请以各项目仓库为准。OpenAI Agents SDK 仍在活跃迭代，API 接口可能在后续版本变化，部署到生产前请阅读最新 README 和 CHANGELOG。文中代码示例仅供学习参考，请在遵循各项目许可证的前提下使用。