LangGraph：破解复杂Agent编排难题

AI Agent需要依次完成以下操作：调用模型、检查结果、决定重试还是升级处理以及并行调用多个工具，最后等待人工审批。线性链式结构无法表达这种复杂逻辑，而这也是为什么随着应用规模扩大，团队总会遇到阻碍的根源。

根据2025年Agent工程现状调查，57.3%使用大语言模型构建Agent的组织现已将Agent投入生产，高于前一年的51%。

LangGraph是由LangChain团队构建的底层编排框架，专门为有状态、多步骤AI Agent设计。LangGraph框架让你能够显式控制状态如何在循环图中流动、节点如何基于条件分支，以及执行如何在故障和重启后持久化。

本文主要内容包含：LangGraph 的定义、核心组件的工作机制、相较于其他框架的选型时的差异，以及在生产环境下构建Agent应用时，它与其他框架的具体对比。

什么是LangGraph？

LangGraph 是一个开源框架，专为有状态的 AI Agent提供基于图的编排能力。它用有向图模式替代了原有的线性链，该模式支持循环、条件分支和持久化状态，一定程度上扩展了 LangChain 工具链。

只需把逻辑定义为节点（负责执行具体任务的函数）和边（决定下一步走向的转移规则），然后将Agent图编译为可运行的 LLM 应用。

该框架会将这张图编译成一个状态机，LLM 应用能够在各个步骤之间运行并恢复这个状态机，并不是编译成一个运行完就退出的普通脚本。后续章节将介绍构成图的基本构件，以及 LangGraph 如何在节点间流转执行时追踪状态。

核心概念：图、节点和边

构建应用程序依赖三种基本组件。其中，节点是 Python 或 JavaScript 函数，它接收当前状态，执行相应操作（比如调用 LLM、调用工具、转换数据），然后返回更新后的状态。

边连接节点并定义转换逻辑。固定边始终从节点A路由到节点B。条件边则依据当前状态对函数求值，根据结果将流程路由向不同节点。

这种结构允许循环图，这正是它与有向无环图（DAG）的本质区别。DAG 只能单向流动，而 LangGraph 构建的图可以形成回路，让 LLM Agent能够重试失败的工具调用、重新审视计划，或反复迭代优化输出。

与专攻静态图计算的 NetworkX 不同，LangGraph 的图通过Agent运行时按步骤执行有状态的逻辑。

状态管理与上下文跟踪方式

使用类型化的数据模式来定义状态，通常借助 Python 的 TypedDict。每个节点都会从这个共享状态对象中读取数据，并向其写入更新。随着图的逐步执行，状态会不断累积完整的上下文历史，包括：交换过的消息、发起的工具调用、中间结果以及已做出的决策。

这种集中式设计意味着，Agent当前的上下文始终只有一个可信来源。这也让调试变得十分直观，你可以在执行过程中任意时刻检查状态，从而了解Agent当时的上下文和决策操作。

这种能力在多轮对话或长期运行的工作流中尤为关键，因为你需要图能够从上一次中断的位置精确接续，而非从零开始重建上下文。检查点（Checkpointers）机制会在步骤间持久化状态，这正是实现挂起与恢复（例如等待人工审批或依赖外部系统响应）的基础。

为什么链式方法对复杂Agent不够用

一开始从简单入手，构建的Agent应用可能没什么问题：输入提示词，模型响应，至多先由检索器获取上下文。但一旦Agent需要循环、分支或协调多子任务，线性链模型就会开始力不从心。

线性链式工作流的局限性

当你的Agent需要重试或并行分支时，你很快会碰到这些限制。链式架构按顺序处理步骤，每一步接收前一步的输出并传递自己的输出。

这对于检索增强生成（RAG）管道、聊天机器人提示链和简单LLM应用效果很好。但它无法原生表达基于输出质量重试步骤、分支到并行子任务，或基于中间结果路由到不同逻辑路径等模式。

当开发者试图将这些模式硬塞进链中时，结果是深度嵌套的回调和自定义路由逻辑，变得难以阅读、测试和维护。控制流是隐式的而非显式的。

基于图的编排如何填补空白

基于图的编排控制流是显示可见的。将每一步声明为一个节点，将每次转换声明为边，包括基于运行时状态的分支条件。循环可以让Agent在需要时回到前面的步骤。图本身成为Agent决策过程的可读导航地图。

这就是LangGraph作为一个独立框架存在，而非链式模式扩展的一部分的原因。二者的底层执行模式完全不同：一种是支持循环的图结构，另一种则是线性序列。

LangGraph的关键特性与组件

