框架与 SDK 选型

一句话理解：框架选型的本质是决定“哪些 Harness 能力买现成的、哪些自己写”；先按任务形态（改文件写代码，还是调业务接口）和运行形态（同步对话，还是长时间后台作业）缩小范围，再看模型绑定、状态管理和团队技术栈。

“我们用 LangGraph 还是 OpenAI Agents SDK？”这是 Agent 项目启动会上最常见的问题之一，也是最容易吵成“信仰之争”的问题。其实不同框架解决的问题层次并不相同：有的只是帮你把工具调用循环写短一点，有的直接给你一个能读写文件、执行命令的完整 Agent，有的是用来编排复杂状态机的运行时，有的连服务器都替你托管了。

先搞清楚它们各自在哪一层，比比较功能清单重要得多。框架迭代非常快，本课只描述截至 2026 年 9 月官方文档中的定位，具体 API 请以最新文档为准。

先分层：五种“买多少”

图 1 · 五种“买多少”：越往右，框架替你做掉的 Harness 能力越多，你能控制的细节越少

Anthropic 在《Building effective agents》中的建议值得记住：先直接使用模型 API，很多模式几行代码就能实现；如果使用框架，要确保理解底层发生了什么，因为多一层抽象就可能让提示词和响应变得难以调试。这也是本模块把从零写一个最小 Agent 放在最后作为实操的原因。

主流选项逐个看

模型 API + 自写循环

直接调用模型的消息接口，自己处理工具调用、结果回填与停止条件。Anthropic 的 SDK 还提供了一个 Beta 的工具循环助手（Tool Runner），你只写工具函数，循环由 SDK 驱动，同时保留每一轮介入的能力。

适合：业务工具为主、需要完全掌控、团队想理解原理。
代价：权限、会话、恢复、追踪都要自己补。

OpenAI Agents SDK

OpenAI 官方的轻量 Agent 框架，提供 Python 版和 TypeScript 版（包名 @openai/agents）。核心原语是 Agents、Handoffs（Agent 之间移交）、Guardrails（输入输出校验）、Sessions（会话记忆）和 Tracing（内置追踪），还包括工具审批、MCP、沙箱 Agent、语音与实时 Agent 等能力。对 OpenAI 模型默认使用 Responses API，也可以通过 LiteLLM 等适配层接入其他厂商的模型。

适合：自定义业务工具、多个 Agent 之间需要移交、希望开箱即有追踪。
注意：它提供原语而非成品 Agent，文件读写、命令执行这类能力需要借助内置工具或自己实现；长时间运行的持久化需要结合文档列出的 Temporal、Restate、DBOS 等集成。

LangGraph

LangChain 团队的底层编排框架与运行时，官方定位是构建、管理和部署长时间运行、有状态的 Agent。你用“状态图”显式定义节点和边，可以在同一张图里混合写死的确定性步骤和由模型决策的步骤。通过 Checkpointer 按 thread_id 持久化状态，用 interrupt() 实现人工介入，用 Store 保存跨线程的长期记忆。

适合：流程复杂、需要精确控制分支、需要暂停恢复和时间回溯的混合架构。
注意：抽象层次低，灵活但代码量和学习成本高；恢复时节点会从头重新执行等语义需要吃透。
相关：同一团队的 Deep Agents 是构建在 LangGraph 之上的“Agent Harness”，内置任务规划、虚拟文件系统、子 Agent、技能与记忆文件、自动摘要等能力。

Claude Agent SDK

Anthropic 把 Claude Code 的 Harness 作为库提供，支持 Python 和 TypeScript。它自带与 Claude Code 相同的内置工具（读写编辑文件、Glob 与 Grep 搜索、Bash、网页搜索与抓取、子 Agent、技能等），以及 Hooks、权限模式、会话恢复与分叉、自动上下文压缩、MCP、轮数与金额上限。它还会按设置加载项目中的 CLAUDE.md、技能等配置。

适合：以文件、代码、命令行为主要工作对象的 Agent，例如 Coding Agent、文档处理、数据分析脚本类任务。
注意：面向 Claude 模型；运行时捆绑了 Claude Code 的原生程序，部署时通常需要容器等宿主环境；官方对使用 Claude 品牌有明确规范。纯业务 API 调用型的 Agent 用它可能“功能过剩”。

Claude Managed Agents

Anthropic 的托管方案（目前为 Beta），同时提供 Harness 和运行它的沙箱基础设施。核心概念是 Agent（模型、指令、工具配置）、Environment（在哪里运行）、Session（一次运行实例）和 Events（事件流）。面向长时间、异步、需要持久文件系统和定时执行的任务。

