LangGraph 这两年几乎成了 Agent 开发绕不开的名字。它的定位很直接用图结构编排 Agent把流程、状态、分支和循环变成一张可运行、可控制的图。相比 LangChain 的链式调用LangGraph 更适合处理真实场景里那些需要反复判断、多次调用工具、多个角色协作的任务。如果你已经写过几个 LangChain 应用却总觉得流程控制不够灵活这篇文章应该能帮你把 LangGraph 的核心思路和使用路径完整过一遍。内容按实际落地顺序组织先讲概念差异再跑最小示例接着拆核心组件然后进入多智能体设计和企业级部署要点最后补一份常见问题排查清单。1. 先讲清楚核心概念LangGraph 为什么不适合再用“链”的思维去理解很多人第一次打开 LangGraph 的官方文档第一反应是“这不就是 LangChain 加了个图吗”。这个理解方向没问题但很容易在写代码时被链式思维带偏。LangGraph 不是帮你把多个 Chain 串起来而是让你把整个 Agent 的执行过程建模成一张图。这张图里有节点、边、状态、循环和条件判断。理解这个转变比记任何 API 都重要。1.1 LangChain 和 LangGraph 的核心区别LangChain 早期的核心抽象是 Chain。一个 Chain 通常是线性的输入经过 Prompt 模板、模型调用、输出解析一步一步往后走。这种设计在处理“固定流程”时很清晰但一旦遇到需要循环、判断、回退、多个分支选择代码就开始绕。要么塞进一个巨大的函数要么反复用条件判断拼装不同 Chain整个流程控制逻辑很快就变得不好维护。LangGraph 换了一个思路把流程本身交给图。每个节点是一个逻辑单元可以是大模型调用、工具执行、业务规则判断也可以是自定义函数。节点之间用边连接边可以分为普通边和条件边。运行时一个状态对象在图中传递每个节点读取状态、执行逻辑、更新状态然后根据条件路由决定下一步走哪条边。这样带来的实际好处是流程是显式的不再是隐藏在代码中的调用关系。分支和循环是图的一部分可以直接看到 Agent 的决策路径。状态统一管理多个节点可以共享同一份数据不需要到处创建中间变量。支持持久化和记忆因为每个节点的输入输出都被框架统一收集。我用一个表格把两者的差异说得更直白对比维度LangChain传统 Chain 方式LangGraph流程结构线性为主分支靠代码控制图结构分支、循环、并行都是图的属性状态管理每个环节单独处理上下文全局 State 对象统一流转循环不天然支持需要自己写 while图允许边回到前置节点天然支持循环条件路由靠 if/else 拼接调用add_conditional_edges 根据状态路由多智能体需要自己设计模块间通信子图和节点天然支持多 Agent 协作可观测性依赖手动打印可以看到完整执行路径和节点耗时你可以把 LangGraph 理解成一个“带状态机能力的流程引擎”只是这个引擎的目标对象是 Agent而不是传统业务流程。它的底层运行原理也不复杂图被编译成可执行对象状态对象按边流动每次运行时从入口节点进入最终走到结束节点。看源码时你会发现核心就是 StateGraph、节点、边、状态迁移这几件事。1.2 LangGraph 的四个核心概念图、节点、边、状态这四个概念是 LangGraph 的基础也是文档里的高频词。我建议在写第一行代码之前先记住它们。第一个是图Graph。图是 Agent 执行流程的载体由节点和边构成。在代码里你创建 StateGraph往里面添加节点和边然后编译得到一个 Graph 对象最后用这个对象执行任务。第二个是节点Node。节点是执行逻辑的单元。一个节点可以是一个函数、一个 Runnable、甚至另一个 graph。每个节点的输入是当前的状态对象输出是状态更新。第三个是边Edge。边定义了执行顺序。普通边表示“执行完 A 后必须执行 B”条件边表示“根据状态决定走 A 还是走 B”。第四个是状态State。状态是最容易被忽略、却最关键的概念。LangGraph 的 State 通常是一个 TypedDict定义了整个流程中需要托管的字段。节点函数读取这些字段、生成新值框架负责把返回值合并进全局状态。为什么状态这么重要因为 Agent 不是一个简单的一锤子买卖。它可能要连续调用多轮工具每轮结果都要保留可能多个节点都要修改同一个字段可能用户消息和中间思考过程需要记录。如果没有一个全局统一的状态节点之间就只能靠函数参数层层传递设计复杂度会瞬间爆炸。这里有一个容易被新手忽略的细节节点函数返回的数据会被合并到全局 State而不是直接覆盖。对于普通字段返回什么就更新什么对于消息列表这类带特殊 Reducer 的字段会按照 Reducer 规则做追加或替换。所以设计状态时一定要想清楚哪些字段是全局共享的哪些字段是某个节点临时使用的哪些字段需要保留历史记录。这个设计做好后面写多智能体协作时就轻松很多。2. 环境准备、安装与第一个最小 Agent概念理解得再多都不如先跑通一个最小示例。LangGraph 的安装非常简单但版本和 Python 环境需要注意避免在无关问题上浪费时间。2.1 环境准备LangGraph 本身是 Python 包和 LangChain 是同一个体系。我的建议是新建一个干净的虚拟环境避免依赖冲突。Python 版本建议 3.10 或 3.113.9 也可以但尽量不要太老。安装命令pip install langgraph langchain-core如果你还需要调用大模型根据自己的模型供应商额外安装。比如用 OpenAI 风格的接口一般是安装 langchain-openai。如果你只是测试状态流转也可以先在节点里写普通函数不真正调用模型。第一次跑 LangGraph我建议先跑一个不调用模型的版本重点看“图是怎么走的”等流程跑通了再加入模型调用。安装完成之后建议确认一下版本python -c import langgraph; print(langgraph.__version__)官方文档的 API 变化比较快不同版本的节点签名、图编译方式可能有细微差异。如果某个写法在你的版本上报错优先去官方文档确认对应版本的 API。原始材料里没有给出明确版本号落地时先确认自己安装的版本再对照文档写代码。2.2 第一个最小 Agent下面这个示例包含两个节点第一个节点模拟一个 Agent 收到用户消息第二个节点模拟 Agent 给出回复。通过这个示例你可以看到图是怎么构建、编译和运行的。from typing import TypedDict, Annotated from langgraph.graph import StateGraph, START, END from langgraph.graph.message import add_messages # 定义全局状态 class AgentState(TypedDict): messages: Annotated[list, add_messages] finished: bool # 节点函数接收用户输入模拟处理逻辑 def agent_node(state: AgentState): print(进入 agent_node) user_msg state[messages][-1].content return { messages: [{role: assistant, content: f收到消息{user_msg}}], finished: True, } # 创建状态图 graph StateGraph(AgentState) # 添加节点 graph.add_node(agent, agent_node) # 添加边入口 - agent - 结束 graph.add_edge(START, agent) graph.add_edge(agent, END) # 编译图 app graph.compile() # 运行 result app.invoke({messages: [{role: user, content: 你好LangGraph}], finished: False}) print(result)运行之后你会在控制台看到节点打印的日志以及最终的返回结果。这个示例虽然很简单但包含了一个关键认知Agent 节点的输出不会直接覆盖整个 State而是作为状态更新合并回去。我一般会建议新手把这段代码当作温度计。它能跑通说明环境没问题它打印的日志能让你看到执行顺序。如果这段代码出问题几乎都是依赖版本或 Python 环境问题先不用去检查业务逻辑。2.3 状态是怎么合并的这个最小示例里有一行代码值得展开return {messages: [...], finished: True}。这里的 messages 字段带有 add_messages Reducer所以返回值会被当作一条新的消息追加到原有列表而不是覆盖整个列表。finished 是普通字段没有 Reducer所以直接用新值覆盖。这个设计在实际开发里非常重要。例如在多轮对话 Agent 中你的状态里可能有一个 messages 列表存储用户和助手的完整对话。每次节点调用都会向列表里追加消息而不是每次都要手动拼接历史。如果连接数据库你还可以把检查点保存下来让 Agent 具备跨会话记忆。这种“部分状态返回全局状态合并”的机制让节点设计变得很灵活。一个节点只需要处理自己关心的字段不需要把所有字段都返回一遍。但反过来也意味着你要想清楚每个字段的合并规则否则会出现多个节点同时修改同一个字段、互相覆盖的问题。注意第一次写状态时先少定义字段。字段越多状态合并的复杂度越高。建议先用 messages 和少量业务字段跑通流程再逐步扩展。3. 核心组件节点、边、条件路由、循环和记忆等最小示例跑通之后就可以进入 LangGraph 最常用的部分了。这一部分不会停留在 API 罗列而是帮你理解每个组件背后解决什么问题以及实际使用时的取舍。3.1 节点不只是函数还可以是子图在 LangGraph 里节点函数接收一个状态参数返回一个状态更新字典。这个函数可以非常简单也可以非常复杂。节点的输入输出都是状态这带来一个很重要的特点节点之间不直接依赖只通过状态进行间接通信。这样的设计让每个节点都可以被单独测试。除了普通函数节点还可以是另一个图。这就是多智能体架构的基础。你把整个子 Agent 编译成一个图然后当作父图的一个节点挂上去。父图决定流程顺序子图内部自己管理节点路由。节点设计时有几个经验可以留一下节点函数要尽量单一。一个节点对应一种能力比如调用工具、生成回复、查数据库。不要把多个职责塞进一个节点否则日志和路由都会变难。节点内部考虑是否幂等。生产环境会有重试机制一个节点可能被执行两次。保证节点在重复执行时不会产生重复数据这在批量任务里特别重要。节点返回值不要带无关字段。返回的字段越少状态冲突的可能性越低。3.2 条件路由让 Agent 自己决定下一步普通边只是顺序执行条件边则是 LangGraph 里最核心的控制能力。它让图在运行时根据状态决定下一步去哪个节点这就构成了 Agent 的“决策”。条件边的 API 是 add_conditional_edges。你在某个节点之后注册一个路由函数路由函数从状态里读取关键信息然后返回下一个要执行的节点名称。看一下这个例子def route_after_tool(state: AgentState): if state.get(need_more_tool): return tool_node return response_node graph.add_conditional_edges(agent_node, route_after_tool, { tool_node: tool_node, response_node: response_node, })这个例子的含义是agent_node 执行完之后不会固定走某一条边而是根据 route_after_tool 函数的返回值决定下一步进入 tool_node 还是 response_node。这是 Agent 能不断循环调用工具的核心机制Agent 判断需要继续调用工具就回到工具节点判断可以回复用户了就走向回复节点。条件路由也很像传统工作流引擎里的决策节点但是 LangGraph 的路由条件可以由大模型判断也可以由业务规则判断甚至两者结合。如果你有稳定的判断规则优先用规则规则不稳定再交给模型判断。3.3 循环与递归限制循环是 LangGraph 和传统 Chain 最大的差异点。在图里你只需要在路由函数中返回一个“上游节点”就能形成循环。比如上面的例子tool_node 执行完之后拉回 agent_nodeAgent 就能反复执行“判断—调用工具—再判断”的循环直到满足结束条件。这个能力让 Agent 真正具备了自主性但也有新的问题死循环。如果路由条件写错节点之间无限跳转任务会一直运行下去。LangGraph 提供了递归限制参数来控制最大执行步数。在编译图或用 invoke 时可以指定result app.invoke(state, config{recursion_limit: 50})recursion_limit 表示图运行过程中节点执行的总次数上限。达到上限后任务会中断并报错。这个参数在生产环境一定要设置而且要设置得比正常任务略高一些。如果任务经常跑到上限说明路由逻辑没收敛不是光调参数能解决的。我见过很多新手在循环出现问题时第一反应是加大 recursion_limit结果只是让错误发生得更晚。正确的做法是检查路由条件有没有可能一直满足“继续”的条件结束条件是否清晰状态里是否记录了循环次数超过 N 轮就强制结束在节点里加一个计数字段比依赖框架默认限制更可控。3.4 记忆与持久化Agent 的记忆问题本质上就是状态持久化问题。LangGraph 通过 Checkpointer 机制实现这一点。开启 Checkpointer 之后图会保存每一步的状态快照你可以在不同会话之间恢复状态也可以从某个中间节点继续运行。常见的 Checkpointer 有内存版和 SQLite 版。内存版适合开发测试生产环境建议接入 SQLite 或 Redis否则进程重启后记忆就丢了。开启持久化的方式很简单from langgraph.checkpoint.memory import MemorySaver memory MemorySaver() app graph.compile(checkpointermemory) config {configurable: {thread_id: session-001}} result app.invoke(state, configconfig)thread_id 是关键。同一个 thread_id 下的多次 invoke 会被视为同一个会话的连续轮次状态会在多次调用之间累积。不同 thread_id 之间状态隔离。你可以把它理解成一个会话 ID。这里要明确一点持久化的粒度取决于你用哪种 Checkpointer。SQLite 会把检查点写入数据库文件Redis 可以支持多实例共享。原始文档里没有给出某种特定存储的详细参数落地时建议先确认你的使用场景。单机场景用 SQLite 通常够用多实例部署时需要选择支持共享存储的方案。4. 多智能体架构从单 Agent 到团队协作LangGraph 之所以能适合企业级 Agent 场景一个重要原因是它天然支持多智能体。多智能体不是简单地把多个模型调用塞在一起而是把不同能力的 Agent 组织成有边界、能协作的系统。4.1 三种常见的多智能体模式根据实际项目可以把多智能体架构归纳为下面几种模式。第一种是协作模式。多个 Agent 各自负责不同能力模块通过共享状态来协作。例如一个 Agent 负责查数据库一个 Agent 负责生成回答它们之间通过状态传递数据。这种模式适合任务边界清晰、协作顺序固定的场景。第二种是 Supervisor 模式也常被叫作“超级督工”。总控 Agent 作为 Router负责把每一步任务分配给合适的子 Agent。子 Agent 各自执行自己的专业任务把结果返回给总控总控再决定是继续执行还是汇总输出。这种模式适合任务类型多样、需要动态决策的场景也是目前多智能体落地最多的一种。第三种是层级模式。Supervisor 下面还有子 Supervisor形成多级分工。适合大型组织或复杂业务流程但实现成本也更高不建议一上手就用。从实际落地角度看我建议优先参考这样一张对比表模式适用场景复杂度协作方式协作模式模块边界清晰流程相对固定低共享状态 固定流程Supervisor 模式任务不确定需要动态路由中总控 Agent 判断并分配任务层级模式任务规模大需要多级分工高多级 Supervisor 组合4.2 Supervisor 模式实战思路在用 LangGraph 实现 Supervisor 时通常会创建三个部分Supervisor 节点、路由函数、子 Agent。Supervisor 节点接收任务描述调用大模型判断应该交给哪个子 Agent。路由函数根据 Supervisor 的输出决定走哪条边。子 Agent 可以是独立的图通过 add_node 挂到父图上。子 Agent 内部有自己独立的状态和节点运行结束后返回结果到共享状态。伪代码思路如下def supervisor_node(state: State): # 用 LLM 判断任务类型 decision llm.invoke(f根据用户请求选择执行 agent: code, sql, general。用户请求: {state[messages][-1]}) return {next_agent: parse_decision(decision)} def router(state: State): return state[next_agent] graph.add_node(supervisor, supervisor_node) graph.add_node(code_agent, code_agent) graph.add_node(sql_agent, sql_agent) graph.add_node(general_agent, general_agent) graph.add_conditional_edges(supervisor, router, { code_agent: code_agent, sql_agent: sql_agent, general_agent: general_agent, })这个设计里Supervisor 和各个子 Agent 通过 state 里的 next_agent 字段通信。子 Agent 执行完后可以回到 Supervisor 节点继续决策也可以走到汇总节点结束。是否需要回到 Supervisor取决于你的流程设计。多智能体系统真正难的不是写图而是定边界。每个子 Agent 负责什么、能调用什么工具、返回什么格式、错误怎么处理都要提前定义。如果边界不清最终会导致状态字段混乱、路由错乱甚至出现几个 Agent 之间互相循环调用。4.3 Send API 与动态并行任务多智能体除了顺序协作还有一个高频需求动态并行。你可能要根据输入列表动态创建多个执行分支每个分支处理一部分数据。这时就会用到 LangGraph 里的 Send API。很多人对 send(node_name, state) 困惑主要是因为拿它和条件边混淆了。条件边是“下一步走谁”send 则是“动态地创建一个新状态送入指定节点执行”。一个典型用法是解析出多个子任务后用 Send 把每个子任务分配到同一个节点并行执行。每调用一次 Send就相当于向图里投递了一个新的执行单元。每个执行单元有自己独立的状态互不干扰。这种机制特别适合并行处理多个文件、多个数据片段、多个子查询。代码层面你需要在节点返回值中构造发送列表。from langgraph.types import Send def generate_tasks(state: State): tasks state[tasks] return [ Send(process_node, {task: t, index: i}) for i, t in enumerate(tasks) ] graph.add_node(generate_tasks, generate_tasks) graph.add_node(process_node, process_node) graph.add_edge(START, generate_tasks) graph.add_edge(generate_tasks, process_node)第一次用 Send 时建议先传入两条任务观察并行执行效果确认输出结果和顺序稳定再扩展到更大规模。4.4 消息共享与全局状态多智能体之间怎么“看到”彼此的结果答案是全局状态。在设计共享状态时我一般会把字段分成几组用户消息区保存用户原始输入和所有历史消息。子任务区保存分解后的任务列表、任务状态、每个任务的输出。控制区保存路由结果、当前节点、循环次数、错误信息。最终结果区保存最终回复和结构化结果。这样分层的核心原因是为了调试。看日志时你只要看控制区就知道 Agent 为什么走到某个分支看子任务区就知道每个子任务有没有完成看最终结果区就知道输出是否符合预期。如果把所有字段混在一起状态会越来越大节点之间互相干扰。注意多智能体的状态字段命名尽量统一避免不同模块用自己的名字存储同一类数据。例如统一用 messages 表示用户消息和助手回复不要一个节点用 messages另一个节点用 history。5. 企业级 Agent 落地时的六个实践细节从能跑通的 Demo 到企业级 Agent中间隔着不少坑。有些坑不是 LangGraph 的问题而是工程化习惯的问题。这一部分总结我在类似项目里使用时的经验。5.1 单条任务先跑稳再开批量很多人拿到框架后第一件事是把一堆数据灌进去批量跑。这是一个很容易出问题的做法。我建议的顺序是先用一条最简输入跑通全流程然后换一条边界输入比如超长文本、空内容、特殊符号最后再开批量。批量任务的复杂度和单任务完全不一样。你要考虑输入列表怎么读进来、输出结果怎么命名、中途失败怎么办、日志怎么对应到具体输入。这些在单任务验证时都不会暴露。所以批量任务前先写一个小型样例集覆盖正常、异常、边界三种情况。5.2 并发数不要一开始就拉满LangGraph 本身支持一定程度的并发但并发高不代表速度快。并发数取决于模型 API 的限流、数据库连接数、机器资源等多个因素。如果一开始就把并发拉到最大很容易触发 API 限流或者内存暴涨。更稳妥的做法是先并发 2 到 4 个任务观察成功率和耗时再逐步增加找到当前环境的稳定阈值。这个阈值不是算出来的是测出来的。5.3 错误处理和重试策略Agent 开发里最不稳定的一环通常是大模型调用。网络超时、返回格式不对、内容触发过滤都可能让一个节点执行失败。生产环境必须考虑错误处理。在节点函数内部可以这样设计def robust_node(state: State): try: result llm.invoke(...) # 校验返回格式 return parse_result(result) except Exception as e: return {error: str(e), retry_count: state.get(retry_count, 0) 1}然后在路由函数里判断是否重试。如果 retry_count 超过 3 次就进入失败兜底节点而不是无限重试。把所有依赖外部调用的节点都做这个保护整体稳定性会高很多。同时要意识到重试必须结合幂等性。如果节点在第一次执行时已经写了数据库重试时又写一遍就会产生重复数据。所以节点里涉及写入操作时最好先检查是否已经处理过这个任务。5.4 日志追踪比功能列表更重要企业级 Agent 调试时最头疼的问题是什么是你不知道 Agent 在执行过程中调用了哪些工具、为什么做出某个决策。没有日志你只能看到一个最终结果中间过程全是黑盒。建议每个节点都输出结构化日志至少包含节点名称、进入时间、关键输入摘要、输出摘要、耗时。这样排查问题时你能按时间线还原整个过程。如果节点调用 LLM可以记录模型名、温度、token 使用量、返回的原始内容。这些信息对回答质量分析特别有帮助。默认打印通常够用日志量大时可以接 JSON 格式方便后续分析。5.5 部署时注意权限、路径和超时把 LangGraph 应用部署到服务器或工厂环境时最容易踩的坑反而是最基础的问题。权限问题最常见。进程读取模型文件、写入输出目录、连接数据库都需要相应权限。如果用 Docker 部署容器里要用非 root 用户运行并给数据目录挂载权限。路径问题也常见尤其是 Windows 和 Linux 路径分隔符差异、中文路径、项目目录结构不同。部署到 Linux 服务器后很多“本地能跑、服务器跑不了”的问题最后查出来都是绝对路径写死导致的。超时问题同样需要注意。LLM 调用如果超过服务器的网关超时时间即使 LangGraph 还在处理前面的请求已经被中断了。所以面向 HTTP 调用时接口超时设置要给足或者改成异步任务模式。5.6 参数边界温度、超时、输出长度Agent 的效果很大程度上取决于模型参数而不是框架参数。我一般按任务类型设置不同参数参数建议值说明temperature0 到 0.3工具调用、代码生成、结构化输出建议低温度max_tokens512 到 2048防止输出过长导致成本失控timeout30 到 120 秒根据模型接口稳定性调整接口慢时适当放大recursion_limit20 到 50结合业务路由轮次设置不是越大越好并发数2 到 8根据 API 限流和下游系统承受能力调整这里给的是通用经验值不是硬性标准。具体参数要以你的模型供应商和业务场景为准。低配置环境里可以把并发数降到接近 1先把流程跑稳再逐步加压。6. 常见问题和排查路径最后集中回答几个比较高频的问题。这些问题在社区里反复出现解决思路基本可以复用。6.1 send(node_name, state) 为什么一直搞不懂核心原因是把它当成了“调用”。实际上Send 不是主动调用一个节点而是向图中投递任务。它返回的是一个 Send 对象里面包含目标节点名和一份独立状态。框架收集所有这些 Send 对象后统一分发给目标节点执行。所以使用 Send 时不需要担心节点之间的返回值怎么传递。每个 Send 自带一份状态互不影响。这也决定了它的适用场景有多个互相独立的子任务需要并行处理。如果你的任务之间依赖关系很强比如第二步必须依赖第一步的结果那 Send 并不合适应该用普通边或条件边。想验证自己是否理解可以写一个三任务的示例主节点把任务列表拆成三个 Send每个 Send 带着自己的 index 和执行参数进入处理节点处理节点打印 index观察它们是否会并行执行。6.2 Skill 与 Agent 的区别LangGraph 怎么增加 Skill很多 Agent 框架里会出现 skill 和 agent 两个词容易混淆。Skill 是能力单元Agent 是决策和执行主体。Agent 可以使用多个 Skill 来完成复杂任务。Skill 类似一个“工具箱里的工具”而 Agent 是“使用工具的人”。LangGraph 里没有强制性的 skill 概念但你可以用节点或者工具函数来组织 Skill。一个节点对应一个 Skill由路由逻辑决定何时启用这是最常见的方式。有人也会问 harness 和 agent 的区别。简单来说harness 更偏执行外壳和工具链的封装agent 偏决策逻辑。LangGraph 里你手工写的路由、工具调用、节点组合本质上就是在做 harness 层的工作。所以讨论它俩的区别时不必过于纠结真正重要的是把执行流程和决策逻辑拆清楚。6.3 LangGraph 能不能替代 Flowable能不能结合 MES 部署在工厂这类问题我建议先分清边界。Flowable 是业务流程管理引擎处理的是审批流、任务流、状态机这些结构化业务流程LangGraph 是 Agent 编排框架处理的是大模型驱动、需要动态决策的工作流。两者不是同一个层级。如果你只是用 LangGraph 来做文档问答、数据分析、辅助生成它完全可以独立承担。如果业务有严格的流程审批、角色权限、事务回滚要求LangGraph 并不擅长。它可以和 Flowable 结合Flowable 负责管理人工审批流程LangGraph 负责其中的智能决策环节比如自动生成审批意见、自动提取表单字段。用 LangGraph 直接替换 Flowable 的想法在生产环境里大概率会让流程治理变得困难。关于在工厂结合 MES制造执行系统使用我也见过类似探讨。LangGraph 可以承担制造场景里的知识问答、工单解析、质量报告生成等偏智能化的任务但如果涉及设备控制、生产指令下发这些实时强一致场景核心逻辑还是应该放在 MES 或工控系统里。LangGraph 更适合做边缘侧的辅助编排而不是替代专业系统的实时控制能力。6.4 一个通用排查顺序如果你在运行过程中遇到问题不管是启动失败、任务卡住还是输出异常建议按照下面的顺序排查看现象是报错、卡住、无输出还是输出不符合预期先明确问题类型。看输入文件路径、消息格式、数据编码、输入字段是否完整。很多问题其实是输入格式不对。看日志有没有打印节点进入顺序卡在哪个节点距离上次日志输出多久了看环境依赖版本、API Key 是否生效、网络是否可达、资源占用是否异常。看参数并发数、recursion_limit、timeout、batch size是否设得过大或过小。最后再怀疑代码逻辑有没有路由条件死循环、状态字段覆盖、节点异常未被捕获。这个顺序看起来简单但能覆盖绝大多数问题。很多人一上来就怀疑模型返回格式不对最后才发现是输入列表里有空值导致节点崩掉。先排查环境再排查参数比反复改 Prompt 更有效。6.5 学习路线建议最后说一条可参考的 LangGraph 学习路线方向性强一些大家可以根据自己情况调整第一阶段先跑通最小示例理解状态、节点、边三个概念不急着写复杂功能。第二阶段把条件路由、循环、记忆三个能力组合起来做一个能持续多轮对话、能调用工具的简单 Agent。第三阶段用 Send 做并行任务理解动态分支和批处理。第四阶段用子图方式做一个标准 Supervisor 多智能体 Demo明确各 Agent 边界和共享状态。第五阶段把项目工程化补日志、重试、参数校验、队列做成可以部署的服务。这五步走完你对 LangGraph 的理解就已经覆盖了从入门到生产的大部分内容。过程中一定要动手改代码只读文档很难真正掌握图的思维方式。多智能体系统架构本身并不复杂复杂的是每个节点的边界、状态设计和错误处理。把这些基本功练扎实复杂项目自然能拆出清晰的结构。