这次我们来看 2026 年企业级 AI Agent 开发绕不开的一条技术主线LangChain 1.x LangGraph。标题里的 V1.3 可以理解为课程或文档体系中的版本口径实际动手时你装到的多半是当前 1.x 最新稳定版所以这篇文章不纠结具体补丁号直接按生态里最主流的 API 用法来讲。看完之后你会发现多智能体架构并不神秘核心就几件事状态怎么维护、节点怎么编排、分支和循环怎么控制、结果怎么持久化。LangChain 解决的是“零件”问题模型接入、提示词、工具、RAG、输出解析LangGraph 解决的是“生产线”问题状态管理、节点编排、条件路由、多智能体协作、人机协同和持久化。两者配合正好覆盖了从单次模型调用到复杂 Agent 系统的完整开发链路。比起过去自己用while True写 Agent 循环LangGraph 提供了更规范、更容易上生产的执行框架。这篇文章会带你完成确认技术栈分工、搭好本地环境、跑一个最小 LangGraph Agent、用多智能体模式做流程编排、接入工具调用、完成 API 化部署和批量任务最后给出一份排错清单和工程化建议。适合后端工程师、AI 应用开发者以及准备把 Agent 真正放进业务系统的技术团队。1. 核心能力速览先把这组技术栈的关键信息放在最前面方便你快速判断值不值得投入时间。能力项说明技术栈定位LangChain 提供组件库LangGraph 提供有状态图编排引擎核心功能单 Agent、多智能体、条件路由、循环执行、人工介入、持久化、流式输出开发语言Python 官方支持最全LangGraph 也有 JS/TS SDK启动方式Jupyter / Python 脚本 /langgraph dev本地开发服务是否支持 API支持。LangGraph Server / Platform 提供 REST APIJava、Go 等后端也能接入是否支持批量任务支持。可在代码里循环调用也可接入消息队列做异步批处理模型适配OpenAI、Anthropic、DeepSeek、Ollama 本地模型等通过统一接口接入硬件要求纯 API 方案普通办公本即可本地模型方案按模型规模决定显存和内存适合读者后端工程师、AI 应用工程师、Agent 产品团队有一点需要提前说明Agent 开发的主要资源瓶颈不是显卡而是 token 消耗、接口延迟和状态存储。很多人被“大模型必须大显存”这个印象误导实际上如果你的模型走 API 调用本地开发和测试用一台普通电脑完全够用。真正需要显卡的是本地部署模型场景那是另一条技术路线。版本选择上我的建议是直接安装langchain和langgraph的最新稳定版不要为了教程去锁定老旧版本。1.x 发布之后很多 0.x 时代的手写 Chain 模式已经不建议使用官方更推荐直接把图结构写到 LangGraph 里。2. LangChain 与 LangGraph 的分工别再混淆很多初学者第一个问题就是LangChain 和 LangGraph 到底什么关系是不是学了 LangChain 就不用学 LangGraph不是。两者是分工关系不是替代关系。LangChain 更像是“工具箱”它把模型调用、提示词模板、文档加载、向量检索、工具定义、输出解析这些能力统一封装成标准接口。你可以只学 LangChain 就做一个简单的 RAG 问答但如果要做带状态的 Agent、多智能体协作、循环和人工介入LangChain 0.x 时代那种 Chain 串联方式会非常吃力。LangGraph 是 LangChain 团队推出的“图执行引擎”。它把 Agent 流程建模成一张有向图节点是业务步骤边是步骤之间的流转状态在整张图上共享。它原生支持循环、分支、条件跳转、断点续跑还内置了 checkpoint 机制可以把每次执行状态保存下来。这正好补上了 LangChain 在复杂编排上的短板。对比项LangChainLangGraph定位组件库 / 工具框架有状态图执行引擎核心抽象Model、Prompt、Tool、Retriever、ChainStateGraph、State、Node、Edge状态管理弱靠链式传参强显式 State Reducer循环和分支不擅长需要自己写逻辑原生支持条件边直接表达持久化不内置Checkpointer Thread人机协同实现成本高原生支持 interrupt / resume从材料看LangGraph 1.0 之后已经不只是 Agent 框架更像一个轻量级的 AI 应用运行时。生产级应用里常见的并发控制、断点恢复、人工审批等需求LangGraph 都提供了对应机制这也是它能够进入企业级项目的原因。有人会问LangGraph 能不能替代 Flowable 这类工作流引擎我的判断是“部分可以”。LangGraph 擅长 AI 编排比如多 Agent 协作、RAG 流程、动态路由Flowable 擅长的是严格的 BPM 审批流。如果业务流程需要强合规审计和成熟的审批节点不建议为了技术新鲜感直接替换成熟工作流引擎。两者结合使用反而更符合企业现状。3. 2026 年企业级 AI Agent 开发环境准备在写代码之前先把环境准备好。这里给出一套通用的本地开发环境搭建流程按你自己的系统情况调整即可。3.1 Python 与虚拟环境LangChain 和 LangGraph 都是 Python 生态建议使用 Python 3.9 及以上版本最好在虚拟环境里安装避免和系统 Python 包冲突。python -m venv langchain-demo # Windows langchain-demo\Scripts\activate # macOS / Linux source langchain-demo/bin/activate python -m pip install -U pip3.2 安装核心依赖接下来安装 LangChain 生态的核心包pip install -U langchain langchain-openai langchain-community langgraph pip install -U langchainhub python-dotenv安装完成后可以检查一下版本确认环境可用python -c import langchain, langgraph; print(langchain:, langchain.__version__); print(langgraph:, langgraph.__version__)如果你的项目要用到向量库再额外安装 Chroma、FAISS 或对应的数据库驱动。用不到就先不装保持环境干净。3.3 模型 API Key 配置LangChain 通过环境变量读取模型凭据。最常用的做法是在项目根目录创建.env文件然后用dotenv加载OPENAI_API_KEYsk-xxxxxxx如果你用的是国内模型服务或 OpenAI 兼容端点可以通过base_url参数切换不必修改业务代码from langchain_openai import ChatOpenAI llm ChatOpenAI( modelgpt-4o-mini, temperature0, base_urlhttps://api.example.com/v1, api_keysk-xxxxxxx, )这里需要注意模型名称要和你的服务商提供的名称一致否则启动时就会报模型不存在、认证失败之类的错误。建议先单独测试一次模型调用排除网络和 Key 的问题再进入 Agent 开发。4. LangChain 核心组件拆解模型、提示词、工具、RAG、记忆、输出解析LangChain 的价值不在“调模型”而在把模型周边的工程问题标准化。下面这六个组件是大多数 Agent 系统都会用到的。4.1 模型接入模型层是 Agent 的“大脑”。LangChain 用统一的ChatModel接口屏蔽了不同厂商的差异from langchain_openai import ChatOpenAI llm ChatOpenAI( modelgpt-4o-mini, temperature0, )需要本地模型时可以用 Ollama 配合langchain-ollama接入。模型选择和 Agent 的复杂性没有直接关系业务路由逻辑再复杂底层模型也可以只用一个。不要为了做 Agent 就到处接模型模型调用成本是逐次累加的。4.2 提示词模板Agent 里的提示词往往是动态拼装的。LangChain 提供了ChatPromptTemplate可以结构化组织 system prompt 和 user promptfrom langchain_core.prompts import ChatPromptTemplate prompt ChatPromptTemplate.from_messages([ (system, 你是一名企业级 AI Agent 技术顾问回答要简洁、可落地。), (human, 请解释 {topic} 的实现思路并给出关键代码片段。), ]) chain prompt | llm resp chain.invoke({topic: 多智能体 Supervisor 模式}) print(resp.content)实际项目里提示词不要写在代码里硬编码建议独立成配置文件或模板文件方便运营人员调整。提示词的版本管理直接影响 Agent 线上效果的稳定性。4.3 工具封装Agent 要发挥作用必须能调用工具。LangChain 用tool装饰器把普通函数变成模型可调用的工具from langchain_core.tools import tool tool def query_stock_price(code: str) - str: 查询指定股票代码的最新价格。code 为 6 位股票代码。 return f{code} 最新价 12.30 元工具的描述信息非常重要底层模型依赖描述来判断“什么场景该用这个工具”。描述写得含糊模型就可能乱调用。生产环境里建议给每个工具加上清晰入参说明、超时时间、错误返回格式。4.4 RAG 检索RAG 是企业落地 Agent 最高频的需求。LangChain 把文档加载、切分、向量化、检索串成一条标准流水线from langchain_community.document_loaders import TextLoader from langchain_text_splitters import RecursiveCharacterTextSplitter from langchain_community.vectorstores import FAISS from langchain_openai import OpenAIEmbeddings loader TextLoader(./docs/knowledge.txt) documents loader.load() splitter RecursiveCharacterTextSplitter(chunk_size500, chunk_overlap50) chunks splitter.split_documents(documents) vectorstore FAISS.from_documents(chunks, OpenAIEmbeddings()) retriever vectorstore.as_retriever(search_kwargs{k: 4})很多人把 RAG 理解成简单的“把文档灌进向量库”实际工程里难点在切分策略、召回率、引用溯源和知识更新。这里只演示基础接入正式项目需要结合检索评测持续优化。4.5 记忆与状态0.x 时代的 LangChain Memory 类在新架构里逐渐边缘化。官方更推荐把对话历史直接放进 LangGraph 的 State 中管理。这不仅是实现方式的改变更是思维方式的改变记忆不再是 Agent 内部的黑盒而是整个执行图可见的状态数据。4.6 输出解析结构化输出是 Agent 对接业务系统的关键。用PydanticOutputParser或with_structured_output可以直接让模型输出 JSON 结构避免在业务代码里做脆弱的字符串解析。5. LangGraph 核心概念与最小可跑 AgentLangGraph 的核心概念只有几个State、Node、Edge、Conditional Edge、Checkpointer。把这几个概念理解透多智能体架构就是搭积木。5.1 核心概念State 是整张图的“全局变量”。LangGraph 允许你定义 State 的数据结构并指定 Reducer 来处理状态更新。最常用的 reducer 是add_messages它的作用是当多个节点返回消息时自动拼接而不是覆盖。Node 是一个普通的 Python 函数输入是当前 State输出是一个字典表示要更新的字段。Edge 表示节点之间的流转路径。Conditional Edge 是条件边根据当前 State 动态决定下一步走向哪个节点。Checkpointer 负责保存每一步的执行状态。开启后图可以在任意节点暂停、恢复这就为人工审批、断点调试、失败重跑提供了基础能力。5.2 最小可跑 LangGraph Agent下面这个例子是一个最简单但完整的有状态对话 Agentfrom typing import Annotated, TypedDict from langchain_openai import ChatOpenAI from langgraph.graph import StateGraph, START, END from langgraph.graph.message import add_messages llm ChatOpenAI(modelgpt-4o-mini, temperature0) class ChatState(TypedDict): messages: Annotated[list, add_messages] def chatbot(state: ChatState): response llm.invoke(state[messages]) return {messages: [response]} graph StateGraph(ChatState) graph.add_node(chatbot, chatbot) graph.add_edge(START, chatbot) graph.add_edge(chatbot, END) app graph.compile() result app.invoke({ messages: [{role: user, content: 你好介绍一下你自己}] }) print(result[messages][-1].content)这个例子看起来简单但它包含了 LangGraph 的完整骨架定义了 State注册了节点画了边编译成图最后调用执行。后续多智能体架构只是在这个骨架上增加更多节点和更复杂的路由逻辑。5.3 启动本地开发服务如果你想在本地打开一个可视化调试环境LangGraph 提供了langgraph dev命令pip install -U langgraph-cli # 在项目目录下启动 langgraph dev如果项目用 uv 管理依赖也可以用uv run langgraph dev。启动后根据命令行输出的地址访问本地开发 UI就能看到图结构、State 变化流和每一步的输入输出。这个调试体验比在 Jupyter 里反复打印结果要直观得多。6. 多智能体架构模式与代码实战多智能体架构听起来很高端本质上解决的是一个工程问题当一个任务超过单个模型单次推理能力或者需要多个角色协作时如何把任务拆解、分配、汇总。LangGraph 提供了图级别的表达力可以天然实现多种多智能体模式。6.1 常见多智能体模式第一类是顺序执行模式Agent 之间按固定顺序串联前一个输出作为后一个输入。适合流水线任务比如资料收集、内容生成、人工审核。第二类是监督者模式也叫 Supervisor由中央调度节点决定下一步交给哪个子 Agent。适合任务动态变化、需要自主路由的场景。第三类是层级模式多个 Supervisor 再向上汇总到一个总控节点适合大型组织架构模拟。第四类是协作模式多个 Agent 共享同一个任务池通过共享状态互相传递中间结果。选择模式的依据不是“哪个更高级”而是“哪个更稳”。大多数企业项目从顺序模式开始只有路由逻辑足够复杂时才引入 Supervisor。6.2 代码实战两阶段多智能体条件路由这里给出一个可运行的两阶段例子研究节点产出初稿评审节点判断是否通过不通过就回到研究节点重写通过后进入终稿节点。这个结构在很多内容生成型 Agent 里非常典型from typing import TypedDict from langgraph.graph import StateGraph, START, END class ReportState(TypedDict): topic: str draft: str passed: bool def research_node(state: ReportState): return {draft: f《{state[topic]}》研究报告初稿市场规模与应用现状。} def review_node(state: ReportState): # 真实项目里由模型或人工判断这里用长度做演示 return {passed: len(state[draft]) 20} def finalize_node(state: ReportState): return {draft: state[draft] 已终审} def route_after_review(state: ReportState): if state[passed]: return finalize return research graph StateGraph(ReportState) graph.add_node(research, research_node) graph.add_node(review, review_node) graph.add_node(finalize, finalize_node) graph.add_edge(START, research) graph.add_edge(research, review) graph.add_conditional_edges( review, route_after_review, {finalize: finalize, research: research} ) graph.add_edge(finalize, END) app graph.compile() result app.invoke({ topic: AI Agent 在企业服务中的应用, draft: , passed: False, }) print(result[draft])这里最关键的是add_conditional_edges它能根据route_after_review的返回值决定下一步走向。循环、重试、回退这些逻辑都是通过条件边实现的。理解了这一点多智能体架构的骨架就打通了。6.3 Supervisor 监督者模式实现思路监督者模式是生产环境里讨论最多的多智能体架构。它的核心是一个 supervisor 节点接收所有子 Agent 的返回结果再决定下一步执行谁。LangGraph 的Command类型就是为这种场景设计的可以在节点返回时直接指定下一个节点from langgraph.types import Command def supervisor(state) - Command: # 生产环境用 LLM 路由这里演示固定跳转 return Command( gotoresearcher, update{messages: state[messages] [已调度 researcher]} )完整实现还需要一个路由用的 LLM让它从研究员、写手、代码工程师等成员中选择下一步执行者并确保在任务完成时跳转到 END。实际项目里为了避免 Supervisor 陷入无限循环一定要在 State 里维护任务轮次或完成标记并在条件路由中加上退出条件。6.4 代码实战多工具 ReAct Agent如果不希望维护复杂图结构又想要多角色协作效果可以把多个“角色工具”挂到一个 ReAct Agent 下。底层模型负责判断何时使用哪个工具LangGraph 的create_react_agent帮我们封装了循环逻辑from langchain_openai import ChatOpenAI from langchain_core.tools import tool from langgraph.prebuilt import create_react_agent tool def research_tool(query: str) - str: 检索行业资料并返回摘要适合研究类问题。 return f资料摘要{query} 行业规模约 120 亿元。 tool def coding_tool(requirement: str) - str: 生成 Python 代码片段适合编程类需求。 return f代码def solution():\n return {requirement} llm ChatOpenAI(modelgpt-4o-mini, temperature0) agent create_react_agent(llm, tools[research_tool, coding_tool]) result agent.invoke({ messages: [{role: user, content: 先查 AI Agent 市场规模再写一个输出该数字的 Python 函数}] }) print(result[messages][-1].content)运行后模型会在一次对话中自动完成多轮工具调用先查资料再写代码最后汇总结果。这种模式实现成本低适合快速验证业务逻辑。但要注意工具数量过多时模型可能选错工具需要对工具描述和模型参数做针对性调优。7. 接口 API 与批量任务Agent 写出来最终要服务上层业务。LangGraph 生态提供了把图服务化部署的方案所有节点状态、运行记录、断点恢复都会通过 API 暴露出来。7.1 API 服务启动本地开发阶段用langgraph dev启动的不只是调试 UI同时也是一个本地 API 服务。生产环境可以用 LangGraph Server 或 LangGraph Platform 部署。启动之后你会在命令行看到服务地址常见的调用端口是 2024具体以你启动时的输出为准。7.2 Python 调用 API 示例假设服务已经启动可以通过 REST API 创建会话并发起运行import requests BASE_URL http://localhost:2024 thread_id demo-thread-001 resp requests.post( f{BASE_URL}/threads/{thread_id}/runs, json{ assistant_id: agent, input: { messages: [{role: user, content: 运行一次测试任务}] }, }, timeout120, ) print(resp.status_code) print(resp.json())这是 LangGraph Server 的常见调用格式不同版本可能略有差异以你实际使用的 SDK 方法和接口文档为准。接口方式的好处是上层可以用任何语言接入Java、Go、Node.js 都能通过 HTTP 调用。7.3 批量任务实现批量任务最常见的做法是并发调用已编译好的图或者并发调用 API 服务。这里给出一个 Python 线程池模板from concurrent.futures import ThreadPoolExecutor tasks [任务 1, 任务 2, 任务 3, 任务 4] def run_task(text: str): result app.invoke({ messages: [{role: user, content: text}], }) return result[messages][-1].content with ThreadPoolExecutor(max_workers4) as executor: outputs list(executor.map(run_task, tasks)) for text, output in zip(tasks, outputs): print(f{text} {output})批量任务有两个坑。第一并发数不要盲目调大要同时关注模型 API 的限流策略和下游服务承受能力。第二每个任务最好绑定一个独立的 thread_id方便出问题时定位日志和恢复执行状态。任务量大时建议引入消息队列把任务状态、重试次数和最终结果都持久化。8. 资源占用与性能观察Agent 系统的性能观察重点不在显存而在 token、延迟、步数和持久化存储。每次运行 Agent你至少要记录四类指标。第一是 token 消耗多智能体协作会成倍放大 token 开销因为每个子 Agent 都要看到上下文。第二是运行步数一个正常 Agent 任务通常在 3 到 10 个 step 内完成如果超过 20 步还没有收敛大概率是路由逻辑或提示词有问题。第三是接口延迟模型 API 调用是最大耗时来源工具调用和向量检索相对可控。第四是状态存储增长checkpoint 会记录每一步的 State长时间运行后存储量不可忽视。LangGraph 的stream方法可以逐步观察执行过程定位瓶颈节点for step in app.stream({ messages: [{role: user, content: 逐步处理这个任务}] }): print(step)如果 Agent 跑到某个节点长期没有输出优先看是不是卡在模型调用超时再检查工具的远程接口是否返回了异常。资源调优方面先降低上下文冗余系统提示词不要重复堆叠再引入模型缓存相同语义的查询直接命中缓存最后做任务路由简单问题走小模型复杂问题才走大模型这是企业里最直接的成本优化手段。本地模型方案则重点观察显存和内存模型越大需要预留的空间越多但实际占用必须用本机nvidia-smi或任务管理器实测不同框架和量化方式差异很大。9. 常见问题与排查方法LangChain 和 LangGraph 生态迭代很快遇到问题不要慌按下面这张排查表定位即可。问题现象可能原因排查方式解决方案安装依赖时报冲突Python 版本或包版本不匹配查看完整报错日志使用虚拟环境升级 pip再安装最新版提示 API Key 无效环境变量未加载或 Key 过期打印环境变量单独测试模型调用修正.env文件重新加载环境模型名称不存在服务商模型名写错查服务商模型列表换成正确的模型名称LangGraph 图编译失败节点引用了不存在的 State 字段检查 State 定义和节点返回值统一 State 字段名Agent 执行无限循环条件边缺少退出条件在节点中打印 state 轮次增加最大轮次限制和完成标记调用 API 返回 404接口路径或 assistant_id 不对查看服务端完整日志按实际接口文档修正路径和参数批量任务并发报错触发模型 API 限流查看返回状态码和错误信息降低并发数增加重试和退避checkpoint 无法恢复持久化后端未配置检查启动日志和数据库连接配置 SQLite/Postgres 后端这里最容易踩的坑是网上教程代码版本太旧API 已经改掉。遇到报错先看官方文档的迁移说明不要硬抄旧代码。LangGraph 的报错信息一般比较明确尤其是节点返回类型和 State 字段不匹配的问题按提示修改即可。10. 最佳实践与使用边界技术能跑通只是第一步企业级 Agent 最重要的是稳定、可控、可追溯。第一次接触这套技术栈先不要直接上多智能体。先写一个单 Agent 最小用例确认模型调用、工具调用、状态流转都正常再加分支和循环。每次增加复杂度后都保留一个可运行的备份配置。生产项目里建议把模型配置、提示词、工具描述、图结构完全分开管理这样任何一个环节调整都不会牵一发动全身。日志和可观测性不能落后。每个 Agent 运行建议记录输入、每一步节点输出、token 消耗、耗时、返回状态。出现线上问题时这些日志是唯一的排查依据。接口服务要限制访问范围不能把 Agent 服务直接暴露在公网至少要加一层鉴权。合规和安全边界必须重视。接入内部数据时先完成数据脱敏和权限校验RAG 知识库里的内容要确认来源合法不要拿未经授权的作品做检索。工具调用如果涉及订单、支付、审批等敏感系统要把“模型建议”和“自动执行”分开重要操作走人工确认。提示注入也是企业落地必须正视的问题用户输入可能试图劫持系统指令需要用输入校验和权限隔离来降低风险。如果你是 Java 后端团队也不必担心被 Python 生态隔离。Java 侧可以通过 LangGraph 的 REST API 接入 Agent 能力Spring Boot 应用只负责业务编排Agent 图在 Python 服务里执行两边通过接口协作各司其职。11. 总结与下一步LangChain LangGraph 最值得你投入时间的点不是背 API而是理解图编排的思维方式状态放在哪里、节点之间如何流转、异常时如何恢复。先把文中的最小 Agent 跑通再验证多工具调用最后把 Supervisor 模式和条件路由用在自己的业务场景里这是最快的进阶路径。最容易踩的坑有三个版本混乱导致代码不兼容、多智能体路由缺少退出条件、生产环境没有日志和鉴权。建议收藏这篇文章搭建环境时对照排查表使用。下一步可以按这个方向走先做单 Agent 工具调用再升级为两阶段条件路由的 RAG Agent之后尝试 Supervisor 模式最后接入 LangGraph Server 做 API 化部署。每一步都跑通之后再进入下一个阶段企业级 Agent 开发就不会走太多弯路。