无尘阁日记

无尘阁日记

《LangGraph智能体设计模式与多智能体开发》:骨架讲清了,案例是拼凑的
silcano

《LangGraph智能体设计模式与多智能体开发》,王晓华著,清华大学出版社 2026 年 3 月第 1 版,ISBN 9787302709527,全书 12 章,我在阅读器里一屏一屏翻完 526 屏,从版权页读到书末最后那行“全书完”。书末微信读书显示推荐值 78.8%,33 人点评。我的判断一句话:这本书把 LangGraph 的三块骨头——状态、节点、边——讲得很清楚,第 3 章值得所有刚上手的人认真读一遍;但它的“9 种智能体设计模式”实际用了两套互不相干的编号、中间还跳号,案例章里的“智能”也多半是让大模型照着 prompt 扮演角色。当入门书够用,当工程参考会把你带偏。

一、先看它的形状

这本书的结构非常好懂,12 章分成两半。前 8 章教方法:第 1 章讲智能体是什么、和传统程序差在哪,第 2 章搭环境(Miniconda、CUDA、PyTorch、Qwen3 的本地调用),第 3 章讲 LangGraph 编程基础,第 4 章讲多条件分支,第 5 章讲“动作 React”,第 6 章讲记忆系统,第 7 章讲规划与执行,第 8 章讲上下文工程。后 4 章做案例:第 9 章是多智能体实战,第 10 章是新能源车朋友圈广告文案,第 11 章是共享空间驱动的多智能体,第 12 章是主智能体驱动的多智能体。

每一章的节奏也统一:先讲这个东西为什么需要,再给最小可跑的例子,再往上加一层复杂度。比如第 3 章从“hello world 级别的一张图”开始,两个节点一条边,跑通了再加条件边,加上循环,最后说明状态怎么在节点之间传递。第 5 章从“让大模型调一个天气工具”开始,跑通了再加第二个工具,再加多轮思考。这个“最小可跑 → 逐步加码”的写法,对自学者是最友好的,因为你能在每一步都看到能跑的东西,而不是先读三十页原理。

但它也决定了这本书的性质:它是一本“照敲能跑”的书,不是一本讲原理的书。它对“为什么 LangGraph 要这么设计”只讲到类比为止,往下追问一层——比如 reducer 到底在什么时机被调用、检查点是怎么序列化的、并发节点写同一个键会发生什么——书里基本没有。这不是缺点,是定位。你带着“我要动手做一个能跑的多智能体流程”这个问题来,它答得不错;你带着“我要搞明白这套东西的内部机制”来,它答不上。

二、第 3 章是全书最值钱的地方

如果只读一章,读第 3 章。它干了一件很多同类书都没干好的事:把“图”这个抽象词,换回了人能直接想明白的东西。

书里先问了一个问题:LangGraph 那么多特性里,哪一个最关键?答案是支持循环。理由是传统 LLM 应用的编排本质上是“无环、线性”的,按固定顺序执行,一旦结束就无法回头,这种模式适合回答问题和分类,但撑不起一个会自我修正、会持续推理的系统。然后作者给了一个我觉得是全书最好的一段类比:

普通 chain(链):像一条单行道,走到尽头就结束。
LangGraph(带循环的图):像一个带红绿灯和环岛的城市交通网,车辆(数据/控制流)可以根据路况(状态)反复绕行、等待、转向,直到抵达目的地。

接着是一句我认为整本书的题眼:

换句话说,循环能力=赋予 LLM 应用“时间维度”和“记忆驱动的决策能力”,这是从“脚本化响应”迈向真正智能体的关键一步。

这句话把 LangGraph 的价值讲完了。一个大模型调用是空间上的——给它一段文本,它给你一段文本,前后没有关系;加上循环和状态之后,它才有先后、有因果、有“上一轮做错了这一轮改”的能力。后面第 6 章讲记忆、第 7 章讲规划与执行,本质上都是在给这个“时间维度”加料。

