LangGraph入门指南：构建企业级AI Agent的完整教程

LangGraph是什么

随着AI Agent（智能体）应用的快速兴起，如何编排复杂的多步骤任务、管理状态流转成为开发者面临的核心挑战。AI Agent是指能够感知环境、做出决策并自主执行任务的智能系统——与传统的单次调用大语言模型不同，Agent具备规划（Planning）、记忆（Memory）、工具使用（Tool Use）和反思（Reflection）等能力。这四项能力构成了Agent的核心认知架构：规划能力使Agent能将复杂目标分解为可执行的子任务（如Tree of Thoughts、Plan-and-Solve等策略）；记忆能力包括短期记忆（上下文窗口）和长期记忆（向量数据库检索）；工具使用使Agent能调用API、执行代码、查询数据库等；反思能力则让Agent能评估自身输出质量并进行自我修正。

2023年以来，随着GPT-4等强推理模型的出现，Agent从学术概念走向工程实践，催生了AutoGPT、BabyAGI等标志性项目。这一转变的关键技术突破包括：Chain-of-Thought（思维链）提示让模型具备了逐步推理能力；ReAct范式（Reasoning + Acting）将推理与行动交织进行，使模型能根据观察结果动态调整策略；Function Calling机制则为模型提供了结构化调用外部工具的标准接口。从单Agent到多Agent系统（如AutoGen、CrewAI），行业正在探索让多个专业化Agent协作完成更复杂的任务。企业级Agent应用通常需要处理多轮决策、外部工具调用、错误恢复等复杂场景，这对编排框架提出了极高的要求。

LangGraph正是为解决这一问题而生的框架。作为LangChain生态中的重要组成部分，LangGraph将Agent的执行流程抽象为一张「图」（Graph），通过节点（Node）和边（Edge）来定义任务的流转逻辑。LangChain是目前最流行的大语言模型应用开发框架之一，由Harrison Chase于2022年创建，其核心理念是将LLM调用、提示词模板、外部工具、向量数据库等组件通过Chain（链）的方式串联起来。LangChain生态目前已形成完整的技术栈：langchain-core提供核心抽象（Runnable接口、LCEL表达式语言）；langchain-community集成了数百个第三方工具和服务；LangSmith提供可观测性和评估能力；而LangGraph则专注于Agent编排的模块，弥补了LangChain在复杂控制流方面的不足。

与传统的链式（Chain）编排方式不同，LangGraph的核心优势在于对状态管理和流程控制的精细化支持。它天然支持循环、条件分支、并行执行等复杂控制流，这使得它非常适合构建需要多轮交互、动态决策的企业级Agent应用。LangGraph借鉴了有向无环图（DAG）和状态机的思想，但又超越了传统DAG——它支持循环（Cycle），这意味着Agent可以反复迭代直到满足终止条件。

从图论角度理解，有向无环图（DAG）是一种节点间只有单向连接且不存在环路的图结构，广泛应用于任务调度（如Apache Airflow）、编译器优化和数据管道编排。DAG的局限在于无法表达迭代逻辑——而Agent的核心行为模式恰恰是「思考-行动-观察-再思考」的循环过程。有限状态机（FSM）虽然支持状态间的循环转移，但其状态空间是预定义的、离散的，难以应对Agent运行时的动态状态变化。LangGraph的创新在于结合了两者的优势：用图结构表达流转逻辑，用动态状态对象承载运行时信息，从而实现了一种「有状态的可循环有向图」。

这种设计灵感部分来自Pregel（Google的大规模图处理框架）和Apache Beam等数据流编程模型，将复杂的Agent行为分解为可组合、可观测的离散步骤。Pregel由Google于2010年发表，采用BSP（Bulk Synchronous Parallel，整体同步并行）计算模型来处理大规模图数据。在BSP模型中，计算被划分为一系列「超步」（Superstep），每个超步中所有节点并行执行本地计算、发送消息，然后通过同步屏障（Barrier）确保所有消息传递完毕后再进入下一超步。LangGraph借鉴了这一思想：图中的每个节点是独立的计算单元，节点间通过状态对象传递信息，每一轮执行都经过明确的状态同步。这使得Agent的行为变得确定性更强、更易于调试和重放。

LangGraph的核心特点

