第 17 章 SDK 与框架格局

本章回答一个选型问题，市面上几十个智能体框架与 SDK，该不该用一个、选哪一个；这个问题本身就容易问错，框架每个季度都在换版本、换特性，甚至换名字，逐家对比的选型文章过不了多久就过期，照抄来的结论过期只会更快。17.1 盘 2026 年的格局，OpenAI、Anthropic、微软、Google 四家原生 Agent SDK 各拿出了什么，Assistants API 废弃、AutoGen 分叉与合并、Swarm 停更这些直接影响选型的变化顺带交代，第三方拿 CrewAI 完整讲一遍，中文生态对应物与个人智能体运行框架这第三类参与者也讲到；17.2 给一套十能力评估法，把“哪个框架最好”换成“自己需要哪些能力、各家框架给到几分”，做成一张能反复复用的打分矩阵；17.3 正面回答自建、采用还是混合，把锁入、抽象泄漏和版本节奏三笔迁移成本算清楚。这一章的主线是把框架看懂，框架的名字迟早过时，能力清单却多年不大变，学会拿清单去衡量框架，比背下任何一份排行榜都管用。

17.1 四家原生 Agent SDK

这一节的主角，是模型厂商亲自下场的四家原生 Agent SDK。2024 年问工程师智能体开发用什么框架，候选名单清一色是第三方名字，LangChain 一系、AutoGen 和 CrewAI；到 2026 年再问同样的问题，名单最前面多了四个官方选项，都出自模型厂商。厂商做 SDK 是这两年里最大的一处变化，模型 API 变化最快，接入层老得跟着改，而这件事正好是厂商最有动力、也最有能力接过去的。

OpenAI 是四家里走弯路最多的。它最早想把整个智能体放进服务端，Assistants API 把回路、工具与文件全收到云端，开发者只负责发指令。这条路后来走不下去，2025 年 8 月 26 日官方公告废弃 Assistants API，关停日期定在一年后的 2026 年 8 月 26 日，接棒的是更底层的 Responses API 与 Conversations API。

接棒 Assistants API 的，是 OpenAI Agents SDK（OpenAI 官方的智能体开发包）。形态上它从托管服务缩成轻量库，三件东西用一组很小的原语就包住了，智能体（agent）、交接（handoff，智能体之间的转派）和护栏（guardrail）。跨轮会话与内建追踪都配齐，默认走 Responses API，也能通过适配层去接第三方模型。官方给它的定位是生产就绪。

这套 SDK 的前身是实验框架 Swarm。官方仓库的 README 讲得直白，Swarm 停更了，Agents SDK 就是它迈向生产的下一步。第 8 章见过的 sessions 会话原语、第 15 章见过的 needs_approval 工具审批，源头都在这套 SDK 里。

官方没有把废弃 Assistants API 的理由归纳成一句话，但新接口的设计已经把取舍亮在明面上，回路从服务端收回本地进程，SDK 只供给工程零件，并不收走控制权。

Anthropic 拿出来的方案正好反过来。Claude Agent SDK 是从早期的 Claude Code SDK 演变来的，它不是盖在 API 上的一层薄封装，而是把驱动 Claude Code 的整套设施拆开做成了库。按官方的定位，内置工具、智能体回路和上下文管理这些，在 Python 与 TypeScript 里都能通过代码调用。

通用件在工具包里都有现成的，读写文件、执行命令和网页搜索都在，还带上能挂自定义代码的 hooks。子智能体、权限控制、会话与插件一样不缺。skills（把成套操作打包成文件、按需加载）与 memory（跨会话记忆）也有官方件，第 8 章 8.4 提过的子智能体打包，正是这里的能力之一。

这条路起步就不轻，拿过来就是一个能胜任长任务的完整智能体，上下文压缩、多步规划这些难写的件全都配齐。代价也在这里，工具与回路的设计是贴着 Claude Code 的使用场景来的，想大改的时候，它就不如薄库顺手。

拿它当库用，编程模型长什么样，跟手写回路对照着看最清楚。任务发出去，得到的不是一次应答，而是一条异步消息流，消息一共四类。system 是开场第一条，报会话配置，用哪个模型、挂了哪些工具都在里面。assistant 是模型的回合，文本与工具调用混在同一类里，一条能带多个调用。user 装工具执行的结果，按调用标识对号送回。result 收尾，成本、轮数和用量一次报全。第 2 章手写的那条 while 循环，到这里整个搬进了库。

审批与自定义工具也各有现成做法。SDK 留了一个调用级的审批回调，工具调用没被白名单或权限模式自动放行时，SDK 就带着工具名和完整参数来问这段代码，放行还是拒绝由它答复，第 15 章手写的审批挂起，到这里就是注册一个回调函数。自定义工具的做法更值得看一眼，不是注册个函数了事，而是在进程内起一个 MCP 服务器，工具定义走第 5 章讲过的那套协议，只是不出进程。手写过回路的读者再打开这份 SDK，认出的全是自己写过的那些机制，差别只剩谁来维护。

同一家还有个现成的对照物，Managed Agents 连沙箱与会话基础设施也一并托管，适合不想自己操心运行环境的团队。

微软这条线最后走到合并。研究院出身的 AutoGen 擅长多智能体协作，面向企业的 Semantic Kernel 手里攒了一批生产件，两条线并行几年后，2025 年 10 月官方把二者合成 Microsoft Agent Framework，操刀的仍是原班团队，2026 年 4 月出 1.0 正式版（GA，指接口稳定、官方长期支持的版本）。语言覆盖 .NET 与 Python，Go 另有公开预览版，代码库独立放在 agent-framework-go。