讲完为什么,第 3 章才落到三个部件上,用的还是同一套人话:

节点(Nodes):每个干活的“小站”(大模型、工具)。
边(Edges):连接小站的“路+指路牌”(传数据、做选择)。
状态(State):记录全程的“共用记事本”(保证信息不丢、流程能循环)。

这三个类比都挑得很准。“小站”这个说法把节点从“函数”里解放出来——它可以是调模型,可以是查数据库,可以是跑一段 Python,只要它接状态、返回状态的更新,它就是个节点。“记事本”这个说法则点出了状态的关键性质:它不是某一个节点的私有变量,是所有节点共用的、每个节点都能读能写、流程绕圈回来还能看到最新内容的东西。后面讲 reducer 的时候你就会明白,所谓 reducer 就是“两个人同时往记事本的同一行写字时,怎么合并”的规则。

这种讲法有个好处:你读完不会做,但你会知道自己在做什么。很多人用 LangGraph 用不下去,不是因为 API 记不住,是因为脑子里没有那张图——不知道自己的业务该拆成几个节点、状态里该放什么、哪一步该分叉。第 3 章给的就是这张图。

三、三个技术细节它讲对了

第一个是超级步骤(superstep)。这个概念很多教程一句话带过,这本书讲清楚了执行语义:

一个超级步骤可以被视为对图节点的一次迭代。并行运行的节点属于同一超级步骤,而顺序运行的节点属于不同的超级步骤。……在每个超级步骤结束时,没有收到消息的节点会通过标记自己为非活动状态来停止投票。图执行在所有节点都为非活动且没有消息在传递时终止。

这段话解释了一个很实际的困惑:为什么我两个节点并行跑到一半,其中一个看不到另一个刚写进状态的东西?因为它们在同一个超级步骤里,这一轮谁都看不到谁的结果,要等下一轮。书里把这个叫“离散的超级步骤”,这个“离散”二字是关键词——LangGraph 的执行不是流水线,是一轮一轮的同步点。

第二个是记忆分层。第 6 章把记忆拆成短期和长期两套机制,短期用检查点(InMemorySaver 之类),靠 thread_id 区分会话,同一个 thread 里的历史自动带上;长期则用中间件钩子,after_agent 在一轮结束后把要点写进文件或数据库,before_agent 在下一轮开始前把它读出来、动态拼进上下文。书里还专门对比了“动态注入”和“静态拼 Prompt”两种做法,结论是前者更好——因为静态拼法会让 Prompt 越写越长,而动态注入可以按当前问题只取相关的那几条。这个对比是有工程经验的,不是抄文档。

第三个是结构化输出。第 5 章讲 create_agent 怎么强制模型按固定格式返回,给了两条路:一是 response_format 参数直接指定 schema,二是模型不支持原生结构化输出时,用 ToolStrategy 把 schema 包装成一个“工具”递过去,靠工具调用的机制逼格式生效。书里的原话是“ToolStrategy 会通过工具调用机制强制格式生效,确保输出符合 Pydantic 模型定义的约束,避免多余字符或格式错乱”。这个“不支持原生结构化输出就用工具调用模拟”的招,是实操里真会用到的,很多人卡在国产模型上就是因为不知道这一层。

还有一处小设计值得单独说:第 12 章做主管路由时,没有让模型自由输出下一步,而是定义了 Pydantic 模型 Route,把 next 字段限死成三个字面量。

其中 next 字段采用 Literal 类型限定为 researcher、writer、end 三个可选值,既避免了决策结果的格式混乱(如大小写不一致、无效值),也让 LangGraph 能直接识别决策结果并完成路由跳转,从源头保证了决策与流程的兼容性。