Agent应用由一小套可组合组件组装而成。理解每一个组件，可很好的控制Agent如何推理、行动和恢复。最常使用的构建块包括：

StateGraph：支持类型化的状态定义
**节点：**执行任务并返回状态更新
**条件边：**根据运行时的实际结果动态路由
**检查点机制：**在多次运行间持久化状态
**中断点：**支持人工介入审查

路由工作流示意图，展示编排器Agent如何通过条件边将任务导向专门节点。

StateGraph 与类型化状态模式

首先需要定义一个 StateGraph 并指定其类型化的状态结构。这个结构是一个 TypedDict，其中声明了Agent需要追踪的所有字段，包括：对话消息、各类工具返回的结果、人工审批标志，以及中间计算产生的临时数据。

然后 StateGraph 会利用此结构来校验每一步的状态流转，确保每个节点都能正确地读取和写入对应字段。

from langgraph.graph import StateGraph
fromtypingimport TypedDict, Annotated

class AgentState(TypedDict):
messages: Annotated[list, "append"]
tool_results:list
needs_review: bool

graph= StateGraph(AgentState)

通过将状态声明为 TypedDict，在工作流的每个节点都能获得运行时验证和IDE自动补全。

节点与条件边

将节点作为命名函数添加到图中。每个节点接收当前的 AgentState 并返回部分状态更新。然后用边连接节点。固定边总是从一个节点转换到下一个节点。条件边评估一个路由函数，并根据结果将执行发送到不同的节点。

def should_continue(state: AgentState) ->str:
last_message= state["messages"][-1]
if last_message.tool_calls:
return "tools"
return "end"

graph.add_conditional_edges("agent", should_continue, {
"tools": "tool_node",
"end": END
})

这种模式让不需自定义回调逻辑即可实现循环、重试和分支。

检查点器与持久化层

Agent可以使用检查点在多次执行之间持久化状态。检查点在每次节点执行后序列化图的状态，并将其存储在后端（可以是内存、SQLite、PostgreSQL或自定义存储）。

如果Agent在执行过程中崩溃，可以直接从上一个检查点恢复，而无需从头重来。这种机制使框架非常适合持久化执行场景，尤其是当长时间运行的 LLM Agent对容错能力有硬性要求时。

人工介入（HITL）支持与中断/恢复

可以在图中设置中断点，执行流程会在该处暂停，等待人工输入。这对于需要审批、审核或手动录入数据后才能继续的工作流来说至关重要。

中断点的状态会被持久化保存，一旦人工给出响应，执行便会从上次中断处继续运行。这种人工介入模式是框架的原生能力，而非临时变通方案。

LangGraph 与链式工作流对比

选择链式方法还是 LangGraph，取决于你的Agent对控制流复杂度的实际需求。两者在组件层面是共通的（如模型接口、工具定义、检索器），但架构和执行模型有着本质区别。

维度	链式方法	LangGraph
执行模型	顺序链	带状态的有循环图
控制流	隐式（回调、嵌套链）	显式（节点、边、条件）
状态处理	可选的记忆模块	内置类型化状态模式
循环与重试	手动实现	通过图循环原生支持
人工审核	有限	原生中断/恢复
持久化	外部附加组件	内置检查点
最佳适用	RAG管道、聊天机器人链	多步骤Agent、复杂工作流

架构对比

两种模式在控制流处理上的差异最为明显。基于链的流水线通过 LCEL 构建，利用管道操作符串联组件，输出直接流入下一步。LangChain 的链模式依次处理，一旦涉及重试或分支，就得自己写变通逻辑来绕过去。

LangGraph 则用 StateGraph 取而代之，节点读写共享状态，流转条件由用户显式控制。

使用链式方法

当你的工作流真正是顺序时，你应该坚持使用链：检索文档、提示模型、解析输出、返回结果。如果每个请求都是独立的，你不需要循环或分支，那么更简单的模型构建更快、维护更容易。直接的聊天机器人管道和单轮检索任务是它的强项。

选择LangGraph

当你的Agent需要循环（重试循环、反思步骤）、条件分支 （基于意图路由到不同工具）、跨轮次的持久化状态 ，或人工审核检查点时，你应该选择LangGraph。如果你需要多Agent工作流，子Agent通过共享状态协调，子图组合使其在单一多Agent系统中成为可能。

LangGraph 使用场景

具体怎么实现，取决于你要解决什么问题。框架本身的灵活性足以覆盖不同领域中的各类Agent架构。LangGraph 文档针对下面每个类别都提供了更多示例和参考范式。典型的搭建路径如下：

