从“能跑通 Demo”到“敢上生产环境”中间隔着一条完整的 Agent 工程化路线。很多人学 LangChain 时觉得很简单封装了模型调用、内置了工具调用、文档里全是现成示例。但真到写一个多步骤、有状态、需要稳定输出和异常恢复的 Agent 时才发现 LangChain 给的只是零件不是整机。这正是 LangGraph 出现的原因。它不替代 LangChain而是把 LangChain 里那些“自由发挥”的编排逻辑用图结构重新组织起来让 Agent 从“一条链跑到底”变成“一张图可控流转”。这篇文章会围绕 LangChain LangGraph 这条当前最主流的技术主线说清楚两者的真正分工、全套学习路径、从零开始的项目实战思路以及从个人项目走向企业级 Agent 时需要补上的工程能力。无论你是刚开始接触 AI Agent 开发还是已经用 LangChain 写过几个 Demo 但总觉得差点意思这篇文章都值得收藏作为一份路线参考。1. 这篇文章真正要解决的问题先给出一个明确判断LangChain 解决的是“Agent 能连接什么”LangGraph 解决的是“Agent 应该如何流转”两者组合在一起才是当下 AI Agent 开发最值得先掌握的技术栈。很多初学者容易陷入两个极端。第一个极端是把 LangChain 当成万能框架。看到 LangChain 里有 Agent、有 Tool、有 Memory就觉得已经会做 Agent 了。结果一写复杂业务流程就卡住顺序执行、条件分支、循环重试、人工审批中断这些真实业务里的高频需求在 LangChain 原生链式结构里非常别扭。第二个极端是过早追求“手写一切”。觉得 LangChain 太重、太抽象不如直接调大模型 API 自己写循环。这个思路在单个 Agent 原型阶段可行但一旦需要多个 Agent 协作、需要人机协同审批、需要把每一步执行状态持久化恢复自己维护状态机和持久化逻辑的成本会迅速失控。这篇文章要解决的就是横亘在这两个极端之间的中间地带LangChain 和 LangGraph 到底是什么关系各自负责哪一层从零开始学 Agent 开发的正确路线避免被版本更新和概念轰炸带偏一个完整的最小实战项目应该包含哪些模块从“能跑”到“企业级可用”之间到底差在哪几步。如果此刻你正在规划 2026 年的技术学习路线或者团队准备启动一个 Agent 项目但还没定好技术方案这篇文章适合你完完整整读一遍。2. LangChain、LangGraph、Agent 到底是什么关系很多资料把这几个概念混在一起讲导致新手越看越乱。实际上从架构分层来看非常清晰。2.1 LangChain面向大模型应用的开发工具集LangChain 从 2022 年底开始流行它出现的背景是大模型 API 开始普及但开发者发现直接调用 API 写应用存在大量重复工作Prompt 模板拼接、输出解析、外部工具调用、记忆管理、各种模型厂商的接口差异。LangChain 解决的是这些问题。它提供了一套统一的抽象让开发者可以用相对一致的方式对接不同模型、构建 Prompt、调用工具、管理对话历史。但 LangChain 的核心抽象是 Chain链默认思维是“线性执行”一步做完做下一步。真实业务不可能永远线性当出现“根据上一步结果决定走哪条分支”“某一步失败需要重试”“多个人工节点并行处理”时Chain 模型就不够用了。2.2 LangGraph面向 Agent 流程编排的图执行框架LangGraph 是 LangChain 团队推出的专门用于构建有状态 Agent 的编排框架。它的核心抽象是 Graph图节点是逻辑单元边是流转关系状态是共享数据。用图来表达流程好处非常直接支持条件分支支持循环支持并行节点需要相应运行环境支持支持人工介入节点支持状态持久化和断点恢复每一步执行过程可观测。这些能力正是企业级工作流和高复杂度 Agent 所需要的。LangGraph 不是要取代 LangChain 的模型封装、工具封装能力而是在更上层把“流程怎么走”这件事管起来。2.3 Agent一种以模型为决策核心的应用形态Agent 本身不是某个具体框架而是一种应用范式让大模型根据用户目标和当前上下文自主决定调用哪些工具、按照什么顺序执行、如何判断任务是否完成。传统程序的控制流是开发者写死的Agent 应用的控制流则部分是模型根据输入动态生成的。这既是 Agent 的灵活性来源也是不可靠性的根源。所以真实项目里Agent 绝不会是“模型完全自由发挥”而是开发者用 LangGraph 这样的框架把关键的流转路径、边界条件、安全护栏都定义清楚模型只在允许的范围内做决策。三者关系用一句话概括LangChain 提供零件库LangGraph 提供装配线和控制台Agent 是最终交付的机器。3. Agent 开发学习路线从 0 到 1 再到生产结合当前社区热度与招聘市场的情况Agent 开发的学习路线可以拆成四个阶段。3.1 第一阶段掌握大模型基础调用不依赖任何框架至少会用一种编程语言直接调用大模型 API。这一阶段要理解System Prompt、User Prompt、Assistant 消息的角色区别Temperature、Top_p 等采样参数的作用上下文长度对输入输出的影响什么是函数调用Function Calling或工具调用Tool Calling这是 Agent 的底层能力。不要跳过直接上手 LangChain否则后面排查问题时你会分不清是框架的问题还是模型调用的问题。3.2 第二阶段学习 LangChain 核心模块LangChain 的核心模块包括 Models、Prompts、Parsers、Tools、Memory、Chains。这个阶段以“会用”为目标能用 LangChain 统一调用不同模型能写 Prompt 模板并解析模型输出能把自定义 Python 函数包装成 Agent 工具能维护多轮对话上下文。不建议在这个阶段研究过于复杂的 Chain 组合方式。记住LangChain 在这里是帮你省时间的工具层。3.3 第三阶段学习 LangGraph 编排能力这是 Agent 开发真正的分水岭。需要掌握StateGraph 状态图定义Node 和 Edge 的写法条件边的判断逻辑State 的数据结构设计记忆和持久化配置断点续跑与人工审批节点。学完这一阶段你应该能实现一个带循环判断和外部工具调用的 ReAct 风格 Agent并且能清楚讲出每一步的执行状态。3.4 第四阶段企业级工程化技术社区称之为“AI 工程化”或“LLMOps”。这一阶段关注的不再是某个框架的 API而是模型成本控制与 Token 用量监控Agent 执行日志与追踪工具权限管理与安全边界大规模并发下的限流与降级效果评测与回归测试多环境部署与版本回滚。如果能按这个顺序学完再去看各类 LangChain / LangGraph 视频课程或实战项目你会很清楚自己处在哪个阶段、缺的是哪块能力。4. 环境准备与基础依赖安装开始写代码之前先把基础环境准备好。4.1 运行环境依赖项建议版本/说明操作系统Windows 10/11、macOS、主流 Linux 均可Python3.10 或更高版本部分最新特性需要 3.11包管理器推荐 uv也可使用 pip模型 APIOpenAI 兼容格式即可不限定具体厂商版本说明LangChain 和 LangGraph 目前都处于高频迭代状态本文示例以 0.1.x 和 0.2.x 时期的稳定 API 风格为主。实际安装时请以官方文档和当前发布版本为准不要纠结于某个过时序数。4.2 创建项目并安装依赖# 创建虚拟环境 python -m venv .venv source .venv/bin/activate # Windows 使用 .venv\Scripts\activate # 安装核心依赖 pip install --upgrade langchain langchain-core langchain-community pip install langgraph pip install langchain-openai # 如果需要使用 Anthropic、百度千帆等模型按需安装对应包建议同时安装 jupyter 或直接在 VS Code 里用交互式 Python 环境学习方便查看每一步的中间状态。4.3 配置环境变量在项目根目录创建.env文件# 使用支持 OpenAI 兼容协议的模型服务 OPENAI_API_KEYsk-xxxxxxxxxxxxxxxx OPENAI_API_BASEhttps://your-api-endpoint/v1如果使用的是本地或私有化模型服务把OPENAI_API_BASE指向对应地址即可。LangChain 的ChatOpenAI类天然兼容这类服务。这一段配置非常关键确保模型 API 可达、API Key 正确、网络环境允许请求是后面所有示例能跑通的前提。5. 从最简单的 LangChain 调用开始很多人第一个 Agent 项目失败不是因为概念不懂而是因为环境没通就急着跑复杂链路。这里先写一个最基础的模型调用确认链路畅通。# 文件路径examples/01_basic_llm_call.py import os from dotenv import load_dotenv from langchain_openai import ChatOpenAI load_dotenv() # 创建模型实例 # 使用 OpenAI 兼容接口厂商或本地服务通过环境变量切换 llm ChatOpenAI( modelgpt-4o-mini, # 以实际可用模型为准 temperature0.7, ) response llm.invoke(用一句话解释什么是 AI Agent) print(response.content)运行方式cd examples python 01_basic_llm_call.py预期输出是一句对 AI Agent 的解释文本。走到这一步说明模型调用链路已经打通。这里要说明一个新手常见误区invoke是 LangChain 的统一调用入口返回的是一个AIMessage对象而不是纯字符串。如果只想拿文本内容就用.content。对返回结构不熟悉时可以先用print(response)看完整对象。再进一步把输出解析成结构化数据这是 Agent 与普通聊天应用的关键区别。# 文件路径examples/02_structured_output.py from langchain_core.output_parsers import StrOutputParser from langchain_core.prompts import ChatPromptTemplate from langchain_openai import ChatOpenAI llm ChatOpenAI(modelgpt-4o-mini) prompt ChatPromptTemplate.from_messages([ (system, 你是一个严谨的技术助手只输出 JSON 格式。), (human, 把这句话转成 JSON{input}), ]) chain prompt | llm | StrOutputParser() result chain.invoke({input: LangChain 和 LangGraph 的区别}) print(result)这段代码展示了 LangChain 最经典的管道式写法prompt | llm | parser。管道符在这里不是位运算而是 LangChain 的链式组合语法。每一个元素会接收上一个元素的输出经过处理后传给下一个。下一步把自定义函数接入 LangChain让模型可以“调用工具”。这是 Agent 的技术基础。# 文件路径examples/03_simple_tool.py from langchain_core.tools import tool tool def get_weather(city: str) - str: 查询指定城市的当前天气模拟数据 # 实际项目里在这里调用天气服务 API return f{city} 今天晴气温 24℃适合出行。 # 查看工具的 JSON Schema 定义 print(get_weather.name) print(get_weather.args)注意到tool装饰器的作用它把普通 Python 函数变成模型可以“感知”的工具。模型的工具调用能力依赖这个函数的签名和 Docstring所以参数类型标注和说明文字必须写清楚别写“注意我懒”这种 Docstring模型真的会理解错。到这里你已经掌握了 LangChain 的三个核心能力模型调用、链式组合、工具封装。这足够支撑你进入 LangGraph 学习阶段了。6. LangGraph 核心概念与最小图实现LangGraph 的核心概念并不复杂初次接触只需要盯住四个东西概念作用类比State图的全局共享状态数据库中的一行记录Node一个执行单元业务流程里的一个步骤Edge节点间的流转关系流程线Conditional Edge根据状态决定下一步走向if-else 分支6.1 创建一个最小二节点图# 文件路径examples/04_minimal_graph.py from typing import TypedDict from langgraph.graph import StateGraph, START, END # 定义全局状态结构 class AgentState(TypedDict): input: str output: str # 节点 A接收输入 def node_a(state: AgentState) - dict: print(f节点 A 收到: {state[input]}) return {output: f已处理: {state[input]}} # 节点 B输出结果 def node_b(state: AgentState) - dict: print(f节点 B 收到: {state[output]}) return {final_output: f最终结果: {state[output]}} # 构建图 graph StateGraph(AgentState) # 1. 添加节点 graph.add_node(A, node_a) graph.add_node(B, node_b) # 2. 添加边从 START 到 A从 A 到 B从 B 到 END graph.add_edge(START, A) graph.add_edge(A, B) graph.add_edge(B, END) # 3. 编译 app graph.compile() # 4. 运行 result app.invoke({input: LangGraph 你好}) print(result)这个示例的核心价值在于展示 LangGraph 的执行模型所有节点接收整个 State节点返回值会合并进 State。node_a返回的output字段在node_b里就能通过state[output]读到。相比 LangChain 的 ChainLangGraph 的优势在这一刻就开始体现节点之间不再通过位置参数传递数据而是通过一个共享状态对象。这为复杂流程的状态追踪和持久化打下了基础。6.2 带条件分支的 Agent 循环真实 Agent 往往需要“执行工具 - 判断是否满足退出条件 - 不满足则继续调用工具”。LangGraph 里用条件边来实现这个循环。# 文件路径examples/05_conditional_agent.py from typing import TypedDict, Literal from langchain_openai import ChatOpenAI from langgraph.graph import StateGraph, START, END class AgentState(TypedDict): messages: list steps: int def call_model(state: AgentState) - dict: 调用模型决定下一步动作 llm ChatOpenAI(modelgpt-4o-mini) response llm.invoke(state[messages]) return {messages: state[messages] [response]} def should_continue(state: AgentState) - Literal[tools, end]: 条件判断模型是否请求了工具调用 last_message state[messages][-1] # 如果模型返回 tool_calls说明要继续执行工具 if hasattr(last_message, tool_calls) and last_message.tool_calls: return tools return end def execute_tool(state: AgentState) - dict: 模拟执行工具并返回结果 last_message state[messages][-1] tool_result { role: tool, content: f工具执行成功共执行了 {state[steps] 1} 次, } return { messages: state[messages] [tool_result], steps: state[steps] 1, } graph StateGraph(AgentState) graph.add_node(model, call_model) graph.add_node(tools, execute_tool) graph.add_edge(START, model) graph.add_conditional_edges(model, should_continue, {tools: tools, end: END}) graph.add_edge(tools, model) app graph.compile()这个示例的流程循环结构是model节点调模型should_continue判断模型是否要求调用工具如果要调用工具进入tools节点执行执行完再回到model节点直到模型不再请求工具流转到 END。这就是 ReAct 模式在 LangGraph 里的最小实现。理解了这个循环你就理解了 Agent 最核心的执行机制。7. 完整实战构建一个带工具的问答 Agent把前面所有知识点串起来写一个带工具调用、记忆和条件循环的完整 Agent。7.1 需求定义假设我们需要一个“企业知识库助手”用户问问题时Agent 先判断是否需要查内部知识库如果需要就调用检索工具拿到结果后组织回答。同时要保留多轮对话记忆让用户能自然地进行追问。先看项目目录agent-demo/ ├── .env ├── requirements.txt └── agent.py7.2 完整代码# 文件路径agent-demo/agent.py import os from typing import TypedDict, Literal from dotenv import load_dotenv from langchain_openai import ChatOpenAI from langchain_core.tools import tool from langgraph.graph import StateGraph, START, END from langgraph.checkpoint.memory import MemorySaver load_dotenv() # ---------- 1. 定义工具 ---------- tool def search_knowledge_base(query: str) - str: 检索内部知识库返回与查询相关的文档内容。 # 实际项目中这里可以接入向量数据库、Elasticsearch 或内部 API knowledge { 退款政策: 用户可以在购买后 7 天内无理由申请退款。, 部署方式: 支持公有云 SaaS 和私有化部署两种方式。, API 限制: 免费版每分钟 60 次请求企业版不限制。, } for key, value in knowledge.items(): if key in query: return value return 知识库中未找到相关信息。 # ---------- 2. 定义状态 ---------- class AgentState(TypedDict): messages: list need_search: bool # ---------- 3. 定义节点 ---------- def decide_need_search(state: AgentState) - dict: 判断用户问题是否需要调用知识库工具 last_message state[messages][-1].content need_search 政策 in last_message or 部署 in last_message or API in last_message return {need_search: need_search} def call_search_tool(state: AgentState) - dict: 调用知识库工具 query state[messages][-1].content result search_knowledge_base.invoke({query: query}) state[messages].append({role: tool, content: result}) return {messages: state[messages]} def call_model(state: AgentState) - dict: 调用模型生成回答 llm ChatOpenAI(modelgpt-4o-mini) response llm.invoke(state[messages]) return {messages: state[messages] [response]} def route_after_decision(state: AgentState) - Literal[search, model]: 条件路由是否需要查知识库 return search if state[need_search] else model # ---------- 4. 构建图 ---------- def build_agent(): graph StateGraph(AgentState) graph.add_node(decide, decide_need_search) graph.add_node(search, call_search_tool) graph.add_node(model, call_model) graph.add_edge(START, decide) graph.add_conditional_edges(decide, route_after_decision, { search: search, model: model, }) graph.add_edge(search, model) graph.add_edge(model, END) # 使用内存检查点保存会话状态支持多轮对话 checkpointer MemorySaver() app graph.compile(checkpointercheckpointer) return app # ---------- 5. 主程序 ---------- if __name__ __main__: agent build_agent() # 使用固定线程 ID保持同一会话上下文 config {configurable: {thread_id: user-001}} question 公司的退款政策是什么 result agent.invoke( {messages: [{role: user, content: question}]}, configconfig, ) print(result[messages][-1].content) # 第二轮追问验证记忆是否生效 follow_up 我可以直接申请吗 result2 agent.invoke( {messages: [{role: user, content: follow_up}]}, configconfig, ) print(result2[messages][-1].content)7.3 关键设计说明第一个关键设计是decide_need_search节点。这里用规则判断是否触发工具好处是简单可控。真实项目中可以用模型做意图识别也可以用 RAG 的检索评分做阈值判断。关键在于工具不能随意触发每次触发都意味着额外的 Token 消耗和潜在的错误放大。第二个关键设计是MemorySaver。LangGraph 的 State 配合 checkpointer可以把每一轮对话后的状态保存下来。同一thread_id的后续请求在启动时自动恢复历史状态这就是“多轮记忆”的实现机制。第三个关键设计是消息列表结构。messages数组里混合了 user、assistant、tool 三种角色LangChain 的模型封装协议会正确理解这种结构。7.4 运行验证cd agent-demo pip install -r requirements.txt python agent.py第一次输出应该包含“用户可以在购买后 7 天内无理由申请退款”之类的知识库内容第二次输出应该能结合上一轮的退款政策回答“可以直接申请”的问题。如果第一次输出就没有检索到知识库内容优先检查模型是否正确理解了工具结果decide_need_search的判断条件是否覆盖了你的测试问题知识库内容是否在函数内部被正确命中。8. 从个人项目到企业级 Agent 的工程化差距能把 Demo 跑通只说明你掌握了框架 API。真正决定 Agent 能否上生产环境的是下面这几个工程问题。8.1 状态持久化与容灾恢复当前示例用了内存检查点服务重启后状态就丢了。企业级方案需要把检查点持久化到 Redis、PostgreSQL 或专门的存储服务中让 Agent 在执行到一半宕机后能恢复现场继续跑。8.2 工具权限与安全边界Agent 能直接调用的 API 越多风险越大。企业落地时至少要关注工具是否需要鉴权内部服务和外部第三方 API 的权限模型是否一致工具调用是否有审计日志谁在什么时间调了什么工具、传了什么参数是否有敏感信息泄露风险例如模型把内部 API Key 当作参数传给下一个工具外部工具返回内容是否需要先经过过滤、脱敏再交给模型。最稳妥的做法是工具层强制要求入参校验、出参过滤模型永远只接触经过白名单授权的工具集合。8.3 可观测性传统应用看日志和 TraceAgent 应用除此之外还需要看到“推理轨迹”模型看到了哪些上下文、选择了哪个工具、工具的返回是什么、为什么最终停在了这一步。LangGraph 天生支持按节点追踪配合 LangSmith 一类的平台可以把每一步执行都记录下来这是排查 Agent 异常行为的核心手段。8.4 效果评估与回归测试Agent 的“测试”和传统软件不同。输入同样的问题模型可能给出不同的回答。所以企业级 Agent 必须有一套评测集每个用例需要标注期望行为每次上线前自动跑一遍回归对比输出质量、工具调用准确率、最终回答正确率。8.5 成本控制Agent 的执行链路越长、工具越多Token 消耗越大。生产环境建议对单次 Agent 任务的模型调用次数设置上限对单账号单日 Token 消耗设置预算告警优先使用便宜的轻量模型做意图判断核心生成任务再用强模型对工具返回内容做截断避免大量无关文本进入上下文。9. 常见问题与排查思路问题现象可能原因排查方式解决方案调用模型时报 AuthenticationErrorAPI Key 错误或环境变量未加载打印 os.getenv 确认变量存在检查 .env 位置和 python-dotenv 调用模型返回内容无法被解析成 JSONPrompt 没有明确要求 JSON或模型输出带 Markdown 包裹打印原始返回内容使用输出解析器或让模型直接输出纯 JSON必要时配合结构化输出Agent 一直循环调用工具不结束模型始终认为需要调用工具且工具结果没有提供足够信息查看执行轨迹中每一次工具调用的入参和返回限制最大步数优化 Prompt检查工具返回值是否清晰多轮对话记忆不生效没有传 thread_id或没有配置 checkpointer检查 config 和 graph 编译参数统一会话 ID启用 MemorySaver 或持久化检查点LangGraph 与 LangChain 版本不兼容两者版本差异过大导致 API 变更查看完整堆栈错误尽量保持 langchain 和 langgraph 在同一主版本更新周期内工具参数解析错误函数签名没有类型标注或 Docstring 不清晰打印工具 JSON Schema完善函数签名和 Docstring重新启动服务另外补充一个常见认知误区看到Agent execution terminated due to error这类报错时先不要怀疑框架出了问题。多数情况下是你的工具函数内部抛了异常或者模型返回了无法被tool_calls解析的内容。正确排查顺序是看完整 Traceback - 定位到具体节点 - 检查该节点的输入输出。10. 对于实战课程和系统学习的建议如果现在有一套 LangChain LangGraph 实战视频课程摆在你面前不要抱着“看完就会”的心态去刷。课程的价值在于帮你省去筛选资料的时间、提供一个有体系的路径但真正内化必须靠动手。建议按以下方式使用课程跟着视频敲代码的时候故意改几个参数观察结果变化每学完一个章节关掉视频自己从零实现一版不参考示例代码把课程项目改写成一个自己的需求场景例如把“知识库问答”改成“订单查询助手”或“运维工单分类器”学完 LangGraph 后回头重构之前用 LangChain 写的 Demo对比两种写法的差异拿自己的项目去验证“Agent 工程化”那一章的内容加日志、加评测、加权限控制。只有经历“看完会用”到“看完能改”再到“看完能造”的过程这套课程才真正转化成你的技术资产。还有一个容易被忽略的点学习过程中不要把模型 API 和框架绑定得太死。当前某个模型厂商的能力不代表整个行业的上限LangChain 和 LangGraph 这类框架最大的价值之一就是屏蔽了底层模型差异。多尝试不同模型在同一个图结构里的表现你会更理解 Agent 开发中“模型选择”和“流程设计”是两件独立的事。11. 后续学习方向参考到这里你已经掌握了一条完整的 LangChain LangGraph 学习主线。接下来的深入方向可以从这几条线里选第一RAG检索增强生成。企业级 Agent 很大一部分是“私有知识库问答”形态LangChain 生态里有大量内置的检索器、向量库封装和文档切分策略。学懂 RAG 的评估与调优比学更多 Agent 框架 API 更实用。第二多 Agent 协作。LangGraph 支持在一个图里编排多个 Agent 节点不同 Agent 承担不同角色例如规划 Agent、执行 Agent、审查 Agent。这个方向适合已经吃透单 Agent 状态的开发者。第三人机协同流程。真实业务不可能全自动LangGraph 的断点与人工审批机制非常值得深挖这是在 To B 场景里最受关注的能力之一。第四Agent 工程化体系。评测、追踪、成本治理、权限安全这些能力决定了 Agent 项目能走多远也往往是技术团队最缺的岗位能力。从 2026 年回看AI Agent 已经不再是“能不能做出来”的问题而是“能不能稳定、可控、经济地跑在生产环境里”的问题。LangChain 和 LangGraph 组合提供的正是这条从原型到生产的必经路径。找一个具体的业务问题开始动手吧。