next: Literal["researcher", "writer", "end"]——这七个字是整本书里最能直接抄走的一行代码。把“下一步去哪”从一个开放式的自然语言回答,收窄成三个枚举值,路由就不会因为模型多说了一句“我觉得应该先研究一下”而崩掉。凡是让大模型参与流程控制的地方,都该这么写。

四、硬伤一:模式编号有两套,中间还跳号

这本书的内容简介写得很清楚:“覆盖环境配置、核心组件及 9 种智能体设计模式”。9 种,听起来是个完整的体系。实际读下来,编号是这样的。

第 3 章末尾的 3.5 节,标题就是“智能体设计模式 1:反应式智能体与自动导航案例”,这是模式 1。往后一章一种:第 5 章“智能体设计模式 2:动作 React”,第 6 章“智能体设计模式 3:记忆系统”,第 7 章“智能体设计模式 4:规划与执行”,第 8 章“智能体设计模式 5:上下文工程”。第 4 章的标题是“构建图的多条件分支”,没带编号,夹在模式 1 和模式 2 之间。到这里还算顺,1 到 5 齐了。

然后第 9 章出了问题。9.2 节的小标题是这样的:

两个小标题分别是“9.2.1 多智能体设计模式 1:流式”和“9.2.2 多智能体设计模式 2:反思”。

编号从 1 重新开始了。前面刚数到模式 5,这里又冒出来一个“模式 1”和一个“模式 2”,而且名字跟前面完全不同——前面是反应式、动作、记忆、规划、上下文,这里是流式和反思。两套编号井水不犯河水地共存在同一本书里。

更奇怪的是第 10 章。第 10 章讲新能源车文案案例,其中一节的标题是“10.2.4 多智能体设计模式 8:Swarm”,第 12 章又有一节叫“12.2 多智能体设计模式 9:Supervisor”。于是整个编号的全貌是:第一套 1、2、3、4、5(第 3、5、6、7、8 章),第二套 1、2(第 9 章),然后 8(第 10 章),然后 9(第 12 章)。

模式 6 和模式 7 呢?我把全书 526 屏的正文过了一遍,这两个编号一次都没出现。宣传语里的“9 种模式”,在书里数得出来的是 7 个,而且其中两个是重复编号的第 1 和第 2。

我知道这可能是因为作者在写前半本和后半本之间调整过结构,也可能是因为模式清单本来有 9 条、写着写着合并了几条。但一本书的目录和节标题,是读者唯一的结构索引,编号乱了,“9 种模式”这个承诺就没法兑现——你想回头查“第 6 种是什么”,查不到;你想跟别人说“我在看第 8 种模式”,别人翻到第 9 章会看到“模式 1”。这种问题在出版流程里本该被编辑抓出来,它是校对级别的错,不是内容级别的错,但它直接影响使用。

五、硬伤二:ReAct 印成 React,密钥排进正文

第 5 章的标题是“智能体设计模式 2:React”。正文紧接着给了一句解释:“……通过‘推理—行动’(Reason-Act)的循环闭环构建,打破了传统智能体‘输入-输出’的单一响应”。

这个术语在业界写作 ReAct,是 Reasoning 和 Acting 的合成词,出自 2022 年那篇《ReAct: Synergizing Reasoning and Acting in Language Models》。写成 React 会直接撞上 Facebook 那个前端框架,读者在搜索引擎里查“React 智能体”,出来的全是前端教程。作者自己在括号里写的“Reason-Act”其实已经把答案给出来了,只差一个大小写。目录、书眉、正文标题,三处都印成了 React,这不是输入法的问题,是没人核。

第二处问题比这个严重得多。第 7 章讲规划与执行,接 Tavily 搜索工具那一节,代码是这样的(我按正文原样抄,密钥中间打码):

tavily_api_key="tvly-dev-aNAW…Xn4i" # 替换成读者自己的 API Key

这不是截图,是排版进正文的代码块。同一节前面的文字说明里,还把这个密钥又写了一遍:“需确保 Tavily API 密钥有效(此处已配置为 tvly-dev-aNAW…)”。也就是说,同一个真实密钥在同一节里出现了两次。