定义Agent必须跟踪的类型化状态
添加推理、工具和人工审核的节点
为重试和升级连接条件边
附加检查点，并在发布前运行评估套件

多步骤研究与检索Agent

构建研究型智能体，让它们自主规划查询策略、调用 Tavily 等工具执行多次搜索、评估返回文档的质量，并在初始结果不理想时自动回退并优化查询。

举个例子：研究智能体调用 Tavily 的搜索 API，将结果解析后写入状态，再通过路由逻辑判断，当相关性分数低于设定阈值时，将执行流重新导向搜索节点，发起新一轮查询。

这种"计划→搜索→评估"的循环，正是循环图（cyclical graphs）的用武之地，"评估"节点可以根据质量条件，将流程直接导回"搜索"节点。Tavily 是 LangGraph 社区最常用的搜索集成工具之一，因为它返回的结构化结果能直接与 tool_calls 响应完美对齐。

客户支持与升级工作流

建模一个支持聊天机器人，它分类传入工单，尝试自动解决，并在置信度低时升级到人工Agent。路由条件处理逻辑，中断点让支持代表在将建议响应发送给客户之前审核和批准。

编码助手与迭代反馈循环

构建生成代码、运行测试、分析失败并迭代修复的编码Agent。图的每次循环都优化输出。状态跟踪当前代码、测试结果和错误历史，因此每次迭代都拥有已尝试内容的完整上下文。

带分支逻辑的数据分析管道

创建基于接收数据类型分支的数据分析Agent。数值数据路由到统计分析节点，文本数据路由到NLP节点，混合数据路由到协调节点，该节点扇出到两者。结果合并回单一状态以进行最终综合。

LangGraph 如何扩展

随着业务需求增加，应用也会逐渐复杂，Agent终将面临并发处理、故障容错以及多子Agent协调等挑战。这个框架针对上述每一种需求都提供了相应的基本组件。

开发循环示意图，展示有状态Agent在扩展时遵循的迭代周期：计划、执行、评估、优化。

并行性与并发节点执行

可以设置并行分支（fan-out）模式，让多个节点同时执行。图会等待所有并行分支全部完成后，再将各自的结果合并回共享状态。这种能力对于需要同时查询多个数据源，或一次性发起多个 tool_calls 的Agent来说特别有用。

持久化执行与容错状态

检查点机制让Agent具备持久化执行能力。即便某个节点出错或整个进程崩溃，智能体也能从最近一次检查点恢复，而无需重启整个流程。再配合单节点上的重试逻辑，这套机制足以让智能体在生产环境中保持稳定可靠，即便面对对可用性要求极高的任务也不例外。

多Agent子图组合

可以通过子图节点将多个图组合成一个父图。每个子图拥有独立的状态和逻辑，父图负责协调它们之间的交互。这种模式专为多智能体系统设计，由专业化的智能体分别处理不同领域，再由一个监督者智能体在它们之间进行任务分发。

为Agent添加记忆与持久化

Agent需要记忆来在多轮对话和跨会话之间保持上下文。LangGraph提供两种映射到短期和长期记忆策略的方法。

短期与长期记忆策略

短期记忆存在于图的状态中，在单个会话或线程内持久化。它跟踪当前对话、最近的工具结果和进行中的决策。

长期记忆使用外部存储（数据库、向量存储）在会话之间持久化信息。Agent可能将用户偏好、过去交互摘要或习得事实存储在长期存储中，并在每个新会话开始时检索它们。

策略	范围	存储	典型用途
短期记忆	单个会话或线程	图内状态	当前对话、最近工具调用、进行中的决策
长期记忆	跨会话	外部数据库或向量存储	用户偏好、交互摘要、习得事实

连接外部存储和数据库

可以定义专门的节点来读写外部存储，从而将Agent连接到外部数据库。状态中只保留对外部数据的引用，由这些专用节点负责实际的检索和持久化逻辑。这种设计能让图结构保持干净清晰，因为内存操作本质上与其他节点无异，都被统一视为普通节点。

LangGraph 中的LLM集成

节点可以调用框架通过其模型接口支持的任何LLM提供商。模型只是节点在需要补全时调用的另一个组件。

支持的模型提供商与路由方式

该框架提供了丰富的模型集成，涵盖 OpenAI、Anthropic（Claude）、Google（Gemini），以及通过 Ollama 等推理服务器运行的各类开源模型。你只需用 API Key初始化模型，并将其注入到需要使用该模型的节点即可。

还可以在不同节点中选用不同模型，将简单的对话类请求交给速度快、成本低的模型处理，而把复杂的推理任务交给能力更强的大模型。ChatOpenAI 类是与 OpenAI 模型集成的标准入口，应用最为广泛。