• 状态驱动：通过State对象在各节点间传递和维护上下文，让整个流程具备「记忆」能力。在传统软件工程中，有限状态机（FSM）是管理系统状态转移的经典模式。LangGraph将这一概念引入AI Agent领域，每个节点的执行都基于当前状态（State），并产生状态更新。与Redux等前端状态管理方案类似，LangGraph采用了Reducer模式——状态更新不是直接覆盖，而是通过预定义的合并策略（如列表追加、字典合并）来聚合多个节点的输出，确保状态变更的可预测性和可追溯性。在LangGraph中，Reducer通过Python的Annotated类型注解来声明，例如messages: Annotated[list, add_messages]表示messages字段使用add_messages函数作为Reducer，每次更新时将新消息追加到列表末尾而非替换整个列表。这种声明式的状态管理方式在并发场景下尤为重要——当多个并行节点同时更新状态时，Reducer确保了合并的确定性。
• 图结构编排：以图的形式组织任务逻辑，支持复杂的控制流，比线性Chain更灵活。图结构的优势不仅体现在逻辑表达上，还体现在执行优化上：LangGraph能够自动识别图中的并行分支，将无依赖关系的节点并发执行以提升性能。此外，图结构天然支持子图（Subgraph）嵌套——一个节点本身可以是另一个完整的图，这使得复杂Agent系统可以通过层次化分解来管理复杂度。
• 可视化与可调试：图结构天然便于可视化，开发者能清晰看到Agent的执行路径。LangGraph支持将图结构导出为Mermaid图表或PNG图片，开发者可以直观地看到节点间的连接关系和条件分支逻辑。结合LangSmith平台，还能追踪每次执行的完整Trace——包括每个节点的输入输出、Token消耗、延迟时间等，这对于调试复杂Agent的非确定性行为极为重要。
• 企业级可靠性：支持持久化、断点续跑等特性，满足生产环境需求。LangGraph内置了Checkpointer机制，可以将图的执行状态持久化到SQLite、PostgreSQL等存储后端。当系统故障或需要人工介入时，Agent可以从最近的检查点恢复执行，而不必从头开始。这一特性还支持「人机协作」（Human-in-the-Loop）模式——在关键决策节点暂停等待人工审核后再继续执行。在实际企业应用中，Human-in-the-Loop模式常用于高风险决策场景：如Agent准备发送邮件、执行数据库写操作或调用支付接口前，系统会自动暂停并通知人工审核员。审核通过后，Agent从检查点继续执行；若被拒绝，则可以回退到之前的状态重新规划。

环境配置：从零搭建LangGraph开发环境

入门LangGraph的第一步是搭建开发环境。整个流程可以概括为「安装Python环境 → 创建项目 → 配置依赖」三个步骤。

对于初学者而言，建议从一个干净的Python虚拟环境开始，避免依赖冲突。Python虚拟环境（如venv、conda、poetry）是隔离项目依赖的标准实践。在AI开发中，不同项目可能依赖同一库的不同版本（如某项目需要pydantic v1而另一个需要v2），虚拟环境能有效避免版本冲突。其中venv是Python标准库自带的轻量方案；conda除了管理Python包还能管理系统级依赖（如CUDA、C++库），适合涉及深度学习的项目；poetry则提供了依赖锁定（lock file）和发布管理等更现代的工作流。推荐使用Python 3.10及以上版本，以获得对最新语法特性和类型注解的完整支持——LangGraph大量使用了TypedDict、Annotated等类型注解特性来定义状态结构，这些特性在3.10版本后获得了更完善的语法支持和运行时行为。特别是PEP 604引入的X | Y联合类型语法和PEP 612引入的ParamSpec，使得类型推断在复杂泛型场景下更加精确。创建虚拟环境后，通过pip安装LangGraph及其相关依赖：

pip install langgraph langchain

此外，如果需要接入大语言模型（如OpenAI、通义千问等），还需安装对应的模型SDK并配置API密钥。这一步是Agent能够「思考」的基础。目前主流的LLM提供商包括OpenAI（GPT系列）、Anthropic（Claude系列）、Google（Gemini）以及国内的通义千问、文心一言、智谱等。LangGraph通过LangChain的ChatModel抽象层统一了不同模型的调用接口，开发者只需更换模型名称和API密钥即可切换底层模型。ChatModel抽象层基于LangChain的Runnable接口设计，所有模型都实现了相同的invoke/stream/batch方法签名，并支持结构化输出（通过with_structured_output绑定Pydantic模型）、工具绑定（通过bind_tools注册可调用工具）等统一能力。

在生产环境中，通常还需要考虑API调用的速率限制、重试策略、Token计费和流式输出等工程细节。Token计费是LLM应用的核心成本因素——大语言模型按输入Token（Prompt）和输出Token（Completion）分别计费，其中GPT-4 Turbo的输入价格约为$10/百万Token，输出约$30/百万Token。在Agent场景下，由于多轮迭代会累积大量历史消息，Token消耗可能数倍于单次调用。因此，生产系统通常需要实现Token预算控制、消息历史截断、摘要压缩等优化策略。流式输出则基于Server-Sent Events（SSE）或WebSocket协议，允许模型生成的Token逐个返回给客户端，避免用户等待完整响应，大幅提升交互体验。LangGraph的stream方法不仅支持Token级别的流式输出，还支持节点级别的事件流——每当一个节点完成执行，系统即刻推送该节点的输出，使得前端能实时展示Agent的思考过程。

