LangGraph入门：用图结构构建AI Agent工作流

LangGraph是什么

LangGraph是LangChain生态中相对独立的组件，专门用于以「图」的方式构建AI Agent。虽然同属LangChain家族，但它拥有独立的域名和一整套自成体系的开发规范，与LangChain核心库有明显区别。

LangGraph的核心思想，是把Agent的执行逻辑抽象成一张有向图（Directed Graph）：图中包含起始节点、若干处理节点和结束节点，节点之间通过「边」连接，形成完整的工作流。有向图是图论中的基础数据结构，由顶点（Vertex）和有向边（Arc）组成，每条边都有明确的起点和终点，天然描述了「依赖关系」和「执行顺序」，支持循环、条件分支和并行执行。值得一提的是，传统工作流工具（如Apache Airflow）通常只支持无环的有向无环图（DAG），而LangGraph明确支持含环图——这对AI Agent至关重要，因为Agent往往需要在「调用工具→观察结果→再次推理」之间反复循环，直到任务完成。

这种循环执行模式对应的正是学术界广为人知的ReAct模式（Reasoning + Acting），由Google DeepMind于2022年在论文《ReAct: Synergizing Reasoning and Acting in Language Models》中正式提出。ReAct的核心思想是让语言模型在推理过程中交替生成「思考步骤（Thought）」和「行动指令（Action）」，并将行动结果（Observation）反馈回模型，形成迭代闭环，直至得出最终答案。这种模式天然是有环的执行逻辑，也是LangGraph相较于传统DAG工具的本质优势所在。相比早期LangChain的链式（Chain）调用模式，图结构使原本难以追踪的LLM调用链路变得可视化、可调试，更符合复杂Agent的实际运行逻辑。这种「节点+边」的建模方式，也正是Dify等可视化拖拽平台的底层思想来源。

LangGraph的主要能力可以概括为几点：循环与分支（基于图的天然特性）、持久化（节点间状态存档）、人机交互（断点执行）、流式调用处理，以及与LangChain、LangSmith的深度整合。相比低代码拖拽平台，LangGraph通过代码控制能实现更精确的流程管控，在复杂业务场景下更具优势。

学习路径建议

由于LangGraph是独立体系，官方文档也单独维护。建议初学者按照「概念入门 → 安装示例 → 教程案例 → API参考」的顺序推进。官方提供了丰富的案例，包括RAG、Cyclic Agent、Plan-and-Execute等高级模式，深入学习时可按分类查阅，接口与类的细节则在文档的Reference部分查找。

从Hello World理解开发模式

最好的入门方式是跑通一个最小示例。这个Hello World程序模拟了「查询天气」的工具调用：当用户输入包含「上海」时，工具返回模拟的天气信息，让开发者直观理解如何自定义工具并通过LangGraph调用。

环境准备注意事项

有一个关键细节需要注意：如果你已安装LangChain 0.3最新版本，务必将LangGraph同步升级到匹配版本，否则会触发Pydantic v1的告警。

这里有必要解释一下版本冲突的深层原因。Pydantic v2于2023年6月正式发布，底层从纯Python重写为Rust实现的核心引擎（pydantic-core），解析性能提升高达17倍。但代价是API破坏性变更：v1中的validator装饰器被拆分为field_validator和model_validator，__fields__字典被model_fields替代，dict()方法被model_dump()取代。LangChain 0.3全面拥抱v2的同时，仍需兼容大量基于v1开发的社区插件，因此引入了pydantic.v1兼容层。版本不匹配时，混用两套模型类会导致序列化行为不一致，这正是告警的根源——虽然不影响运行结果，但升级后可以避免不必要的干扰。

示例代码需要引入几个核心组件：typing 用于定义节点流转配置、消息传递相关的类、OpenAI大模型库，以及LangGraph的核心类——MemorySaver（存档）、StateGraph（状态图）、MessagesState（消息状态）和 ToolNode（工具节点）。

核心概念：节点、边与路由函数

理解LangGraph，关键在于吃透三个概念：节点、边和路由函数。

节点本质就是函数

在LangGraph中，所有需要执行的任务都必须封装成节点。示例中定义了两个节点：agent 节点负责调用大模型并决定是否触发工具调用，tools 节点则负责执行具体工具逻辑。简单来说，节点就是「一个干活的函数」。