里面的东西能归成四块，单智能体、工作流和集成件，再有一个开箱即用的 Harness Agent。官方把它定位成一个长任务智能体，成套的件全自带，规划、待办跟踪、上下文压缩和工具审批都在其中，可观测也一次给齐。

叫法上有一处对不上，概述页称它 Harness Agent，概念页与 2026 年 4 月的 GA 公告写的却是 Agent Harness。公告还把它描述成可定制的本地运行时，这与概述页那份能力清单并不完全一致。其实两个名字说的是同一套东西的两层，Agent Harness 指把模型变成智能体的运行时脚手架，Harness Agent 指拿这副脚手架装配出的开箱智能体。本书统一按概述页的叫法，写 Harness Agent，引用官方材料时以官方页为准并注明日期。

清单拉得这么长，用的时候得有自己的判断。开箱组件一多，框架替开发者做的决定也多，哪些带来便利、哪些形成妨碍，得拿一份标准去量。17.2 的能力清单就是这份标准。

并入之前，AutoGen 这条线先分了一次叉。2024 年末，原作者带着一批早期贡献者离开微软仓库，把项目分叉成 AG2，延续 v0.2 那套对话式 API。留在微软的主线推倒重来，变成 v0.4，架构换成事件驱动、actor 式，接口与 v0.2 不兼容。合并以后，微软的 AutoGen 转入维护与迁移状态，官方迁移指南教存量代码怎么迁到 Agent Framework。AG2 照旧独立演进，v0.2 风格的存量代码在它那边还能继续跑。

放到选型上看，认微软生态的团队从此有了唯一的官方入口。手上攒着 AutoGen 存量代码的团队，面前是一次实实在在的迁移工程；想少动代码的话，延续 v0.2 的 AG2 也列在候选里。

Google 的方案叫 ADK（Agent Development Kit，智能体开发套件），主打的就是多语言与云集成。代码全部开源，Python、Java、Go、TypeScript 和 Kotlin 五种语言都有各自的实现，MCP 工具接入与 A2A 跨智能体互操作属于开箱自带的能力，部署上瞄准 Cloud Run、GKE 与 Google Cloud 的托管运行时。MCP 的来龙去脉第 5 章讲过。A2A 协议 1.0 在 2026 年 3 月发布，治理权交到 Linux 基金会手里。

四家里数 ADK 跟云平台绑得最深。工作负载本来就在 Google Cloud 的团队，用它起步最顺手。反过来，想跨云或者在内网部署的团队，这份绑定就得仔细掂量。

厂商	SDK	形态与轻重	底层与绑定
OpenAI	Agents SDK	轻量库，三原语起步，Swarm 的生产化	默认 Responses API，适配层接第三方模型
Anthropic	Claude Agent SDK	重库，Claude Code 全套设施拆成 Python 与 TypeScript 库	内置通用工具与 hooks，大改造不如薄库顺手
微软	Microsoft Agent Framework	AutoGen 与 Semantic Kernel 的合并产物，1.0 覆盖 .NET 与 Python	单智能体、工作流、集成件，审批与可观测内建
Google	ADK	开源，五种语言各有实现	原生 MCP 与 A2A，部署直指 Google Cloud 运行时

SDK 之外，三大云平台还各自备有一层托管智能体平台。编排、工具接入、记忆和护栏这些基础设施由平台代管，工程师把注意力放在智能体的行为上，不必自己搭运行环境。AWS 的 Bedrock Agents、Google 的 Vertex AI Agent Builder、微软的 Azure AI Agent Service 是三家代表。这层产品的名字换得比 SDK 还勤，微软的这项服务如今归在 Azure AI Foundry 名下，AWS 又在托管编排之外推出 AgentCore，选型时以各家厂商的现行文档为准。要横向比较，比的还是模型选择、知识接入、记忆、监控、护栏和云集成这几个维度，正好拿 17.2 的能力清单去量。托管换来的两笔代价得摆在明面上，定制空间收窄，深度改造不如自己写顺手；云绑定加深，数据、身份和计费都留在一家云里。对企业来说，这层平台是自建与采购的第一道入口，先用托管平台快速验证业务价值，确有刚需再往下走到 SDK 自建。

再往降低门槛的方向走一层是无代码平台。OpenAI 的 GPTs 让非工程师用一段指令加几份资料搭出定制助手，国内对应的是字节的扣子（Coze），都做成应用商店的样子。够不够用，拿本书的老问题一问便知，工具能不能接进自家系统，回路行为改不改得动，评测回归做不做得了。答不上来的，就该回到代码了。微软把这条路分成了三级，Copilot 是现成产品，Copilot Studio 让业务人员无代码搭智能体，Foundry 面向专业开发，同一生态里按人手和需求选层。

n8n 这类可视化编排工具夹在中间，拖拽连线能撑到演示，复杂了仍要落代码。代码这头还有个轻量的工程选项常被漏掉，LiteLLM 这类网关库把各家厂商的模型 API 归一成一套接口，换模型不动调用代码。它不是框架，只管模型接入这一段，混用多家模型时却往往是最先值得装的一件。

厂商亲自下场，不等于第三方框架就此出局，空间确实小了一些，但谈不上淘汰。LangGraph 2025 年 10 月发 1.0，官方承诺 2.0 前不破坏兼容，十个月过去大版本没动，2026 年 8 月停在 1.2.11，承诺至今在兑现。CrewAI 也是 2025 年 10 月把开源版 1.0 宣布为 GA，主打多角色协作的快速搭建。Swarm 停更，AutoGen 并入微软新框架，AG2 接着 v0.2 那条线继续走，各自都有了去处。

