OpenAI Agents SDK 实战观察：它适合替代 LangGraph 吗？

团队用 LangGraph 搭了客服 Agent 原型,跑起来才发现图里大部分节点只是在做一件事：调用模型,再调一个工具。代码写得挺工整,但样板占了不小比例,于是有人问：能不能换成 OpenAI Agents SDK 减掉这一层？

另一个场景看起来更棘手：报表 Agent 每天跑 20 分钟,中途要等人审批 SQL 才能继续。这时”代码少”已经不是唯一指标,能不能暂停、恢复、审计才是关键。OpenAI Agents SDK 有 sessions 和 guardrails,但它能替代 LangGraph 的 checkpoint 和 interrupt 吗？

两个场景指向同一个问题：OpenAI Agents SDK 看起来轻量,但它到底适合替代 LangGraph,还是只适合一部分任务？真正要判断的是,你的 Agent 只是需要模型、工具和委派,还是已经需要持久状态、人工暂停、恢复执行和审计回放。

先搞清楚一件事：它们不在同一层

在讨论替代之前,先看清楚两个框架的定位差异。OpenAI Agents SDK 的官方文档把自己描述为”轻量、易用、少抽象的 agentic app 构建包”——核心是跑 agent loop、管理工具调用、处理 handoff 委派、执行 guardrails 校验和记录 tracing。LangGraph 则明确说自己是”long-running stateful workflow 的底层编排基础设施”——核心是显式状态图、checkpoint 持久化、interrupt 暂停、resume 恢复、time travel 回放和 fault tolerance。

一个更像对话+委派模式,一个更像有向图状态机。下表直接对比它们的抽象层级：

维度	OpenAI Agents SDK	LangGraph
核心抽象	Agent loop + 工具调用	显式状态图（节点+边）
状态管理	Sessions（对话连续性）	Checkpointers（图状态快照）
委派机制	Handoffs（agent as tool）	Graph routing（节点转移）
校验机制	Guardrails（input/output）	Interrupt（状态机暂停）
恢复机制	无内置恢复	Resume（从 checkpoint 继续）
回放机制	无内置回放	Time travel（状态回放）
故障恢复	无内置容错	Fault tolerance（故障后继续）
官方定位	Agentic app 构建包	Long-running workflow 编排

从这张表可以看出：Agents SDK 更偏 agent runtime 原语,LangGraph 更偏 stateful workflow orchestration。如果你只需要一个能调用工具、偶尔委派给专家 agent 的 agent loop,Agents SDK 可能就够了。但如果你的任务需要暂停、恢复、审计或故障后继续跑,LangGraph 的 checkpoint 和 interrupt 机制才是关键。

这不是”谁更强”的问题,而是它们根本不在同一层。类比一下：Agents SDK 像是给你一套跑 agent 的 SDK 和 tracing,LangGraph 像是给你一个状态机引擎和持久层。如果你的流程能画成明确的状态转移图,LangGraph 更合适；如果只是”模型+工具+偶尔升级”,Agents SDK 可能更轻。关于为什么 prompt 难以替代状态机,可以继续看 Agent 状态机与 workflow 边界。

能力矩阵：10个维度对照

抽象层级不同,不代表不能对比具体能力。下表从 10 个维度对照两个框架的实际表现,落到具体场景和实现方式：

维度	OpenAI Agents SDK	LangGraph
Agents/Tools	强：Agent + Runner 管工具调用	强：节点可嵌套 agent 或纯函数
Handoffs	强：agent as tool,支持 input_filter	需显式画图：routing 边转移
Guardrails	强：input/output + tripwire	不同抽象：interrupt 是状态机暂停
Tracing	强：内置 span/model/tool/handoff	强：需配 LangSmith 或自建
Sessions/HITL	中：session 对话连续性,HITL API	强：interrupt 暂停,Command(resume=…) 恢复
MCP	强：MCP-backed tools 集成	强：MCP server 可接入节点
状态持久化	弱：只有 session conversation	强：checkpointer 保存图状态快照
失败恢复	无：无内置容错机制	强：fault tolerance,checkpoint 后继续
可回放 workflow	无：无 time travel	强：time travel 回放历史状态
生产部署	中：需自己搭部署和监控	强：LangSmith Deployment / Agent Server