说个细节，工具节点与普通节点的处理方式不同。普通大模型调用可以直接用函数，但工具调用需要用LangGraph专门提供的 ToolNode 类来包装，因为工具通常是列表形式且需要特殊处理。

状态在节点间流转

LangGraph通过 MessagesState 实现节点间的数据共享。可以用一个形象比喻来理解：节点执行就像打游戏通关，每通一关产生一个「存档」，这个存档会传递到下一关。MemorySaver（官方称为Checkpoint，检查点）正是负责这种持久化的组件。

检查点机制的设计思想源自分布式系统领域。其理论基础可追溯至1985年由Chandy和Lamport提出的分布式快照算法。在现代大数据领域，Apache Flink将其发展为「异步屏障快照（Asynchronous Barrier Snapshotting）」算法：周期性地在数据流中插入屏障（Barrier），触发所有算子将当前状态序列化至分布式存储（如HDFS、S3），故障恢复时从最近检查点重放，保证Exactly-Once语义。LangGraph将这一思想引入Agent执行：每次节点执行后，完整的状态快照会被序列化存储，key由thread_id标识。默认实现是内存存储（MemorySaver），生产环境中可替换为langgraph-checkpoint-postgres等持久化后端，以支持水平扩展和服务重启后的状态恢复。这不仅支持多轮对话的上下文延续，还为「人机交互」场景提供了基础：可以在任意节点暂停执行，等待人工审核后再恢复，对于需要人工介入的审批流、内容审核等场景尤为关键。

值得补充的是，MessagesState 本身基于 Reducer 模式设计——这一概念源自函数式编程，在前端领域因 Redux 状态管理库而广为人知。其核心思想是：状态（State）不可直接修改，每个节点返回的是「状态变更描述」，由框架层统一应用变更、生成新状态。LangGraph 中每个消息字段默认使用 add_messages reducer，意味着节点只需返回新增消息，框架会自动将其追加到历史列表，而非覆盖——这既避免了并发写入冲突，也天然保留了完整的对话历史链路，为后续的检查点序列化提供了结构清晰的数据基础。

路由函数决定分支走向

工作流中的关键判断逻辑由「路由函数」承担。在示例中，should_continue 函数从状态中取出最新消息，判断大模型是否需要调用工具：

• 如果大模型返回结果表明需要调用工具，函数返回 tools，流程走向工具节点；
• 如果不需要调用工具，函数返回 end，流程直接结束。

这就是为什么图中会出现虚线——虚线代表条件边（Conditional Edge），由路由函数动态决定走向；实线代表普通边（Edge），是确定性的流转，比如工具执行完后必定返回agent节点。

组装完整的图：四步搭建Agent工作流

理解了核心组件之后，可以按以下步骤搭建完整工作流。

第一步：绑定工具与大模型

工具调用的匹配实际上由大模型完成——大模型返回它认为应该调用的工具名称。OpenAI于2023年6月在GPT-4和GPT-3.5-turbo上正式推出Function Calling功能（2024年初更名为Tool Calling，并扩展支持并行工具调用）。其核心机制是：开发者将工具的名称、描述和参数schema以JSON格式传给模型，模型在推理时会判断是否需要调用某个工具——若触发，则返回包含tool_calls字段的结构化响应，而非纯文本。这一能力依赖模型在RLHF阶段的专项训练，使其学会在「直接回答」和「请求工具」之间做出正确判断。Anthropic的Claude、Google的Gemini随后均推出了类似机制，形成了如今各主流模型API的事实标准。bind_tools 方法正是将这套schema注册到模型请求中，使模型「知道」有哪些工具可用；同时通过 ToolNode 将工具封装成工具节点，负责解析模型返回的结构化调用指令并实际执行。

需要特别关注的是工具描述（description）的质量。模型决定「是否调用工具」以及「调用哪个工具」，完全依赖对工具名称和描述的语义理解，而非任何硬编码规则。这意味着描述写得越精准、越贴近用户可能的表达方式，模型的工具选择准确率就越高。在生产环境中，工具描述的撰写本身已成为一项需要反复测试迭代的提示工程（Prompt Engineering）工作，其重要性不亚于工具本身的实现逻辑。

第二步：创建状态图并添加节点