Java 这边也有对应物，LangChain4j 与 Spring AI 把工具调用和智能体抽象带进了 JVM 生态。本书坚持原生实现讲机制，机制讲通了，换到哪种语言里都一样。

第三方框架里，CrewAI 算少见的任务中心设计。它的思路是先把要做的任务写清楚，再给任务配上角色。整套系统分三层，crew 是一支队伍，task 是一件任务，agent 是一个执行任务的成员。每个成员用三段材料定义。role 写它是什么角色，goal 写它要交出什么，backstory 写它的经历与视角，框架把这三段编进系统提示。不想用框架默认提示的团队也有整体接管的途径，system、prompt 和 response 三段模板可以整个换掉。

CrewAI 官方文档提过一条八二法则，八成力气花在任务定义上，两成花在角色人设上。任务写清楚了，再简单的成员也能交出成果；任务写得含糊，人设再讲究也难以弥补。任务这一层还立着一道类型化契约。每件任务都能声明结构化输出的数据模型，上游任务交出的数据先过一遍校验，再自动进下游任务的上下文。这样一来，成员之间递的是有形状的数据，不是自由发挥的文本。

人设带来的增益有多少，跟用哪个模型也有关系。社区里流传一条使用经验。三段人设对便宜的小模型增益很明显，小模型要靠人设把角色立起来，输出才够具体。到旗舰模型这里，作用就有限了，旗舰本来分得清一个资深工程师该怎么做事。这是经验之谈，不是控制实验的结论。它跟第 9 章 9.3 的人设检验也不冲突，那边拦的是把架构档位押在人设上，这边讲的是人设在便宜模型上确实有一点增益。

人设怎么写才算写好，有几条要领。声称具体经验，别声称泛泛专长，“给大型电商平台做过多年商品编目”强过“你非常懂商品”，具体经历会把模型里相关的知识引出来。还要点名希望它留意的域细节，写清要看材质、做工和包装，这些不是装饰，是在告诉模型哪类观察算数，删掉它们，输出就退回泛泛而谈。人设的繁简则要配任务的难度，简单分类用不着长篇身世；要模型分得清头层皮与贴合皮这种细差别，就得给它一个常年做这种鉴别的人设。照这几条写完还嫌输出太浅、漏了原本期待的细节，第一个该回去翻的就是 backstory。

中文生态这边，阿里 Qwen 团队有个 Qwen-Agent，围绕 Qwen 系列模型做工具调用、MCP 支持和代码解释器，star 数已经过 17k。只是仓库的更新停在 2026 年 3 月，眼下只能拿它当个线索，真到选型还得自己再核一遍。

2026 年，SDK 与框架之外又多出第三类参与者，个人智能体运行框架。OpenClaw 是这类的代表，一个开源、自托管的个人智能体，跟具体模型解绑，Claude、GPT 和 DeepSeek，或者 Ollama 拉起来的本地模型，随换随用。它走消息通道跟人打交道，聊天软件、邮件这类入口都算，GitHub 的 star 数也排得靠前。

它把一条架构判断验证得很清楚，模型成了可替换的模块，真正定义产品的是运行框架。所谓运行框架（agent harness），说的就是第 2 章手写过的那套东西，只不过做成了产品。回路、记忆、工具路由、审批和追踪全归框架所有，代码执行单独关进沙箱，凭据与敏感数据留在框架层，不混进模型生成代码的运行环境。13.2 的沙箱隔离，到这里成了整个产品的地基。

企业一侧也有对应的东西。NVIDIA 的 NemoClaw 参考栈把智能体放进 OpenShell 这个沙箱化运行时里跑，网络、文件访问与推理调用全都圈在受控范围里。

这类产品离多数读者日常做的事较远，可它把一个道理展示给了全行业，模型商品化越快，真正让模型可用的那层工程脚手架就越值钱。本书从头到尾坚持手写那些零件，瞄准的也是这个。

数下来六七个候选，四个 SDK 加上几家活跃框架，怎么挑？本书只想给一条倾向，凡是已经绑了某家模型或某朵云的团队，先把自家厂商的 SDK 拿来试，接入成本最低。除此之外，网上的意见谁也别急着全信，一家家读文档、跑评测，攒下的印象要不了多久就会过时。

17.2 十能力评估法

拿框架当比较对象，写出来的东西天生容易过时。要比的是特性，特性却每个版本都在变，2024 年还算卖点的流式支持，2026 年各家框架都有。反过来倒有一样几乎不变，智能体系统想进生产，翻来覆去离不开那几类能力。

一家一家追着框架比，永远赶不上特性的变化，值得做的是把这几类能力整理成一张清单，再拿它去量随便哪个候选。清单共十条，每一条都能在前面的章节里找到亲手写过的对应物，评估框架时对标的不是各家框架的宣传页，而是自己写过的代码。

分层抽象与开发体验（layered abstractions）拼的是门槛和上限两头，低门槛（low floors）、高上限（high ceilings）都要顾到，常见场景几行代码就起步，特殊需求不必改框架源码，复杂度跟着用到的层级一步步显露。怎么验这一条？看一个基本的多智能体工作流能不能在二十行代码内跑起来。第 10 章手写的监督者编排有一百五十多行，拿这条一量，各家框架替人省了多少行立见分晓。

第二条看异步优先与流式（async-first with streaming）。多智能体天生并发，几个智能体同时想、几个工具同时跑，同步阻塞的接口从第一天就是瓶颈，取消与超时的配套处理同样要紧。写过第 10 章优雅取消的人，最明白这一条会吞掉多少工时。头两条衡量的是上手的难易程度。