关键差异集中在状态持久化、失败恢复和可回放 workflow 三个维度。Agents SDK 的 sessions 用于对话连续性,但 LangGraph 的 checkpointers 保存的是整个图的状态快照，包括节点执行历史、中间变量和等待的外部输入。如果报表 Agent 跑到一半突然崩溃,Agents SDK 只能重新从头跑；LangGraph 可以从最后一个 checkpoint 继续,避免重复执行已完成的步骤。

另一个关键差异是 HITL 的实现方式。Agents SDK 有 guardrails 和 HITL API,适合校验输入输出,但它的中断机制是”tripwire”——触发后整个执行停止。LangGraph 的 interrupt 是状态机级别的暂停：interrupt() 可以在某个节点暂停,checkpointer 保存当前状态,等外部输入后再用 Command(resume=...) 恢复。这意味着 LangGraph 可以在 tool call 之前暂停,等人审批后再继续；而 Agents SDK 的 guardrails 更适合”输入不符合预期就停掉”,而不是”暂停等人审核再继续”。更完整的人审边界可以参考 Human-in-the-loop Agent 审批设计。

第三个差异是回放能力。LangGraph 的 time travel 让你可以回到任意 checkpoint,查看当时的状态和执行路径,适合审计和排障。Agents SDK 有 tracing,能可视化执行路径,但不能回到某个历史状态重新执行。如果你的场景需要”看两小时前为什么走了这条分支”,LangGraph 更合适。

Agents SDK 能做什么：核心原语清单

OpenAI Agents SDK 的核心原语分成五块：Agents、Handoffs、Guardrails、Tracing 和 Sessions/HITL/MCP。下面是清单式的梳理：

Agents：一个 Agent 是 LLM + instructions + tools + optional runtime behavior 的组合。Runtime behavior 包括 handoffs（委派给其他 agent）、guardrails（输入输出校验）、structured outputs（强制返回特定格式）。Agent 和 Runner 配合,SDK 管整个 agent loop 的 turns、工具调用、guardrails 检查和 handoffs 委派。

Handoffs：handoff 让一个 agent 把任务委派给另一个 agent——本质是以 tool 形式暴露给 LLM。handoff() 可配置目标 agent、tool name/description、on_handoff 回调、input_type（限制输入格式）、input_filter（过滤输入）和 is_enabled（动态开关）。适合多 specialist 场景：比如客服 agent 先判断问题类型,再委派给技术支持或订单查询的专门 agent。

Guardrails：guardrails 分 input 和 output 两层。Input guardrails 在用户输入进入 agent 之前检查,output guardrails 在 agent 返回结果之前检查。触发 tripwire 后中断执行,适合”输入不符合预期就停掉”或”输出包含敏感信息就拦截”。官方文档示例是用一个较快的模型检查用户输入是否在请求范围内。

Tracing：SDK 内置 tracing,追踪 agent run 中的 LLM generations、tool calls、handoffs、guardrails 检查和 custom events。每个 span 记录开始时间、结束时间和 metadata,可用于 debug、visualize 和 monitor workflows。Tracing 默认启用,但可以通过 trace_include_sensitive_data 控制是否记录敏感字段。

Sessions、HITL 和 MCP tools：Sessions 用于 conversation continuity——同一个 session_id 下的多次 run 会共享历史对话。HITL API 允许在执行过程中等待外部输入,但它的中断机制和 LangGraph 的 interrupt 不是同一抽象。MCP tools 允许 agent 调用 MCP server 提供的工具,和 function tools 一样被 SDK 管理。

