LangGraph 核心架构全景：用状态图构建可控 Agent 工作流

在构建基于大语言模型的自动化系统时，线性链式调用（Chain）往往是许多开发者的起点：将上一步的输出直接拼入下一步的 Prompt，连续触发多次模型推理。这种模式在快速验证原型时简单有效，但随着业务逻辑引入条件分支、循环重试、多路并发以及人工介入（Human-in-the-loop），单纯依靠线性链或在代码中堆砌 if-else 与 while 循环，会让控制流迅速失控。

LangGraph 的核心思想是将应用程序的执行流抽象为状态图（StateGraph）：

  • 状态（State）：作为全局统一的数据契约，在整个图的生命周期中单向流转；
  • 节点（Node）：独立的 Python 函数，接收当前状态并返回局部增量更新；
  • 边（Edge）：定义节点之间的确定性流转或基于状态推断的条件路由。

这一范式将应用开发从“面向过程的面条式代码”拉回到“基于确定性状态机的架构设计”，让复杂的 Agent 工作流具备了清晰的可调试性、状态可恢复性与工程可维护性。

为什么需要从“链”走向“图”

普通链式编排与状态图编排在系统拓扑与控制权上存在根本差异：

架构维度 传统链式调用（Chain） LangGraph 状态图（StateGraph）
拓扑形态 严格单向线性（ ），无法原生表达环 有向图（DAG 或带有环的循环图），原生支持分支与迭代反馈
状态共享 依靠隐式变量传递，跨多步骤数据容易遗漏 显式强类型 TypedDict，所有节点共享且通过 Reducer 安全更新
控制流表达 业务逻辑、错误重试与 API 混杂在应用代码中 节点（动作）与边（路由规则）严格解耦，路由逻辑独立抽离
并发与扇出 难以优雅表达多节点并行与结果汇总 原生支持 Fan-out（并发分发）与 Fan-in（增量状态汇聚）
可观测性 依赖日志断点打印，排查状态依赖困难 运行时图结构可直接导出图片，支持按节点进行流式调试

专栏知识体系全景

本专栏围绕 LangGraph 核心抽象与实战落地，由浅入深划分为 7 篇专题工程解析：

章节导览与核心要点

  1. 《LangGraph 是什么，为什么不用链式调用》

    • 梳理链式调用的三大现实瓶颈：分支膨胀、重试破坏上下文与状态依赖混乱；
    • 建立 State、Node、Edge 的直观心智模型；
    • 明确何时该坚持简单脚本，何时必须引入状态图框架。

  2. 《State、Node、Graph 三件套：状态模式、节点签名与追加 Reducer》

    • 基于 TypedDict 构建强类型系统状态；
    • 掌握节点“增量更新”（局部返回 dict）而非全量覆盖的核心原则；
    • 使用 Annotated 与 operator.add 实现历史消息列表的安全追加。

  3. 《顺序图：第一个可运行的 Workflow 与流式状态观测》

    • 编写首个标准单向工作流，建立规范的图定义与编译（compile）流程；
    • 使用 app.invoke() 执行批量调用，并使用 app.stream() 逐节点捕获状态演进；
    • 初始化 State 字段的边界处理与缺省值设计。

  4. 《条件分支：add_conditional_edges 与动态路由决策》

    • 深入 add_conditional_edges 机制：源节点、路由函数与分支映射字典；
    • 将条件判断从节点执行逻辑中剥离，保持处理节点的纯函数特性；
    • 结合 Pydantic 结构化输出实现高可靠的模型驱动条件路由。

  5. 《并行执行：Fan-out / Fan-in 与并发状态合并》

    • 构建多路并发执行拓扑：从单一源节点同时触发多个异构分析节点；
    • 处理并发写操作下的状态合并冲突（Race Condition）；
    • 实现并发结果的自动汇聚与报告聚合。

  6. 《Prompt Chaining：分步生成模式与流水线质量控制》

    • 破解长文本单次生成导致的幻觉与逻辑跳步；
    • 实现“大纲规划 章节生成 润色审查”的三步质量闭环；
    • 验证中间节点交付物并设置质量拦截门禁。

  7. 《接入 LLM：模型接入、结构化输出与容错兜底》

    • 在图节点中优雅集成 ChatOpenAI 与本地 HuggingFace / Ollama 模型；
    • 统一不同模型的接口封装，设计提示词模板管理策略；
    • 节点级网络异常重试、API 限流与安全降级方案。

核心心智模型：状态单据与工序车间

理解 LangGraph 最轻松的方式是将整个应用视作一座自动化流水线车间：

  • State 是一张随传送带流转的业务单据，上面印有固定的字段表格；
  • Node 是车间里的加工工位。工位工人只阅读单据上自己关心的参数，完成计算或调用外部模型后，将加工产出的新数据填入单据对应栏位；
  • Edge 是底部的自动化传送带。它根据工序安排，将单据准确运送给下一个工位；
  • Conditional Edge 则是道岔分流器。分流器根据单据上的检验印章，自动决定将单据分拨给质检工位、重工工位还是包装工位。

只要把握住“单据始终在流转，工位只负责增量更新”这条主线，无论图的拓扑扩展到多少个节点，系统的控制流都能保持清晰可辨。

前置要求与建议学习路径

  • 开发语言：具备基础的 Python 3.10+ 编程能力，熟悉字典操作与类型注解（TypedDict）；
  • 基础认知：了解大模型 API 的调用原理与参数格式（可先阅读专栏前置基石篇：《Agent 基础认知与工程架构全景》）；
  • 实战演练：建议按篇目顺序动手运行示例代码，逐步从基础顺序图进阶到带条件判断与并行执行的复合 Agent 系统。

系列导航与参考