LangGraph 快速上手指南：如何构建可恢复、可持久化的有状态智能体

LangGraph 快速上手指南如何构建可恢复、可持久化的有状态智能体【免费下载链接】langgraphBuild resilient agents.项目地址: https://gitcode.com/GitHub_Trending/la/langgraph做 Agent 的人大概率踩过这两个坑模型中途报错整个对话上下文全丢流程跑到一半想让人类插一手改个参数却发现根本没法暂停。LangGraph 就是为了解决这类问题而生的低层编排框架它把智能体拆成一张状态图每一步都能落盘存档、随时断点续跑并原生支持在任意节点暂停等待人工确认。核心功能词就三个——状态图StateGraph、检查点checkpoint、持久执行。最快上手步骤5 分钟跑通第一个状态图本节帮你解决装完包之后第一步该敲什么的问题。不需要接 LLM15 行以内就能看到图在跑。pip install -U langgraphfrom typing import TypedDict from langgraph.graph import StateGraph, START, END from langgraph.checkpoint.memory import InMemorySaver class State(TypedDict): count: int def add_one(state: State) - dict: return {count: state[count] 1} builder StateGraph(State) builder.add_node(add_one, add_one) builder.add_edge(START, add_one) builder.add_edge(add_one, END) graph builder.compile(checkpointerInMemorySaver()) config {configurable: {thread_id: t1}} print(graph.invoke({count: 0}, config)) # {count: 1} print(graph.invoke({count: 0}, config)) # {count: 2} 同一线程状态接着上次第二段invoke的结果是 2 而不是 1——同一个thread_id会加载上次的检查点继续跑。这就是 LangGraph 和一次性脚本的本质区别。如果你要的是开箱即用的对话 Agent直接用预构建模块from langgraph.prebuilt import create_react_agent省掉上面的搭图过程。核心机制拆解状态图、检查点、Pregel 循环本节帮你解决这三个词到底怎么协作的问题只讲最关键的三处不逐文件展开。1. 状态图 StateGraph它是什么你用add_node/add_edge声明节点和流转关系节点读入当前状态、返回一个增量字典框架负责合并。为什么这么设计节点不共享内存、只通过状态交换数据流程天然是可序列化的。你什么时候会碰到它写业务逻辑时全部在这层完成入口在 StateGraph 类定义。2. 检查点 Checkpointer它是什么每个超步super-step结束框架把全部通道值写成快照。为什么这么设计故障恢复和时间回溯都靠它——恢复时从最近快照 未完成的写入重建现场。你什么时候会碰到它只要compile(checkpointer...)后续任何thread_id都能续跑。仓库自带内存版 InMemorySaver另有 SQLite / Postgres 两套实现放在libs/checkpoint-sqlite、libs/checkpoint-postgres。3. Pregel 执行循环它是什么核心调度源码 里的Pregel类把执行切成规划→并行执行→更新三阶段循环直到没有节点可跑。为什么这么设计同一步内节点的写操作互不可见下一才对可见所以并行节点不会读到彼此的半成品。你什么时候会碰到它多节点并发写同一字段、或怀疑执行顺序时先理解这个批量同步模型再定位问题。参数与配置速查最常碰的几个开关本节帮你解决调哪个参数、什么时候才需要动的问题。参数名作用什么时候需要改checkpointer指定状态存档后端默认不传则不持久化需要跨进程恢复、多轮记忆时必须传thread_idconfig 内标识一条独立会话线多用户/多会话场景每个会话一个 idstream_mode控制stream()吐什么values/updates/messages做前端流式 UI 时改成messages只看节点结果用updatesinterrupt_before/interrupt_after在指定节点前/后暂停等待人工输入做 human-in-the-loop 审批、改状态时recursion_limit最大超步数防止死循环循环型图Agent 反复调工具跑超时再调大 划重点最容易配错的两处——thread_id不传时每次运行都是新线程记忆失效十有八九是它InMemorySaver只适合调试进程一退数据全没生产环境务必换成 Postgres 或 SQLite 实现。高频问题排查三个最典型的症状本节帮你解决报错/行为怪异时先查哪里的问题。症状一图跑完没记忆第二次调用状态是空的。原因要么compile()时没传checkpointer要么两次调用用了不同或缺失的thread_id。解法确认graph.get_graph()之外invoke的第二个参数config里带了configurable.thread_id且全程一致。症状二节点写了新值下游读到的还是旧值。原因这往往不是 bug 而是 Pregel 模型的正常行为——同一步并行的节点看不到彼此本步的写入更新要到下一超步才可见。解法如果依赖先 A 后 B的严格顺序把两条并行边改成串行边A → B或把该字段放到独立的节点里。症状三跑到某个节点报错想从错误处继续而不是从头再来。原因没有检查点存档或错误发生在节点函数内部且重试耗尽。解法给易失败节点配retry_policy如{max_attempts: 3}并挂上持久化 checkpointer需要人工介入的用interrupt()预构建模块暂停修好状态后用Command(resume...)续跑。下一步怎么走三条进阶路径本节帮你解决跑通之后往哪深入的问题。读官方示例学模式多智能体、RAG、人在环路的完整笔记本都在 examples 目录建议从examples/react-agent-from-scratch.ipynb开始。换持久化后端看 Postgres 检查点实现理解get_tuple/put/put_writes三件套协议之后实现任意存储都能照抄。摸执行引擎细节顺着 Pregel 主类 读_loop.py与_algo.py搞懂超步是怎么调度和落盘的。把上面的 15 行示例存成脚本跑一遍然后给它换个thread_id再跑两次——看到状态各自独立地累加你就真正入门 LangGraph 了。【免费下载链接】langgraphBuild resilient agents.项目地址: https://gitcode.com/GitHub_Trending/la/langgraph创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考