这些原语覆盖了 agent loop、工具调用、委派、校验、追踪和会话,但缺少显式状态图、checkpoint 持久化、interrupt 暂停、resume 恢复、time travel 回放和 fault tolerance。如果你的场景只需要”模型+工具+偶尔委派”,Agents SDK 可能够用；但如果需要”暂停等人审批+恢复执行+故障后继续+状态审计”,LangGraph 的能力更匹配。

LangGraph 的强项：状态机制清单

LangGraph 的强项集中在状态管理和恢复机制：Checkpointers、Interrupts、Time travel、Fault tolerance 和 Stores。下面是清单式的梳理：

Checkpointers：checkpointers 保存 thread graph state 为 checkpoints——包括节点执行历史、中间变量、等待的外部输入和当前节点位置。每个 checkpoint 是一个完整的状态快照,用于 conversation continuity、HITL、time travel 和 fault tolerance。官方文档明确说 checkpointers 和 Agents SDK 的 sessions 不是同一概念：sessions 是对话连续性,checkpointers 是图状态快照。

Interrupts：interrupt() 可以在 graph node 中暂停执行,checkpointer 保存当前状态,等待外部输入。恢复时用 Command(resume=...),同一个 thread_id 是持久游标。官方文档列了四种常见模式：approval workflows（审批 tool call）、review/edit state（人工编辑状态）、interrupting tool calls（在调用工具前暂停）、validating human input（校验人工输入）。这个机制和 Agents SDK 的 guardrails tripwire 不同：interrupt 是状态机级别的暂停,guardrails 是执行级别的中断。

Time travel：time travel 允许回到任意 checkpoint,查看当时的状态和执行路径。适合审计、排障和复现问题——比如”两小时前为什么走了这条分支”。Agents SDK 有 tracing 能可视化执行路径,但不能回到某个历史状态重新执行。

Fault tolerance：fault tolerance 是故障后继续执行的能力。如果报表 Agent 跑到一半突然崩溃,LangGraph 可以从最后一个 checkpoint 继续,避免重复执行已完成的步骤。Agents SDK 没有内置容错机制,只能重新从头跑。

Stores：stores 保存跨线程长期数据——比如用户偏好、历史记录或业务状态。官方文档说 stores 和 checkpointers 的区别：checkpointers 保存 thread graph state,stores 保存跨线程长期数据。如果你的场景需要在多个 agent run 之间共享状态,stores 更合适。

这些机制让 LangGraph 更适合 long-running、stateful workflow：长任务、多分支、可恢复、状态可审计、需要人工介入的工作流。如果你的项目已经有这些需求,LangGraph 的复杂度是值得的；如果只是简单的 tool agent 或多 specialist handoff,Agents SDK 可能更轻。

什么时候用 Agents SDK：适合场景

基于前面能力矩阵和原语清单,Agents SDK 更适合这些场景：

1. 简单 tool agent：只需要检索、总结、偶尔升级给人工的场景。比如内部知识库问答：检索相关文档、总结答案、如果不确定就提示用户联系人工客服。这种场景不需要复杂状态恢复或审批流,Agents SDK 的 tools + handoffs + guardrails 可能够用。

2. 多 specialist handoff：需要委派给多个专家 agent 的场景。比如客服 Agent：先判断问题类型,再委派给技术支持、订单查询或售后退款。Agents SDK 的 handoffs 机制本身就是”agent as tool”,适合这类委派模式。

3. 快速原型：需要快速验证想法,不想一开始就画显式状态图。Agents SDK 的代码量少、上手快,适合先跑起来再看要不要加状态层。如果原型跑起来后发现确实不需要 checkpoint 或 interrupt,可以直接用 Agents SDK 上线。

4. OpenAI 生态贴合：如果项目主要用 OpenAI 模型、Responses API 或 OpenAI hosted tools,Agents SDK 是官方构建包,集成更顺畅。比如实时语音 agent、sandbox agents 或 OpenAI 托管的工具,Agents SDK 有现成支持。

5. 已有其他状态层：如果项目已经有业务数据库、队列或其他工作流引擎管理状态,Agents SDK 可以只跑 agent loop,不重复建状态层。比如某个节点用 Agents SDK 调工具,状态交给业务数据库和消息队列。