运行时基础设施一口气占三条，第一条是可观测性与开发工具。事件流得能看清每一次模型决策与工具调用，日志要带关联 ID 贯穿整条多智能体链路，token 用量、延迟和成功率都得有指标可查。第 14 章的链路追踪与成本核算，搁进框架里对应的正是这一条。

接着轮到状态管理与持久化。会话状态得能序列化，长流程要有检查点，崩溃之后可以恢复，存储后端还要可插拔。第 8 章的会话存储、第 15 章的暂停恢复都亲手写过一遍，这项工作有多重，心里大致有数。

还有声明式配置与可复现。智能体的定义要能存成配置文件、进版本库、跨环境迁移。多数团队最看轻的恰恰是这一条，配置一旦可序列化，换一组参数跑一轮评测就能完全自动化，第 12 章那种两版对比与回归测试，少了它就得每次改代码。

再往生产走，又分三条，第一条是护栏与中间件（guardrails and middleware）。模型调用前后得留拦截点，工具执行前要能校验参数，护栏本身还得可组合、可串联。第 13 章的注入防御与权限控制，落到框架里全靠这套钩子，一个没有拦截点的框架，等于逼使用者去改它的源码。

模式支持与可扩展性排在这三条里。第 10 章那条线上的七种编排模式，框架内置了哪些、没内置的能不能自己搭出来，都要问一遍。图引擎类的框架天然能覆盖全部模式，薄库类的框架只给原语，模式得自己组合。

生产部署与安全管着最后一程。沙箱执行、容器化、水平扩展、认证授权和审计日志，这一条直接决定 demo 与生产系统之间隔了多远。

十条里最后两条最容易漏，其中之一是评测与测试支持，轨迹级评测、把真实会话沉淀成任务集和跑分自动化，这几件事最好框架全都自带。第 12 章讲智能体回归时提醒过别只盯最终输出，框架自带这套设施，评测回路就省得从零搭。

其二是生态与长期生命力。要看维护节奏、社区响应和破坏性变更的处理方式，还要看有没有商业支持。这一条不进打分，更适合拿来当门槛，生态不行直接出局，分数再高，也不敢把两年的工程托付给它。

十条并到一起就变成一张表。打分时给其中九项配上权重，生态一项不进打分，单独当门槛看。打分沿用这份权重结构，候选换成三个读者在前面章节已经打过交道的对象，LangGraph、OpenAI Agents SDK 和原生自建，三家轮廓叠画在图 17-2 的雷达上，分数明细列在下表。表中的分数只作演示，量级取自前文核实过的各家框架能力，读者完全能自己复评一遍。

能力	权重	LangGraph	OpenAI Agents SDK	原生自建
分层抽象与开发体验	20%	6	8	4
异步优先与流式	15%	9	8	7
可观测性与开发工具	10%	9	8	3
状态管理与持久化	15%	9	7	2
声明式配置与可复现	5%	7	6	7
护栏与中间件	10%	7	7	9
模式支持与可扩展	10%	9	6	10
生产部署与安全	10%	8	6	3
评测与测试支持	5%	7	6	5
生态与长期生命力	门槛项	通过	通过	不适用
加权总分	100%	7.9	7.2	5.3

状态管理这一项，LangGraph 拿了 9 分。检查点体系靠 thread_id 存取，中断恢复也一起包办，第 15 章引用过它的 interrupt。开发体验只值 6 分，图抽象本身就有概念门槛，起步代码量也比三原语那类风格多出一截。

OpenAI Agents SDK 在开发体验上得 8 分，智能体、交接和护栏三个原语十行内就能起步，会话与追踪都内置。模式支持给了 6 分，除了交接，其余模式大多要自己拼。

反差最大的要数自建那一列。模式支持给到满分，第 10 章亲手搭的监督者编排就是现成例子；状态管理却只有 2 分，文件会话、共享存储和并发隔离，每一样都得从零写。加权之后，LangGraph 7.9、Agents SDK 7.2 和自建 5.3。

看这张表，重点不是谁总分高，而是权重稍微调整，排名会跟着怎么变。换成一家金融内网团队来设权重试试，护栏和模式各提到 20%，生产部署压到 5%，评测升到 10%，分层、异步各压到 10%，可观测压到 5%，状态与声明式维持 15% 和 5%，九项仍然凑满 100%。同一组分数重新加权，自建从 5.3 涨到 6.4，离 Agents SDK 的 6.9 只差半分，LangGraph 还是 8.0 领跑。

这番重算做成一个函数，权重一换，三列总分当场重出。

"""示意代码：十能力打分的加权重算，python3 可直接运行。
分数沿用上表演示值，权重一换，排名跟着动。"""

CAPABILITIES = [           # (能力, 权重, LangGraph, Agents SDK, 原生自建)
    ("分层抽象", 0.20, 6, 8, 4),
    ("异步流式", 0.15, 9, 8, 7),
    ("可观测", 0.10, 9, 8, 3),
    ("状态持久化", 0.15, 9, 7, 2),
    ("声明式配置", 0.05, 7, 6, 7),
    ("护栏中间件", 0.10, 7, 7, 9),
    ("模式支持", 0.10, 9, 6, 10),
    ("生产部署", 0.10, 8, 6, 3),
    ("评测支持", 0.05, 7, 6, 5),
]

def rescore(weights: dict) -> dict:
    """九项按传入权重重算总分，生态不进打分、单独当门槛。"""
    scores = {"LangGraph": 0.0, "Agents SDK": 0.0, "原生自建": 0.0}
    for name, _, lg, sdk, own in CAPABILITIES:
        scores["LangGraph"] += weights[name] * lg
        scores["Agents SDK"] += weights[name] * sdk
        scores["原生自建"] += weights[name] * own
    return {k: round(v, 2) for k, v in scores.items()}