项目结构建议

在正式编码前，规划清晰的项目结构十分重要。一个典型的LangGraph项目通常包含状态定义、节点函数、图的构建与编译等模块。将这些逻辑拆分到不同文件，有助于后期维护和团队协作。推荐的项目结构如下：state.py定义TypedDict状态类和Reducer；nodes.py包含各节点的业务逻辑函数；graph.py负责组装图结构并编译；tools.py定义Agent可调用的工具集；config.py管理API密钥和环境变量。这种关注点分离的架构使得每个文件职责清晰，便于单元测试和代码审查。

第一个LangGraph案例：理解核心概念

理解LangGraph编程模型的最佳方式是动手写一个简单案例。在入门示例中，有两个核心概念需要重点掌握：Message State（消息状态）和Graph（图/流）。

理解Message State（消息状态）

Message State是LangGraph中用于承载对话消息的状态对象。它记录了Agent与用户交互过程中产生的所有消息，并在图的各个节点之间流转。可以把它理解为整个Agent运行过程中的「共享内存」——每个节点都可以读取当前状态，并对其进行更新。

在LangGraph的类型系统中，Message State通常定义为一个TypedDict，其核心字段是messages: Annotated[list[BaseMessage], add_messages]。BaseMessage是LangChain中所有消息类型的基类，包括HumanMessage（用户输入）、AIMessage（模型回复）、ToolMessage（工具返回结果）、SystemMessage（系统提示）等。每种消息类型都携带特定的元数据——如AIMessage包含tool_calls字段记录模型请求调用的工具，ToolMessage则通过tool_call_id与对应的调用请求关联。这种结构化的消息体系使得Agent的对话历史完整可追溯，也为后续的调试和评估提供了数据基础。

这种设计的巧妙之处在于，开发者无需手动在函数间传递大量参数，状态的更新会自动合并到全局State中，大大简化了多步骤任务的编排复杂度。具体而言，Message State内部维护了一个消息列表，新消息通过Reducer策略（默认为追加模式）自动合并到已有列表中。这意味着当一个节点返回新的AI消息时，系统会将其追加到消息历史中，而非覆盖原有内容。这种不可变数据的设计理念使得状态变更可追踪、可回溯。值得注意的是，add_messages这个内置Reducer还支持消息去重和更新——如果返回的消息带有已存在的id，则会更新对应消息而非追加新消息，这在需要修改历史消息的场景（如流式输出中逐步更新最后一条AI消息）中非常有用。

图的调用流程与注意事项

定义好节点和状态后，需要将它们组装成一个完整的Graph，然后通过编译（compile）生成可执行的应用。LangGraph中的compile步骤类似于代码编译过程——将开发者定义的图结构（节点、边、条件分支）转化为一个可高效执行的运行时对象。编译过程中会进行图的合法性校验（如检查是否存在孤立节点、入口点是否正确定义），并生成优化后的执行计划。编译后的图对象支持invoke（同步调用）、stream（流式输出）、ainvoke（异步调用）等多种执行模式，满足不同场景的需求。

其中，invoke模式等待整个图执行完毕后一次性返回最终状态，适合后台批处理任务；stream模式基于Python的Generator机制逐步yield每个节点的执行结果，适合需要实时反馈的交互场景；ainvoke和astream则是对应的异步版本，基于Python asyncio事件循环，适合高并发的Web服务场景。在实际开发中，stream模式最为常用——它允许前端在Agent思考过程中就开始展示中间结果，而不必等待整个推理链完成。

调用图的过程中，有一些容易被忽视的细节值得注意：比如节点的执行顺序、状态的更新时机、以及如何正确处理条件分支的返回值。

这些细节往往是初学者踩坑的重灾区。理解清楚状态如何在图中「流动」，是掌握LangGraph的关键所在。一个常见的误区是认为节点的返回值会完全替换当前状态——实际上，节点只需返回它希望更新的状态字段，系统会通过各字段对应的Reducer将更新合并到全局状态中。另一个容易出错的地方是条件边（Conditional Edge）的返回值：条件函数应返回下一个节点的名称（字符串），而非节点函数本身。此外，当使用END作为条件分支的目标时，意味着图的执行在此终止并返回最终状态。

从LangChain到LangGraph的迁移指南

对于已经熟悉LangChain的开发者，这里特别对比了如何用LangGraph重新实现一个Agent案例。同样一个Agent逻辑，用LangChain的高级封装（如AgentExecutor、create_react_agent等）可以快速实现，而用底层的LangGraph实现则需要更明确地定义状态和流转逻辑。

