LangGraph 完整指南五分钟跑通你的第一个有状态多智能体工作流【免费下载链接】langgraphBuild resilient agents.项目地址: https://gitcode.com/GitHub_Trending/la/langgraphLangGraph 是一个用于构建长期运行、有状态智能体的底层编排框架它把智能体流程建模为一张状态图让执行过程可持久、可恢复、可在任意节点插入人工审核。Klarna、Replit、Elastic 等公司都在用它交付生产级 AI 应用。如果你写过那种跑一遍就忘、断了就重来的智能体脚本这篇指南就是为你准备的。智能体脚本常见的三个翻车现场写一次就能用是最理想但最罕见的情况。实际做多智能体应用时你大概率会遇到这三类问题流程太长会断一个要跑十几步、调用多个工具和模型的智能体中途任何一步失败整个任务就得从头再来之前的推理成果全部丢弃。没有暂停键你希望在敏感操作比如发消息、扣款前让人看一眼但纯函数式的调用链里没有地方能停下来等人工确认。状态无处安放多轮对话里的上下文、跨会话的用户偏好只能靠自己在代码里传来传去一复杂就乱。这三件事本质上是同一件事长流程需要一份能存下来、能恢复的现场记录。这正是 LangGraph 存在的理由——它把状态管理、执行恢复、人工介入做成了框架级能力而不是让你每个项目自己重造一遍。LangGraph 的回答把流程变成一张带存档的图LangGraph 的核心抽象只有一句话节点负责干活边负责调度每一步执行完自动存档。状态图每个智能体或工作流步骤是一个节点节点之间用边连接决定谁接谁的棒子。条件边还能根据状态里的内容动态选择走向比如有工具调用就走工具节点没有就结束。共享状态所有节点读写同一份状态对象节点执行产生的更新会按规则合并你不用手动在节点间传递数据。逐超步存档框架在每一轮官方术语叫 superstep执行后保存一份检查点。这意味着失败后不是从零重跑而是从最近的检查点继续且已完成的其他节点不会被重复执行。随时暂停执行中可以随时中断并检查、修改状态人工审核通过后再从断点恢复——这就是 human-in-the-loop 的实现基础。这套设计借鉴了 Pregel 的消息传递模型和 Apache Beam 的思路README 中有明确致谢但对外接口更接近 NetworkX 的图表达上手门槛低了不少。三步跑通最小工作流你不需要先读源码装好就能写第一个流程。最短路径是这三步装包终端执行pip install -U langgraph即可核心包已自带预构建组件无需单独安装。定义图和状态用图 API 声明共享状态添加几个节点再用普通边和条件边把它们连起来。整个概念只有状态、节点、边三样东西。选一条启动方式本地快速验证可以直接调用图对象如果想要开发服务器加热重载和可视化界面安装 CLI 包langgraph-cli后运行langgraph dev它会起一个本地 API 服务并自动打开浏览器里的可视化面板。如果你想看完整可运行的参考实现仓库的 examples 目录里按主题分好了examples/ 下有多智能体协作、RAG 问答、人工介入等待、计划-执行等十几类 Notebook 示例每个都能对照学习。想少走弯路的话建议从examples/react-agent-from-scratch.ipynb这类从零构建的示例看起比看黑盒 API 收获大。上图是本地开发时的可视化界面执行路径、节点输入输出和状态变化都能直接看到。对多节点流程来说比翻日志快得多——这也是建议尽早启用langgraph dev的原因。三分钟看懂检查点持久化的关键在 thread_id检查点checkpoint是 LangGraph 持久化的最小单位它是某一时刻整张图状态的一份快照。理解它只需抓住三个概念Checkpoint一次快照包含当时状态的完整内容、时间戳和关联的中间写入。Thread一串检查点的容器用thread_id标识。跑图时必须指定 thread_id这样同一个会话的所有快照归在一起不同用户、不同会话互不干扰——多租户聊天应用就靠这个隔离。Pending writes挂起写入某个超步里如果只有一个节点失败其他节点已完成的写入会被单独存下来。恢复时框架只重跑失败的那个节点不重跑已成功的部分。这是从故障中精确恢复承诺的底层机制。存储层是可插拔的libs/checkpoint/ 定义了统一的 checkpointer 接口put、get_tuple、list 等几个方法仓库内就带了内存版和 SQLite 版实现生产环境要上 Postgres仓库同样提供了独立的 libs/checkpoint-postgres/ 包。你不用关心存储细节选一个包装上、把实例传给图就行。一个容易踩的坑默认反序列化接受检查点数据中的任意 Python 类型官方在新应用中明确要求通过环境变量或参数白名单限制可反序列化的类型。如果你的流程涉及不可信数据源配置这一步比装包本身更重要。四个核心模块各管一摊仓库采用 monorepo 结构libs/下每个子目录是一个可独立发布的包按需安装即可模块职责什么时候需要它libs/langgraph/核心框架图定义、通道channels、Pregel 执行引擎始终需要一切的基础libs/prebuilt/预构建组件ReAct 智能体工厂、工具节点、校验器想快速搭标准工具调用型智能体时libs/checkpoint/检查点与存储接口含内存和 SQLite 实现需要持久化、记忆、人机协同时libs/cli/官方命令行建项目、本地开发服务器、Docker 部署本地开发调试时两个使用建议先用 prebuilt再考虑手搓create_react_agent和ToolNode覆盖了最常见的模型 工具循环场景直接用它验证想法跑通后再决定是否换成手写图。核心包安装时已附带 prebuilt无需单独引入。想理解调度原理就看 channelslibs/langgraph/langgraph/channels/ 里的 LastValue、Topic、Binop 等通道类型定义了状态字段在节点之间如何更新与合并读一遍基本就懂了图执行模型。常见坑与经验跑起来之前先注意这几件事能省掉大量排查时间忘了传 thread_id不指定线程检查点无处安放持久化和中断恢复功能会静默失效。养成每次调用都带thread_id的习惯。循环不收敛智能体反复调用工具是新手最常见的问题。建议在状态里加步数限制框架提供 IsLastStep 这类受管值辅助判断并对 LLM 输出设置重试上限——examples 里的extraction/retries.ipynb演示了重试模式。节点里藏了副作用但没做幂等检查点恢复会重跑失败节点如果节点里有发消息、写库这类操作恢复时可能重复执行设计时要把这类操作放到可重入的位置。版本混装仓库各包独立发版但核心包、CLI、检查点包应保持一致来源。用 uv 管理锁定版本比手装多个 pip 包省心。下一步从哪走建议按这个顺序推进先用langgraph dev跑通 examples 里的一个示例感受图执行和可视化调试再把它改成你自己的最小场景重点体验中断—人工修改状态—恢复这一条链路最后按需引入检查点后端做持久化。多智能体架构不用急着上examples/multi_agent/ 里的分层团队和协作示例等你单智能体流程稳定后再看也不迟。装好包、建个 thread你的第一个有状态工作流今天就能跑起来。【免费下载链接】langgraphBuild resilient agents.项目地址: https://gitcode.com/GitHub_Trending/la/langgraph创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考