LangGraph 的定位：把控制流画成图
Agent 的朴素实现是一个 while 循环：调模型 → 执行工具 → 把结果喂回去 → 直到模型不再调工具。这个循环简单、灵活，但有一个工程上的软肋：控制流是隐式的——「接下来做什么」藏在模型的决策里，代码里看不到系统的形状。当 Agent 变复杂（多步骤、多角色、有人工审批、要可恢复），隐式循环就不够用了。LangGraph 的答案：把 Agent 的控制流画成显式的状态图（StateGraph）——节点是处理步骤（调模型、执行工具、人工检查），边是流转关系（条件边、固定边），状态是贯穿全图的共享数据。
这个抽象的收益直接：流程可审查（图就是架构图）、步骤可单独测试（每个节点是纯函数式的变换）、执行可中断恢复（状态可持久化）。LangGraph 由 LangChain 团队推出，如今已是 Python/JS 生态里 Agent 编排的事实标准之一——它不是「更聪明的循环」，是「把循环升级成图」。
核心抽象：StateGraph、节点、边与 reducer
LangGraph 的三件套。StateGraph：定义状态的 schema（TypedDict 或 Pydantic 模型）+ 图的结构。节点（node）：接收当前状态、返回状态更新的函数——「模型的调用」与「工具的执行」都是节点。边（edge）：固定边（无条件流转）与条件边（按状态决定下一节点——路由函数），条件边是 Agent 循环的实现位（「模型还要调工具吗？要 → 工具节点；不要 → END」）。
Reducer 是理解 LangGraph 的钥匙：状态字段可以指定「合并策略」——默认是覆盖（新值替换旧值），消息列表字段配 add_messages reducer 则是追加（新消息并入历史）。这个设计解决了并行节点的状态合并问题：多个节点并行执行时（fan-out），各自的输出按各自的 reducer 合并回状态——不用锁、不用手工合并，框架按声明的策略收拢。Anthropic 式的多智能体（supervisor 派活给多个 worker 并行干活）在 LangGraph 里的实现就是「fan-out 节点 + append reducer」。
Checkpoint：持久化、时间旅行与断点恢复
LangGraph 的杀手级特性是 checkpoint：图的每一步执行后，状态自动持久化（内存/SQLite/Postgres 等存储后端，按 thread_id 组织）。checkpoint 带来四个能力。断点恢复：进程崩了，从最近的 checkpoint 继续跑（本库断点续训思想在 Agent 层的镜像）。时间旅行（time travel）：回退到历史任意节点重放（从某个 checkpoint 分叉重新执行——调试与「如果当时换个决策」的实验）。多轮会话的状态延续：同一 thread_id 的新请求自动加载历史状态——长对话的记忆管理有了框架级的落点。人工介入的基础设施：见下节。
工程提醒：checkpoint 保存的是完整状态（含消息历史与工具输出）——大状态的存储成本与隐私（用户数据进库）要纳入设计，checkpoint 的清理策略与加密策略要在上线前定好。
Human-in-the-loop：interrupt 与审批流
human-in-the-loop（HITL）是 LangGraph 的招牌场景：在图的任意节点前设置 interrupt()——执行到此处暂停并持久化状态，把「待审批事项」交给人；人审批后用 Command(resume=...) 恢复执行（从暂停点继续）。典型模式：工具执行前的审批（危险工具——发邮件、删数据、转账——先暂停等人确认，本库 Agent 工程安全篇的「不可逆操作人工确认」在此有了框架级实现）、人类反馈的注入（模型草稿 → 人改 → 继续跑）。
HITL 的工程价值在「暂停是持久的」：审批可以过夜、可以转给另一台机器上的另一个人（状态在库里不在内存里）——异步的人机协作与「同步等人」的 naive 实现划清界限。配合 checkpoint 的时间旅行，「人类否决后改参数重跑」也成了标准操作。
与朴素循环、其他框架的取舍
vs 朴素 Agent 循环：朴素循环（直接调 API + while）在简单任务上永远更快更透明——LangGraph 的价值随复杂度兑现（多步骤流程、需要恢复与审计、多人协作开发）。vs CrewAI/AutoGen 类角色化框架：那些框架的抽象是「角色与对话」，LangGraph 的抽象是「状态与流程」——需要精细控制流与持久化的选 LangGraph，需要快速搭角色协作的原型选前者。vs Dify/n8n 类可视化平台：可视化平台低门槛但表达受限，LangGraph 是代码优先的完全控制。LangGraph 的代价也要诚实：学习曲线（图思维、reducer 的心智模型）、样板代码量、以及与 LangChain 生态的耦合度（可以只用 LangGraph 而不用 LangChain 的其他部分，但文档与示例常混着讲）。选型直觉：你的 Agent 有「流程」可言（审批、多阶段、恢复）→ LangGraph 的抽象正中靶心；只是「模型 + 工具 + 循环」的单体 → 朴素实现或轻框架。
LangGraph 实战模式：五个高频拓扑的参考实现
LangGraph 的学习成本主要在「图怎么搭」，五个高频拓扑的参考实现是最好的教材。拓扑一：ReAct 循环图——模型节点 + 工具节点的双向环（条件边判断「还要不要调工具」），最简单的 Agent 形态，LangGraph 文档的第一个例子。拓扑二：plan-and-execute 图——规划节点先生成任务清单 → 执行节点逐个完成 → 重规划节点按结果修订——「计划可见可干预」的研究类任务形态。拓扑三：supervisor 多智能体图——一个中央调度节点 + 多个专长子图，调度节点按状态把任务路由给专家（fan-out/fan-in 用 reducer 收拢）——本库多智能体形态篇的分层派实现。拓扑四：多智能体网络图——智能体互相 handoff（无中心的网状），灵活但难调试（本库形态篇协作派的代价在此显形），慎用。拓扑五：带 HITL 的审批图——关键节点前 interrupt，人审后恢复——合规场景的形态。五个拓扑的选型逻辑与本库多智能体形态篇一致：任务清晰度决定拓扑——流程清晰用 1/3/5，探索性强用 2，专业分工用 3。调试的实用工具：LangGraph Studio（图的可视化执行——节点的状态变迁、每步的状态快照，图的调试体验远超 print 大法）。学习路径建议：先跑通拓扑一（理解 reducer 与条件边）→ 再按业务选拓扑 → 复杂场景才上多智能体——从最简单的图开始，是避免「框架眩晕」的唯一路径。
LangGraph 的取舍与陷阱：什么时候不该用它
诚实的框架评价要包括「什么时候不该用」。不该用的三种情况。情况一：单体 Agent 就够——「模型 + 工具 + 循环」一个函数能写完的任务，上图是过度工程（图的样板代码是真实成本）。情况二：控制流需要极低延迟——图的调度层有框架开销（对多数场景可忽略，但对高频轻任务的场景是纯负担）。情况三：团队没有状态图的心智——图思维（reducer、状态合并、条件路由）对新手有学习曲线，强推框架不如让团队先用朴素循环跑通再升级。用它的三种信号：流程要审批（HITL 的 interrupt 是刚需）、任务要可恢复（长任务的 checkpoint 是刚需）、多个角色要协作（图的结构化是多智能体的刚需）。两个常见的坑。坑一：状态设计失控——往状态里塞一切（所有中间产物都进 state），checkpoint 膨胀、reducer 冲突、调试困难——状态要「最小充分」（只放下游节点需要的）。坑二：条件边的路由函数复杂化——路由函数里塞业务逻辑（它应该是纯粹的「路由」——复杂逻辑放节点里），路由函数失控的图不可读。LangGraph 的成熟度评价：它是 Python/JS 生态里「图编排」路线的头部实现（社区、文档、生态的厚度），v0.2 后的 API 稳定性也改善——它的正确位置是「复杂 Agent 的编排层」，而不是「所有 Agent 的默认框架」——用与不用，由复杂度说话。
LangGraph 生态的运维面：LangSmith 与生产监控
LangGraph 的运维面由 LangSmith 补全——框架与观测平台的一体化是 LangGraph 生态的隐性优势。LangSmith 的能力：trace 的可视化（每次图执行的全轨迹——节点、状态、token、延迟）、数据集与评测（本库评测篇的集成）、提示词的版本管理、以及监控的仪表盘（生产流量的成功率、延迟、成本）。生产监控的自建方案（不想绑 LangSmith 的）：LangGraph 的事件回调（astream_events——每个节点的事件流，自接 OTel/自建面板——本库可观测性篇的自建路线）、checkpoint 库的状态审计。监控的重点指标（Agent 图特有）：各节点的耗时与 token（瓶颈节点的定位）、条件边的路由分布（路由漂移的检测——「本该走工具节点的都走了直接回答」是退化的信号）、interrupt 的积压（人工审批的堆积——HITL 的瓶颈）。运维面的收束：图的执行是天然可观测的（每步有状态快照）——LangGraph 的运维优势不是工具多，是「图的执行本身就有结构」，观测只是把结构读出来。
LangGraph 的学习路径：一周入门的实践计划
LangGraph（正文框架）的学习路径：一周入门的实践计划。第一天：朴素循环打底——不用框架，直接调 API 写一个「模型 + 工具 + while 循环」的最小 Agent（本库 Agent 工程第 2 章）——先懂朴素，才懂框架在解决什么。第二三天：跑通官方教程——ReAct 图（reducer 与条件边的核心概念）、interrupt 的 HITL 例子。第四五天：改造一个真实小任务——选一个自己的真实需求（比如「仓库的 issue 分类器」），用 StateGraph 实现（真实需求是最好的老师）。第六七天：加持久化与评测——checkpoint 接上、promptfoo 的评测集建起来（本库评测篇）——一个带恢复能力、带评测防线的 Agent 才算入门完成。学习的避坑提示：不要从多智能体图开始（新手直接上 supervisor 网络是「框架眩晕」的头号来源——单智能体图跑稳了再上）；不要背 API（LangGraph 的 API 在演进，概念才是资产：状态、reducer、interrupt、checkpoint 四个概念吃透，API 怎么变都能跟上）。一周计划的元逻辑：朴素 → 最简图 → 真实任务 → 工程化——四步的顺序不能乱，乱了就是教程看了十遍还是不会写的经典困境。
小结
LangGraph 把 Agent 的隐式循环升级为显式状态图：StateGraph + 节点 + 条件边让控制流可审查可测试，reducer 声明状态合并策略（并行 fan-out 的无锁收拢），checkpoint 给出持久化、断点恢复、时间旅行与会话延续，interrupt 把人机协同做成异步的持久审批流。它与朴素循环的分工是复杂度分层：单体循环用朴素，流程化 Agent 用图。选 LangGraph 的信号是「你的 Agent 有流程可言」——审批、多阶段、可恢复；没有这些需求，别为图而图。
读者留言
COMMENTS 暂无还没有留言，来说第一句？