DEFAULT = {name: w for name, w, *_ in CAPABILITIES}
FINTECH = {"分层抽象": 0.10, "异步流式": 0.10, "可观测": 0.05,
           "状态持久化": 0.15, "声明式配置": 0.05, "护栏中间件": 0.20,
           "模式支持": 0.20, "生产部署": 0.05, "评测支持": 0.10}

if __name__ == "__main__":
    print(rescore(DEFAULT))   # 出发点那组权重
    print(rescore(FINTECH))   # 金融内网团队那组，自建追到只差半分

跑出来的 7.15 与 5.25，按一位小数报就是表里的 7.2 与 5.3；金融内网那组权重一出，自建与 Agents SDK 果然只差半分。

矩阵真正起的作用，不是给出“哪个框架最好”的答案，而是让选型的人把“最看重什么”摆在台面上。权重一旦想清，答案常常自然浮现；权重想不清，打分再细致，也不过把含糊放大成貌似精确的错误。

17.3 自建、采用与混合

自建、采用和混合三路的判据，这一节落到框架的真实收益与三笔迁移成本上。监督者编排在第 10 章里手写了一百五十多行，会话与子智能体、审批与暂停恢复分别在第 8 章、第 15 章写过，全是原生代码，既然写得出来，为什么还有那么多团队用框架？框架能省开发工作量，这一点显而易见，可不少团队弄清机制后反而退回自建，这又是为什么？两个问题靠口号回答不了，得拿成本和收益来回答。

先把框架真正带来的好处摆清楚，大头在工程侧，不在功能面。AutoGen 团队的开发者当年反复见到的收益有两条。最大那条是维护负担换了承担方，模型厂商改 API、发安全补丁、做性能优化，框架团队替全部使用方接下来；自建团队这些事一样不少，桩桩都得自己承担。

标准化接口是另一条收益。AutoGen 里最常见的组件之一就是多厂商模型接入层，今天接 DeepSeek、明天换通义，适配的工作别人早做完了。标准化还藏着隐性收益，新人进框架项目，上手对齐的是行业通行的概念和接口；进自建项目，得先把内部文档甚至源码读一遍。团队一扩大，这个差别就越拉越大。

现成的例子，第 8 章与第 15 章其实都见过。Agents SDK 的 sessions 把取历史、存增量做成了默认行为；needs_approval 一个参数，能顶手写版几十行。重试、追踪和会话这些件，一旦采用框架就是开箱即得。

这两条好处，在 demo 阶段根本露不出来。demo 能碰到的只有功能，维护与接口的成本要等进了生产才显现。原型期怎么选都行，轮到生产系统，不算清成本就没法拍板。

三路之间怎么定，得看团队是什么处境。挑自建的处境有个轮廓，需求特殊到通用框架满足不了，人手和时间都够，关键环节要求完全可控，领域还稳定不常变。银行内网的风控问答正是这种处境，模型要私有化部署，审计链路得自己证明合规，框架的云端集成一个都用不上，十能力表里护栏与模式权重最高，17.2 末尾那轮重算就是照它来的。

私有化这条路真要走下去，紧跟着的工程问题是模型拿什么跑。开放权重到手只是一份文件，要变成能正常处理请求的服务，中间还隔着一层推理引擎。选型按场景分两头。单机自用，Ollama 门槛最低，一条命令就能把权重拉起来跑；要把模型当服务对外提供、支持多人并发，用 vLLM 或 SGLang，这两个开源引擎主打高吞吐的服务化部署。三家还有一层共同的便利，接口都兼容 OpenAI 格式，全书走 OpenAI 接口那一路的示例代码，只要把 base_url 指向自建服务，原样就能跑。自部署的代价也要看清，GPU 自己管、显存自己算、安全补丁自己追，所以多数团队从 API 起步，私有化多半是合规推着做的选择，怎么权衡，第 19 章专门展开。

走采用这条路，前提正好相反，人不多、要尽快交付、需求不出常见模式，还得靠生态和文档支撑。五人团队给电商客服做多路由分发就是这样的例子，监督者编排在哪个框架里都是教科书场景，拿 Agents SDK 或 LangGraph 起步，精力几乎全投在业务提示词与工具上。

多数团队真正用起来的其实是混合式，编排骨架、持久化这类通用件交给框架，护栏回调、评测回路和领域工具则自己写。第 12 章的评测与第 13 章的安全本就不该绑在编排层上，挂哪家框架都能跑。看一支做舆情简报的团队，编排骨架与检查点用 LangGraph，敏感词护栏与任务集自己研发，理由很实在，任务集是团队最值钱的资产，得保证随时能带走。

自建和混合走得久了，一路攒下的公共件会渐渐聚成内部平台。一开始只是某个团队用着顺的评测回路，或者好几个团队都来借的模型接入层，等到有人专职维护它们，平台就算立住了。平台这个话题，这一节只讲建设的一半，失败是什么样、逃生舱口开在哪，留给第 18 章治理那侧接着讲。给平台能力排优先级，现成经验是按全局效率排，谁强势听谁的，这种做法要不得。把帕累托原则（Pareto principle）放宽一点来用，先做那 20% 多数团队都用得上的能力，复杂度与维护开销压到最低，价值已经相当可观。找这 20% 有个常见障碍，团队来提需求时往往带着现成方案，讲不清底下的真问题，照单全收只是治标，得扎进他们的工作流里把问题挖出来。

照顾用户还有个反直觉的思路，别照着平均用户去设计，把两头各自服务好就行。一头是从没调过模型接口的新手，他们要的是几步就能跑起来的最简用例；另一头是微调过模型的专家，他们要的是在最复杂的用例里也动得了底层。两头都顾住了，夹在中间的大多数自然也照顾得到，团队从新手长成专家，平台也不会断档。