提供商	类	常用模型	典型用途
OpenAI	ChatOpenAI	GPT-4, GPT-4o	推理节点、工具调用Agent
Anthropic	ChatAnthropic	Claude 3.5 Sonnet	长上下文分析、代码生成
Google	ChatGoogleGenerativeAI	Gemini Pro, Gemini Ultra	多模态任务、大上下文窗口
开源	ChatOllama	Llama 3, Mistral	本地开发、隐私敏感工作负载

节点内的工具调用与函数绑定

通过 bind_tools，可以将工具绑定到 LLM，告知模型当前可用的函数及其调用方式。当模型决定调用某个工具时，它会返回一个结构化的 tool_calls 响应。

随后，ToolNode 会执行所请求的函数，将执行结果写入状态，并将执行流导回模型节点，进入下一轮推理。

fromlangchain_openaiimport ChatOpenAI
from langgraph.prebuilt import ToolNode
from langchain_community.tools.tavily_search import TavilySearchResults

tavily_tool= TavilySearchResults(max_results=3)
tools= [tavily_tool]

llm= ChatOpenAI(model="gpt-4o").bind_tools(tools)
tool_node= ToolNode(tools)

大多数 LangGraph Agent正是借助这种模式来实现 ReAct（推理 + 行动）循环。ChatOpenAI 模型先进行推理，决定下一步该做什么，然后在响应中返回 tool_calls，ToolNode 接着执行所请求的函数（例如调用 Tavily 搜索）。

执行结果会回流到状态中，供下一轮推理使用。每一次 tool_calls 响应都会被记录，形成一条完整的工具调用审计链，方便后续追溯。

监控、调试和评估你的Agent

LLM Agent可能会调用错误工具、循环时间超出预期，或产生错误输出。追踪和评估工具让你能够快速诊断这些问题。

多步骤Agent运行的追踪跨度层级，展示模型调用、工具调用和状态转换之间的父子关系。

LangSmith 追踪与运行检查

可以使用LangSmith追踪Agent执行的每一步，它为LangGraph应用提供可观测性。每个节点执行、模型调用和工具调用都被记录为带有输入、输出、延迟和Token计数的跨度。

可以检查完整运行，查看图走了哪条路径、每一步状态的样子、以及错误发生在哪里。设置两个环境变量即可启用所有运行的自动追踪和流式传输。

LangGraph Studio：工作流开发的可视化界面

可以使用LangGraph Studio，一个桌面应用，可视化图的结构、交互式逐步执行、以及无需阅读原始日志即可调试问题。

可以看到哪些节点触发了、路由条件评估为什么、以及状态如何随时间演变。在迭代图结构和路由逻辑时，它在开发期间特别有用。

评估模式与Agent行为回归测试

像测试任何非确定性系统一样测试Agent：使用评估数据集和评分函数。定义一组输入场景，让它们通过Agent图运行，并根据正确性、完整性和工具使用准确性等标准评分输出。

在每次代码更改时运行这些评估，在它们到达生产环境之前捕获回归。LangSmith集成评估工作流，但你也可以使用现有测试基础设施构建自定义评估管道。

LangGraph 的更广泛工具生态与未来发展

对 LangGraph 的投入，不仅能获得核心框架的能力，还能接入其周边不断壮大的工具生态和多样化部署方案。

LangGraph Cloud 与部署选项

可以使用LangGraph Cloud将Agent部署到生产环境，它为将它们作为API端点运行提供托管基础设施。它处理扩展、持久化和流式传输，无需你管理服务器。

可以使用LangServe自托管应用，它将编译后的图包装在FastAPI服务器中。对于已经在云基础设施上的团队，这种部署灵活性意味着你可以从托管开始并迁移到自托管（或反之），而无需重写Agent逻辑。

新兴模式：反思循环、计划-执行与Agentic RAG

实际上，我们会发现几种LLM应用模式正在生产中成为标准。反思循环 让Agent评估自己的输出并迭代，直到满足质量标准。计划-执行将计划（生成任务列表）与执行（运行每个任务）分离，计划器能够基于中间结果修订计划。

Agentic RAG将检索增强生成包装在Agent循环中，该循环可以重新表述查询、评估检索文档的相关性，并决定是再次搜索还是综合答案。这些模式都依赖于该框架的核心优势：在有状态图中表达循环和条件转换的能力。

总结

LangGraph 提供了构建 LLM Agent所需的图原语，让Agent能够循环、分支、持久化状态，并在多个子Agent之间进行协调。