LangGraph 上手指南：5 步从零跑通有状态 Agent 框架

LangGraph 上手指南5 步从零跑通有状态 Agent 框架【免费下载链接】langgraphBuild resilient agents.项目地址: https://gitcode.com/GitHub_Trending/la/langgraphLangGraph 是 LangChain 团队开源的低层编排框架用于构建可持久化、可中断恢复、支持人工介入的有状态智能体。本文面向刚接触 Agent 开发的 Python 工程师带你跑通最小示例并讲清状态、检查点、流式输出等核心概念。 先说清楚它解决什么问题LangGraph 的定位是低层编排当你需要的不只是一个会调用工具的聊天机器人而是一个能记住上下文、中途暂停等人工确认、失败后从断点继续跑的任务系统时它的价值才体现出来。典型场景有三类多步骤数据处理流水线中某一环节需要人工审批客服类 Agent 需要跨会话记住用户偏好长任务执行到一半进程重启希望从上次保存的状态继续而不是从头再来。README 中给出的官方定义也很直接它是构建、管理、部署长时间运行的有状态 Agent的基础设施提供持久执行、流式输出、人工介入、记忆等能力且可以脱离 LangChain 单独使用。仓库本身也是按职责拆成多个子包的核心引擎在 libs/langgraph/各类检查点存储在 libs/checkpoint/部署用的命令行工具在 libs/cli/预制 Agent 组件在 libs/prebuilt/。值得注意的是examples/ 目录中的示例已整体迁移到 LangChain 官方文档站仓库里仅保留存档本地调试时请以 PyPI 安装版为准。▶ 实操阅读源码前可先克隆仓库git clone https://gitcode.com/GitHub_Trending/la/langgraph最小上手路径4 步跑通第一个有状态图这一步的目标不是造 Agent而是先让状态在两次调用之间被记住这个核心行为跑起来。整个过程只依赖langgraph和langgraph-checkpoint两个包后者是前者的默认依赖。第 1 步安装。项目要求 Python 3.10 及以上uv add langgraph # 或 pip install langgraph第 2 步写一个最小图。下面这段取自InMemorySaver的官方文档示例它用整数作为状态节点把值加一两次调用同一thread_id可以观察状态累加from langgraph.checkpoint.memory import InMemorySaver from langgraph.graph import StateGraph builder StateGraph(int) builder.add_node(add_one, lambda x: x 1) builder.set_entry_point(add_one) builder.set_finish_point(add_one) graph builder.compile(checkpointerInMemorySaver()) print(graph.invoke(1, {configurable: {thread_id: t1}})) # 2第 3 步理解调用约定。invoke的第二个参数是RunnableConfig其中configurable.thread_id标识一条会话线程。同一个thread_id再次invoke时图会先从检查点加载上次保存的状态再执行节点。第 4 步升级到真实对话场景langgraph.prebuilt提供了一整套现成件create_react_agent可以直接绑定模型和工具from langgraph.prebuilt import create_react_agent from langgraph.checkpoint.memory import InMemorySaver agent create_react_agent(model, tools, checkpointerInMemorySaver()) cfg {configurable: {thread_id: conv-001}} agent.invoke({messages: [{role: user, content: 你好}]}, cfg) agent.invoke({messages: [{role: user, content: 我刚才说了什么}]}, cfg)到这里多轮记忆已经生效。核心机制速览5 个概念一张表对照LangGraph 的概念不多但每个都对应一类实际问题先建立整体印象再查文档效率最高概念在仓库中的位置一句话解释状态Statelibs/langgraph/langgraph/graph/state.py用 Pydantic 模型或 TypedDict 定义的共享数据节点之间通过它传递信息节点与边libs/langgraph/langgraph/graph/_node.py节点是任意可调用对象边分固定边和条件边决定执行走向通道Channellibs/langgraph/langgraph/channels/状态字段的底层存储单元决定新值如何并入旧值如last_value.py覆盖、binop.py按运算符合并检查点Checkpointlibs/checkpoint/每个执行步骤结束时的状态快照按thread_id组织是实现记忆、回放、人工介入的基础流式输出stream_modelibs/langgraph/langgraph/pregel/main.pyvalues输出整份状态、updates只输出各节点增量、debug给出逐步调度细节可以把它类比成一套带存档系统的游戏流程thread_id是存档槽位检查点是自动存档点节点是关卡。读存档、进关卡、存新档三件事循环往复就是整个执行引擎的工作方式。两个容易忽略的细节状态字段若希望追加而不是覆盖需要用 reducer 约定如add_messagesInMemorySaver官方文档明确标注仅用于调试与测试生产环境应换成 libs/checkpoint/ 下的 SQLite 或 Postgres 实现。常见问题排查4 类高频故障的定位思路报错 GraphRecursionError 如何解除现象图跑到一半抛出Recursion limit of 25 reached。可能原因默认recursion_limit是 25 步条件边写死循环或 Agent 反复调用工具时会快速耗尽。定位方法用stream_modeupdates跑一遍看最后卡在哪个节点反复出现。解法调大上限例如graph.invoke(input, {recursion_limit: 100})但先确认不是业务逻辑死循环。同一 thread_id 的状态为什么串了现象换了话题模型却记得上一段对话的内容。可能原因不是 Bug是同一thread_id的检查点被自动加载这正是记忆功能的来源。定位方法调用graph.get_state(config)查看当前线程已保存的状态内容。解法新场景换新thread_id确实要清档时InMemorySaver提供delete_thread(thread_id)。状态更新没有生效怎么查现象节点逻辑改对了但下一节点读到的还是旧值。可能原因节点返回值不是状态更新字典比如返回了None或者更新的字段名与状态 Schema 不一致。定位方法stream_modeupdates会按节点列出每次写入了什么缺失的节点直接暴露。解法确保节点返回{字段名: 新值}的字典字段名以状态类定义为准。interrupt 之后图不恢复现象代码里用了interrupt()但恢复执行时行为像全新启动。可能原因interrupt依赖检查点保存暂停位置没有传checkpointer就无法恢复。定位方法检查compile(checkpointer...)是否传参以及两次调用是否复用同一个thread_id。解法两者同时满足后用graph.invoke(Command(resume...), config)继续执行详见 libs/langgraph/langgraph/types.py 中Interrupt的定义。进阶方向跑通之后的 3 条路线换持久化存储把InMemorySaver换成libs/checkpoint/下的SqliteSaver或PostgresSaver重启进程后线程状态不丢这是上线前必做的一步。接入人工介入与回放研究interrupt_before/interrupt_after参数配合get_state_history(config)遍历历史检查点实现改状态、回到某一步重跑的时间旅行调试。学会部署阅读 libs/cli/ 中的命令行工具配合项目根目录的langgraph.json配置文件可以在本地启动 LangGraph Server 并通过 Studio 界面可视化查看图的执行过程。状态、检查点、流式输出这三块概念一旦吃透LangGraph 里大部分 API 都能自己推导出来。建议把本文的最小示例改成你自己的第一个真实场景遇到问题时先查tests/目录下的测试用例——它们是最贴近正确用法的一份活文档。【免费下载链接】langgraphBuild resilient agents.项目地址: https://gitcode.com/GitHub_Trending/la/langgraph创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考