常见错误里有个典型，平台把核心能力全押在组织共享的提示词上，为编辑、共享和版本管理养了一整套笨重设施。这条路走不通，问题出在提示词这种材料本身。提示词是段文本，天生针对具体用例甚至具体模型定制，换一版模型、换一家厂商，效果就可能失效。何况新模型对措辞的小扰动越来越不敏感，花大力气去精调，回报反而越来越低。再往深处想，把同一套提示词拿到跨团队去复用，实践中几乎没人这么干。提示词不过是 AI 应用的一个组件，评测、监控和数据这些同样值得平台化的东西，投入都让它占走了，别的就没了位置。简单的做法是把提示词放进调用代码旁边的版本库，当变量用，单独存一个文件，A/B 测试照做不误。

动手建平台之前，还有一步常被跳过，先清点一遍组织里已有的平台能复用什么。内部开发平台攒着流水线、环境与凭证管理，数据平台或数据网格（data mesh）手里有目录、治理与取数通道，MLOps 平台带实验追踪、模型注册和漂移监控。智能体平台要的地基，身份、数据和可观测，多半已经在这些平台上跑了几年。所以正确的第一反应是扩展而不是重建。旧平台积了债、带着约束，这都不假，可它有多年攒下的组织学习、久经考验的可靠性，还有一批已经信任它的存量用户；为智能体另起炉灶，等于把这些年的积累重新攒一遍，再养两套。

全书到第 15 章坚持原生实现，不是因为框架不好，而是机制要先懂再选。手写过回路，才知道框架在上下文管理上替人做了多少默认决定。编排 API 里哪些参数要紧、哪些无关紧要，也只有在亲手搭过监督者之后才分辨得清。至于暂停恢复，不自己写一遍，很难想象一个中断点背后要序列化多少状态。

原生代码还是评估框架时的参照物。17.2 表里自建一列能填出数字，靠的是全书前面十几章攒下的四样东西，回路执行器、会话存储、审批挂起和评测回路，件件都已成型。选完框架之后，这些亲手写的件照样有用，回调、扩展点和评测基准，都拿它当底稿。

迁移成本一共三笔，一笔一笔来。第一笔是锁入，框架的检查点格式、会话结构和编排语义全是私有的，用得越深，将来迁出要重写的就越多。这不是纸上谈兵的风险，AutoGen 存量用户如今面对的迁移指南就是现成先例。锁入多深有个粗略量法，数一数多少框架私有的数据格式落进了数据库。检查点、会话和轨迹这三类，凡是私有序列化格式落了库的表，迁出那天都得补一个转换器。

第二笔算抽象泄漏，第 15 章埋过伏笔的那个陷阱在这里浮出来，LangGraph 的 interrupt 一恢复，所在节点会从头重跑，带副作用的代码得放到中断点之后。这类细节埋在文档深处，多半要等出了事才碰上。我自己就碰过一回，恢复之后节点从头重跑，带副作用的调用执行了两遍，翻轨迹才对上号。

第三笔成本落到版本节奏上。LangGraph 1.0 承诺过 2.0 之前不破坏兼容，可承诺的边界恰恰画在 2.0，大版本一到照样要迁。这种先例厂商那边就有，Assistants API 从公告废弃到关停，留了一年缓冲，一年内没迁完的调用直接失效。版本承诺能做的只是把风险缓解一些，想把风险彻底消除，从来都做不到。

版本走得快的另一面，是修复也来得快。框架里的陷阱往往别人先遇到过，issue 区翻一翻常有现成答案；自建的陷阱却只能自己填。这笔反过来的收益，也是真的。

拿一支十人团队给连锁品牌做智能客服来走一遍，起步用 LangGraph。锁入那一问先摆出来，检查点与轨迹打算落库，LangGraph 的私有序列化格式就会进数据库，锁入按中等记，退出动作定在轨迹层多存一份通用 JSON 导出。接着问泄漏，检索工具带副作用，interrupt 恢复会让所在节点重跑，对策是把副作用挪到中断点之后，并写进团队编码规范。版本放在最后问，1.0 到 2.0 之间是窗口期，升级预算提前排进季度计划。

三个问题都答完，采用的决定才算有依据。到了评审会上，这三行就是全部论证，比整整一页“技术选型对比”的长文更结实。

把三笔成本折成一份通用清单时，锁入与版本节奏能写成固定问句，抽象泄漏却写不成，每家框架藏的陷阱都不一样，只能逐家去查。这份清单，选型会上照着过一遍就行。

选型决策清单
1. 十能力打分表里，本团队权重最高的三项是哪三项？
2. 这三项中，哪一项既没有能力自建、也没有人力自建？
3. 候选框架的检查点与会话格式是否私有？迁出预计要重写哪几层？
4. 框架最近一次破坏性变更是什么时候？官方迁移指南有多长？
5. 智能体跑在内网还是云上？框架的云端集成是助力还是负担？
6. 评测与护栏是挂在框架上，还是独立于框架、随迁移可带走？

还有一层批评值得带进评审会。社区里流传的一种拆法，把智能体看成模型加运行框架，框架那一半再切成工具、知识、观察、动作接口和权限五份。五份里三份能在本书前文找到落点，权限对应第 13 章的最小权限，工具对应第 4 章的函数，知识对应第 6 章的库；观察是智能体读取环境的通道，动作接口是它改动环境的出口。批评点在于这套拆法把推理和反思整个漏掉了，等于认定思考全归模型。候选框架要是只围着这五样转，模型该想多深、要不要自评，这些同样决定质量的问题就没了着落。所以选型时多加一问，推理与反思的落点，框架留了没有？