写“替换成读者自己的 API Key”这句注释,说明作者知道这里该放占位符;但他把自己的真实密钥填了进去,然后没有换回来。这是典型的“本地能跑就交稿”。后果不难想:密钥一旦公开就是公开了,Tavily 的免费额度是按账号算的,这本书卖出去多少本,这个号就可能被多少人共用,直到被平台判定滥用。

我提这两条不是要挑刺。恰恰相反——这本书自己在第 2 章就交代过“获取到的 API Key 可以放到环境变量中保存起来”,后面调 Qwen 的代码也一直用 os.getenv("DASHSCOPE_API_KEY") 读取,第 9 章还专门封装了一个校验:密钥“既可以通过参数传入,也能从环境变量读取,若未配置则直接抛出异常”。规矩立得很清楚。结果到了 Tavily 这一处,直接写死在代码里。正文自己立的规矩,自己的示例第一个不遵守,这个反差比错误本身更值得说。

六、短板:案例里的“智能”,多半是大模型在扮演

这本书后半本是案例,四个案例占了两百多屏。我读的时候一直在等一件事:哪个案例里能看见“流程在做决策”,而不是“大模型在演决策”。等到最后也没等到几个。

最典型的是第 3 章末尾那个反应式清扫智能体,3.5.3 节。名字听着很硬:智能体在 PyGame 环境里自主清扫,要避障、要沿墙走、要探索。打开代码一看,所谓“决策”是这样实现的:把传感器数据(前方距离、左右最小距离之类)填进一个 PromptTemplate,模板里写着“基于以上规则和输入数据,请作出决策并输出纯 JSON”,然后用 with_structured_output 把输出约束成一个只有四个取值的枚举——紧急避障、预防避障、沿墙跟随、随机探索。

整张图只有一个节点:

graph_builder.add_node(agent_action)
graph_builder.set_entry_point("agent_action")
graph_builder.add_edge("agent_action", END)

入口是它,出口也是它,一条边直连 END。这不叫图,这叫函数调用穿了件图的外套。而那个四选一的“决策”,本质是把 if-else 的四条分支写成了自然语言,交给大模型去选——同样的逻辑用五行 if 写得又快又准,还不花钱不联网。书里自己也在 PyGame 仿真那段写明了:没有障碍物时不调用智能体,直接直线运动。也就是说,真正跑起来的时候,大模型只在“有障碍物”的分支上被问一次,问的还是个四选一。

我不是说这个例子没价值,它作为“怎么把结构化输出接进一个循环”的演示是合格的。但它被放在“智能体设计模式”的语境里,会让初学者以为“把 prompt 拆成角色,让模型输出 JSON”就是智能体设计。这个误解很贵——真实项目里你按这个思路搭出来的东西,延迟高、贵、还不稳定,而它解决的问题本来是 if-else 该解决的。

第 7 章的儿童成长规划案例是另一个方向的别扭。这一节从 7.4 开始,用状态空间建模长短期目标,接 PlanExecute 拆解任务,接 Tavily 检索资料,前后写了十几屏。然后在开头放了一句:

重要提醒:本节有关儿童成长的规划流程,不具备任何指导真实儿童成长的作用!

这句话本身是对的,甚至是有良心的——用一个技术 demo 去指导真实的孩子确实不该。但问题在于时序:声明放在最前面,后面照样写了十几屏,从目标拆解一直写到资料检索,中间没有任何一处回到这个声明上。读者读到第 12 屏的时候,早就忘了开头那句免责。要么就别写这么长,要么就把免责和边界说在每一处该说的位置。写完再声明“不作数”,更像是在给自己留后路,而不是在保护读者。

