原创：给聪明人讲AI
第一章：LangGraph 概述
1.1 什么是 LangGraph
LangGraph 是 LangChain 团队开发的一款开源 AI Agent 框架，主要用来帮开发者搭建、部署和管理那些比较复杂的生成式 AI Agent 工作流。
它是 LangChain 生态里的重要一员，提供了一个基于图（Graph）的框架，能让开发者做出带有循环工作流和状态管理功能的 LLM 应用程序。
它的设计思路很简单，就是把复杂的 AI 应用拆成一个个相互连接的节点，这些节点通过边（Edges）来传递信息，而且在整个运行过程中，会一直维持一个统一的状态（State），这样就能让 Agent 的行为更可控、更靠谱。
和传统的线性工作流不一样，LangGraph 能让开发者定义循环和分支逻辑，也就是说 Agent 可以根据当下的上下文，灵活调整自己的执行路径。
比如一个智能客服 Agent，如果回答不了用户的问题，就可以选择去搜索网络，或者在需要的时候请求人工帮忙。
这种灵活性，让 LangGraph 特别适合用来做生产级的 AI 应用，尤其是那种需要精细控制 Agent 行为的场景。
1.2 LangGraph 的核心优势
LangGraph 能在众多 AI Agent 框架里脱颖而出，主要是因为它有这几个核心优势：
首先是可靠性和可控性，通过审核检查和人工审核来引导 Agent 操作，确保 Agent 做出来的行为和我们预期的一致；
其次是持久性，Agent 在多次调用之间，能记住之前的对话状态，还支持暂停、恢复和回溯操作；
第三是可扩展性，开发者可以很轻松地给 Agent 增加新功能，添加新的工具和能力；
最后就是能和 LangChain 生态无缝衔接，可以充分利用 LangChain 提供的各种组件和工具。
1.3 LangGraph 与 LangChain 的关系
LangGraph 是 LangChain 生态系统的一部分，但它主要专注于解决某一类特定的问题。
LangChain 提供的是搭建 LLM 应用的基础组件，比如调用模型、提示模板、集成工具这些；而 LangGraph 则专注于怎么把这些组件整合起来，形成复杂的工作流。
简单来说，我们可以把 LangChain 看作是一个“零件库”，里面有各种各样搭建 AI 应用需要的零件，而 LangGraph 就是“组装蓝图”，告诉我们怎么把这些零件拼起来，两者相互配合，就能帮开发者做出更强大的 AI 应用。
LangGraph 可以使用 LangChain 所有的组件，同时还额外增加了状态管理和流程控制的能力。
第二章：核心概念
2.1 四大核心组件
LangGraph 的架构，主要是建立在四个核心概念之上的，分别是图（Graph）、节点（Nodes）、边（Edges）和状态（State）。这四个组件相互配合、协同工作，一起定义了 Agent 的行为和执行流程。
理解这几个概念，是掌握 LangGraph 的关键，它们就像是搭建智能系统的积木，有了这些积木，开发者就能做出各种灵活多变的 AI 应用。下面我们就一个个来详细说说每个组件的设计思路和实际用法。
2.1.1 状态（State）
状态是 LangGraph 里最关键的概念之一，它其实就是一个共享的数据结构，里面存着应用程序运行过程中所有相关的信息。
比如对话历史、用户输入的内容、中间产生的结果、决策记录等等，只要是需要在各个节点之间传递的数据，都能放在状态里。
每个节点都能读取状态里的信息，也能修改状态，而状态一旦更新，就会触发图的下一次运行。
我们定义状态的时候，通常会用 Python 的 TypedDict 或者 Pydantic 模型，这样能保证类型安全，也让代码更容易看懂。
状态管理的核心，在于“状态规约”（State Reduction），简单说就是如果有多个节点同时想要修改同一个状态字段，该怎么把这些修改合并起来。
LangGraph 提供了好几种规约策略，比如追加内容、覆盖原有内容，或者自己定义合并的方法。
所以，设计好状态结构，对搭建一个容易维护的 Agent 来说特别重要，开发者得仔细考虑清楚，哪些数据需要长期保存，以及怎么让这些数据在不同节点之间共享。
2.1.2 节点（Nodes）
节点就是图里的计算单元，每个节点都对应一个具体的操作或者功能。它可以是一个简单的函数，比如调用 LLM 生成回复；
也可以是一个复杂的模块，比如执行网络搜索、查询数据库，或者调用外部的 API。
节点的输入是当前的状态，输出则是对状态的更新。
LangGraph 里的节点设计，遵循的是“单一职责原则”，也就是说每个节点只做一件事，这样一来，图的逻辑会更清晰，后期调试和维护也更方便。
在实际使用中，常见的节点类型有这么几种：
Agent 节点，主要负责做决策、生成回复；工具节点，负责执行具体的操作；路由节点，决定下一步该执行哪个节点；条件节点，根据不同的条件执行不同的逻辑。
节点的粗细可以根据需求灵活调整，既可以是一个完整的功能模块，也可以是模块里的一个小步骤。关键是要保证每个节点的职责明确，输入和输出都清晰明了。
2.1.3 边（Edges）
边主要是用来定义节点之间的连接关系，决定了执行流程从一个节点结束后，该跳到哪个节点继续执行。
LangGraph 支持两种类型的边：普通边（Normal Edges）和条件边（Conditional Edges）。
普通边就是无条件的执行流程，比如节点 A 执行完，肯定会接着执行节点 B；而条件边则可以根据状态里的信息，动态选择下一个要执行的节点，这也是实现复杂控制流的关键。
有了条件边，Agent 就能根据当下的上下文做决策，比如需要的时候调用搜索工具，或者任务完成后就停止执行。
边的设计直接影响着 Agent 的行为模式，设计得合理，就能实现循环功能，让 Agent 反复执行某个操作，直到满足设定的条件；也能实现分支功能，让 Agent 根据不同的情况，选择不同的执行路径。
把循环和分支结合起来，开发者就能搭建出非常复杂的 Agent 行为，同时还能保持代码的可读性和可维护性。
2.1.4 图（Graph）
图是 LangGraph 的顶层抽象，它把节点和边整合在一起，形成一个完整的工作流。LangGraph 提供了 StateGraph 类来搭建图，开发者需要先定义好状态结构，然后添加节点和边，最后编译图，就能生成可以执行的应用程序了。
图的编译过程，会检查图的完整性，确保所有节点都连接正确，没有孤立的节点，也没有死循环。编译好的图可以重复执行，每次执行都会从初始状态开始，经过一系列节点的处理，最后到达结束状态。
LangGraph 支持多种类型的图结构，比如单 Agent 图、多 Agent 图、层次化图等等。
单 Agent 图是最简单的，只有一个 Agent 和它相关的工具；多 Agent 图可以让多个 Agent 一起协作，完成复杂的任务，每个 Agent 都有自己的状态和工具；层次化图则允许在图里面嵌套子图，实现更复杂的模块化设计。
至于选择哪种图结构，主要看具体的应用需求和复杂程度。
第三章：安装与快速入门
3.1 环境准备
在开始用LangGraph之前，得先把开发环境配置好才行。LangGraph支持Python和JavaScript/TypeScript两种语言，不过Python版本的功能更全，官方也更推荐大家用Python。
首先得装Python 3.8或者更高的版本，建议用虚拟环境来管理项目里的依赖，这样不容易乱。
然后通过pip安装LangGraph和相关的依赖包，包括langgraph、langchain还有需要用到的模型SDK。安装命令很简单，就是：
pip install langgraph langchain langchain-openai
除了最基础的LangGraph包，根据你项目的实际需求，可能还需要装其他依赖。
比如你要是想用Anthropic的Claude模型，就可以装langchain-anthropic；要是需要用到搜索工具，就装对应的搜索API客户端。
建议大家在项目的requirements.txt或者pyproject.toml里，把所有用到的依赖都写清楚，这样不管是自己复现环境，还是和团队一起协作，都能更方便。
3.2 第一个LangGraph应用
咱们通过一个简单的例子，来看看LangGraph到底怎么用。我们会做一个简单的对话Agent，它能和用户进行基本的问答互动。
这个例子虽然简单，但里面包含了LangGraph所有的核心概念，学会了这个，再去学更复杂的应用就容易多了。
下面这段代码，就展示了怎么定义状态、创建节点、连接边，还有编译和运行这个图。
3.3 代码详解
上面的示例代码，展示了LangGraph应用的基本结构，咱们一步步拆解，看看每个部分是做什么的、具体怎么实现的。
首先是状态定义，用TypedDict定义了一个叫AgentState的状态结构，里面包含messages和user_input两个字段。
这种类型化的定义方式，不仅能让代码有提示，还能在编译的时候做类型检查，减少运行的时候出错误。
接下来是节点函数的定义。chat_node这个函数就是一个简单的节点，它接收当前的状态作为参数，调用OpenAI的GPT-4模型生成回复，然后返回需要更新的状态。
注意哦，节点函数的返回值是一个字典，里面只包含需要更新的状态字段，LangGraph会自动把这个返回值和当前的状态合并到一起。
最后是图的构建和编译过程。我们先创建一个StateGraph实例，然后添加节点和边，设置好入口点，再调用compile()方法编译这个图。编译好的图可以反复调用，每次调用都会生成一个新的执行实例。
第四章：实战案例
4.1 构建智能客服Agent
智能客服是LangGraph最常用的应用场景之一。一个完整的客服Agent，通常需要具备这些能力：能理解用户想说什么、能回答常见问题、能搜索知识库，必要的时候还能转接到人工客服。
用LangGraph的话，我们可以把这些能力整理成一个清晰的工作流，让Agent根据具体情况，选择最合适的处理方式。下面咱们就来看一个完整的智能客服Agent实现。
这个智能客服Agent的设计思路很简单：先对用户输入进行分类，看看是简单问题还是复杂问题；简单问题就直接用LLM回答，复杂问题就调用搜索工具找相关信息；
如果Agent觉得这个问题超出自己的能力范围，就把对话转交给人工客服。整个流程通过条件边实现动态路由，确保每个用户的请求都能得到最合适的处理。
4.2 Agent 工作流程设计
在设计Agent工作流程的时候，有几个关键问题需要考虑：首先是状态结构的设计，里面得包含对话历史、用户意图、搜索结果这些必要的信息；
其次是节点的划分，每个节点都要职责明确，不能又做这个又做那个；最后是边的连接，要覆盖所有可能的执行路径。
一个好的工作流程，既要清晰、可预测，又要足够灵活，能处理各种特殊情况。
一个典型的智能客服Agent工作流程，大概包含这几个步骤：接收用户输入，把它添加到对话历史里；分析用户的意图，判断问题类型；
根据意图选择处理路径，是直接回答、搜索信息，还是转人工；执行选定的处理逻辑；生成回复，返回给用户。
4.3 常见工作流模式
LangGraph支持多种常见的工作流模式，开发者可以根据自己的具体需求，选择合适的模式，或者把多种模式组合起来用。
理解这些模式，能帮我们设计出更高效、更好维护的Agent系统。下面这几种，是最常用的工作流模式，还有它们的适用场景。
- 链式工作流（Chain）：这是最简单的一种模式，节点按照顺序一步步执行。适合那些能明确拆分成一系列步骤的任务，比如文档摘要生成，就是先读取文档，再分析结构，然后提取要点，最后生成摘要。这种模式的优点是逻辑清晰，容易理解和调试；缺点是不够灵活，不能根据中间结果调整执行路径。
- 路由工作流（Router）：根据输入或者中间结果，选择不同的执行路径。通过条件边实现动态路由，适合那些需要根据不同情况采取不同处理方式的场景。比如一个客服系统，能根据问题类型，把请求转到不同的专业团队：技术问题找技术支持，订单问题找客服团队，投诉问题找投诉处理部门。
- 循环工作流（Loop）：可以重复执行某些节点，直到满足退出条件。这是LangGraph和传统工作流引擎不一样的重要特性，对于需要反复优化或者持续监控的场景特别有用。比如一个代码审查Agent，可以循环检查代码问题，每次修复后再重新检查，直到没有问题为止；还有研究Agent，可以一直搜索、整理信息，直到收集到足够的内容。
- 协作工作流（Collaborator）：多个Agent一起协作，共同完成复杂任务。每个Agent负责特定的领域或者功能，通过共享状态来协作。比如一个内容创作系统，可以包含研究Agent、写作Agent、编辑Agent和审核Agent，它们分工合作，完成从选题到发布的整个流程。这种模式的难点在于，要协调好多个Agent的执行顺序，还要合并它们的结果。
第五章：进阶应用
5.1 持久化与状态管理
在实际应用中，Agent的状态持久化是个关键问题。用户可能会暂停对话，过一会儿再继续；也可能需要回到之前的某个状态，重新执行。
LangGraph提供了完善的持久化机制，支持多种存储后端，比如内存存储、SQLite、PostgreSQL等等。
只要配置好checkpointer，就能自动保存Agent的执行状态，实现暂停、恢复和回溯的功能。
状态持久化还有一个重要的应用，就是“时间旅行”（Time Travel）。LangGraph会记录每次状态变更的检查点（Checkpoint），开发者可以查看完整的执行历史，甚至能从任意一个检查点重新开始执行。
这对于调试复杂的Agent、分析Agent的行为，还有实现撤销操作，都特别有帮助。在生产环境中，合理配置持久化策略，对保证服务的可靠性和用户体验至关重要。
5.2 人机协作（Human-in-the-Loop）
很多场景下，完全自动化的Agent并不能满足需求，这时候就需要引入人工干预，来提高可靠性，或者处理一些特殊情况。
LangGraph的Human-in-the-Loop机制，允许在特定的节点暂停执行，等人工审核或者输入后，再继续执行。这对于需要审批的业务流程、高风险操作的确认，还有处理Agent能力范围之外的问题，都非常重要。
实现人机协作的关键，是使用interrupt_before或者interrupt_after参数。当执行到指定的节点时，图会自动暂停，返回当前的状态，等待外部输入。
人工审核完成后，可以用update_state方法更新状态，然后继续执行。这种机制，能让Agent在保持自动化效率的同时，获得必要的人工监督和干预。
5.3 多Agent 系统
随着任务越来越复杂，单个Agent可能很难满足需求。多Agent系统通过让多个专业化的Agent协作，就能处理更复杂的任务。
LangGraph提供了构建多Agent系统的完整支持，包括Agent之间的通信、协调和结果合并。
常见的多Agent架构有这几种：主从架构（一个协调器Agent把任务分发给多个工作Agent）、团队架构（多个地位平等的Agent一起讨论协作）、层次架构（多层Agent组成的组织结构）。
构建多Agent系统的关键难点，在于协调和通信。LangGraph通过共享状态机制，简化了Agent之间的数据交换，每个Agent都能读取和更新共享状态。
如果需要更复杂的协调，还可以用专门的协调节点，来管理Agent之间的交互。设计多Agent系统时，要考虑Agent的分工、通信协议、冲突解决机制这些因素，好的架构设计是成功的关键。
5.4 流式输出与实时交互
对于需要实时反馈的应用，LangGraph支持流式输出（Streaming）。通过astream或者stream方法，能实时获取节点执行的中间结果，不用等整个图执行完。
这对于聊天类应用来说特别重要，用户能看到LLM的回复一点点生成，不用等很久才能看到完整结果。
流式输出不仅能提升用户体验，还能让监控和调试变得更方便。LangGraph支持多个层面的流式输出：可以流式输出单个节点的结果、流式输出token（需要LLM支持），还有流式输出状态更新。
开发者可以根据自己的应用需求，选择合适的流式模式。实现流式输出的时候，要注意处理异步逻辑和并发问题，确保数据的一致性和正确性。
第六章：最佳实践与建议
6.1 状态设计原则
好的状态设计，是构建可维护Agent的基础。首先，状态里只需要包含必要的信息，别存那些没用的冗余数据。
其次，状态字段要有明确的类型定义，用TypedDict或者Pydantic模型都可以。
第三，要考虑状态的更新策略，分清哪些字段是追加式的（比如对话历史，越聊越多），哪些是覆盖式的（比如当前任务，完成一个换一个）。
最后，如果状态比较复杂，可以考虑用嵌套结构或者引用ID，别让状态变得太庞大。
6.2 节点设计原则
每个节点都要遵循单一职责原则，只做一件事。节点要有明确的输入和输出，尽量避免产生副作用。
对于那些可能失败的操作，要在节点内部处理好异常，并且返回有意义的状态更新。节点的粒度要适中，太细的话，图会变得很复杂；太粗的话，又不容易复用和调试。
建议把那些通用的功能抽出来，做成独立的节点，形成可复用的节点库。
6.3 调试与监控
LangGraph提供了很多实用的调试工具。LangSmith是LangChain生态里的可观测性平台，能追踪Agent的每一步执行，查看状态变化和LLM调用的详细信息。
在开发的时候，建议打开详细日志，记录每个节点的输入和输出。到了生产环境，要配置合适的监控和告警，这样能及时发现和处理异常情况。用时间旅行功能，还能帮助我们分析和复现问题。
6.4 学习路径建议
对于刚接触LangGraph的新手，建议按照这个路径一步步学习，循序渐进：首先掌握LangChain的基础概念，比如怎么调用LLM、怎么写提示模板、怎么用工具等等；
然后学习LangGraph的核心概念，搞明白状态、节点、边、图各自的作用；接着通过官方教程和示例，自己动手做一个简单的Agent应用；最后再深入学习持久化、人机协作、多Agent这些高级主题。
实践是最好的学习方式，建议大家边学边做，通过实际项目来加深理解，这样才能真正掌握LangGraph的用法。