留个练习，拿本节那张决策清单，把当前系统的三个主力依赖（框架、模型和向量库）逐个过一遍，每个写下三项成本的结论与对应的退出动作。三个都过完，整套系统哪里锁了、怎么退出，就都收在一页纸上，评审会上拿出来，比口头争论管用得多。

本章小结

• 17.1 格局仍会流动。四家原生 SDK 各有定位，OpenAI Agents SDK 轻量库三原语、Claude Agent SDK 重库全套设施、Microsoft Agent Framework 合并产物、Google ADK 多语言深绑云；Assistants API 2026-08-26 关停，AutoGen 分叉出 AG2 又并入微软新框架，Swarm 停更；LangGraph 与 CrewAI 站稳 1.0；中文生态有 Qwen-Agent；第三类玩家个人智能体运行框架以 OpenClaw 为代表。
• 17.2 十能力清单几乎不动，分层抽象、异步流式、可观测、状态、配置、护栏、模式、部署、评测和生态；九项配权重打分，生态单独当门槛；权重一变排名就跟着变，矩阵问出来的是“最看重什么”。
• 17.3 三笔迁移成本，锁入（数私有格式落库多少）、抽象泄漏（interrupt 恢复节点从头重跑一类坑，只能逐家翻）、版本节奏（大版本一到照样要迁）；框架的真实收益是维护负担转移与标准化接口；私有化部署配开源推理引擎，单机 Ollama 门槛最低、服务化用 vLLM 或 SGLang，接口兼容 OpenAI 格式，示例代码改 base_url 指向自建服务就能跑；选型会上过一遍六问决策清单，外加推理与反思落点一问。

框架的名字年年在换，清单与方法却能一直拿在手里。拿它们去打量任何一个新发布的 SDK，先翻开文档逐条对上十项能力，再拿团队权重最高的三项去问迁移成本。答案每回都不一样，可用的方法每次都一样。

参考资料

