OpenAI Agents SDK 拆解:官方这个 Agent 框架到底图什么
GitHub 上 28,787 stars,Apache-2.0 协议,Python 3.10+ —— 这是 OpenAI 官方在 openai-agents-python 这个仓库交出的成绩单。
市面上的 Agent 框架已经够多了:LangGraph、CrewAI、AutoGen,每家都有自己的设计哲学。OpenAI 这个时间点再做一个,是单纯凑热闹,还是有真东西?我翻了一遍代码、跑了一遍 demo,也对比了一下 LangGraph,结论是:值得花一个下午试试。
它解决什么问题
多 Agent 开发从 demo 到生产之间,隔着几道沟:
- 工具调用:怎么让 LLM 安全地调外部 API?
- 人机协作:Agent 跑到一半需要人确认怎么办?
- 会话状态:多轮对话的 context 怎么持久化?
- 可观测性:Agent 内部到底做了什么?trace 在哪看?
- 安全护栏:用户输入和模型输出怎么校验?
OpenAI 把这些工程化能力打包成一个轻量 SDK,名字就叫 openai-agents,pip 装一下就能用。开发者不用每次重新造轮子。
怎么用
三步跑通一个 Agent:
pip install openai-agents
# 或者用 uv
uv add openai-agents
如果需要语音能力:
pip install openai-agents[voice]
需要 Redis 做会话存储:
pip install openai-agents[redis]
最小可运行的 hello world:
from agents import Agent, Runner, function_tool
@function_tool
def get_weather(city: str) -> str:
"""查询指定城市的天气"""
return f"{city} 今天晴,25°C"
agent = Agent(
name="WeatherBot",
instructions="你是天气助手,用户问天气就调用工具回答",
tools=[get_weather],
)
result = Runner.run_sync(agent, "北京今天天气怎么样?")
print(result.final_output)
跑起来就这几行。要流式输出,把 run_sync 换成 Runner.run_streamed 就行。
它怎么工作(架构)
核心循环不复杂:
Agent → Runner → LLM 调用 → tool 执行 → 结果回灌 → 直到 final_output
关键模块拆开看:
- Agent:配置层。名字、instructions、tools、handoffs、output_type 都挂在这。
- Runner:执行层。负责驱动整个 run loop。
run_sync/run/run_streamed三种入口。 - Session:会话层。多轮对话的 history 管理,支持 SQLite、Redis 等后端。
- Trace:可观测层。每次 run 自动产生 trace,UI 在
openai.github.io/openai-agents-python/tracing/。 - Guardrail:输入输出校验。input guardrails 跑在用户消息上,output guardrails 跑在 final output 上,双向把关。
Handoff 是这套框架最值得讲的机制 —— Agent 之间的委托。本质是当前 Agent 把控制权交给另一个 Agent 的 run loop。常见用法是「前台 Agent 接到复杂需求 → handoff 给专家 Agent」。
它哪里好 / 哪里不好
好的地方
- 官方背书 + SDK 而非平台。不是 LangGraph 那种需要单独部署 Studio 的平台,就是一个 pip 包,跟你现有代码融在一起。
- Provider-agnostic。原生支持 OpenAI Responses API 和 Chat Completions,也支持 100+ 其他 LLM(通过 LiteLLM 之类的适配层)。不是只能锁 OpenAI。
- Tracing 内置。不用自己接 LangSmith 或别的,开箱即用。
- Guardrails 是输入输出双校验。这点比很多框架想得周全。
- HITL(Human-in-the-loop)原生。
needs_approval之类的机制直接内置。
不好的地方
- 对 OpenAI Responses API 的实时特性有依赖。虽然支持其他模型,但要体验 Realtime Agents 这类高级特性,还是得用 OpenAI。
- 复杂状态机不如 LangGraph。LangGraph 是图结构,能表达任意 DAG;Agents SDK 本质是循环 + handoff,表达力没那么强。
- Voice / Realtime 对国内网络不友好。Realtime Agents 用的是
gpt-realtime,依赖 OpenAI Realtime API,延迟和稳定性都是问题。
我试了下
用 uv init 起个项目,uv add openai-agents,配好 OPENAI_API_KEY,跑 hello world —— 从装包到出结果,< 5 秒。
然后写了个带 Function Tool 的 Agent(就是上面那个查天气的),tool 调用一次成功,输出符合预期。
对比 LangGraph 同等 demo:
- LangGraph 要定义 StateGraph、节点、边,代码量大约是这个的 1.7 倍。
- 但 LangGraph 的状态管理更细,能精确控制每一步的输入输出 schema。
Tracing UI 我点开看了,能看到每次 run 的 tool 调用、LLM 响应、guardrail 触发情况。但本地看不到完整 dashboard(UI 是托管在 GitHub Pages 上的),这点不如 LangSmith 本地化做得好。
它跟同类怎么比
| 维度 | Agents SDK | LangGraph | CrewAI | AutoGen |
|---|---|---|---|---|
| 形态 | SDK | 框架 + 平台 | 框架 | 框架 |
| 状态表达 | 循环 + handoff | DAG 图 | 角色协作 | 对话 |
| 上手成本 | 低 | 中 | 低 | 中 |
| Tracing | 内置 | LangSmith | 第三方 | 第三方 |
| 适合场景 | 标准化工具链 | 复杂工作流 | 角色扮演 | 研究 |
一句话总结:比 LangGraph 轻量,比 CrewAI 偏 SDK 风格,比 AutoGen 更工程化。
谁该用
适合:
- 想快速搭生产级 Agent 工具链的团队
- 已经在用 OpenAI API 的项目
- 需要标准化 Tracing 的多 Agent 系统
- 需要 Guardrails / Handoff / Session 这些开箱即用能力的小到中型应用
不适合:
- 需要复杂 DAG / 状态机的工作流(建议 LangGraph)
- 完全离线 / 本地部署(依赖太重)
- 国内需要稳定 Voice / Realtime 的产品
我的判断
OpenAI 这个 SDK 不是要取代 LangGraph,而是给「已经在用 OpenAI API、想快速给 Agent 加工程化能力」的团队一个官方选择。28k stars 说明社区认账。
如果你刚开始做 Agent,没历史包袱,这个 SDK 的体验是当下最顺的。如果你的工作流已经是图结构了,别为了换而换。