第 10 章的新能源车文案案例,问题在另一层。这一节把三个角色——文案师、合规师、设计师——都做成了独立的 agent,然后 10.2.4 节宣布:“前面我们实现了能依据长短期目标完成文案回顾与生成的智能体,本质上精准对应了智能体设计领域的 Swarm 模式。”

Swarm 模式的定义,书里上一段刚讲过:不存在中心化的主控智能体,每个智能体独立决策,通过预设交互规则自发协同。可这个案例的执行代码是这样的:

copywriter_result = run_agent(copywriter_agent, "文案师")
compliance_result = run_agent(compliance_agent, "合规师")
designer_result = run_agent(designer_agent, "设计师")

三行顺序调用,一行等一行,谁也没“自主认领任务”,谁也没“动态补位”。这是最标准的流水线,跟 Swarm 的定义正好相反。把一个顺序执行的函数调用链叫成 Swarm,然后在这个名字下面写两段关于蜂群涌现的抒情,这个落差不是笔误能解释的。

还有一处我印象很深,在第 9 章。那一章做了一个内容审核的循环:生成 → 审核打分 → 低于 8 分打回重写 → 达标结束。逻辑很完整,代码也跑得通。但贴出来的运行日志里,审核结果是这样的:

审核结果:评分 10 分,理由:该文本陈述的是关于儿童心理发展和养育环境的一般性观点,属于心理学和教育学领域的共识性内容,未包含可验证的具体事实性主张(如统计数据、历史事件、科学实验结果等),因此不存在……

“未包含可验证的具体事实性主张,因此不存在(事实性错误)”——这个推理是成立的,但它的成立方式是:因为没有可查证的东西,所以判不了错。这不是审核通过,这是审核弃权。而系统给出的分数是 10 分,满分。一个把“无法验证”读成“没有问题”的审核环节,接在一个自动重写的循环上,会让整个流程看起来在自我纠错,实际上它在自我确认。这一段作者是当成功案例贴出来的,还配了“内容达标,流程结束”的输出。我觉得这是全书最需要读者自己动脑的一处。

七、一处代码自己打自己

第 3 章那个最小的对话图,有一个细节我反复看了三遍。节点函数是这样写的:

reply = llm.invoke(messages) # reply 是 AIMessage 对象
# 返回更新后的状态(messages 会自动追加)
return {"messages": reply.content}

reply.content 是一个字符串。返回 {"messages": "一段文字"},等于往消息列表里塞了一个裸字符串,而不是一条消息对象——这正是“混入字符串”的定义。而注释却说“messages 会自动追加”,仿佛它返回的是个合规的消息。

更妙的是这一章的小结。小结第一段就写:“在实践过程中,我们重点解决了‘类型匹配’这一核心问题——确保对话状态中的 messages 始终以字典列表的形式流转,避免因混入字符串或 HumanMessage 对象导致的校验错误。”

也就是说:代码里做的事,正是小结里宣称已经解决掉的那个问题。同一章,隔了六屏。而且那个 StateGraph(QwenState) 用的是 Pydantic 模型定义状态,节点却返回一个 dict,这两者能不能对上,取决于框架的兼容层,作者没有解释,直接跳过去了。

第 12 章还有一处痕迹更直白。同一段代码在 12.1 和 12.2 各出现一次,两次都带着同一行注释:# 适配不同版本的 LangChain Agent 状态结构(核心修复点)。

“核心修复点”这个词很诚实——它说明这段代码曾经是坏的,作者调通之后把这段带补丁痕迹的版本留在了书里。这不算错,甚至可以说是真实开发的样子。但它跟第 3 章小结那句“我们重点解决了类型匹配这一核心问题”放在一起看,就有意思了:如果第 3 章真解决了,第 12 章为什么还要再“核心修复”一次?

八、那这本书该怎么读

我给一个明确的分工。