适合：不想自建队列、沙箱、会话存储的长任务。
注意：处于 Beta，行为可能调整；有状态设计导致目前不适用零数据保留安排；对运行过程的底层控制少于自建。

Google ADK

Google 的开源 Agent Development Kit，支持 Python、TypeScript、Go、Java、Kotlin 五种语言，文档中以 Gemini 为主，但声明可以适配多种模型；内置会话与记忆、评估工具，并可部署到自有容器或 Google Cloud。2.0 版本加入了图式工作流。

对比总表

维度	自写循环	OpenAI Agents SDK	LangGraph	Claude Agent SDK	Claude Managed Agents
所在层次	最底层	轻量框架	编排运行时	成品 Harness 库	托管平台
模型	任意	OpenAI 为主，可适配其他	通过集成支持多家	Claude	Claude
内置文件与命令工具	无	部分（按工具提供）	无（Deep Agents 提供）	有	有（在沙箱中）
流程控制方式	代码	模型驱动 + Handoff	显式状态图	模型驱动	模型驱动
人工审批	自己写	工具级审批 + 状态序列化	`interrupt()`	权限模式 + Hooks	权限策略
会话与持久化	自己写	Sessions（多种存储后端）	Checkpointer + Store	本地会话文件，可接自定义存储	服务端保存
部署	自己	自己	自己或官方平台	自己（容器等）	平台托管
学习成本	低到高（取决于补多少）	低	高	中	中

选型建议

你的场景	优先考虑	理由
学习原理、验证一个想法	自写循环	百行代码看清全部机制
业务 API 查询与诊断（如订单售后诊断）	自写循环 / Tool Runner，或 OpenAI Agents SDK	工具都是自己的业务接口，不需要文件系统
多个专职 Agent 之间移交（客服分流到退款、技术支持）	OpenAI Agents SDK	Handoff 是一等原语，追踪开箱即用
流程分支多、需审批、需时间回溯（如大额退款审核）	LangGraph	显式状态图与检查点
代码修改、仓库维护、批量文档处理	Claude Agent SDK	内置文件、命令、权限、压缩与 Claude Code 同源
数小时的后台任务，不想自建基础设施（如全站 SEO 诊断）	Claude Managed Agents，或持久化执行引擎 + 任一框架	会话、沙箱、事件流由平台负责
多云或必须支持多家模型	LangGraph、Google ADK、OpenAI Agents SDK（经适配层）	模型可替换
深度绑定 Google Cloud	Google ADK	原生部署集成

决策顺序建议：

任务形态：主要操作文件与命令，还是调用业务接口？
运行形态：几十秒的同步交互，还是几小时的后台作业？
模型策略：是否必须支持多家模型？
控制需求：流程需要显式建模吗？审批、回溯有多复杂？
团队与合规：团队用什么语言？数据能否离开自有环境？

五步的先后关系如下，前两步通常就能把候选缩小到一两个：

图 2 · 决策顺序：前两步通常就能把候选缩小到一两个

常见误区

“选最流行的框架总没错。” 框架解决的问题层次不同，流行度不等于匹配度。一个查询型业务 Agent 套上重型编排框架，调试成本可能比收益高。
“用了框架就不用懂循环。” 线上出问题时，你要能看懂框架替你发出的每一次模型请求。
“一旦选定就不能换。” 把工具实现、业务规则、评测集与框架解耦，迁移成本会低很多。真正难迁移的是散落在框架回调里的业务逻辑。

产品经理检查清单

这个框架替我们解决了本模块列出的哪些 Harness 能力？哪些仍需自研？
框架的会话与状态存在哪里？是否满足数据合规要求？
人工审批在框架里如何暂停与恢复？能否等待数小时？
能否导出完整的运行轨迹用于评估与排查？
框架目前是正式版还是 Beta？版本更新有多频繁？升级成本谁来承担？
如果半年后要换模型或换框架，哪些代码需要重写？

练习

用 45 分钟为下面三个需求各写一段不超过 150 字的选型结论，说明选什么、为什么、主要风险是什么：

销售分析 Agent：每天早上查询数据仓库，生成区域销售异动简报，发到企业 IM。
Coding Agent：在公司内部仓库里自动修复依赖升级导致的测试失败，并提交合并请求。
订单售后处理 Agent：诊断订单异常，金额超过阈值的退款需要主管审批，审批可能隔天才处理。

下一步

选框架之前，先亲手写一个。下一课「实操：从零写一个最小 Agent」用约百行 Python 实现一个带两个工具的 Agent Loop。

框架与 SDK 选型