1. 先搞清楚 LangGraph 到底解决什么问题这两年只要聊 AI 大模型应用开发就绕不开几个词LangChain、LangGraph、MCP、Agent、智能体。很多人一看到这些名词就头大尤其是 LangGraph 和 LangChain 的关系很多人到现在都没分清。这篇文章直接围绕 LangGraph 智能体实战展开从环境安装、核心组件、代码落地到常见坑点按实际开发顺序拆一遍。文章不是官方文档翻译而是我实际跑过之后的理解带有很强的工程判断。先说结论LangGraph 不是 LangChain 的替代品也不是一个新框架来“吊打”谁。LangGraph 是一个专门用来构建有状态、可编排的智能体应用的编排框架。它解决的核心问题是让多个 LLM 调用、工具调用、条件判断和循环逻辑变成一个清晰、可控制、可调试的图结构。你可以把它理解成LangChain 提供了各种零件LangGraph 负责把这些零件按流程串起来并且让流程可控、可回放、可中断、可恢复。很多人和我说为什么不用普通 Python 代码写死流程如果你只是调用一次大模型然后拿结果确实没必要用 LangGraph。但当你需要让模型自己决定下一步调用哪个工具、需要多轮循环、需要根据中间结果走不同分支时普通代码会变得又乱又难维护。LangGraph 的价值就在这里把流程当图画出来把状态当数据传下去把每个节点当成可单独调试的函数。这篇文章适合谁看适合已经用过一点 LangChain但还没搞懂智能体怎么落地的人。也适合刚接触 LangGraph不知道第一步该装什么、怎么写、怎么调试的人。如果你连 Python 环境都没配置过建议先把 Python 基础补一补再回来看这篇文章。最值得你关注的点有三个第一LangGraph 的状态管理到底怎么理解第二节点、边、条件边这些核心概念怎么和实际代码对应第三它和 MCP、LangChain 在一起时分工是什么。这三个问题搞清楚LangGraph 基本就入门了。2. 环境安装准备先把基础环境理干净LangGraph 本地开发环境并没有想象中复杂。我建议不要一上来就搭建大而全的服务架构先把最小环境跑通再往里面加模型、加工具、加 MCP Server。2.1 Python 环境和依赖版本怎么选LangGraph 是基于 Python 的库所以第一步是保证 Python 环境正常。我的建议是直接用 3.10 或 3.11 版本这两个版本对 LangChain 生态兼容性最好。Python 3.12 虽然也能用但有些旧依赖包还没跟上容易出现版本冲突。安装 LangGraph 的命令很简单pip install langgraph只装这个库图编排能力就已经有了。但实际开发智能体还需要 LangChain 生态和模型接入库。所以一般我会一次性把常用依赖装上pip install langchain langchain-core langchain-openai langgraph这里要注意LangChain 版本更新很快接口经常有小变化。如果你网上复制的代码报错先别慌很大概率不是逻辑问题而是版本不匹配。建议安装完以后先执行一下检查命令pip show langgraph langchain langchain-core langchain-openai把版本号记录一下。后面遇到问题排查依赖版本会省很多时间。2.2 模型 API 需要准备什么LangGraph 本身不包含大模型它只是编排框架。真正回答问题、生成内容的是模型。所以你必须先有一个能调用的模型接口。常见选择有三类OpenAI 兼容接口。国内大模型服务一般也提供 OpenAI 兼容接口。本地部署模型比如通过 Ollama 或 vLLM 暴露的接口。我建议第一次学习时直接用 OpenAI 兼容接口因为 LangChain 的支持最成熟出问题也好排查。你需要准备一个 API Key然后在代码里配置环境变量。在 Python 里可以这样临时配置import os os.environ[OPENAI_API_KEY] 你的key在命令行环境里可以这样配置export OPENAI_API_KEY你的key不要在生产代码里写死 Key也不要把 Key 提交到 Git 仓库。这是一个很低级但经常有人犯的错误。2.3 MCP 和 LangChain 需要先装吗先解释一下 MCP。MCP 的全称是 Model Context Protocol中文叫模型上下文协议。它是一个标准化的接口协议用来让大模型应用连接外部工具和数据源。你不需要把 MCP 理解得很玄它本质上就是一套“工具接入标准”。MCP 和 LangGraph 的关系是LangGraph 负责流程编排和状态管理MCP 负责把外部工具暴露成统一接口。两者不冲突可以配合使用。LangChain 生态里也有专门适配 MCP 的工具可以帮你把 MCP Server 暴露的工具变成 Agent 能调用的工具。第一次学习时没必要急着接 MCP。先把 LangGraph 的节点、边、状态跑明白再考虑接入真实工具。如果你一上来就搞十几个 MCP Server问题大概率出在接口协议和参数传递上反而不容易找到根源。注意学习 LangGraph 的顺序强烈建议是“先图和状态再 LangChain 工具最后接 MCP”。跳过前两步直接上 MCP会把简单问题复杂化。3. 核心组件逐个拆解状态、节点、边、条件边LangGraph 最核心的编程模型就是把应用设计成一张图。图里有节点节点之间有边。数据在节点间流动靠的是一个全局状态对象。我第一次看官方文档时最不理解的就是这个 State 概念。后来把代码跑了几遍才明白你可以把 State 理解成一个字典所有节点共享这个字典每个节点都可以读取和修改它。节点之间不直接传参而是通过 State 来传递信息。3.1 State所有节点共享的数据结构在 LangGraph 里State 不是一个普通字典而是一个带有类型定义的数据结构。最简单的写法是使用 TypedDictfrom typing_extensions import TypedDict class AgentState(TypedDict): messages: list current_step: str这里定义了状态里包含两个字段messages 保存对话消息current_step 记录当前流程步骤。为什么用 TypedDict 而不用普通字典因为 LangGraph 需要知道每个字段的类型才能正确处理状态的合并和更新。如果你只写普通字典很多高级功能没法用。3.2 节点真正干活的地方节点就是普通 Python 函数。输入是 State输出是一个字典表示要把哪些字段更新到 State 里。def call_model(state: AgentState): messages state[messages] response chat_model.invoke(messages) return {messages: messages [response], current_step: model_called}这个函数做的事情很简单从 State 里取消息列表调用模型生成回复然后把新消息放回 State同时更新当前步骤。节点函数有几个特点输入参数必须是 State。返回值必须是字典字典的键要和 State 字段对应。不修改 State 本身而是返回要更新的部分。这个“返回更新部分”的设计很关键它让流程变得可追踪。你随时能知道每个节点改了哪些字段。3.3 边和条件边控制流程走向边的作用是连接节点。最简单的边是普通边表示上一个节点执行完以后无条件进入下一个节点。from langgraph.graph import StateGraph, START, END graph StateGraph(AgentState) graph.add_node(call_model, call_model) graph.add_edge(START, call_model) graph.add_edge(call_model, END)这段代码创建了一个最小流程从 START 进入 call_model 节点执行完以后进入 END。真实场景下流程很少这么简单。比如模型决定要调用工具那就要走工具节点如果模型判断已经完成就直接输出结果。这时候就需要条件边。from langgraph.graph import add_conditional_edges def should_continue(state: AgentState): if state[current_step] need_tool: return tool_node else: return end graph.add_conditional_edges( call_model, should_continue, { tool_node: call_tool, end: END } )条件边的作用是根据 State 里的信息决定下一步走哪个节点。它让图有了分支能力这就是“智能体自己决定下一步”的核心机制。3.4 循环智能体反复调用工具的基础很多初学者只理解直线流程不理解为什么需要循环。其实智能体处理复杂任务时往往需要多轮推理和工具调用。比如用户问“帮我查一下天气然后根据天气推荐穿搭”模型可能需要先调用天气查询工具拿到结果后再做下一步判断。这个“判断-调用-再判断”的过程就是通过条件边加上目标节点循环实现的。你可以让 call_model 节点执行完后条件判断是否进入 call_tool 节点执行完工具后把工具结果写回 State再回到 call_model 节点让模型继续推理。graph.add_edge(call_tool, call_model)这样 graph 就形成了循环模型思考 - 工具调用 - 模型再思考。每一次循环State 里的消息列表都在增长模型能看到越来越多的上下文信息。我实际测试时一般会在循环里加一个最大轮数限制避免模型陷入死循环。比如执行超过 10 轮就强制结束。这个在工程上非常必要否则一个 Agent 任务可能无限调用工具消耗大量费用。4. 代码实战从最小智能体开始理论概念看再多不如亲手跑一个能工作的代码。下面我从一个最小智能体开始逐步加功能。4.1 最小可运行示例单节点流程先演示最简单的 LangGraph 流程。这个流程只有一个模型调用节点from typing_extensions import TypedDict from langchain_openai import ChatOpenAI from langgraph.graph import StateGraph, START, END class AgentState(TypedDict): messages: list model ChatOpenAI(modelgpt-4o-mini, temperature0) def call_model(state: AgentState): response model.invoke(state[messages]) return {messages: [response]} graph StateGraph(AgentState) graph.add_node(call_model, call_model) graph.add_edge(START, call_model) graph.add_edge(call_model, END) app graph.compile()运行代码如下result app.invoke({ messages: [{role: user, content: 你好简单介绍一下你自己}] }) print(result[messages][-1].content)执行成功后你会看到模型返回的文本。这个示例虽然简单但完整展示了 LangGraph 的四个关键要素State 定义、节点函数、图构建、编译运行。注意invoke 时的输入结构必须是一个字典字典的键要和 State 字段一致。如果你传了 State 里不存在的字段运行时不会直接报错但后续处理会非常难排查。4.2 加入工具调用让智能体拥有执行能力最小示例跑通后下一步是加入工具调用。这里用 LangChain 的 tool 装饰器来定义一个简单函数from langchain_core.tools import tool tool def get_weather(city: str) - str: 查询指定城市当前的天气情况 return f{city} 今天晴温度 24 度东北风 3 级定义好工具后需要用 bind_tools 把这个工具绑定到模型上model_with_tools model.bind_tools([get_weather])然后修改节点逻辑模型如果认为需要调用工具会返回 tool_calls 信息而不是直接返回内容。def call_model(state: AgentState): response model_with_tools.invoke(state[messages]) return {messages: [response], current_step: model_called}再增加一个工具执行节点def call_tool(state: AgentState): last_message state[messages][-1] tool_calls last_message.tool_calls tool_results [] for tool_call in tool_calls: tool_name tool_call[name] tool_args tool_call[args] result {role: tool, content: str(get_weather.invoke(tool_args)), tool_call_id: tool_call[id]} tool_results.append(result) return {messages: tool_results}这里的核心逻辑是模型返回的 tool_calls 里有函数名、参数和调用 IDAgent 拿到这些信息后去执行真正的工具函数再把执行结果包装成 tool 消息放回 State。图结构变为graph StateGraph(AgentState) graph.add_node(call_model, call_model) graph.add_node(call_tool, call_tool) graph.add_edge(START, call_model) graph.add_conditional_edges( call_model, should_continue, { tool_node: call_tool, end: END } ) graph.add_edge(call_tool, call_model)当工具执行完流程会重新回到 call_model模型看到工具返回结果后再生成最终回答。这就是一个完整的 Agent 循环。4.3 编译和运行用可视化效果加深理解LangGraph 提供了编译后图形的可视化能力。虽然不要求每个人都配置可视化环境但我建议有条件的话试一次。你可以在 Jupyter Notebook 里安装pip install langgraph-cli编译后的图对象可以生成一个简单的图结构表示。真实工程里用可视化来检查流程分支是否合理比自己死盯着代码高效得多。第一次跑完整代码时如果结果不对我建议按这个顺序排查是否正常打印出模型最终回答。是否输出了 tool_calls 内容。工具函数是否真的被调用。State 里的 messages 是否完整。大部分问题都出在工具调用的消息格式上尤其是 tool_call_id 必须和模型返回的 ID 严格一致。5. LangGraph、LangChain、MCP 三者怎么分工很多人的困惑在于这三个概念重叠不知道什么时候用哪个。我用工程场景来拆解一下。5.1 LangChain工具库和组件生态LangChain 提供了大量可复用的组件比如模型接口封装、Prompt 模板、文档加载器、向量存储、工具封装等。你可以把 LangChain 理解成一个零件库里面有很多现成的积木。但 LangChain 本身不擅长编排复杂流程。早期版本用 AgentExecutor 来做 Agent但它的流程控制能力很弱一旦业务逻辑复杂就很难维护。5.2 LangGraph流程编排和控制LangGraph 的作用是补充 LangChain 在这方面的短板。它提供了图结构、状态管理、条件分支、循环、断点、持久化等机制适合构建复杂的 Agent 应用。用一句话总结LangChain 提供能力LangGraph 编排能力。LangGraph 的代码里经常导出来自 langchain 的模型和工具类两者是配合关系不是竞争关系。5.3 MCP外部工具接入标准MCP 的定位又不一样。它解决的是工具接入的标准化问题。比如你的系统要接企业内部 API、数据库、文件系统每个系统如果都要单独写适配代码改起来很麻烦。MCP 把这些工具封装成统一协议Agent 侧只要实现 MCP Client就能调用任意 MCP Server 暴露的工具。三者配合时一个典型的架构是使用 LangChain 的 ChatOpenAI 等组件接入大模型。使用 LangGraph 编排 Agent 的思考、推理、工具调用循环。使用 MCP Server 暴露外部系统能力通过 MCP 适配器转换成 LangChain Tool。这个架构下LangGraph 是“大脑的思维流程”LangChain 是“四肢的工具组件”MCP 是“连接外部世界的标准接口”。5.4 什么时候不需要 LangGraph不是所有 AI 应用都需要上 LangGraph。如果你只是做一个简单的问答接口用户发一句话模型回一句话那就没必要引入图编排。直接调用模型 API 反而更简单。判断标准很简单如果流程是固定的直线且不需要循环、不需要条件分支、不需要模型自主决策就用最简单的方式实现。LangGraph 的复杂度只有在流程复杂时才是值得的。6. 进阶玩法条件路由、子图和并行分支跑通最小智能体后再往深走LangGraph 还有几个比较重要的能力条件路由、子图和并行分支。这些是面试和工程实战里经常提到的点。6.1 条件路由和分支控制条件路由就是根据当前状态让流程走不同分支。比如一个客服智能体用户问“查订单”就走订单查询子流程用户问“退货”就走退货流程。条件路由的核心是 conditional_edges。你写一个函数输入 State输出下一个节点的名称。LangGraph 会根据函数返回值把流程引导到对应节点。def route_by_intent(state: AgentState): intent state.get(intent, general) if intent order: return order_node elif intent refund: return refund_node else: return general_node这种写法代码可读性很高而且后续加新意图分支很容易只要扩展映射字典就行。实际使用中要注意路由函数的判断逻辑不要依赖模型输出里的自由文本最好有结构化的意图识别结果。否则分支很多时模型判断不稳定流程容易走错。6.2 子图把复杂流程拆小子图就是图里面套图。当一个主流程太复杂时可以把一部分节点封装成子图子图内部有自己的状态和边。subgraph StateGraph(SubState) # ... 添加子图节点和边 sub_app subgraph.compile() main_graph StateGraph(MainState) main_graph.add_node(sub_task, sub_app)子图的好处是模块化。每个子图负责一个独立业务域主图只负责流程调度。调试时可以单独运行子图不用每次跑完整流程图。我在实际项目里一般会把“意图识别”“工具调用”“结果整理”分别做成子图。这样代码结构清楚多人协作时也方便分工。6.3 并行分支LangGraph 支持一个节点同时连通多个后续节点。如果你的智能体需要同时查询天气、查询航班、查询酒店就可以在工具调用节点后面接多个并行节点。并行分支能提升效率因为多个工具调用可以并发执行而不是串行等待。但要注意并行时 State 的更新要小心多个节点同时修改同一个字段会产生冲突。LangGraph 提供了一些合并机制但最稳妥的方式是让不同并行节点更新不同字段。我第一次写并行分支时踩过一个坑两个并行节点都修改“messages”字段结果只有一个节点的新消息保留下来了。后来改成各自维护独立的字段再统一合并问题就解决了。7. 实战中的资源占用与性能判断LangGraph 本身不消耗多少资源它只是一个流程引擎。真正的资源大头在模型调用和工具执行。7.1 显存内存占用看什么如果你用的是云端模型 API那本地的资源消耗非常低基本就是 Python 进程和网络请求。内存占用一般在几百 MB 到 1GB取决于你加载的依赖数量。如果你用的是本地模型那就要重点看显存。这里给出一个通用参考模型规模显存需求量化后说明1.5B 级别2GB - 4GB轻量任务足够7B 级别6GB - 10GB中等任务可用14B 级别12GB - 20GB推荐 A 级显卡70B 级别40GB 以上需要多卡或大显存低显存环境也能跑 LangGraph但要把模型换小或者把并发数降低。LangGraph 的 Agent 循环里有多个模型调用如果你同时开多个任务本地模型可能会被排队机制拖慢。7.2 速度不只看模型推理很多初学者以为 Agent 慢是因为模型慢。其实不一定。Agent 任务里模型可能被调用多次。每次调用都需要几百毫秒到几秒多轮循环叠加后整体耗时就上去了。我一般会统计两个指标单次模型调用平均耗时。完成一个完整 Agent 任务的总耗时。如果总耗时远大于单次耗时乘以调用次数那就要检查是不是工具调用卡住了、网络超时了、或者输出队列阻塞了。7.3 怎么判断稳定不稳定稳定性判断不能只看一次运行。我用 LangGraph 跑批量任务时会连续跑 20 到 50 条样本然后统计成功率完成多少条失败多少条。平均耗时所有任务的平均时长。超时数量超过设定时间的任务有多少。失败原因分布是模型报错、工具错误、还是流程卡住。只有这些指标都合理才说明 Agent 应用可以进入批量环境。8. 常见报错和排查顺序最后系统整理一下 LangGraph 实战里最常见的报错和排查思路。这些坑我自己基本都踩过写出来帮你少走弯路。8.1 最常见的几类问题第一类依赖版本冲突。典型现象是 import 时报错比如找不到某个模块或者某个函数参数不匹配。原因基本都是 LangChain、LangGraph、langchain-openai 版本不一致。解决办法是统一升级到兼容版本或者安装前先看官方文档的版本要求。第二类状态字段定义错误。典型现象是节点函数返回的字典里键名和 State 定义的字段不一致。LangGraph 不会自动创建新字段所以你会发现在某个节点写进去的数据下一个节点读不到。解决办法是打印 State 内容检查字段名是否完全一致。第三类工具调用消息格式错误。典型现象是模型调用了工具但工具执行时报错或者 Agent 看不到工具结果。主要原因一般是 tool_call_id 对不上或者工具结果没有使用 role“tool” 的消息格式。这个在 LangChain 的版本更新中经常变化务必查阅对应版本文档。第四类条件边配置错误。典型现象是流程走到了不存在的节点或者一直停在某个节点不往下走。解决办法是检查条件路由函数的返回值确认返回的字符串和映射字典里的键完全一致。第五类无限循环。典型现象是任务一直不结束日志里不断出现工具调用。解决办法是设置最大递归轮数或者设置超时时间。app graph.compile() result app.invoke( {messages: [{role: user, content: 请查询上海天气并推荐穿搭}]}, config{recursion_limit: 20} )我在代码里一般都会设置 recursion_limit这个参数表示流程最多执行多少个节点步骤超过后强制停止。否则模型一旦陷入循环既浪费费用又浪费时间。8.2 排查顺序先现象后原因遇到 LangGraph 项目报错或结果异常我建议按这个顺序排查先看报错信息在哪一层。是 import 阶段、编译阶段、还是运行阶段。再看输入数据。State 初始值是否完整messages 格式是否正确。再看节点函数。每个节点是否都正确返回了字典字段名是否和 State 一致。再看图的连接。条件路由的返回值是否在映射字典里边是否闭环。最后看模型返回。模型是否输出了标准格式的 tool_calls工具执行结果是否写回 State。不要一上来就怀疑 LangGraph 有 Bug。绝大多数问题出在自己的状态定义、消息格式和路由配置上。8.3 调试时的小技巧调试 LangGraph 项目时我一般会在节点函数里面加打印语句把 State 的核心字段打出来。虽然不够优雅但非常有效。def call_model(state: AgentState): print( call_model state ) print(messages count:, len(state[messages])) response model_with_tools.invoke(state[messages]) print(response type:, type(response)) print(has tool_calls:, bool(getattr(response, tool_calls, None))) return {messages: [response]}这样你能清楚看到每个节点输入输出是否符合预期。等流程稳定后再把这些打印去掉或者替换成日志系统。9. 从学习到落地我的建议清单如果你现在准备开始学习 LangGraph并考虑以后把它应用到实际项目里我给出一个比较务实的路线。9.1 学习顺序建议第一周先把环境装好跑通最小智能体。不要急着接复杂工具不要急着上 MCP。重点理解 State、节点、边、条件边。第二周加入工具调用。用一个简单函数作为工具让 Agent 自己决定是否调用、怎么调用。重点理解多轮循环和条件路由。第三周尝试子图和并行分支。找一个真实业务场景比如客服工单分类、自动信息查询、多文档问答把它拆成子图。第四周接 MCP Server把真实业务系统封装成工具接入 Agent。这个顺序的核心理念是每一步都在前一步的基础上增加复杂度。不要跳步。9.2 工程落地时最容易忽略的三件事第一日志记录。Agent 任务是多步骤的一旦结果不对你不知道是模型判断错了还是工具执行错了还是流程编排错了。所以从第一天开始就要记录每个节点的输入输出。第二超时和重试。大模型 API 偶尔会超时工具调用也可能失败。生产环境必须设计超时、重试和失败后的降级策略。否则一个任务跑到一半API 超时整个流程就挂了。第三成本控制。Agent 任务不是一次模型调用而是多次调用。如果不加限制一个复杂任务可能消耗几十次模型调用。所以必须设置最大轮数、最大 Token、工具调用次数等限制。9.3 LangGraph 的边界不可能替代所有方案最后说一点冷静的话。LangGraph 是一个好框架尤其适合中大型复杂智能体应用。但它也有边界简单流程用不上它。需要强人工审批的流程用它来编排可能有点重。如果团队没人熟悉图编排思想学习成本会比直接写代码高。有一些特殊场景普通状态机可能比 LangGraph 更合适。我在实际项目里会根据需求判断用什么方案。不是所有 Agent 都非要用 LangGraph但如果你要做的是复杂 AgentLangGraph 确实是目前生态成熟度较高的选择之一。我的建议是先跑通最小示例再逐步加工具、加 MCP、加条件分支。每一层都要先确认上一步稳定了再继续往下走。踩过几次坑之后你就会发现LangGraph 的复杂度不像很多人说的那么可怕它的核心思想其实就一句话把流程画成图让状态在节点间流动让模型在循环中自主决策。把这句话理解了LangGraph 就算真的入门了。 LangGraph智能体实战：从环境安装到状态管理与核心组件
1. 先搞清楚 LangGraph 到底解决什么问题这两年只要聊 AI 大模型应用开发就绕不开几个词LangChain、LangGraph、MCP、Agent、智能体。很多人一看到这些名词就头大尤其是 LangGraph 和 LangChain 的关系很多人到现在都没分清。这篇文章直接围绕 LangGraph 智能体实战展开从环境安装、核心组件、代码落地到常见坑点按实际开发顺序拆一遍。文章不是官方文档翻译而是我实际跑过之后的理解带有很强的工程判断。先说结论LangGraph 不是 LangChain 的替代品也不是一个新框架来“吊打”谁。LangGraph 是一个专门用来构建有状态、可编排的智能体应用的编排框架。它解决的核心问题是让多个 LLM 调用、工具调用、条件判断和循环逻辑变成一个清晰、可控制、可调试的图结构。你可以把它理解成LangChain 提供了各种零件LangGraph 负责把这些零件按流程串起来并且让流程可控、可回放、可中断、可恢复。很多人和我说为什么不用普通 Python 代码写死流程如果你只是调用一次大模型然后拿结果确实没必要用 LangGraph。但当你需要让模型自己决定下一步调用哪个工具、需要多轮循环、需要根据中间结果走不同分支时普通代码会变得又乱又难维护。LangGraph 的价值就在这里把流程当图画出来把状态当数据传下去把每个节点当成可单独调试的函数。这篇文章适合谁看适合已经用过一点 LangChain但还没搞懂智能体怎么落地的人。也适合刚接触 LangGraph不知道第一步该装什么、怎么写、怎么调试的人。如果你连 Python 环境都没配置过建议先把 Python 基础补一补再回来看这篇文章。最值得你关注的点有三个第一LangGraph 的状态管理到底怎么理解第二节点、边、条件边这些核心概念怎么和实际代码对应第三它和 MCP、LangChain 在一起时分工是什么。这三个问题搞清楚LangGraph 基本就入门了。2. 环境安装准备先把基础环境理干净LangGraph 本地开发环境并没有想象中复杂。我建议不要一上来就搭建大而全的服务架构先把最小环境跑通再往里面加模型、加工具、加 MCP Server。2.1 Python 环境和依赖版本怎么选LangGraph 是基于 Python 的库所以第一步是保证 Python 环境正常。我的建议是直接用 3.10 或 3.11 版本这两个版本对 LangChain 生态兼容性最好。Python 3.12 虽然也能用但有些旧依赖包还没跟上容易出现版本冲突。安装 LangGraph 的命令很简单pip install langgraph只装这个库图编排能力就已经有了。但实际开发智能体还需要 LangChain 生态和模型接入库。所以一般我会一次性把常用依赖装上pip install langchain langchain-core langchain-openai langgraph这里要注意LangChain 版本更新很快接口经常有小变化。如果你网上复制的代码报错先别慌很大概率不是逻辑问题而是版本不匹配。建议安装完以后先执行一下检查命令pip show langgraph langchain langchain-core langchain-openai把版本号记录一下。后面遇到问题排查依赖版本会省很多时间。2.2 模型 API 需要准备什么LangGraph 本身不包含大模型它只是编排框架。真正回答问题、生成内容的是模型。所以你必须先有一个能调用的模型接口。常见选择有三类OpenAI 兼容接口。国内大模型服务一般也提供 OpenAI 兼容接口。本地部署模型比如通过 Ollama 或 vLLM 暴露的接口。我建议第一次学习时直接用 OpenAI 兼容接口因为 LangChain 的支持最成熟出问题也好排查。你需要准备一个 API Key然后在代码里配置环境变量。在 Python 里可以这样临时配置import os os.environ[OPENAI_API_KEY] 你的key在命令行环境里可以这样配置export OPENAI_API_KEY你的key不要在生产代码里写死 Key也不要把 Key 提交到 Git 仓库。这是一个很低级但经常有人犯的错误。2.3 MCP 和 LangChain 需要先装吗先解释一下 MCP。MCP 的全称是 Model Context Protocol中文叫模型上下文协议。它是一个标准化的接口协议用来让大模型应用连接外部工具和数据源。你不需要把 MCP 理解得很玄它本质上就是一套“工具接入标准”。MCP 和 LangGraph 的关系是LangGraph 负责流程编排和状态管理MCP 负责把外部工具暴露成统一接口。两者不冲突可以配合使用。LangChain 生态里也有专门适配 MCP 的工具可以帮你把 MCP Server 暴露的工具变成 Agent 能调用的工具。第一次学习时没必要急着接 MCP。先把 LangGraph 的节点、边、状态跑明白再考虑接入真实工具。如果你一上来就搞十几个 MCP Server问题大概率出在接口协议和参数传递上反而不容易找到根源。注意学习 LangGraph 的顺序强烈建议是“先图和状态再 LangChain 工具最后接 MCP”。跳过前两步直接上 MCP会把简单问题复杂化。3. 核心组件逐个拆解状态、节点、边、条件边LangGraph 最核心的编程模型就是把应用设计成一张图。图里有节点节点之间有边。数据在节点间流动靠的是一个全局状态对象。我第一次看官方文档时最不理解的就是这个 State 概念。后来把代码跑了几遍才明白你可以把 State 理解成一个字典所有节点共享这个字典每个节点都可以读取和修改它。节点之间不直接传参而是通过 State 来传递信息。3.1 State所有节点共享的数据结构在 LangGraph 里State 不是一个普通字典而是一个带有类型定义的数据结构。最简单的写法是使用 TypedDictfrom typing_extensions import TypedDict class AgentState(TypedDict): messages: list current_step: str这里定义了状态里包含两个字段messages 保存对话消息current_step 记录当前流程步骤。为什么用 TypedDict 而不用普通字典因为 LangGraph 需要知道每个字段的类型才能正确处理状态的合并和更新。如果你只写普通字典很多高级功能没法用。3.2 节点真正干活的地方节点就是普通 Python 函数。输入是 State输出是一个字典表示要把哪些字段更新到 State 里。def call_model(state: AgentState): messages state[messages] response chat_model.invoke(messages) return {messages: messages [response], current_step: model_called}这个函数做的事情很简单从 State 里取消息列表调用模型生成回复然后把新消息放回 State同时更新当前步骤。节点函数有几个特点输入参数必须是 State。返回值必须是字典字典的键要和 State 字段对应。不修改 State 本身而是返回要更新的部分。这个“返回更新部分”的设计很关键它让流程变得可追踪。你随时能知道每个节点改了哪些字段。3.3 边和条件边控制流程走向边的作用是连接节点。最简单的边是普通边表示上一个节点执行完以后无条件进入下一个节点。from langgraph.graph import StateGraph, START, END graph StateGraph(AgentState) graph.add_node(call_model, call_model) graph.add_edge(START, call_model) graph.add_edge(call_model, END)这段代码创建了一个最小流程从 START 进入 call_model 节点执行完以后进入 END。真实场景下流程很少这么简单。比如模型决定要调用工具那就要走工具节点如果模型判断已经完成就直接输出结果。这时候就需要条件边。from langgraph.graph import add_conditional_edges def should_continue(state: AgentState): if state[current_step] need_tool: return tool_node else: return end graph.add_conditional_edges( call_model, should_continue, { tool_node: call_tool, end: END } )条件边的作用是根据 State 里的信息决定下一步走哪个节点。它让图有了分支能力这就是“智能体自己决定下一步”的核心机制。3.4 循环智能体反复调用工具的基础很多初学者只理解直线流程不理解为什么需要循环。其实智能体处理复杂任务时往往需要多轮推理和工具调用。比如用户问“帮我查一下天气然后根据天气推荐穿搭”模型可能需要先调用天气查询工具拿到结果后再做下一步判断。这个“判断-调用-再判断”的过程就是通过条件边加上目标节点循环实现的。你可以让 call_model 节点执行完后条件判断是否进入 call_tool 节点执行完工具后把工具结果写回 State再回到 call_model 节点让模型继续推理。graph.add_edge(call_tool, call_model)这样 graph 就形成了循环模型思考 - 工具调用 - 模型再思考。每一次循环State 里的消息列表都在增长模型能看到越来越多的上下文信息。我实际测试时一般会在循环里加一个最大轮数限制避免模型陷入死循环。比如执行超过 10 轮就强制结束。这个在工程上非常必要否则一个 Agent 任务可能无限调用工具消耗大量费用。4. 代码实战从最小智能体开始理论概念看再多不如亲手跑一个能工作的代码。下面我从一个最小智能体开始逐步加功能。4.1 最小可运行示例单节点流程先演示最简单的 LangGraph 流程。这个流程只有一个模型调用节点from typing_extensions import TypedDict from langchain_openai import ChatOpenAI from langgraph.graph import StateGraph, START, END class AgentState(TypedDict): messages: list model ChatOpenAI(modelgpt-4o-mini, temperature0) def call_model(state: AgentState): response model.invoke(state[messages]) return {messages: [response]} graph StateGraph(AgentState) graph.add_node(call_model, call_model) graph.add_edge(START, call_model) graph.add_edge(call_model, END) app graph.compile()运行代码如下result app.invoke({ messages: [{role: user, content: 你好简单介绍一下你自己}] }) print(result[messages][-1].content)执行成功后你会看到模型返回的文本。这个示例虽然简单但完整展示了 LangGraph 的四个关键要素State 定义、节点函数、图构建、编译运行。注意invoke 时的输入结构必须是一个字典字典的键要和 State 字段一致。如果你传了 State 里不存在的字段运行时不会直接报错但后续处理会非常难排查。4.2 加入工具调用让智能体拥有执行能力最小示例跑通后下一步是加入工具调用。这里用 LangChain 的 tool 装饰器来定义一个简单函数from langchain_core.tools import tool tool def get_weather(city: str) - str: 查询指定城市当前的天气情况 return f{city} 今天晴温度 24 度东北风 3 级定义好工具后需要用 bind_tools 把这个工具绑定到模型上model_with_tools model.bind_tools([get_weather])然后修改节点逻辑模型如果认为需要调用工具会返回 tool_calls 信息而不是直接返回内容。def call_model(state: AgentState): response model_with_tools.invoke(state[messages]) return {messages: [response], current_step: model_called}再增加一个工具执行节点def call_tool(state: AgentState): last_message state[messages][-1] tool_calls last_message.tool_calls tool_results [] for tool_call in tool_calls: tool_name tool_call[name] tool_args tool_call[args] result {role: tool, content: str(get_weather.invoke(tool_args)), tool_call_id: tool_call[id]} tool_results.append(result) return {messages: tool_results}这里的核心逻辑是模型返回的 tool_calls 里有函数名、参数和调用 IDAgent 拿到这些信息后去执行真正的工具函数再把执行结果包装成 tool 消息放回 State。图结构变为graph StateGraph(AgentState) graph.add_node(call_model, call_model) graph.add_node(call_tool, call_tool) graph.add_edge(START, call_model) graph.add_conditional_edges( call_model, should_continue, { tool_node: call_tool, end: END } ) graph.add_edge(call_tool, call_model)当工具执行完流程会重新回到 call_model模型看到工具返回结果后再生成最终回答。这就是一个完整的 Agent 循环。4.3 编译和运行用可视化效果加深理解LangGraph 提供了编译后图形的可视化能力。虽然不要求每个人都配置可视化环境但我建议有条件的话试一次。你可以在 Jupyter Notebook 里安装pip install langgraph-cli编译后的图对象可以生成一个简单的图结构表示。真实工程里用可视化来检查流程分支是否合理比自己死盯着代码高效得多。第一次跑完整代码时如果结果不对我建议按这个顺序排查是否正常打印出模型最终回答。是否输出了 tool_calls 内容。工具函数是否真的被调用。State 里的 messages 是否完整。大部分问题都出在工具调用的消息格式上尤其是 tool_call_id 必须和模型返回的 ID 严格一致。5. LangGraph、LangChain、MCP 三者怎么分工很多人的困惑在于这三个概念重叠不知道什么时候用哪个。我用工程场景来拆解一下。5.1 LangChain工具库和组件生态LangChain 提供了大量可复用的组件比如模型接口封装、Prompt 模板、文档加载器、向量存储、工具封装等。你可以把 LangChain 理解成一个零件库里面有很多现成的积木。但 LangChain 本身不擅长编排复杂流程。早期版本用 AgentExecutor 来做 Agent但它的流程控制能力很弱一旦业务逻辑复杂就很难维护。5.2 LangGraph流程编排和控制LangGraph 的作用是补充 LangChain 在这方面的短板。它提供了图结构、状态管理、条件分支、循环、断点、持久化等机制适合构建复杂的 Agent 应用。用一句话总结LangChain 提供能力LangGraph 编排能力。LangGraph 的代码里经常导出来自 langchain 的模型和工具类两者是配合关系不是竞争关系。5.3 MCP外部工具接入标准MCP 的定位又不一样。它解决的是工具接入的标准化问题。比如你的系统要接企业内部 API、数据库、文件系统每个系统如果都要单独写适配代码改起来很麻烦。MCP 把这些工具封装成统一协议Agent 侧只要实现 MCP Client就能调用任意 MCP Server 暴露的工具。三者配合时一个典型的架构是使用 LangChain 的 ChatOpenAI 等组件接入大模型。使用 LangGraph 编排 Agent 的思考、推理、工具调用循环。使用 MCP Server 暴露外部系统能力通过 MCP 适配器转换成 LangChain Tool。这个架构下LangGraph 是“大脑的思维流程”LangChain 是“四肢的工具组件”MCP 是“连接外部世界的标准接口”。5.4 什么时候不需要 LangGraph不是所有 AI 应用都需要上 LangGraph。如果你只是做一个简单的问答接口用户发一句话模型回一句话那就没必要引入图编排。直接调用模型 API 反而更简单。判断标准很简单如果流程是固定的直线且不需要循环、不需要条件分支、不需要模型自主决策就用最简单的方式实现。LangGraph 的复杂度只有在流程复杂时才是值得的。6. 进阶玩法条件路由、子图和并行分支跑通最小智能体后再往深走LangGraph 还有几个比较重要的能力条件路由、子图和并行分支。这些是面试和工程实战里经常提到的点。6.1 条件路由和分支控制条件路由就是根据当前状态让流程走不同分支。比如一个客服智能体用户问“查订单”就走订单查询子流程用户问“退货”就走退货流程。条件路由的核心是 conditional_edges。你写一个函数输入 State输出下一个节点的名称。LangGraph 会根据函数返回值把流程引导到对应节点。def route_by_intent(state: AgentState): intent state.get(intent, general) if intent order: return order_node elif intent refund: return refund_node else: return general_node这种写法代码可读性很高而且后续加新意图分支很容易只要扩展映射字典就行。实际使用中要注意路由函数的判断逻辑不要依赖模型输出里的自由文本最好有结构化的意图识别结果。否则分支很多时模型判断不稳定流程容易走错。6.2 子图把复杂流程拆小子图就是图里面套图。当一个主流程太复杂时可以把一部分节点封装成子图子图内部有自己的状态和边。subgraph StateGraph(SubState) # ... 添加子图节点和边 sub_app subgraph.compile() main_graph StateGraph(MainState) main_graph.add_node(sub_task, sub_app)子图的好处是模块化。每个子图负责一个独立业务域主图只负责流程调度。调试时可以单独运行子图不用每次跑完整流程图。我在实际项目里一般会把“意图识别”“工具调用”“结果整理”分别做成子图。这样代码结构清楚多人协作时也方便分工。6.3 并行分支LangGraph 支持一个节点同时连通多个后续节点。如果你的智能体需要同时查询天气、查询航班、查询酒店就可以在工具调用节点后面接多个并行节点。并行分支能提升效率因为多个工具调用可以并发执行而不是串行等待。但要注意并行时 State 的更新要小心多个节点同时修改同一个字段会产生冲突。LangGraph 提供了一些合并机制但最稳妥的方式是让不同并行节点更新不同字段。我第一次写并行分支时踩过一个坑两个并行节点都修改“messages”字段结果只有一个节点的新消息保留下来了。后来改成各自维护独立的字段再统一合并问题就解决了。7. 实战中的资源占用与性能判断LangGraph 本身不消耗多少资源它只是一个流程引擎。真正的资源大头在模型调用和工具执行。7.1 显存内存占用看什么如果你用的是云端模型 API那本地的资源消耗非常低基本就是 Python 进程和网络请求。内存占用一般在几百 MB 到 1GB取决于你加载的依赖数量。如果你用的是本地模型那就要重点看显存。这里给出一个通用参考模型规模显存需求量化后说明1.5B 级别2GB - 4GB轻量任务足够7B 级别6GB - 10GB中等任务可用14B 级别12GB - 20GB推荐 A 级显卡70B 级别40GB 以上需要多卡或大显存低显存环境也能跑 LangGraph但要把模型换小或者把并发数降低。LangGraph 的 Agent 循环里有多个模型调用如果你同时开多个任务本地模型可能会被排队机制拖慢。7.2 速度不只看模型推理很多初学者以为 Agent 慢是因为模型慢。其实不一定。Agent 任务里模型可能被调用多次。每次调用都需要几百毫秒到几秒多轮循环叠加后整体耗时就上去了。我一般会统计两个指标单次模型调用平均耗时。完成一个完整 Agent 任务的总耗时。如果总耗时远大于单次耗时乘以调用次数那就要检查是不是工具调用卡住了、网络超时了、或者输出队列阻塞了。7.3 怎么判断稳定不稳定稳定性判断不能只看一次运行。我用 LangGraph 跑批量任务时会连续跑 20 到 50 条样本然后统计成功率完成多少条失败多少条。平均耗时所有任务的平均时长。超时数量超过设定时间的任务有多少。失败原因分布是模型报错、工具错误、还是流程卡住。只有这些指标都合理才说明 Agent 应用可以进入批量环境。8. 常见报错和排查顺序最后系统整理一下 LangGraph 实战里最常见的报错和排查思路。这些坑我自己基本都踩过写出来帮你少走弯路。8.1 最常见的几类问题第一类依赖版本冲突。典型现象是 import 时报错比如找不到某个模块或者某个函数参数不匹配。原因基本都是 LangChain、LangGraph、langchain-openai 版本不一致。解决办法是统一升级到兼容版本或者安装前先看官方文档的版本要求。第二类状态字段定义错误。典型现象是节点函数返回的字典里键名和 State 定义的字段不一致。LangGraph 不会自动创建新字段所以你会发现在某个节点写进去的数据下一个节点读不到。解决办法是打印 State 内容检查字段名是否完全一致。第三类工具调用消息格式错误。典型现象是模型调用了工具但工具执行时报错或者 Agent 看不到工具结果。主要原因一般是 tool_call_id 对不上或者工具结果没有使用 role“tool” 的消息格式。这个在 LangChain 的版本更新中经常变化务必查阅对应版本文档。第四类条件边配置错误。典型现象是流程走到了不存在的节点或者一直停在某个节点不往下走。解决办法是检查条件路由函数的返回值确认返回的字符串和映射字典里的键完全一致。第五类无限循环。典型现象是任务一直不结束日志里不断出现工具调用。解决办法是设置最大递归轮数或者设置超时时间。app graph.compile() result app.invoke( {messages: [{role: user, content: 请查询上海天气并推荐穿搭}]}, config{recursion_limit: 20} )我在代码里一般都会设置 recursion_limit这个参数表示流程最多执行多少个节点步骤超过后强制停止。否则模型一旦陷入循环既浪费费用又浪费时间。8.2 排查顺序先现象后原因遇到 LangGraph 项目报错或结果异常我建议按这个顺序排查先看报错信息在哪一层。是 import 阶段、编译阶段、还是运行阶段。再看输入数据。State 初始值是否完整messages 格式是否正确。再看节点函数。每个节点是否都正确返回了字典字段名是否和 State 一致。再看图的连接。条件路由的返回值是否在映射字典里边是否闭环。最后看模型返回。模型是否输出了标准格式的 tool_calls工具执行结果是否写回 State。不要一上来就怀疑 LangGraph 有 Bug。绝大多数问题出在自己的状态定义、消息格式和路由配置上。8.3 调试时的小技巧调试 LangGraph 项目时我一般会在节点函数里面加打印语句把 State 的核心字段打出来。虽然不够优雅但非常有效。def call_model(state: AgentState): print( call_model state ) print(messages count:, len(state[messages])) response model_with_tools.invoke(state[messages]) print(response type:, type(response)) print(has tool_calls:, bool(getattr(response, tool_calls, None))) return {messages: [response]}这样你能清楚看到每个节点输入输出是否符合预期。等流程稳定后再把这些打印去掉或者替换成日志系统。9. 从学习到落地我的建议清单如果你现在准备开始学习 LangGraph并考虑以后把它应用到实际项目里我给出一个比较务实的路线。9.1 学习顺序建议第一周先把环境装好跑通最小智能体。不要急着接复杂工具不要急着上 MCP。重点理解 State、节点、边、条件边。第二周加入工具调用。用一个简单函数作为工具让 Agent 自己决定是否调用、怎么调用。重点理解多轮循环和条件路由。第三周尝试子图和并行分支。找一个真实业务场景比如客服工单分类、自动信息查询、多文档问答把它拆成子图。第四周接 MCP Server把真实业务系统封装成工具接入 Agent。这个顺序的核心理念是每一步都在前一步的基础上增加复杂度。不要跳步。9.2 工程落地时最容易忽略的三件事第一日志记录。Agent 任务是多步骤的一旦结果不对你不知道是模型判断错了还是工具执行错了还是流程编排错了。所以从第一天开始就要记录每个节点的输入输出。第二超时和重试。大模型 API 偶尔会超时工具调用也可能失败。生产环境必须设计超时、重试和失败后的降级策略。否则一个任务跑到一半API 超时整个流程就挂了。第三成本控制。Agent 任务不是一次模型调用而是多次调用。如果不加限制一个复杂任务可能消耗几十次模型调用。所以必须设置最大轮数、最大 Token、工具调用次数等限制。9.3 LangGraph 的边界不可能替代所有方案最后说一点冷静的话。LangGraph 是一个好框架尤其适合中大型复杂智能体应用。但它也有边界简单流程用不上它。需要强人工审批的流程用它来编排可能有点重。如果团队没人熟悉图编排思想学习成本会比直接写代码高。有一些特殊场景普通状态机可能比 LangGraph 更合适。我在实际项目里会根据需求判断用什么方案。不是所有 Agent 都非要用 LangGraph但如果你要做的是复杂 AgentLangGraph 确实是目前生态成熟度较高的选择之一。我的建议是先跑通最小示例再逐步加工具、加 MCP、加条件分支。每一层都要先确认上一步稳定了再继续往下走。踩过几次坑之后你就会发现LangGraph 的复杂度不像很多人说的那么可怕它的核心思想其实就一句话把流程画成图让状态在节点间流动让模型在循环中自主决策。把这句话理解了LangGraph 就算真的入门了。