智能体工程 · 16b
换了框架名字,哪些工程责任仍归你?
读完能做的判断:将框架映回工具、状态、检索和评测,保留同题对照与共同陷阱。
📑 本页目录(点开跳转)
16b · 框架这层皮
⏱ 阅读参考约 51 分钟 · 动手实践另计;可分段完成
🔗 可运行实践: LangGraph 两个进程暂停与恢复 。
🎯 一句话
框架不是新知识,是你前面十几章学过的机制被打了个包。 这一章不教 API(写了半年就过期),只做一件事:把你上班第一周就会撞见的那些名字,一个一个对回本教程讲过的哪一节机制。
🧭 一、先把立场说清楚
第 00 章的陷阱表写着:「先学完 LangChain/框架再说——框架把机制藏起来了,出问题你不知道在哪」。第 18 章更狠,让你从裸 HTTP 请求开始把框架造出来,目标是那句「啊,原来 LangChain 就这?」。
这一章不推翻它,它是这个立场的下半句:你终究会撞上这些框架,手里得有张对回机制的地图——因为定位问题的前提,就是知道这层封装的是哪个机制。也因为框架会过期而原理不会,这章只写映射和坑,一行 API 都不写。
⭐ 框架是词汇表,机制是语法。 只背词汇表的人写不出句子;懂语法的人翻一下词汇表就能读懂任何一段。
🗺️ 二、对照表:每个名字对回哪一节
先记这张表,其余都是注脚。
| 框架 | ≈ 你已经学过的 |
|---|---|
| LangGraph | 第 12 章手搓 Harness 里那个状态机 / 检查点 / 从出错点恢复 |
| LangChain | 第 7 章工具定义 + 第 4 章上下文拼装 + 第 3 章提示词模板 |
| LlamaIndex | 第 11 章 RAG 管线(切分 → 嵌入 → 检索 → 重排)的封装 |
| CrewAI / AutoGen | 第 13 章多 Agent 的几种协作模式 |
| Ragas / promptfoo / DeepEval | 第 14 章你自己搭的那套评测 |
| Dify / Coze | 第 6 章工作流的可视化版 |
| Claude Agent SDK / OpenAI Agents SDK | 第 1 章那个循环 + 第 12 章 Harness |
每行都要问第二个问题:它没替你做什么。
① LangGraph ≈ 第 12 章的状态机与恢复
第 12 章说 Harness 由四样组成:循环、工具、上下文管理、护栏。LangGraph 主攻第一样里最难的半截:状态怎么外置、断了怎么接着跑——正对上五头怪里的「状态丢失」和第 13 章的「状态错误会复利,要从出错点恢复而不是从头重跑」。
没替你做的:护栏(max_steps / 超时 / 预算)还得你定;第 12 章的过早宣告完成,没有框架能救。
② LangChain ≈ 第 7 章工具 + 第 4 章上下文 + 第 3 章模板
LangChain 提供模型、工具和消息等通用抽象:工具装饰器和自动生成 schema = 第 7 章(也就是第 18 章 T1 的 @tool);消息拼装、历史管理、摘要 = 第 4 章的压缩与外置笔记;提示词模板、变量填充、输出解析 = 第 3 章的骨架与预填响应。
当前 LangChain 还提供 create_agent,组织模型与工具调用循环,并可通过 middleware 配置行为,具有 Agent 构建能力。其 Agent 建立在 LangGraph 上;具体控制、持久化与恢复能力仍需核对版本及配置,业务权限和审批规则仍由应用落实。同题边界见 16e 的能力对照(该例未配置 checkpointer);接口定义见 LangChain 官方概览。
没替你做的:第 7 章说「工具描述就是提示词」,仅仅精化描述就曾拿下 SWE-bench SOTA——这件投产比最高的事,它一个字都不替你写。
③ LlamaIndex ≈ 第 11 章 RAG 管线的封装
第 11 章把 RAG 拆成五环节,框架只包了前两个的一半:
| 第 11 章的环节 | 框架默认给的 |
|---|---|
| 切分(按结构 / 重叠 / 父子块) | 一个默认切分器,默认参数就是坑 |
| 上下文检索(每块补上下文;原实验上下文向量降 35%,再加上下文 BM25 降 49%,不是通用保证) | 通常不默认开 |
| 混合检索 + RRF | 有,但常要显式打开,默认只走向量 |
| 重排(性价比最高的一步)、评估(Recall@K) | 都要自己接 |
⚠️ 最危险的错配:第 11 章的铁律是「答案不对,先查检索」。 框架把切分和检索藏进一行调用,于是所有人第一反应都去调提示词——本章的事故复盘死的就是这个。
④ CrewAI / AutoGen ≈ 第 13 章的协作模式
CrewAI 的「角色 + 任务 + 流程」≈ Agent 团队(持久化工作者)叠编排器;AutoGen 的「多 Agent 同场发言」≈ 消息总线——连局限也照单全收:执行路径难追踪、路由错误会静默失败。
没替你做的:第 13 章最贵的两条——等预算对照实验(固定自己的实测预算,再比较单 Agent 与协作方案)和结构化委派(目标 + 输出格式 + 工具指引 + 边界)——它一条不管,反而让你更容易跳过第一条:「拉三个 Agent」只要三行。
⑤ Ragas / promptfoo / DeepEval ≈ 第 14 章的评测
第 14 章八步里它只管评分器实现 + 跑批出表,最贵的三步一步不管:第 2 步无歧义任务 + 参考解、第 3 步正反平衡(只测正例会学成「什么都做」)、第 6 步读转录(「最容易跳过也最有价值」的一步)。
💀 第 14 章讲过 pass@k 和 pass^k 讲的是相反的故事(单次 75% 时 pass@3 = 98.4%,pass^3 = 42.2%)。评测框架的默认报表大多只给一个平均分,面向客户的 Agent 必须看 pass^k,这得你自己配。
⑥ Dify / Coze ≈ 第 6 章工作流的可视化版
第 6 章的判断技巧是「我能提前画出这个任务的流程图吗」。可视化平台妙就妙在它逼你把图画出来——可视化平台也能包含循环、Agent 节点与动态工具选择,不能据“画得出来”断言它只能支持前三种。看实际节点、状态与权限语义,再映射到本教程的机制。
判断的是谁选择下一步以及如何处理状态,不是有没有画布。Dify 等平台可在固定工作流中嵌入 Agent 节点;是否适合自己的任务仍需用同题对照。
⑦ Agent SDK ≈ 第 1 章循环 + 第 12 章 Harness
第 1 章末尾已经写过:真实开发会用官方 tool use API 或 Agent SDK,「循环都帮你写好了」。你手写的那 60 行——发历史、判断是工具调用还是最终答案、执行、回填、max_steps 兜底——就是它的 run()。
没替你做的:第 12 章的核心命题依然生效——每个组件都编码了一个会过时的假设。SDK 的默认 harness 也是一堆假设,也要定期做「体检五问」。
🧰 三、框架到底替你做了什么(六类,附行数量级)
行数是量级感,基准来自第 1 章那个 60 行的完整 Agent 和第 18 章约 90 行的 MiniAgent。
| 类别 | 你自己写要多少行 | 值得白嫖吗 |
|---|---|---|
| ① 循环与状态管理 | 裸循环 60 行;加检查点、断点续跑、人工介入 300–600 行 | 中,只有恢复机制值得买 |
| ② 工具注册与调度 | @tool + schema 40–80 行;加并行 / 超时 / 截断 200 行 |
低 |
| ③ 上下文拼装 | 模板 + 组装 50 行;加压缩 150 行 | 低,压缩提示词写什么决定成败,框架默认版太笼统 |
| ④ 重试与错误处理 | 指数退避 30 行;加错误分类 + 幂等 150–300 行 | 高 |
| ⑤ 可观测性 | 结构化 trace 80 行;加 span 树、成本归因、回放界面 数千行 | ⭐ 最高 |
| ⑥ 供应商抽象 | 接一家约 100 行;接三家 + 抹平工具调用格式 500 行以上 | 高,但别指望它救你(坑④) |
🔑 ①–③ 你在第 18 章已经亲手写过,加起来不过几百行——框架在这三类省下的时间,抵不过它的学习成本。 真正值得白嫖的是 ④⑤⑥:枯燥、没创造性、写错了还很难发现。
📋 四、该不该上框架:一个判断清单
每项 0–2 分,总分 ≥ 6 才值得上框架。
每项选一个符合现状的分数,再按下文解释合计。这里是评分标准,不是待办勾选。
| 评估项 | 0 分 | 1 分 | 2 分 |
|---|---|---|---|
| 团队规模 | 1-2人 | 3-5人 | 6人以上或跨团队 |
| 要不要换供应商 | 锁死一家 | 可能换 | 已在做A/B或多供应商灰度 |
| 调试频率 | 每天改循环内部 | 偶尔 | 循环不动只改提示词和工具 |
| 人工介入/断点续跑 | 不需要 | 偶尔要 | 核心需求(审批、长任务恢复) |
| 上线时间压力 | 有时间打磨 | 一两个月 | 两周内要上 |
四条「手搓更快」的判据(命中任意两条,别上框架):
| 判据 | 为什么 |
|---|---|
| 工具少于 10 个且只有一家供应商 | ②⑥ 两类价值直接归零 |
| 要在循环内部插自定义逻辑超过 3 处 | 扩展点很少长在你需要的位置,绕开的成本 > 自己写 |
| 团队没人读过这个框架的源码 | 出事时没人掀得开它 |
| 任务路径基本固定 | 第 6 章:能画出流程图就用工作流,工作流不需要 Agent 框架 |
⚠️ 一个高频误判:「团队新人多,用框架好上手」。恰恰相反—— 抽象泄漏会让新人同时要懂两层(坑①)。新人多,更该给他们一个几百行、读得完的手搓循环。
⚠️ 五、框架的六个共同坑(全章最值钱的一节)
坑① 抽象泄漏
框架承诺「你不用管下面」,兑现的却是「顺利的时候你不用管下面」。一出问题,你要同时懂框架和底层——比只懂底层更难。
🔑 自检:你能说出「框架的这一行,对应第 X 章的哪个机制」吗? 说不出来 = 你现在依赖的是运气,不是理解。
坑② 调试链路变长
坑③ 版本变动快
教程和示例的过期速度远快于原理。更麻烦的是:语义化版本号管的是 API 兼容,不管行为兼容——补丁号变了、签名没变,但默认值变了、重试策略变了、截断行为变了,于是CI 全绿,线上悄悄退化。
⚠️ 三条最低纪律:① 锁死版本,lockfile 进仓库,不做
-U式例行升级; ② 升级前读 changelog 里所有带 default / behavior 字样的条目; ③ 升级和上线分成两次发布,中间跑一遍评测(第 14 章)。
坑④ 供应商锁定
框架的承诺是「换模型只要改一个字符串」,真实情况是这层抽象保不住你:它确实抹平了工具调用的格式和字段名,但提示词该怎么写(第 3 章)、缓存前缀布局(第 4 章要求逐字节相同,第 12 章明说「不要中途换模型」)、哪些 harness 组件已经多余(第 12 章体检五问)——一个都不管。
抽象层只抹平了「怎么调」,抹不平「怎么调得好」,而后者是换模型时 90% 的工作量。
坑⑤ 默认值是坑
默认值是框架作者为「一般情况」选的,而你的场景不是一般情况。 下面每一个都直接决定质量:
流程图
🔑 可以直接执行的纪律:上面这些参数一个都不许用默认值,全部显式写在你自己的配置里。 哪怕写的值和默认值一模一样——显式写出来,升级时 diff 才看得见。
坑⑥ 提示词被藏起来
你不知道框架实际发出去的提示词长什么样。 它可能加了自己的系统提示、重排了工具描述顺序、追加了格式要求,甚至在稳定前缀前插了个时间戳(第 4 章:缓存 100% 失效)。
可使用 SDK 支持的请求钩子或追踪功能,先用合成资料观察请求。HTTPX 的 event hooks提供客户端级入口;异步客户端使用异步钩子。不要全局替换所有 Client.send,也不要默认打印真实 URL、凭证或整份正文。
import json
import httpx
def inspect_request(request):
# 只记录结构计数;不输出 URL、请求头、问题或文档正文。
info = {"method": request.method, "body_available": False}
try:
raw = request.content # 不读取尚未缓冲的流,不改变发送语义
if len(raw) <= 100000:
obj = json.loads(raw)
if isinstance(obj, dict):
info.update(body_available=True,
message_count=len(obj.get("messages", [])) if isinstance(obj.get("messages", []), list) else None,
tool_count=len(obj.get("tools", [])) if isinstance(obj.get("tools", []), list) else None)
except (ValueError, TypeError, httpx.RequestNotRead):
pass
print(json.dumps(info))
client = httpx.Client(event_hooks={"request": [inspect_request]})
# 将 client 传给支持自定义 HTTP 客户端的 SDK;用完关闭。
# AsyncClient 的 request hook 必须写成 async def。
打印出来后按优先级盯五件事:system 段被框架加了什么(塞进来的模板常和你的指令打架)、稳定内容是不是真在最前面(第 4 章缓存铁律,动态内容混进前缀就全废)、工具描述是不是你写的那版(被改写等于换了提示词)、塞进去的检索块长什么样(半句话的块 = 切分参数错了)、实际的 temperature / max_tokens。
⭐ 把它做成随时能打开的开关,而不是一次性的调试动作。 再把框架版和第 18 章手搓版的请求体 diff 一下——那个 diff 就是「框架替你做了什么」最诚实的答案。
💀 六、一个事故复盘
下面是把常见形态归并后的典型复盘,数字是量级感。
背景与触发:内部文档问答 Agent,2.4 万篇文档,日均约 6000 次提问,稳跑三个月。周二例行依赖更新,检索框架从 0.11.3 升到 0.11.7——补丁版本号,CI 全绿,代码一行没改。这个版本悄悄改了默认切分器:chunk_size 从 1024 降到 512、overlap 从 200 降到 20,而团队从没显式配过这两个参数(坑⑤)。当晚重建索引,块数从 8.7 万涨到 19.6 万——没人看这个数。
症状:不报错、不抛异常、延迟正常。只是回答变短,「资料里没有相关内容」从 4% 涨到 17%,满意度按周从 82% 掉到 71%。没有告警,因为没有任何指标在盯检索。
| 天 | 做了什么 | 结果 |
|---|---|---|
| D1–D3 | 认为模型退化,反复调提示词 | ❌ 第 11 章铁律是答案不对先查检索,他们反着来 |
| D4 | 换更贵的 embedding 重算全库 | ❌ 白花一笔钱,Recall@10 从 61% 只挪到 63% |
| D6 | 终于按第 14 章建了 20 条检索评测 | ⭐ Recall@10 = 61%,而升级前的抽样记录是 88% |
| D8 | 按坑⑥ 拦截真实请求打印出来 | 💀 塞进提示词的 5 个块全是被拦腰砍断的半句话 |
| D9 | 翻 changelog,锁版本 + 写死切分参数 | ✅ Recall@10 回到 87% |
代价:约 3 人周工程师时间 + 一次全库 embedding 重算的白花费。而修复只改了两行配置。
💀 四个坑同时发作:坑③ 补丁版本改了行为 → 坑⑤ 默认值本就不该信 → 坑⑥ 提示词被藏起来,让 D8 的发现推迟七天 → 坑① 抽象泄漏让所有人都在错误的层里找原因。
最该带走的一条:⭐ 没有评测就没有告警——索引重建后自动跑 Recall@K,跌 5 个点就阻断上线(第 14 章)。
🔑 如果第一天就打开了「打印真实请求」的开关,D8 的发现会在 D1 出现,9 天变 1 天。 掀开框架的通路,要在出事之前就修好。
🧷 七、掀开它:上线前的四个动作
操作步骤
- 锁版本 + lockfile 进仓库,升级走单独的发布窗口
- 影响质量的参数全部显式配置,一个默认值都不留
- 第一天就准备受控请求追踪开关:默认仅结构计数,合成数据可对照全文,而不是出事再现搭
- 留一条 50–100 行的手搓兜底路径,评测集要能同时跑框架版和手搓版
第 ④ 条不是炫技,是逃生舱:框架挂了、供应商要临时切、或你要证明「这个 bug 是框架的不是模型的」——手上有一条不经过框架的路径,就永远有的可比。
🎓 八、务实的结论
不是「别用框架」。 六类表已经说明白:重试、可观测性、供应商适配这三类,自己写既枯燥又容易错,该白嫖就白嫖。
⭐ 先懂机制 → 再用框架当加速器 → 出问题时你要能掀开它。 顺序不能颠倒。先学框架的人,缺的不是知识,是把现象对回机制的能力。
第 18 章那个项目的价值就在这里:做完之后,你看框架源码的感受会从「框架很神秘」变成「框架就是我写的这几个机制 + 一堆适配器和边界处理」。这一章的对照表,就是那个顿悟的速查版。
🔗 这一章连到哪里
| 去哪 | 为什么 |
|---|---|
| 12 · Harness:长时任务的骨架 | ⭐ 对照表第一行的原件:循环 / 工具 / 上下文管理 / 护栏 |
| 18 · 挑战项目A-手搓Agent框架 | 这章是地图,那章是实地走一遍。做完再回来看这张表,每行都会变具体 |
| 上线之后 17 · 版本回溯与可复现 | ⚠️ 坑③ 和事故复盘的正解:依赖版本要锁、要可复现 |
| 全景导论 13 · LLMOps | 最值得白嫖的那一类(可观测性)在更大的工程图里长什么样 |
| 全景导论 08 · RAG 深水区 | LlamaIndex 那一格背后真正的难点 |
用同一业务规则检查框架
16e · LangChain 同题实作 使用真实 create_agent 与可控模型夹具。固定身份与操作号由程序提供,搜索/草稿回到同一 core/workflow,模型没有审批或执行工具。框架契约通过与真实模型答案质量分别验收。
✅ 检查点
- 这一章和第 00 章「先学完框架再说是陷阱」是什么关系?用「词汇表 / 语法」那个说法解释一遍。
- LangGraph 对回第 12 章 Harness 四件套里的哪一件?它替你做的具体是哪两个机制?
- Dify / Coze 覆盖了第 6 章五种工作流模式里的哪几种?画不出来的时候说明什么?
- 框架替你做的六类里,哪三类最值得白嫖?为什么另外三类不值得?
- 「手搓更快」的四条判据是什么?为什么「团队新人多所以用框架」是误判?
- 六个共同坑分别是什么?事故复盘里同时发作的是哪四个?
- 为什么「补丁版本号 + CI 全绿」不能保证安全?该有哪三条纪律?
- 怎样在不默认泄露正文与凭据的条件下观察实际请求?打印后优先盯哪几件事?
- 事故复盘里 Recall@10 从多少掉到多少?如果第一天就打开请求打印开关,9 天会变成几天?
- 上线前的四个动作是什么?为什么要留一条手搓的兜底路径?
👀 答案
- 不是推翻,是下半句。前面十几章教你别让框架替你思考,这一章补的是「你终究会撞上它们,得有张对回机制的地图」。框架是词汇表,机制是语法——只背词汇表写不出句子,懂语法的人查一下词汇表就能读懂任何一段。
- 对回循环那一件(四件套是循环 / 工具 / 上下文管理 / 护栏)。它替你做的是状态外置(检查点)和从出错点恢复——对应第 12 章五头怪里的「状态丢失」和第 13 章的「状态错误会复利」。护栏和「什么时候算完成」它不管。
- 画布不只支持前三种;Agent 节点、循环与动态工具调用也可嵌入工作流。判断谁选择下一步、如何保存状态与验证权限,再看平台实际支持。
- 最值得白嫖:④重试与错误处理、⑤可观测性、⑥供应商抽象——枯燥、没创造性、写错难发现。不值得的是①循环 ②工具注册 ③上下文拼装:第 18 章你已经亲手写过,加起来不过几百行,而且压缩提示词该写什么直接决定成败,框架的默认版本通常太笼统。
- ①工具少于 10 个且只有一家供应商 ②要在循环内部插自定义逻辑超过 3 处(扩展点很少长在你需要的位置)③团队没人读过框架源码 ④任务路径基本固定(那是工作流,不需要 Agent 框架)。「新人多用框架」是误判,因为抽象泄漏让新人同时要懂两层——新人多更该给他们一个几百行、读得完的手搓循环。
- 抽象泄漏、调试链路变长、版本变动快、供应商锁定、默认值是坑、提示词被藏起来。事故里同时发作的是③⑤⑥①:补丁版本改了行为 → 默认值本就不该信 → 提示词被藏住让发现推迟七天 → 抽象泄漏让所有人在错误的层里找原因。
- 因为语义化版本号管的是 API 兼容,不管行为兼容——签名没变,但默认值、重试策略、截断行为都可能变,所以 CI 全绿而线上悄悄退化。三条纪律:锁死版本(lockfile 进仓库)、升级前读 changelog 里所有带 default/behavior 的条目、升级和上线分两次发布且中间跑评测。
- 使用 SDK 支持的客户端级追踪或 HTTPX event hooks,先以合成数据检查实际提示结构、工具和检索片段。真实数据默认只记录结构计数和脱敏标识;不全局替换 send,不打印凭证、完整 URL 或整份私有正文。
- 从 88% 掉到 61%,修复后回到 87%。如果第一天就打开开关,D8 的发现会在 D1 出现,9 天变 1 天。
- ①锁版本、lockfile 进仓库 ②影响质量的参数全部显式配置 ③第一天就把打印真实请求做成开关 ④留一条 50–100 行的手搓兜底路径,且评测集能同时跑两版。兜底路径是逃生舱:框架挂了、要临时换供应商、或要证明「这个 bug 是框架的不是模型的」时,有一条不经过框架的路径就永远有的可比。
本节回顾
⚡ 走神救援
回来时接住这四点
- 先把框架名称对回循环、工具、上下文、恢复与评测机制,再判断省下什么工作。
- 画布可包含动态 Agent 节点;控制结构与状态语义比界面形态更重要。
- 锁定版本,显式记录影响质量的配置,用同题回归检查升级。
- 先用合成资料观察实际请求;真实数据仅记录必要结构与脱敏标识。
下一节 👉 16c-接进真实产品.md