使用 StateGraph 创建一个支持 MessagesState 的状态图（示例中命名为 workflow）。随后通过 add_node 添加节点，第一个参数是节点名称，第二个参数是对应的处理函数。

第三步：设置入口与连接边

通过 set_entry_point 将 agent 设为起点，表示LangGraph启动后首先调用agent节点。接着连接边：用 add_conditional_edges 添加带路由函数的条件边（agent → tools 或 end），用 add_edge 添加普通边（tools → agent）。

第四步：编译并运行

最后调用 compile 方法编译图，传入 MemorySaver 作为checkpoint。编译会生成一个可运行的对象，其本质遵循LCEL（LangChain Expression Language）规范——这是LangChain从0.1版本起推出的组件互操作标准，深受函数式编程范式影响。

LCEL的设计哲学借鉴了Haskell等函数式语言中「函子组合（Functor Composition）」的思想。其核心是Runnable协议——任何实现了invoke/stream/batch/ainvoke四个方法的对象均可参与组合。|运算符通过Python的__or__魔术方法重载实现，将左侧组件的输出自动作为右侧组件的输入，形成无需显式声明中间变量的管道（Pipeline）。更重要的是，LCEL在编译阶段（而非运行阶段）完成类型推断，并自动为整个管道注入LangSmith追踪、指数退避重试、并发限流等横切关注点。这种「声明式」设计使得编译后的图可以无缝嵌入任何已有的LangChain管道中，也可以作为子图被更大的图调用，体现了组合式架构的设计理念。

调用方式与普通LangChain完全一致：传入message提示词，通过 config 传递 thread_id（即session_id或user_id）。只要传入相同的id，上下文就会生效——先问「上海天气」，再问「我刚问了哪个城市」，Agent能正确回忆起是上海，验证了会话共享的实际效果。

Agent与大模型的本质区别

这里有一个常被混淆的概念需要澄清：大模型本身不等于智能体（Agent）。

「智能体（Agent）」概念最早来自1980年代AI研究者的工作，后由Russell & Norvig在《人工智能：一种现代方法》中系统定义为「能感知环境并采取行动以最大化目标函数的实体」。在大模型时代，Anthropic将其进一步细化：凡是LLM输出能够影响外部世界（如执行代码、调用API、操作文件）并将结果反馈回模型的系统，均可称为Agent。Agent可以调用大模型，而且不止能调用一个——它能编排多个大模型和多种工具协同工作。

从学术定义看，Agent具备「感知-推理-行动」的闭环能力：感知外部输入（用户消息、工具返回值），通过大模型进行推理，再决定下一步行动（调用工具或输出结果）。这个闭环可以反复迭代，直到目标达成。这与传统问答系统的本质区别在于：问答系统是「开环」的（输入→输出），Agent是「闭环」的（输入→推理→行动→观察→再推理）。

多Agent系统（Multi-Agent）则进一步引入了「协作」维度。在实际工程中，单一Agent往往面临上下文窗口长度限制、单点能力瓶颈和任务专注度不足等问题。多Agent架构通过将复杂任务拆解，分配给具备不同专长的子Agent（如「搜索Agent」「代码执行Agent」「结果汇总Agent」）并行或串行处理，再由一个协调Agent（Orchestrator）统筹结果，从而突破单Agent的能力上限。不同专职Agent之间通过消息传递分工协作，LangGraph通过send机制和子图（Subgraph）原生支持这一模式——子图本质上是一个完整的独立StateGraph，可以被父图当作普通节点调用，实现了「Agent即节点」的递归组合，是真正意义上超越单次LLM问答的智能体系统。

这也解释了当下Agent工作流的发展趋势：Dify等开源拖拽式平台，本质上就是把LangGraph这套「节点+边」的思想做了可视化封装。对于增删改查、管理后台等简单业务，拖拽工具足够快捷；面对复杂场景，用LangGraph通过代码进行精确管控则是更合适的选择。

小结

LangGraph通过图结构将Agent逻辑显式化，核心可以归纳为四点：节点即函数、边即流转、路由函数控分支、状态实现记忆。其背后融合了图论、分布式系统检查点机制、函数式编程范式以及ReAct智能体理论等多个领域的精华思想。掌握了这套Hello World的开发模式，再去理解Plan-and-Execute、Cyclic Agent等高级特性，乃至市面上各类可视化工作流工具的底层原理，都会变得清晰许多。

核心要点