这些场景的共同特点：不需要显式状态图、不需要 checkpoint 持久化、不需要 interrupt 暂停和 resume 恢复、不需要 time travel 回放。如果你的项目命中这些特点,先试试 Agents SDK 可能更省事。

什么时候保留 LangGraph：不适合替代的场景

如果你的项目命中下面这些场景,LangGraph 的复杂度是值得的：

1. 长任务（20+ 分钟）：报表 Agent、数据处理或复杂分析跑 20 分钟以上,中途可能崩溃或超时。LangGraph 的 checkpointers 和 fault tolerance 能让任务从最后一个 checkpoint 继续,避免重新从头跑。Agents SDK 没有内置容错机制,只能重新执行。

2. 需要人工审批：tool call interrupt 场景,比如高风险操作（删除数据、发送邮件、修改权限）需要人审批后才能继续。LangGraph 的 interrupt 可以在 tool call 之前暂停,checkpointer 保存状态,等人审批后用 Command(resume=…) 恢复。Agents SDK 的 guardrails 是”触发就停掉”,不是”暂停等人审核再继续”。

3. 需要状态可审计：需要回放历史状态、查看执行路径或审计决策原因的场景。比如合规要求：两小时前为什么走了这条分支？LangGraph 的 time travel 能回到任意 checkpoint 查看。Agents SDK 有 tracing 能可视化路径,但不能回到历史状态重新执行。

4. 故障后要继续：Agent 跑到一半崩溃或网络中断,需要恢复后继续执行而不是重新开始。LangGraph 的 fault tolerance 能从 checkpoint 继续,Agents SDK 只能重新从头跑。如果任务有外部依赖（API 调用、数据库写入）且不能重复执行,这个差异很关键。

5. 多分支、条件路由、业务状态机：需要显式画状态图、条件分支或业务状态机的场景。比如订单处理：支付成功->发货->确认收货；支付失败->取消订单；支付超时->人工介入。这种流程用 LangGraph 的显式状态图更清晰,Agents SDK 的 handoffs 机制更适合委派,不适合画复杂路由。

这些场景的共同特点：需要显式状态图、需要 checkpoint 持久化、需要 interrupt 暂停和 resume 恢复、需要 time travel 回放或需要 fault tolerance。如果你的项目命中这些特点,LangGraph 的复杂度不是负担而是必要。

替代判断：四步清单

看完适合场景,你可能还是不确定自己的项目该选哪个。下面是四步判断清单：

第一步：列出项目的核心需求

把需求拆成具体项：工具调用？状态恢复？人工审批？长任务？多分支路由？审计回放？故障恢复？不要只写”需要一个 agent”,要落到具体功能。比如”报表 Agent 跑 20 分钟,中途要等人审批 SQL,崩溃后要能继续”——这是三个具体需求：长任务、审批、故障恢复。

第二步：对照能力矩阵,看哪些是强需求

把第一步列出的需求对照前面能力矩阵的 10 个维度。比如”长任务+审批+故障恢复”对应的是：状态持久化（强）、失败恢复（强）、HITL（强）。这三个维度 Agents SDK 都是”无”或”弱”,LangGraph 都是”强”。如果你的强需求集中在 Agents SDK 的弱项,替代可能不合适。

第三步：判断是否需要显式状态图

问一个问题：我的流程能画成明确的状态转移图吗？如果能画——比如订单处理有支付成功/失败/超时三个分支,每个分支后还有确定步骤——LangGraph 的显式状态图更合适。如果只是”模型+工具+偶尔委派”,没有固定流程,Agents SDK 可能更轻。

第四步：评估团队对复杂度的承受度

LangGraph 要求团队承担更多图、状态和节点设计。如果团队对复杂度承受度低,先从 Agents SDK 原型开始,再看要不要加状态层。如果团队已经有状态机或工作流经验,LangGraph 的复杂度可能不是负担。