前 3 章认真读,第 6 章细读。第 1 章讲清了智能体和“会调工具的聊天机器人”差在哪,第 2 章的环境配置是这本 2026 年 3 月出版的书里最不容易过期的一章(Miniconda 装 Python 3.12.4、CUDA 11.8、PyTorch 2.6.0,这套组合现在还能用),第 3 章就是前面说的那张图。第 6 章的记忆系统是全书工程含量最高的一章,短期靠 thread_id、长期靠 after_agent / before_agent 两个钩子,动态注入优于静态拼 Prompt 这个判断,值得抄进自己的项目。第 8 章的上下文工程也值得翻,它讲的是“上下文窗口有限时先丢什么”,这个问题所有做智能体的人都会撞上。

案例章当“prompt 组织示范”看,别当工程示范。第 9 到 12 章的价值不在架构,在它把一个大任务拆成哪几个角色、每个角色的系统提示词怎么写、结构化输出的 schema 怎么定。这几件事它做得挺细,尤其第 12 章那个 Literal 锁路由、以及把主管和专家拆成两个状态类的做法,是可以直接搬的。但“Swarm”“涌现”“自发协同”这类词,你跳过就好——代码里没有。

代码一律重敲,别复制。理由不是怕你学到坏习惯,是这本代码里有三类东西必须自己校:密钥(书里印的是作者的,你得换自己的)、返回值类型(第 3 章那处 reply.content 就得自己改)、版本(LangGraph 1.0 到现在的 API 还在动,create_agent 的中间件签名、ToolStrategy 的导入路径都可能变)。重敲一遍,这三类问题会在报错里自己跳出来,比读十遍注释管用。

至于适合谁:适合已经会用 LangChain、想搞清楚“多个角色怎么串起来”的人;适合要给自己的产品加一个多步、可回溯、能人工干预的流程的人;适合被 llama-index 那套黑盒编排折磨过、想换一个能看见图的人。不适合谁:不适合想学“智能体到底是什么原理”的人——这本书不碰规划算法的内部、不碰强化学习、不碰评估,它讲的是怎么用框架;也不适合想做高并发生产系统的人——书里没有一次压测,没有一次成本核算,没有一次失败重试的设计,检查点用的还是内存版。

《LangGraph智能体设计模式与多智能体开发》核心知识图谱
四列拆开:第一列是它真正讲清楚的东西;第二列是 LangGraph 的最小骨架;第三列是三类硬伤,编号、密钥、和写完才说不作数的案例;第四列是我建议的读法。

最后说一句我自己的感受。这本书最像“认真写的技术书”的地方,是第 3 章那个城市交通网的类比——它说明作者真的想过“怎么让人一次就懂”,而不是把官方文档翻译一遍。最不像的地方,是那行印在正文里的 API 密钥——它说明这份书稿在最后一公里上,没有人替读者检查过一遍。一个类比和一个密钥,恰好是一本书的两端:前者要花心思,后者只要花十分钟。这一本在前者上花了心思,在后者上省了那十分钟。

它把 LangGraph 这张图给你画清楚了,只是图上的路牌有两个编号、有一块还钉反了,走之前得自己看一眼。

阅读记录 · 王晓华《LangGraph智能体设计模式与多智能体开发》,清华大学出版社,2026 年 3 月第 1 版,ISBN 9787302709527。全书 12 章,我在微信读书网页版逐屏翻阅 526 屏,从版权页读至书末“全书完”,书末显示推荐值 78.8%、33 人点评。文中引文、代码与运行日志均照录原书,涉及作者真实 API 密钥的部分已打码处理。因原书为图片版,OCR 存在个别字符误差,凡引用处均已对照上下文校正,未改写原意;个别整段重复的页面,我无法区分是排版重复还是阅读器翻页未滚完导致的重叠,故未计入书的错误。

关于作者 · 江天(楠哥)
AI 实战导师 / 企业 AI 落地顾问 / 智能体工程师,17 年跨界、15,000+ 小时 AI 实操、20+ 套已交付工作流。