• OpenAI Agents SDK 官方文档（生产就绪定位、agent 与 handoff 与 guardrail 原语、sessions、内建 tracing、默认走 Responses API、第三方模型适配层），https://openai.github.io/openai-agents-python/ ，核实于 2026-08。
• OpenAI 官方废弃公告页（Assistants API 2025-08-26 公告废弃、2026-08-26 关停，替代方向 Responses API 与 Conversations API），https://developers.openai.com/api/docs/deprecations ，核实于 2026-08。
• OpenAI Swarm 仓库 README（Swarm 停更、Agents SDK 为其生产化演进的表述、实验与教学定位），https://github.com/openai/swarm ，核实于 2026-08。
• Claude Agent SDK 官方概述（Claude Code 的工具、回路与上下文管理成库，Python 与 TypeScript，内置工具、hooks、子智能体、MCP、权限、sessions、skills 与 memory、插件，Managed Agents 托管形态），https://code.claude.com/docs/en/agent-sdk/overview ，核实于 2026-08。
• Google ADK 官方站点（开源，Python/Java/Go/TypeScript/Kotlin，原生 MCP 与 A2A，Cloud Run、GKE 与托管运行时部署），https://adk.dev/ ，核实于 2026-08。
• Microsoft Agent Framework 官方概述（AutoGen 与 Semantic Kernel 的继任者、单智能体、工作流、集成件与 Harness Agent 四块，.NET 与 Python，Go 公开预览），https://learn.microsoft.com/en-us/agent-framework/overview/ ，核实于 2026-08。
• Microsoft Agent Framework 1.0 发布公告（.NET 与 Python 到达 1.0；其中 Agent Harness 写作可定制的本地运行时），https://devblogs.microsoft.com/agent-framework/microsoft-agent-framework-version-1-0/ ，核实于 2026-08。
• Microsoft Agent Framework 概念页 Agent Harness（agent harness 定义为把语言模型变成智能体的运行时脚手架，装配产物即 HarnessAgent 与 create_harness_agent；概述页的 Harness Agent 与公告的 Agent Harness 两个名字同指这套设施），https://learn.microsoft.com/en-us/agent-framework/concepts/harness/ ，核实于 2026-09-02。
• Microsoft Agent Framework 官方迁移指南（AutoGen 存量代码迁往 Agent Framework 的对照与步骤），https://learn.microsoft.com/en-us/agent-framework/migration-guide/from-autogen/ ，核实于 2026-08-29。
• AG2 仓库 README（AutoGen 的分叉：AG2 Classic 延续 autogen 命名空间与 v0.2 对话式 API、既有代码继续可跑，Apache 2.0，志愿者维护），https://github.com/ag2ai/ag2 ，核实于 2026-09-01。AutoGen 原作者 2024 年末离开微软仓库分叉出 AG2、微软将主线重构为 v0.4 事件驱动与 actor 式架构的演变，另经社区文档多方印证。
• LangChain 官方文档 human-in-the-loop（LangGraph interrupt 的恢复语义，恢复时所在节点从头重跑，带副作用的代码应放在中断点之后），https://docs.langchain.com/oss/python/langgraph/human-in-the-loop ，核实于 2026-08。
• PyPI langgraph（1.2.11，2026-08-11 发布），https://pypi.org/project/langgraph/ ，核实于 2026-08。
• CrewAI 官方博客（开源版 1.0 GA，2025-10-20），https://crewai.com/blog/crewai-oss-1-0---we-are-going-ga ，核实于 2026-08。
• Qwen-Agent 仓库（Qwen 系列模型上的智能体框架，工具调用、MCP 支持、代码解释器；17k star，最后推送 2026-03-04），https://github.com/QwenLM/Qwen-Agent ，核实于 2026-08。
• A2A 协议官方公告（1.0.0 于 2026-03-12 发布，Linux Foundation 治理），https://a2a-protocol.org/latest/announcing-1.0/ ，核实于 2026-08。
• 《Designing Multi-Agent Systems》（2025）第 9 章（十项核心能力、加权评分矩阵、自建采用混合三路判据、维护负担转移与标准化接口的价值——两条收益出自作者在 AutoGen 团队的那几年、关于别低估配置驱动设计的提醒）。见 txt-ref-zh/designing-multi-agent-systems/。
• 《Building AI Agent Platforms》（Ben O'Mahony、Fabian Nonnenmacher，2027 Early Release，O'Reilly）第 2 章（平台能力取舍：帕累托原则与 80/20 必备能力、XY 问题、为极端用户设计；过度聚焦提示词管理是平台反模式，提示词应放调用代码旁的版本库）。见 txt-ref-zh/building-agent-platforms/。
• OpenClaw 仓库（开源个人智能体运行框架，模型无关、本地优先、多消息通道），https://github.com/openclaw/openclaw ，核实于 2026-08。star 数各来源口径不一，正文不采具体数。
• NVIDIA NemoClaw 仓库与用户文档（企业级参考栈，智能体运行在 OpenShell 沙箱化运行时），https://github.com/NVIDIA/NemoClaw ，核实于 2026-08。
• vLLM 仓库（高吞吐开源推理与服务引擎，起于 UC Berkeley 的 Sky Computing Lab，PagedAttention；自带 OpenAI 兼容 API 服务器），https://github.com/vllm-project/vllm ，核实于 2026-10-07。
• SGLang 仓库（开源推理框架，为智能体负载与大规模服务优化，Apache 2.0，非营利开源组织 LMSYS 托管；文档以 OpenAI 兼容接口为调用示例），https://github.com/sgl-project/sglang ，核实于 2026-10-07。
• Ollama 仓库与 OpenAI 兼容公告（本地一条命令拉起开源权重；OpenAI 兼容端点把 base_url 指向本地服务即可接入），https://github.com/ollama/ollama 、https://ollama.com/blog/openai-compatibility ，核实于 2026-10-07。
• 《Building Agentic Applications with CrewAI and MCP》（Max Gfeller，Manning MEAP）第 1、2、5 章（任务中心的 crew/task/agent 三层与 role/goal/backstory 编译进系统提示、system/prompt/response 三模板可整体接管、八二法则出自 CrewAI 官方文档、任务级 Pydantic 输出作智能体间的类型化契约、人设增益分模型的使用经验）。见 txt/crewai-mcp.txt（英文原文，第 1、2、5 章，行 312-375、437-445、678-700、1063-1138、3532-3533、3551-3593）。
• 《Designing AI Agents》（Jia Huang，Manning MEAP）第 2 章（harness 五分解——工具、知识、观察、动作接口、权限——对得上七个认知模块里的五个、独缺推理与反思槽位的批评）。见 txt/designing-ai-agents.txt（英文原文，第 2 章，行 1116-1199）。
• 《The Claude Code Operating Model》（2026）第 8 章（Agent SDK 编程模型：system/assistant/user/result 四类消息的异步流、调用级审批回调在白名单与权限模式未自动放行时触发、自定义工具以进程内 MCP 服务器实现），机制另经官方参考文档复核，https://code.claude.com/docs/en/agent-sdk/typescript ，核实于 2026-09。见 txt/claude-code-operating-model.txt（英文原文，第 8 章，行 8750-8830、9400-9470）。
• 《Agentic AI for Engineers: Architecting Goal-Driven Systems》（Dhivya Nagasubramanian，Apress 2026）第 7 章（云厂商托管智能体平台：Bedrock Agents、Vertex AI Agent Builder、Azure AI Agent Service 托管编排换定制损失与云绑定，企业自建对采购的第一道入口；源书表格条目按版本时差，AWS 已另有 AgentCore、Azure 服务归入 Azure AI Foundry，经 2026-09 网络复核）。见 txt/agentic-ai-for-engineers.txt（英文原文，第 7 章，行 9260-9290、9420-9450）。
• 《AI Agents in Action》（Micheal Lanham，Manning 2024）第 2 章（GPTs 与 GPT Store：指令加资料搭定制助手的无代码形态）。见 txt-ref-zh/ai-agents-in-action/。
• 《Building and Distributing Agentic AI Solutions》（Julian Soh、John Tidwell、Priyanshi Singh，Apress 2026）第 8 章（微软三级开发选项：Copilot 现成产品、Copilot Studio 无代码搭建、Foundry 专业开发的分野）。见 txt-ref-zh/building-distributing-agentic-ai/。
• 《The Bible of Agentic AI Systems》（Stefanos Drakos，自出版 2026）第 16 章（LiteLLM 网关库：多家厂商模型归一成统一接口的轻量工程选项）。见 txt/agentic-ai-bible.txt（英文原文，第 16 章，行 5384-5400）。
• 扣子（Coze）官网（字节跳动旗下的无代码智能体开发平台），https://www.coze.cn/ ，核实于 2026-09。
• 《AI Agents with Java》（Alex Soto Bueno 等，O'Reilly 2027）（LangChain4j 与 Spring AI：JVM 生态的智能体抽象与工具调用）。见 txt/ai-agents-with-java.txt（英文原文）。
• 《Building AI Agent Platforms》（Ben O'Mahony、Fabian Nonnenmacher，2027 Early Release，O'Reilly）第 2 章（智能体平台复用既有 IDP、数据网格与 MLOps 平台，扩展而非重建）。见 txt-ref-zh/building-agent-platforms/。