这种对比的价值在于：LangChain提供的是「开箱即用」的便捷，而LangGraph提供的是「精细可控」的灵活。当业务逻辑变得复杂、需要自定义控制流时，直接使用LangGraph能获得更大的自由度和可维护性。

具体而言，LangChain的AgentExecutor本质上是一个预定义的ReAct循环：模型思考→调用工具→观察结果→再次思考，直到模型决定给出最终答案。这种模式对于标准的工具调用Agent已经足够，但当需求超出这一范式时就会遇到限制。例如，当Agent需要在工具调用失败时执行特定的回退逻辑，或者需要根据中间结果动态调整后续步骤时，LangGraph的条件边（Conditional Edge）和循环结构能优雅地表达这些需求，而LangChain的AgentExecutor则可能需要通过复杂的回调和异常处理来实现相同效果。

更深层次地看，这一迁移反映了AI应用开发的成熟化趋势。早期开发者追求快速原型验证，高层封装（如AgentExecutor）能以最少代码跑通一个Demo。但当应用进入生产阶段，对可观测性、错误处理、性能优化、多Agent协作等方面的需求急剧增加，底层框架（如LangGraph）的优势便凸显出来。事实上，LangChain官方也在逐步将Agent相关功能向LangGraph迁移——最新文档已经推荐使用LangGraph的create_react_agent替代原有的AgentExecutor，这标志着LangGraph正在成为LangChain生态中Agent开发的事实标准。

两种编程接口：Graph API vs Functional API

LangGraph提供了两种并行的编程接口：

• Graph API：以显式的图结构进行编排，是目前使用最广泛的方式。它清晰地定义节点、边和状态流转，适合构建复杂的企业级Agent。开发者通过StateGraph类创建图实例，使用add_node添加节点、add_edge和add_conditional_edges定义流转规则，最后调用compile生成可执行对象。这种声明式的编程风格使得Agent的行为逻辑一目了然。Graph API的核心优势还体现在组合性上：通过子图（Subgraph）机制，一个复杂的Agent系统可以由多个独立开发、独立测试的子图组合而成。例如，一个客服Agent可以由「意图识别子图」「知识检索子图」「工单创建子图」组合构成，每个子图都有独立的状态定义和测试用例。
• Functional API：以更接近函数式编程的风格来定义流程，语法上更简洁，但在实际生产中应用相对较少。它通过@task和@entrypoint等装饰器将普通Python函数标记为可编排的计算单元，无需显式构建图结构。这种方式降低了入门门槛，适合逻辑相对简单的场景。Functional API的设计哲学受到了Temporal（工作流引擎）和Prefect（数据编排框架）等项目的影响——通过装饰器自动捕获函数执行的中间状态，实现隐式的持久化和重试。然而，由于缺少显式的图定义，在可视化调试、团队协作理解复杂流程方面不如Graph API直观，因此在生产级复杂Agent中采用率较低。

对于大多数开发者而言，建议将学习重心放在Graph API上。它不仅是社区主流，也代表了LangGraph设计理念的核心——用图来表达Agent的思考与行动过程。从软件工程的角度看，Graph API的声明式风格类似于Terraform之于基础设施、React之于UI——开发者描述「期望的状态和结构」，框架负责「如何高效执行」。这种关注点分离让开发者能专注于Agent的业务逻辑设计，而将并发调度、状态持久化、故障恢复等底层复杂性交给框架处理。

总结与下一步学习建议

LangGraph为构建企业级AI Agent提供了一套强大而灵活的编排框架。从环境配置、第一个案例，到状态管理与两种API的取舍，本文梳理了入门LangGraph的完整路径。对于希望将Agent应用真正落地到生产环境的开发者来说，深入理解Graph API和状态驱动的编程模型，将是迈向进阶的必经之路。

下一步，建议动手实践一个完整的Agent项目，在实战中体会状态流转与流程控制的精妙之处。可以从一个带工具调用的ReAct Agent开始——ReAct（Reasoning + Acting）是由Yao等人在2022年提出的Agent范式，其核心思想是让模型在每一步都先进行推理（Thought），然后执行动作（Action），再观察结果（Observation），形成一个思考-行动-观察的循环。在LangGraph中实现ReAct Agent非常直观：定义一个「模型调用」节点和一个「工具执行」节点，通过条件边判断模型是否请求了工具调用——如果是则路由到工具节点，如果不是则终止循环返回结果。

逐步加入多Agent协作、人机协作审批、长任务持久化等高级特性，循序渐进地掌握LangGraph的全部能力。多Agent协作可以通过Supervisor模式（一个主Agent调度多个子Agent）或Swarm模式（Agent之间平等协作、动态交接任务）来实现。建议同时关注LangGraph Platform（云托管服务）和LangGraph Studio（可视化IDE），它们能显著提升开发效率和部署体验。

核心要点