如果你是一个用 LangChain 写过 Agent 的开发者大概率会遇到这几个问题Agent 一旦涉及多个步骤逻辑就散落在各种回调、循环、判断里根本没法维护想给 Agent 加一个“先查资料、再决定调用哪个工具”的流程用 Chain 写出来像一团乱麻当 LLM 需要对接企业内部的数据库、设计稿、IDE 时工具接入方式五花八门换一个场景就要重写一遍对接代码。这篇文章不打算复读 LangChain 的官方文档。我想从一个工程视角说清楚LangGraph 到底解决了什么、它和 LangChain、MCP 是什么关系、以及你如何从零开始用它写出一个真正可控、可调试、可扩展的 Agent。如果你正处于“会用 LangChain 写 Chain但不知道怎么管理复杂 Agent 状态”的阶段这篇文章会非常合适。全程包含环境搭建、最小示例、条件路由、子图分支、MCP 工具接入和完整实战建议收藏后跟着敲一遍。1. 为什么要关注 LangGraphAgent 开发的核心痛点先说一个很容易被忽略的事实LangChain 早期最擅长的东西是“链式调用”而不是“Agent 编排”。什么叫链式调用就是“先做 A再做 B最后做 C”的线性流程。比如先检索文档再把检索结果拼进 Prompt最后调用 LLM 生成回答。这个流程用 LangChain 的 LCEL 表达式写起来非常舒服chain retriever | prompt | llm | output_parser但真实业务里Agent 很少是线性的。它会遇到这些场景根据用户的输入决定走“查天气”分支还是“订机票”分支根据 LLM 输出的 Tool Call 结果决定是否再次调用模型多个子任务可以并行执行最后汇总结果Agent 运行过程中出错需要重试或者回退到上一步整个运行过程需要保留历史状态而不是每次调用都从零开始。如果你尝试用传统的 LangChain Chain 去实现这些需求你会发现代码很快就变成了一堆if-else和循环嵌套。更麻烦的是状态管理完全靠手动传递变量一旦流程复杂起来你根本不知道当前 Agent 已经执行到哪一步、中间结果放在了哪里。LangGraph 的定位就是解决这个问题它把 Agent 的运行过程抽象成一张有向图节点是业务逻辑边是流转控制状态是节点之间共享的数据载体。换句话说LangGraph 把“写可控 Agent”这件事从“拼 Prompt 调工具”的层面拉到了“编排状态机”的工程层面。这才是它和 LangChain 最本质的区别。2. LangGraph、LangChain、MCP 的区别与定位很多初学者看到 LangGraph、LangChain、MCP 三个词放在一起容易产生混乱。这里用一个类比帮你快速建立框架LangChain是“工具箱”提供 LLM 调用封装、Prompt 模板、输出解析、文档加载器等基础能力LangGraph是“流水线控制系统”负责编排 Agent 的执行流程决定什么时候调用工具、什么时候调用模型、出错怎么重试MCP是“万能插座标准”让 Agent 能统一对接各种外部工具和数据源而不是为每个工具写一套私有对接逻辑。三者不是替代关系而是分层协作的关系。用一张表格来看更清晰技术核心定位解决什么问题典型使用方式LangChainLLM 应用开发框架封装模型调用、Prompt、RAG、工具调用等基础能力写 Chain、封装 Tool、管理模型实例LangGraph智能体编排框架Agent 状态管理、分支控制、循环、子图、并行执行用 StateGraph 构建可执行的 Agent 工作流MCP工具接入协议统一 Agent 与外部工具的交互方式定义 Tool Server、通过 Client 连接工具这里还要顺带说一下很多人问的另一个问题Agent Skill 和 MCP 有什么区别简单理解Skill 是 Agent 的“技能包”通常包含一组指令、Prompt 策略和示例目的是让模型学会做某一类事情MCP 是“工具接口”解决的是 Agent 如何调用外部系统的问题。Skill 偏向于“增强模型能力”MCP 偏向于“扩展工具连接”。两者可以共存Agent 先用 Skill 学会判断再通过 MCP 去执行具体动作。3. 环境准备与最小依赖安装在动手写代码之前先把环境准备好。以下所有示例基于 Python 3.10如果你本机版本较低建议先用 conda 或 venv 创建虚拟环境。python -m venv langgraph-demo source langgraph-demo/bin/activate # Windows 下使用 langgraph-demo\Scripts\activate安装核心依赖pip install --upgrade langgraph langchain langchain-openai这里说明一下最新版 LangGraph 已经可以脱离 LangChain 独立使用但实际工程中两者配合最顺畅所以建议一起安装。如果你后面要接入 MCP 工具还需要安装适配器pip install langchain-mcp-adapters mcp版本方面可以安装时查看当前最新稳定版本文示例以通用 API 为准不绑定某个具体小版本。安装完成后验证一下版本python -c import langgraph; print(langgraph.__version__)如果你看到版本号正常输出说明环境已经就绪。4. 第一个最小示例用 StateGraph 构建你的首个 Agent直接看代码。LangGraph 的核心概念只有三个State状态、Node节点、Edge边。State一张全局共享的状态表所有节点都能读取和写入Node一个普通的 Python 函数接收 State 并返回更新后的状态Edge连接节点决定流程走向。4.1 定义状态# 文件路径demo/state_demo.py from typing import TypedDict, Annotated from langgraph.graph import StateGraph class AgentState(TypedDict): messages: Annotated[list, append] next_step: str这里的Annotated[list, append]表示messages字段在多个节点执行时使用“追加”而不是“覆盖”的方式更新。这是 LangGraph 状态管理里最容易忽略的细节之一。4.2 定义节点def step_one(state: AgentState): print(Step one, current next_step:, state[next_step]) return {messages: [step_one done], next_step: step_two} def step_two(state: AgentState): print(Step two, current next_step:, state[next_step]) return {messages: [step_two done], next_step: end}每个节点就是普通的 Python 函数入参是当前状态字典返回值是会合并进全局状态的字段。这种设计最大的好处是节点本身不需要关心整个图的结构只关注自己的输入输出。4.3 构图并运行def build_graph(): graph StateGraph(AgentState) # 添加节点 graph.add_node(step_one, step_one) graph.add_node(step_two, step_two) # 入口和出口 graph.set_entry_point(step_one) graph.set_finish_point(step_two) # 添加边 graph.add_edge(step_one, step_two) return graph.compile() if __name__ __main__: app build_graph() result app.invoke({ messages: [], next_step: start }) print(Final state:, result)运行结果Step one, current next_step: start Step two, current next_step: step_two Final state: {messages: [step_one done, step_two done], next_step: end}这个最小示例看起来很简单但它已经完整具备了 LangGraph 的核心运行机制状态初始化 - 节点执行 - 返回值合并 - 边决定下一个节点。后面的所有复杂功能都是在这个基础上扩展出来的。5. 条件路由与分支控制Conditional Edge 深度解析如果只是线性执行LangGraph 相比普通 Chain 的优势还不明显。真正拉开差距的是条件路由。场景你希望 Agent 根据用户的问题自动决定走“天气查询分支”、“新闻查询分支”还是“闲聊分支”。用 LangGraph 可以这样做。5.1 定义路由函数路由函数接收状态返回下一个节点名称def route_by_keyword(state: AgentState): user_input state[messages][-1].lower() if 天气 in user_input: return weather_node elif 新闻 in user_input: return news_node else: return chat_node5.2 在图中使用条件边def build_router_graph(): graph StateGraph(AgentState) graph.add_node(weather_node, lambda state: {next_step: weather done}) graph.add_node(news_node, lambda state: {next_step: news done}) graph.add_node(chat_node, lambda state: {next_step: chat done}) graph.set_entry_point(router) # 关键条件边 graph.add_conditional_edges( router, # 从哪个节点出发 route_by_keyword, # 路由逻辑函数 { weather_node: weather_node, news_node: news_node, chat_node: chat_node, } ) graph.set_finish_point(weather_node) graph.set_finish_point(news_node) graph.set_finish_point(chat_node) return graph.compile()add_conditional_edges接受三个参数起始节点路由函数接收state返回一个字符串键映射表字符串键对应下一个实际节点。这套机制的价值在于流程的控制权从硬编码的if-else转移到了可配置的图结构上。你新增一个分支只需要加一个节点、加一个键值映射不需要改动其他节点代码。5.3 结合 LangChain 的 Tool Calling在实际 Agent 中路由判断通常不是靠关键词而是靠 LLM 自主决定是否调用某个工具。LangGraph 官方推荐的做法是让 LLM 输出 Tool Call然后把 Tool Call 作为路由依据。from langchain_openai import ChatOpenAI from langgraph.prebuilt import ToolNode llm ChatOpenAI(modelgpt-4o, temperature0) # 先让模型决定调用哪个工具 tools [get_weather_tool, get_news_tool] llm_with_tools llm.bind_tools(tools) def model_node(state: AgentState): response llm_with_tools.invoke(state[messages]) return {messages: [response]} # 路由函数判断是否需要执行工具 def should_continue(state: AgentState): last_message state[messages][-1] if last_message.tool_calls: return tools return END这是一个非常典型的 ReAct 模式模型决定调用工具工具执行结果再返回给模型直到模型认为可以输出最终答案。LangGraph 把这种“循环”变成了图结构中的一条环状边。6. 循环、子图与并行分支6.1 循环让 Agent 可以反复调用工具LangGraph 支持环状边也就是一个节点可以回到之前的节点。这个能力让 Agent 不再是一次性流水线而是可以反复迭代。graph.add_edge(tools, model) # 工具执行完回到模型继续决策 graph.add_conditional_edges( model, should_continue, { tools: tools, END: __end__, } )这里的__end__是 LangGraph 预定义的特殊节点表示流程结束。循环最重要的工程价值是Agent 可以自主决定“调用几次工具”而不是在代码里写死。6.2 子图把复杂流程拆成可复用的模块当流程图变得很大时全部塞进一个文件会很痛苦。LangGraph 提供了子图机制把你的核心功能封装成独立对象。子图本质也是一个编译好的StateGraph只是它可以作为普通节点嵌入到父图中。def build_subgraph(): sub StateGraph(AgentState) sub.add_node(sub_step1, sub_step1) sub.add_node(sub_step2, sub_step2) sub.add_edge(sub_step1, sub_step2) sub.set_entry_point(sub_step1) sub.set_finish_point(sub_step2) return sub.compile()在父图中直接添加子图graph.add_node(nested_flow, build_subgraph())6.3 并行分支提高执行效率当你需要对同一批数据执行多个互相独立的任务时可以使用扇出结构。LangGraph 的节点返回一个Send对象可以动态创建多个并行任务。from langgraph.types import Send def fan_out(state: AgentState): return [ Send(analysis_node, {segment: seg}) for seg in state[items] ]并行分支在实际生产环境中很有用。比如用户上传 10 份文档Agent 可以并行解析每一份最后合并结果而不是一份一份串行处理。7. MCP 接入让 Agent 具备标准工具能力7.1 MCP 解决的核心问题在 MCP 出现之前Agent 每对接一个工具几乎都要写一套专属的工具调用代码图床有图床的 API、数据库有数据库的驱动、设计工具有设计工具的协议。MCP 把这套过程标准化了。它定义了两个角色MCP Server暴露工具能力的一方比如一个提供“查询天气”功能的服务MCP Client调用工具的一方比如 LangGraph Agent。Agent 只要实现了 MCP Client 协议就可以动态发现并调用任何兼容的 MCP Server。这就是为什么 MCP 被认为是 Agent 生态里的“USB-C 标准”。7.2 一个简单的 MCP Server 示例先写一个最简 MCP Server基于 Python SDK# 文件路径mcp_server/weather_server.py from mcp.server.fastmcp import FastMCP mcp FastMCP(WeatherServer) mcp.tool() def get_weather(city: str) - str: 查询某个城市的天气情况 # 真实项目中这里会调用天气服务 API return f{city} 的天气是晴朗气温 26 度 if __name__ __main__: mcp.run()启动服务python mcp_server/weather_server.py7.3 在 LangGraph Agent 中接入 MCP ServerLangGraph Agent 可以通过langchain-mcp-adapters来加载 MCP 工具。以下是一个通过标准输入输出stdio连接本地 MCP Server 的例子# 文件路径demo/mcp_agent.py from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client from langchain_mcp_adapters.tools import load_mcp_tools from langgraph.prebuilt import create_react_agent from langchain_openai import ChatOpenAI server_params StdioServerParameters( commandpython, args[mcp_server/weather_server.py], ) async def build_mcp_agent(): async with stdio_client(server_params) as (read, write): async with ClientSession(read, write) as session: tools await load_mcp_tools(session) model ChatOpenAI(modelgpt-4o) agent create_react_agent(model, tools) return agent注意由于 MCP 连接通常涉及异步操作生产环境建议把这部分逻辑封装在 Async 接口中避免阻塞 Agent 主流程。7.4 远程 MCP Server 的注意点远程 MCP 服务通过 HTTP/SSE 等方式传输。实际项目中安全性是第一位的必须先确认服务方身份和鉴权方式不要将内部 API Key 直接暴露给远程 MCP 工具建议通过网关做流量审计和白名单控制。从当前生态看MCP 的接入方式还在快速演进不同 SDK 的 API 名称会略有差异。核心学习目标是理解“工具发现、调用、返回”这三段式交互而不是死记某个方法名。8. 完整实战构建一个“检索 工具调用”的 Agent下面把前面所有内容串起来完成一个综合示例。场景是用户提问时Agent 先判断是否需要搜索外部信息如果需要就调用搜索工具最后生成回答。8.1 定义工具和状态# 文件路径demo/full_agent.py from typing import TypedDict, Annotated from langgraph.graph import StateGraph, END from langgraph.prebuilt import ToolNode from langchain_openai import ChatOpenAI from langchain_core.messages import HumanMessage class AgentState(TypedDict): messages: Annotated[list, append]8.2 定义搜索工具def search_web(query: str) - str: 模拟搜索接口实际项目中可替换为真实搜索 API return f关于“{query}”的搜索结果LangGraph 是用于构建状态化 Agent 的编排框架。 tools [search_web] tool_node ToolNode(tools)8.3 构建模型节点和路由llm ChatOpenAI(modelgpt-4o) model_with_tools llm.bind_tools(tools) def call_model(state: AgentState): response model_with_tools.invoke(state[messages]) return {messages: [response]} def should_continue(state: AgentState) - str: last_message state[messages][-1] if last_message.tool_calls: return tools return end8.4 组合成图def build_full_agent(): graph StateGraph(AgentState) graph.add_node(agent, call_model) graph.add_node(tools, tool_node) graph.set_entry_point(agent) graph.add_conditional_edges( agent, should_continue, { tools: tools, end: END, } ) graph.add_edge(tools, agent) return graph.compile() if __name__ __main__: app build_full_agent() result app.invoke({ messages: [HumanMessage(content请帮我搜索 LangGraph 是什么)] }) for msg in result[messages]: print(f{msg.type}: {msg.content})运行后你会看到类似输出human: 请帮我搜索 LangGraph 是什么 ai: 工具调用结果... tool: 关于“LangGraph 是什么”的搜索结果... ai: LangGraph 是一个用于构建状态化 Agent 的编排框架...这个 Agent 的核心特征是模型自己决定是否搜索、搜索什么、什么时候结束。你不需要编写任何硬编码的业务分支逻辑。9. 常见问题与排查思路实际运行 LangGraph 时常见问题主要集中在状态更新、工具调用格式和环境版本上。问题现象可能原因排查方式解决方案节点返回值没有生效State 字段使用覆盖更新而手动写成了 append检查 TypedDict 里的 Annotated 修饰需要追加时使用Annotated[list, append]条件路由无法匹配路由函数返回的 key 不在映射表中打印路由函数返回值检查映射表是否包含所有返回键工具调用报错 tool_calls 不存在模型没有成功绑定工具打印model_with_tools配置确认bind_tools是否生效MCP 工具加载失败本地 Server 启动失败或通讯协议不匹配单独启动 Server 测试检查 stdio 参数和 Server 日志图编译时报错有节点没有可达路径排查所有边的连接关系使用get_graph().draw_mermaid()可视化检查状态中的消息顺序混乱多个节点同时修改 messages打印执行过程中每一步的状态统一使用 append 更新语义如果运行出错第一步永远是看两样东西错误堆栈中提到的节点名称以及当前状态字典的完整内容。LangGraph 的报错一般都会明确指出是哪个节点执行失败这对定位问题非常有效。10. 最佳实践与工程建议从学习到生产环境落地以下几点值得认真对待。10.1 将每个节点设计成纯函数节点函数不要依赖外部可变全局变量尽量只用 State 作为输入并通过返回值改变状态。这样做的好处是流程可以回溯、可以测试、可以并行。10.2 为状态字段设计明确语义状态结构是 LangGraph 工程的“数据库设计”。建议用messages保存对话消息用intermediate_result保存中间结果用metadata保存执行上下文如用户 ID、请求 ID。10.3 善用 LangGraph 的持久化和恢复能力检查点是 LangGraph 一个重要的工程能力。启用检查点后Agent 可以在任意节点暂停、恢复这为“人工审核后继续执行”提供了基础。from langgraph.checkpoint.memory import MemorySaver checkpointer MemorySaver() app graph.compile(checkpointercheckpointer) # 运行后记录 thread_id之后可以恢复 config {configurable: {thread_id: user-session-1}}生产环境建议使用数据库类型的检查点实现如 PostgresSaver因为内存检查点重启后会丢失。10.4 安全边界涉及数据库操作、文件系统访问、外部支付等敏感工具时必须在工具函数内部做权限校验。LangGraph 本身只负责流程编排不负责鉴权。工具调用前应确认当前用户是否有权限执行该工具输入参数是否经过合法性校验是否需要进行操作审计是否配备回滚预案。10.5 不要为简单场景引入 LangGraph如果业务流程只有三五个步骤、没有分支循环用普通 Chain 或直接调用 LLM 更合适。LangGraph 的图模型适合的是“可能发生回路、需要状态管理、需要人工介入”的复杂场景。为简单项目强行引入图编排只会增加维护成本。11. 总结与后续学习方向写到这里LangGraph 的核心内容已经完整覆盖了一遍State、Node、Edge 的基础模型条件路由与分支控制循环机制子图拆解并行执行以及 MCP 工具接入。这些内容组合起来足够支撑你搭建一个可用的生产级 Agent 原型。如果你接下来想继续深入建议按这个顺序走把文中的最小示例和实战 Agent 完整跑通尝试用 LangGraph 复刻一个带有“人工确认节点”的审批流程感受检查点恢复的价值将 MCP 从本地 stdio 扩展为远程服务理解工具接入的标准化过程深入研究 LangGraph 的持久化方案和流式输出这两个能力在高并发生产环境中至关重要。很多人学 LangGraph 容易陷入一个误区上来就研究各种高级 API结果连状态模型都没理解透。其实 LangGraph 的设计哲学很简单——把 Agent 当成一张可以动态执行的图节点只做一件事边决定下一步去哪。理解了这个心智模型再看任何官方文档都会轻松很多。最后想多说一句无论你用什么框架真正决定 Agent 上限的仍然是你对业务流程的理解以及对状态、错误、权限这些工程细节的把控。框架只是让这些控制变得更加清晰和可维护。希望这篇教程能帮你把 LangGraph 这块硬骨头啃下来后续遇到复杂的 Agent 业务场景至少心里已经有了一张图。