这四步做完,你应该能判断自己的项目更适合 Agents SDK、LangGraph 还是两者组合。下面的迁移路径章节会给出具体判断表。如果你还在做更上层的框架全景选型,可以把 AI Agent 工程化 2026 选型清单 作为补充阅读。

迁移路径：已有 LangGraph 怎么办

如果你已经有 LangGraph 原型,想知道能否删掉一部分复杂度,用 Agents SDK 替代,下面的判断表能帮你决定：

LangGraph 原型里的内容	能否删掉改用 Agents SDK	原因
简单 tool agent 节点（只调用模型+工具）	能	不依赖 checkpoint 或 interrupt,Agents SDK 的 tools + tracing 可能够用
多 specialist 委派节点（判断类型后委派）	能	Agents SDK 的 handoffs 本身就是”agent as tool”,不需要显式画 routing 边
不需要 checkpoint 的短任务（5 分钟内完成）	能	没有 checkpoint 需求,Agents SDK 的 sessions 可能够用
依赖 interrupt 的审批流（tool call interrupt）	不能	LangGraph 的 interrupt 是状态机暂停,Agents SDK 的 guardrails 是执行中断,不是同一抽象
依赖 checkpoint 的长任务（20+ 分钟）	不能	Agents SDK 没有 checkpoint 持久化,崩溃后只能重新从头跑
需要 time travel 的审计需求（回放历史状态）	不能	Agents SDK 有 tracing 但没有 time travel,不能回到历史状态重新执行
多分支、条件路由、业务状态机	不能	Agents SDK 的 handoffs 不适合画复杂路由,显式状态图更清晰

如果你是 Agents SDK 用户,想知道何时需要升级到 LangGraph,下面的判断表给出触发点和迁移路径：

触发点	建议迁移路径	原因
任务变长（从 5 分钟变成 20+ 分钟）	保留 Agents SDK 跑短任务节点,LangGraph 包外层状态图	长任务需要 checkpoint 和 fault tolerance
需要审批（高风险 tool call 要人审核）	把审批流从 guardrails 改成 interrupt	interrupt 是状态机暂停,guardrails 是执行中断
需要状态恢复（崩溃后继续）	引入 checkpointers	Agents SDK 没有内置容错机制
需要分支路由（多条件分支）	画显式状态图	Agents SDK 的 handoffs 不适合复杂路由

互补组合模式示例：如果你不想完全替换,也可以组合使用——LangGraph 管外层状态图,某个节点用 Agents SDK 跑短任务 agent。比如报表 Agent 的主流程用 LangGraph：数据预处理->SQL生成->人工审批->执行查询->结果导出。其中”SQL生成”和”结果导出”两个节点不需要 checkpoint 或 interrupt,可以改用 Agents SDK 的 agent loop 调工具,状态仍由 LangGraph 管理。这样既保留了状态恢复和审批能力,又减少了部分节点的样板代码。

组合模式的关键是：状态层由 LangGraph 管理,短任务节点可以换成 Agents SDK。这样不是二选一,而是各用各的强项。

结论

OpenAI Agents SDK 和 LangGraph 不是二选一的问题,而是要不要加状态层的问题。如果你的项目只需要 agent loop、工具调用、委派和校验——比如知识库问答、客服委派、快速原型——先试试 Agents SDK,代码少、上手快。如果你的项目已经需要长任务恢复、人工审批、状态审计或故障后继续——比如报表 Agent、订单处理、合规流程——LangGraph 的 checkpoint、interrupt、time travel 和 fault tolerance 是必要能力,复杂度不是负担。

不必强制替换：LangGraph 管外层状态图,Agents SDK 跑短任务节点,是组合模式。判断的关键是列出你的核心需求,对照能力矩阵看强需求落在哪个框架,再决定保留、替代或组合。

下一步：如果你有现成的 LangGraph 原型,先按迁移判断表检查哪些节点能改用 Agents SDK；如果你刚开始选型,先用四步清单判断项目是否需要显式状态图,再决定框架。