1. 项目概述如果你正在寻找一个能帮你从零开始真正搞懂 LangGraph 1.0 并动手构建智能体的实战教程那么你找对地方了。LangGraph 作为 LangChain 生态中负责工作流编排和状态管理的核心框架在 2025 年 10 月发布 1.0 稳定版后已经成为构建复杂、可靠智能体应用的事实标准。但官方文档往往侧重于 API 参考而社区中的许多教程又停留在 0.x 版本这让很多开发者尤其是刚接触智能体开发的同行感到无从下手。这个名为 “Dive into LangGraph” 的开源项目正是为了解决这个问题而生。它是一本结构清晰、内容详实、完全基于 LangGraph 1.0 的实战指南旨在帮助开发者无论是刚入门的新手还是希望体系化进阶的资深工程师快速掌握构建生产级智能体所需的核心技能。这个项目最吸引我的地方在于它的“完整性”和“实战性”。它没有停留在简单的概念介绍而是将 LangGraph 与 LangChain 的核心功能拆解成 14 个循序渐进的章节从创建一个最简单的 ReAct 智能体开始逐步深入到状态图、中间件、记忆系统、人机交互、MCP 集成、监督者模式、并行处理、RAG 乃至最终打包成 Gradio 应用。每一个章节都是一个独立的 Jupyter Notebook你可以边学边跑亲眼看到代码如何工作状态如何流转。更值得一提的是它现在已经进化成了一个 “Agent Skill”这意味着你可以直接将它安装到 Claude Code 这类 AI 编程助手中让它来辅助你写出更地道的 LangGraph 代码这简直是把“学习”和“实践”无缝衔接了起来。接下来我将带你深入拆解这个项目的设计思路、核心内容以及如何最高效地利用它来提升你的智能体开发能力。1.1 核心价值与目标读者这个教程的核心价值在于它提供了一个“最小可行知识体系”。智能体开发涉及面广从提示工程、工具调用到工作流编排、状态持久化知识点非常分散。该项目作者敏锐地抓住了 LangGraph 1.0 稳定发布这个时间窗口将两个核心库LangChain 和 LangGraph中最常用、最关键的功能提炼出来形成了一条平滑的学习路径。它避免了让你在浩瀚的官方文档中迷失直接指向了构建一个可用、可扩展智能体所必须掌握的技能。它主要适合以下几类开发者智能体开发新手如果你对 LLM 应用开发有基本了解但不知道如何将想法组织成可维护、有状态的工作流这个教程是你的绝佳起点。它会手把手教你搭建第一个智能体。从 LangGraph 旧版本迁移的开发者1.0 版本在接口和设计理念上相比 0.x 有显著优化。本教程承诺“不含任何 v0.6 的历史残留”是进行版本迁移和知识更新的可靠参考。寻求最佳实践的进阶开发者即使你已经用过 LangGraph教程中关于中间件预算控制、敏感信息过滤、记忆系统短期/长期记忆、上下文管理State, Store, Runtime以及监督者模式的深入讲解也能帮你优化现有项目结构提升应用的健壮性和可观测性。希望将智能体产品化的工程师最后的 Gradio 应用实战章节展示了如何将一个 LangGraph 工作流封装成带有流式响应的 Web 应用这对于构建演示原型或最终产品至关重要。项目的目标非常明确让你不仅能“看懂” LangGraph更能“用好” LangGraph最终具备独立设计和实现复杂智能体工作流的能力。2. 教程内容深度解析与学习路径“Dive into LangGraph” 的目录结构设计体现了作者对学习曲线的深刻理解。它不是简单的功能罗列而是遵循了“由浅入深、从核心到外围”的认知规律。我们可以将 14 个章节划分为四个主要阶段这构成了一个高效的学习路径。2.1 第一阶段核心概念与基础构建第1-3章这一阶段的目标是建立对 LangGraph 最核心抽象——状态图StateGraph——的直观理解并跑通第一个智能体。第1章快速入门这一章通常会带你创建一个经典的ReActReasoning Acting智能体。ReAct 模式是智能体基础的推理-行动循环。在这里你会首次接触到如何定义工具Tool、如何构建提示模板PromptTemplate、如何创建执行器Graph。关键是理解State的定义它通常是一个 Pydantic 模型包含了智能体运行过程中所有需要传递和修改的数据比如对话历史、中间思考过程、工具调用结果等。通过这一章你能立刻获得一个能运行、能调用简单工具比如计算器、搜索引擎的智能体建立初步的信心。第2章状态图这是 LangGraph 的灵魂。本章会深入讲解StateGraph的构建。你会学习如何定义节点Node——即工作流中的具体步骤函数以及边Edge——决定工作流走向的条件逻辑。重点是理解“状态”如何在节点间流动和更新。例如一个节点处理用户问题下一个节点决定调用哪个工具再下一个节点解析工具返回结果。你会接触到add_node,add_edge,add_conditional_edges等核心方法并理解如何通过compile()方法将图编译成可执行的对象。第3章中间件在掌握了基础工作流后本章引入中间件Middleware的概念这是实现生产级应用的关键。中间件允许你在工作流执行的生命周期如节点执行前、后或整个流程开始、结束时注入自定义逻辑。教程实战了四个非常实用的功能预算控制限制智能体单次对话的最大 Token 消耗或 API 调用次数防止成本失控。消息截断当对话历史过长时自动截断或总结确保不超出模型上下文窗口。敏感词过滤在输入或输出层过滤不当内容满足合规要求。PII个人身份信息检测自动检测并脱敏用户输入中的电话号码、邮箱等信息保护隐私。注意中间件的学习是区分“玩具项目”和“严肃项目”的重要一步。在早期就养成使用中间件处理通用横切关注点如日志、监控、鉴权的习惯能让你的代码更清晰、更健壮。2.2 第二阶段高级功能与状态管理第4-8章在打好基础后这一阶段开始探索如何让智能体更智能、更可控、更易集成。第4章人机交互智能体不是全自动的有时需要人类介入做出关键决策。本章介绍如何使用内置的HITLHuman-In-The-Loop中间件。例如当智能体试图执行一个高风险操作如发送邮件、修改数据库时工作流可以暂停并通过一个预设的通道如 Slack、钉钉机器人或简单的 CLI 输入向人类操作员发送审批请求待批准后再继续执行。这为智能体在关键业务场景中的应用提供了安全阀。第5章记忆没有记忆的智能体每次对话都是全新的开始。本章深入讲解 LangGraph 如何管理短期记忆和长期记忆。短期记忆通常指单次对话轮次中的上下文由State对象管理。长期记忆涉及持久化存储教程会介绍如何使用langgraph-checkpoint系列库如 SQLite, Redis来保存和加载对话状态。这使得智能体能在多次会话中记住用户偏好、历史任务上下文实现真正的持续性对话。第6章上下文工程这是对状态管理的进阶探讨。除了基础的StateLangGraph 还提供了Store用于存储全局、共享的只读数据和Runtime上下文提供执行环境信息。合理使用这三者可以优雅地管理配置、工具集、数据库连接等资源避免在State中传递一切导致的臃肿和混乱。第7章MCP ServerMCPModel Context Protocol是 LangChain 生态中一个重要的开放协议用于标准化工具、知识库等资源的接入。本章教你如何创建一个自定义的 MCP Server例如一个连接公司内部知识库的服务器并将其无缝接入 LangGraph 智能体。这极大地扩展了智能体的能力边界使其能够安全、规范地使用任何通过 MCP 暴露的资源。第8章监督者模式当任务复杂时单一智能体可能力不从心。监督者模式采用“管理者-工作者”的架构。本章介绍两种实现方式基于 Tool Calling 的监督者一个主智能体监督者将子任务分解并通过调用“工具”的方式将任务分配给专门化的子智能体工作者去执行。使用langgraph-supervisor库这是更官方、更强大的方式。它提供了专门的Supervisor节点类型可以更方便地管理多个子工作流Sub-graph的创建、执行和结果汇总非常适合实现复杂的多智能体协作系统。2.3 第三阶段性能优化与核心应用第9-11章这一阶段关注如何提升智能体的性能和解决两类核心应用场景知识问答和实时信息获取。第9章并行为了提高效率需要让智能体并行工作。本章讲解四种并发模式节点并发在定义图时让多个无依赖关系的节点同时执行。task装饰器将一个普通的 Python 函数标记为可异步执行的任务。Map-reduce经典的大任务分解模式。将一个大型查询映射Map到多个并行处理的子任务上然后将所有子结果归约Reduce成一个最终答案。子图将复杂的图分解成多个可复用的子图子图内部可以有自己的并发逻辑主图通过调用子图来组织更宏观的并行流程。第10章RAG检索增强生成是当前 LLM 应用的核心范式。本章不满足于一种方法而是展示了三种检索策略的实现向量检索最主流的方式使用嵌入模型将文档和查询转换为向量通过相似度计算找到最相关的片段。会涉及文档加载、切分、向量化存储如使用 Chroma, Pinecone和查询的全流程。关键词检索传统但快速有效的方法例如使用 TF-IDF 或 BM25 算法。在文档结构清晰或需要精确匹配时非常有用。混合检索结合向量检索和关键词检索的优点先通过关键词快速筛选出一个候选集再用向量检索进行精排在精度和速度间取得平衡。第11章网络搜索让智能体“联网”获取最新信息。本章介绍了集成三个搜索工具的方法DashScope阿里云的通义千问模型服务平台提供的搜索能力。Tavily一个专为 AI 优化的搜索 API返回的结果已经过针对 LLM 的优化和总结。DDGSDuckDuckGo 搜索的 Python 库提供免费、匿名的搜索服务。 每种方式都会讲解如何将其封装成 LangChain Tool并集成到 LangGraph 工作流中让智能体能够回答关于实时事件的问题。2.4 第四阶段应用落地与生态拓展第12-14章最后阶段着眼于如何将所学投入实际应用并了解更前沿的生态。第12章Deep Agents这是一个对 LangChain 旗下更高级框架Deep Agents的简要介绍。Deep Agents 在 LangGraph 基础上进一步抽象旨在让智能体具备更复杂的规划、反思和从失败中学习的能力。本章为你打开一扇窗指明更深入的学习方向。第13章Gradio APP这是从代码到产品的关键一步。本章完整演示了如何将一个训练好的 LangGraph 智能体工作流封装成一个带有 Web 界面的、支持流式输出打字机效果的应用程序。你会学习到如何使用 Gradio 的ChatInterface如何将 LangGraph 的流式响应适配到 Gradio 的事件循环中。这个实战章节提供的代码可以直接运行和二次开发是你构建演示原型或轻量级产品的绝佳模板。第14章附录调试页面工欲善其事必先利其器。langgraph-cli提供的开发服务器和调试页面是一个强大的可视化工具。本章教你如何使用langgraph dev命令启动本地调试环境。在这个页面里你可以清晰地看到工作流的执行图谱、每一步的状态变化、输入输出甚至可以直接编辑状态并重新执行某个节点这对于开发和排查复杂工作流中的问题至关重要。3. 从学习到实践如何高效使用本教程拥有了一份优秀的地图还需要正确的行走方法。下面我结合自己的学习经验分享如何最高效地利用这个项目并将其转化为你自己的开发能力。3.1 环境准备与工具链搭建教程的requirements.txt文件已经列出了所有依赖。我建议的实践环境如下Python 环境使用 Python 3.10 或以上版本。强烈推荐使用Conda或venv创建独立的虚拟环境避免包冲突。# 使用 conda conda create -n langgraph-tutorial python3.10 conda activate langgraph-tutorial # 或使用 venv python -m venv venv # Windows: .\venv\Scripts\activate # Linux/Mac: source venv/bin/activate安装依赖克隆项目后直接安装。git clone https://github.com/luochang212/dive-into-langgraph.git cd dive-into-langgraph pip install -r requirements.txt实操心得如果安装缓慢或遇到网络问题可以临时使用国内镜像源如pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple。另外langchain[openai]这个 extras 声明会安装 OpenAI 相关的依赖如果你计划使用其他模型如通义千问、智谱GLM可以先安装基础版langchain-core,langchain再单独安装对应的社区集成包。开发工具Jupyter Lab / VS Code教程本身是.ipynb文件用 Jupyter Lab 打开学习是最直观的。VS Code 配合 Jupyter 插件也有很好的体验方便做笔记和调试。LangGraph CLI确保langgraph-cli安装成功后续的调试页面依赖它。API 密钥准备你需要的 API 密钥如 OpenAI, DashScope, Tavily并在项目根目录创建.env文件进行配置例如OPENAI_API_KEYsk-... DASHSCOPE_API_KEYsk-... TAVILY_API_KEYtvly-...3.2 学习方法论动手、修改、调试不要仅仅阅读代码一定要动手运行。顺序推进逐章运行严格按照 1 到 14 章的顺序学习。每一章都是一个完整的、可运行的例子。确保你理解了前一章的核心概念尤其是State和StateGraph再进入下一章。修改参数观察变化在成功运行示例后尝试修改代码。例如修改State模型增加或减少一个字段看看图如何运行。在中间件章节调整预算控制的阈值触发限制看看效果。在 RAG 章节换用自己的文档体验不同的检索效果。在 Gradio 章节修改 UI 布局或添加新的功能按钮。善用调试页面从第 2 章开始就可以在代码中启动调试页面。在关键节点设置检查点然后在浏览器中打开http://localhost:2024可视化地跟踪状态流转。这是理解复杂工作流不可替代的工具。结合 Agent Skill 学习这是本教程的一大特色。按照说明使用npx skills add ...命令将这个教程安装为 Claude Code 的 Skill。之后当你在编写 LangGraph 相关代码时可以直接向 Claude Code 提问比如“如何为我的智能体添加一个记忆功能”或“这个中间件怎么写”它会参考本教程的内容给出更精准、更地道的代码建议实现“学以致用用以促学”的闭环。3.3 构建你自己的第一个项目在完成前 6 章的学习后你就可以尝试脱离教程构建一个自己的小项目了。我建议从一个具体的、有明确目标的场景开始项目构思一个“旅行规划助手”智能体。定义 State包含destination目的地、dates日期、interests兴趣列表、conversation_history对话历史、research_results网络搜索的结果、itinerary最终生成的行程草案。设计工作流节点1信息收集与用户对话澄清目的地、日期、兴趣偏好。条件边如果信息不完整循环回节点1如果完整进入节点2。节点2网络研究调用 Tavily 或 DDGS 工具搜索目的地的景点、美食、天气、注意事项。节点3行程生成将收集到的信息和研究结果发送给 LLM生成一份初步的每日行程安排。节点4人机确认可选使用 HITL将生成的行程发送给用户确认或修改。节点5最终输出格式化输出最终行程。添加增强功能中间件为节点2网络搜索添加预算控制防止搜索过于昂贵。记忆使用 SQLite Checkpoint让用户下次可以接着说“帮我修改一下上次的行程”。RAG进阶如果你有自己的旅行攻略文档库可以增加一个 RAG 节点在生成行程前先检索内部知识。通过这样一个完整的项目实践你会把分散的知识点串联起来深刻理解 LangGraph 各个模块是如何协同工作的。4. 常见问题与避坑指南实录在实际学习和开发中你肯定会遇到各种问题。下面我整理了一些常见坑点及其解决方案这些在官方文档里不一定找得到。4.1 状态State设计不当这是新手最容易出错的地方。问题State模型设计得过于庞大或混乱所有数据都往里塞导致节点函数参数冗长且难以维护。解决方案遵循“最小化”和“结构化”原则。只将需要在节点间流动和改变的数据放入State。对于全局配置、工具实例、数据库连接等使用Store或通过图的构造参数传入。使用嵌套的 Pydantic 模型来组织复杂状态。例如可以将所有和用户相关的字段放在一个UserContext子模型里所有和任务相关的放在TaskContext里。from pydantic import BaseModel, Field from typing import List, Optional class UserContext(BaseModel): user_id: str preferences: dict Field(default_factorydict) class TaskContext(BaseModel): query: str research_materials: List[str] Field(default_factorylist) answer: Optional[str] None class AgentState(BaseModel): user: UserContext task: TaskContext conversation: List[dict] Field(default_factorylist) # 在节点中可以清晰地访问 state.user.user_id 或 state.task.query4.2 图编译与执行错误问题在调用graph.compile()或graph.invoke()时出现ValidationError或键错误。排查思路检查 State 模型默认值确保State中所有字段都有合理的默认值使用Field(default_factory...)或标记为Optional。因为工作流初始调用时传入的是一个空字典Pydantic 会用它来初始化State对象。检查节点函数的输入输出每个节点函数接收的第一个参数是当前的State对象它必须返回一个字典用于更新update状态而不是替换状态。常见的错误是返回了整个新的 State 对象。# 正确返回要更新的字段字典 def research_node(state: AgentState): result do_search(state.task.query) return {task: {research_materials: result}} # 更新嵌套字段 # 错误返回了新的State实例或错误的键 def research_node_wrong(state: AgentState): result do_search(state.task.query) state.task.research_materials result return state # 错误应该返回字典。 # 或者 return {research_materials: result} # 错误键与State结构不匹配。使用调试页面在langgraph dev模式下错误信息通常会更有帮助并且你可以看到执行到哪一步失败了。4.3 流式输出与 Gradio 集成问题问题在 Gradio 应用中无法正常显示 LangGraph 的流式输出即一个字一个字出现的效果。解决方案关键在于正确处理 LangGraph 的异步迭代器。LangGraph 的graph.astream()或graph.astream_events()返回的是异步生成器。import gradio as gr from langgraph.graph import StateGraph async def predict(message, history): # history 是 Gradio 的格式需要转换成你的 State 格式 inputs {conversation: history, query: message} full_response async for event in graph.astream(inputs, stream_modevalues): # 假设我们只关心名为“final_node”的输出 if final_node in event and answer in event[final_node]: token event[final_node][answer] full_response token yield full_response # 这是实现流式的关键持续 yield 部分结果注意确保你的 GradioChatInterface的fn是一个异步函数并且使用了yield。同时检查 LangGraph 图中对应最终输出的节点其返回的字典是否包含了逐步生成的 token。4.4 记忆Checkpoint不生效问题配置了 SQLite 或 Redis Checkpoint但智能体似乎并没有记住上次的对话。排查步骤线程/进程标识Checkpoint 通过configurable参数中的thread_id来区分不同的对话会话。确保在每次属于同一会话的graph.invoke()调用中传入了相同的thread_id。config {configurable: {thread_id: user_123_session_1}} result1 graph.invoke(inputs, configconfig) # 下一次调用使用相同的 thread_id 才能加载上次的状态 result2 graph.invoke(new_inputs, configconfig)检查点配置确保在创建图时正确配置了检查点。from langgraph.checkpoint.sqlite import SqliteSaver memory SqliteSaver.from_conn_string(:memory:) # 或文件路径 graph StateGraph(AgentState) # ... 添加节点和边 ... app graph.compile(checkpointermemory) # 关键传入 checkpointer状态序列化确保你的State模型中所有字段都是可 JSON 序列化的。自定义类或复杂的 Python 对象可能导致保存失败。4.5 工具调用Tool Calling失败问题智能体决定调用工具但工具执行失败或返回意外结果。调试方法启用详细日志在代码开头设置import logging; logging.basicConfig(levellogging.DEBUG)查看 LangChain 和 OpenAI 的详细通信日志。检查工具 Schema确保你传递给 LLM 的工具描述name,description,args_schema是清晰、准确的。模糊的描述会导致模型错误理解工具用途。验证工具函数单独测试你的工具函数确保其能处理各种边界情况并返回结构化的、字符串化的结果。LLM 需要解析这个结果。使用langgraph-cli调试页面在调试页面中你可以清晰地看到模型决定调用哪个工具、传递了什么参数、工具返回了什么这是定位问题最直观的方式。遵循这个教程的路径避开这些常见的坑你就能相对平滑地掌握 LangGraph 1.0。记住智能体开发是一个迭代和实践的过程多动手、多思考、多参考这个项目提供的范例你会逐渐建立起构建复杂 AI 应用的自信和能力。这个项目最大的贡献就是为你铺平了从理论到实践的那段最难走的路。