前阵子一个朋友跟我吐槽说他们团队用 LangChain 做了个 AI Agent 原型demo 汇报时全场鼓掌结果一上线就翻车任务稍微复杂一点就丢中间状态工具调用时好时坏日志里全是碎片根本看不出来 Agent 到底在哪一步做了决策。这个场景这两年我听过太多次了。问题通常不在模型也不在 LangChain 本身而在于很多人把 Agent 当成一个“更聪明的对话接口”却没有把它当成一个需要状态管理、错误恢复、权限控制和可观测性的系统工程来设计。LangChain V1.3 和 LangGraph 这套组合真正能帮到你的不是把 prompt 封装得更漂亮而是逼你把流程、状态、工具、异常处理这些工程问题显式地写出来。这听起来比“多智能体”少了很多科幻感但恰恰是企业落地时最缺的部分。下面我会从框架分工讲起再拆解核心组件带你把一个最小可运行的多智能体流程跑通最后补上生产化需要的几块拼图以及一条实战排查链路。1. 先搞清楚LangChain V1.3 和 LangGraph 到底在解决什么问题1.1 一次真实的“demo 能跑生产翻车”经历先说那个朋友的团队踩过的坑。他们最初用 LangChain 写了一个客服问答 Agent结构很简单用户问题进来先从向量库检索资料然后拼进 prompt再让大模型生成回答。单条测试效果不错领导看完就说“可以上了”。上线后问题一个接一个用户连续追问时Agent 忘记了上一轮已经给过的结论反复推荐同一个方案。需要查库存、查订单、查物流三步操作时只要中间某个工具报错整条流程就断而且不知道断在第几步。同一个问题不同人问结果差异很大但因为没有任何决策日志根本没法复盘。想把“查订单”这个能力单独交给一个专门的小 Agent发现原来的链式结构根本插不进去。这些问题本质上是同一个流程没有状态、没有边界、没有观测点。LangChain 早期的 Chain 抽象擅长处理线性调用但真实业务里的 Agent 是分支、循环、条件判断、人工确认混杂在一起的。单靠 Chain 把工具一长串排进去等于把业务逻辑藏在了模型的黑盒判断里出了问题只能靠猜。1.2 框架分工LangChain 是零件箱LangGraph 是装配线LangChain V1.x 阶段框架已经在往更稳定的方向收敛。我们可以把它理解成一个“零件箱”模型调用、消息结构、输出解析、向量库、检索器、工具封装这些零件被整理得越来越整齐方便你组合使用。很多人说 LangChain “太重”其实到了 V1.x 阶段它更像一个标准化的整合层价值不在某个单点功能而在于帮你减少“模型 A 配向量库 B 再配工具 C”时需要自己写的胶水代码。LangGraph 则完全是另一层的东西。它关心的问题是一个 Agent 任务从开始到结束要经过哪些节点每个节点输入什么、输出什么状态怎么流转失败怎么回退谁能打断流程。你可以把它理解成装配线零件箱里的东西最终要放到生产线上生产线负责任务的分工、顺序和异常处理。两者不是替代关系。LangChain 负责“怎么调用模型、怎么调用工具”LangGraph 负责“这些调用按照什么图结构组织、状态怎么更新”。通常的做法是在 LangGraph 的节点函数里去用 LangChain 的模型封装和工具封装两者配合使用。至于标题里的 V1.3它的具体版本号不用太纠结。更值得关注的是这个阶段给开发者带来的两个信号一是组件接口更稳定迁移成本变低二是 Agent 相关的状态管理、工具调用、可观测性能力被提到了核心位置而不是作为插件存在。如果你们团队还在用老版本的链式写法现在确实是切换到图式编排的好时机。2. 多智能体架构不是角色越多越好而是状态和分工更清晰2.1 单 Agent 的物理与逻辑瓶颈很多人一听到“多智能体”就想得很玄仿佛要让几个 AI 互相聊天、吵架、博弈。但在企业场景里多智能体的核心动机往往更朴素一个 Agent 装不下所有东西。先说物理瓶颈。模型上下文窗口再大也扛不住“系统指令 长期记忆 工具说明 当前任务 多轮历史”无限往里塞。工具一多模型反而容易选错prompt 越长决策稳定性越差。再说逻辑瓶颈。客服、质检、订单处理、知识库问答这些任务如果全部塞进同一个系统 prompt它们之间的规则会互相冲突。你想让它对用户礼貌又想让它对内部系统果断执行两种语气和规则挤在一起模型经常“精神分裂”。从维护角度看单 Agent 更像一个不断膨胀的主类。今天加一个工具明天加一条规则后天改一个提示词最后没人知道某个行为是哪条规则触发的。多智能体的一个隐含价值是把这种“大杂烩”拆成多个高内聚的模块每个模块只做好一件事。2.2 常见多智能体拓扑调度、流水线与协作我用下表把最常见的几种多智能体结构列出来方便你在设计时对号入座。拓扑类型工作方式适合场景主要问题调度者-执行者Supervisor-Worker一个调度者判断任务类型分发给多个专门执行者任务类型明确、可分类比如客服、工单、数据分析调度者是瓶颈需要设计好分发规则和兜底策略流水线Pipeline任务按固定顺序经过多个处理节点前一个节点的输出是后一个节点的输入流程稳定比如“解析需求→生成初稿→格式校验”不适合需要动态跳转或反复迭代的任务协作/辩论Swarm/Debate多个 Agent 并行处理同一问题再做汇总或投票需要多角度分析、质量评审、方案对比成本高结果不稳定需要额外的汇总机制分层结构Hierarchy上层调度者下面还有子调度者层层往下分业务线很多且有明确层级复杂度高初期不建议直接上在 LangGraph 里实现这些结构并不需要给每个“智能体”都单独部署一个模型服务。更常见的做法是每一个 Agent 对应图里的一个 Node 函数函数内部维护自己的 model、tools、prompt通过共享状态与其他 Node 协作。多智能体在工程上首先是一种代码组织方式其次才是一种算法架构。2.3 企业级多智能体真正要关注的三个核心点第一是状态共享与隔离。团队里多个人同时开发A 节点往状态里写一个result字段B 节点也往result写就会互相覆盖。我建议从一开始就给每个节点的输出字段做明确的命名空间比如customer_result、order_result避免系统变成一团乱麻。第二是任务编排与循环控制。Agent 任务经常要“先试一次失败了换个方式再试”如果这条循环路径没有最大次数限制模型可能陷入死循环每次调用都在消耗真金白银的 token。所以编排时一定要给循环加上阈值、超时和兜底出口。第三是人机协同。企业级流程里很多环节需要人确认才能往下走比如退款金额、合同条款、对外发布内容。LangGraph 通过interrupt_before或 checkpointer 机制可以停在某个节点前等人审批后再继续。这一条如果没设计好多智能体再聪明也没法真正进入生产环境。3. 核心组件拆解模型、工具、状态不是三个孤立模块3.1 模型层不是“一个模型打天下”在多智能体系统里模型选择应该跟着任务走。调度节点可以用一个快一点、便宜一点的模型因为它的职责是分类和判断不需要深度生成执行节点可能需要更强的推理能力提取结构化信息的场景则最好让模型使用结构化输出或函数调用而不是靠正则去解析自由文本。例如在 LangChain 里绑定工具的方式是from langchain_openai import ChatOpenAI from langchain_core.messages import HumanMessage llm ChatOpenAI(modelgpt-4o-mini, temperature0) resp llm.invoke([HumanMessage(content你好帮我查一下北京的天气)]) print(resp.content)这里有一个常见的误解明明给模型绑定了天气工具模型却不肯调用。这时候先别怪模型要先检查工具的描述是否够清楚、工具的入参是否是模型能从用户问题里自然提取的格式。工具调用的稳定性很大程度取决于工具自身的 Schema 设计而不是 prompt 里的“你必须调用工具”这句话。3.2 工具与 SkillLangGraph 里怎么“加技能”很多人会搜“langgraph 怎么增加 skill”。其实在 LangChain 体系里Skill 往往就是对工具函数的一层封装。一个技能可以包含工具函数本体、模型调用策略、前置状态要求、后续输出处理。在 LangGraph 中新增一个技能通常分成三步用tool装饰器定义工具函数写好 name、description、参数说明。在某个 Node 内部把工具绑定到对应模型或者放入ToolNode统一执行。在状态里定义该技能需要读取和写入的字段避免跨节点冲突。工具的容错设计也要提前做。工具可能因为下游系统不稳定而抛异常我建议在工具函数内部就把异常转换成机器可读的错误信息而不是让它直接炸穿整个图。比如查询订单失败时返回{status: error, reason: order_api_timeout}让上层节点有条件地决定是重试还是换一种方式处理。3.3 状态与记忆把临时变量升级成系统协议LangGraph 最核心的抽象是 State。每个节点接收当前 State返回 State 的部分更新。State 可以是一个TypedDict可以是消息列表也可以是更复杂的自定义对象。通常我会推荐这种写法from typing import TypedDict, Annotated from langgraph.graph.message import add_messages class AgentState(TypedDict): task: str messages: Annotated[list, add_messages] result: str finished: bool用Annotated[list, add_messages]声明的字段LangGraph 会自动把新消息追加到旧消息后面而不是覆盖。这种“规约式更新”在多智能体协作里非常重要它避免了每个节点都要手动拼历史消息的麻烦。记忆则是一个更上层的话题。短期记忆可以放在 State 里跟着图一起流转长期记忆建议放到外部存储比如向量库或普通数据库。我看到不少设计把“记忆”简单理解成“把历史都塞进 prompt”这是最贵的做法。更好的思路是先想清楚系统到底需要记住什么——用户偏好历史结论已经尝试过的失败方案然后给每种记忆设定生命周期和读写权限。3.4 节点、边和条件边图编排的三个基本语法LangGraph 的源码实现其实不复杂核心就是把“节点函数”和“边关系”解释成一个可执行图。节点是一个普通 Python 函数输入 State输出 State 的部分更新。边分为普通边和条件边条件边的返回值决定下一步进入哪个节点。from langgraph.graph import StateGraph, END def decide(state: AgentState): if state.get(finished): return END return next_step graph StateGraph(AgentState) graph.add_node(worker, worker_node) graph.add_conditional_edges(worker, decide)条件边是实现 Agent 循环、分支、人工审批的核心。需要特别注意的是条件函数必须是确定性逻辑不要在条件函数里去调大模型做开放式判断。如果必须根据模型结果决定跳转那就把“模型判断”做成一个独立的 Node它输出的结构化字段再交给条件函数去路由。4. 用 LangGraph 跑通一个“调度者-执行者”多智能体最小流程4.1 环境准备先准备好基础环境。这里的版本建议以你实际安装时为准我用一个常见配置做示例python -m venv .venv source .venv/bin/activate # Windows 下执行 .venv\Scripts\activate pip install langgraph langchain langchain-openai如果你使用 OpenAI 兼容接口需要配置对应的 API Key如果使用国内模型厂商的接口通常也是 OpenAI 兼容协议改一下base_url和api_key即可。先把单条请求跑通再进入图编排这是省时间的关键。4.2 最小多智能体代码Supervisor Worker下面是一个很克制的示例只演示“调度者-执行者”的最小骨架。调度者节点负责接收和分发任务执行者节点模拟处理任务并返回结果条件边确保流程最终走到结束。from typing import TypedDict from langgraph.graph import StateGraph, END class State(TypedDict): task: str result: str finished: bool def supervisor(state: State): # 真实项目里这里可以用 LLM 或规则做意图识别和任务分发 print(f[supervisor] 收到任务: {state[task]}) return {task: state[task]} def worker(state: State): # 真实项目里这里会调用模型或具体工具 print(f[worker] 开始处理: {state[task]}) return {result: fworker 已完成: {state[task]}, finished: True} def after_worker(state: State): if state.get(finished): return END return worker graph StateGraph(State) graph.add_node(supervisor, supervisor) graph.add_node(worker, worker) graph.set_entry_point(supervisor) graph.add_edge(supervisor, worker) graph.add_conditional_edges(worker, after_worker, {worker: worker, END: END}) app graph.compile() result app.invoke({task: 把季度销售数据汇总成一份简报, result: , finished: False}) print(result[result])运行后控制台会依次打印supervisor和worker的日志最后输出处理结果。这个示例肉眼可见地简单但它揭示了一个事实多智能体的骨架并不神秘就是一组有状态、有边界、有路由规则的函数。你在这个骨架上逐步加入真正的模型调用、工具函数、人工确认节点就是一个可演化的企业级 Agent。4.3 单条任务验证的三个检查点跑通之后不要直接上批量任务先检查三件事状态字段是否符合预期。打印最终 State确认result和finished被正确更新没有节点产生意外的副作用。循环是否真的能退出。把finished初始值改成True看条件边是否直接返回END。异常路径是否可见。临时在worker里抛一个异常观察控制台和日志确保你能定位到是哪个节点出了问题。关于启动方式如果你想在开发时做交互式调试LangGraph 提供了浏览器端调试面板如果你希望暴露成 API 服务可以自己用 FastAPI 包一层 graph 调用。两种方式并不冲突看团队需要的是“可视化调试”还是“对外服务”。5. 从单条流程到企业级必须补上的四块拼图5.1 可观测性知道每一步发生了什么Agent 类应用最让人头疼的就是“模型为什么不按我想的走”。回答这个问题需要足够细的观测数据。至少要有每个节点的入参和出参摘要。每次 LLM 调用的输入、输出、token 消耗和延迟。每次工具调用的入参、返回结果、耗时、是否异常。条件边的路由结果以及循环的执行次数。在 LangGraph 里可以通过 callback 或 tracer 把这些信息统一记录下来也可以对接 OpenTelemetry 体系。即使不上商业产品自己写一个“节点进入/退出”日志插件也能解决 80% 的问题。5.2 异常恢复从“崩溃重启”到“断点续跑”生产环境里下游系统超时、模型限流、工具返回畸形数据都是常态。你需要给每个节点设置超时时间给关键调用配置重试并且要知道“重试多少次之后应该停下来转人工还是走降级方案”。LangGraph 的 checkpointer 机制可以把图的中间状态持久化到数据库里。这样当任务中断后你不需要从头执行整个图而是从最近的检查点继续。这个能力在长耗时任务里非常重要没有它任何超过一分钟的 Agent 流程都会变得很脆。5.3 权限与成本控制Agent 不能拿到“所有工具”企业内部系统里Agent 能访问的数据边界必须显式定义。“给所有 Agent 所有工具的访问权”是最危险的设计。更合理的方式是不同 Agent 节点只绑定它职责范围内需要的工具。对涉及外部系统的工具在工具函数内部做二次校验确认当前任务确实有这个权限。设置单任务 token 上限和总成本阈值超过之后自动中断避免模型异常循环烧钱。权限控制不是安全团队的额外要求而是 Agent 能稳定运行的前提。一个拿到全部工具的 Agent会用自己的方式制造各种“惊喜”。5.4 评估与测试别用“感觉不错”当验收标准Agent 的评估比传统功能测试复杂因为同一个输入可能产生多种合理输出。我见过比较靠谱的评估体系是“三层结构”单元层单独测试每个 Node 函数特别是工具函数和自己的逻辑函数保证输入输出符合契约。集成层给定一批标准输入跑完整图用规则校验关键字段、必选动作、禁止行为是否被满足。回归层每次改 prompt 或工具后跑一遍历史测试集对比结果差异防止“修好一个 bug 引出三个新问题”。此外还要保留一部分人工评估的样本池。尤其是涉及语气、合规、专业判断的场景机器规则只能覆盖底线真实质量仍需要人来看一批、抽一批。不要把评估做成一次性的要把它嵌入到每次代码变更的流程里。6. 一条实战排查链路从现象到根因别一上来就怪模型6.1 先复现再缩小范围排查 Agent 问题最忌讳一上来就改 prompt。先做三件事用同一条输入重新跑看是否稳定复现。如果报错读完整堆栈定位是模型调用层、工具执行层还是图路由层。不确定时写一个“最小复现脚本”把状态里无关字段全部去掉只保留触发问题的必经字段。很多问题在“缩到最小”的过程中自己就暴露了。比如某个字段为None、某个工具函数返回值类型不对或某个条件边走到了错误的节点。6.2 分层排查法输入、环境、参数、工具边界下面这张表是我在排查时常用的顺序排查层核心问题常见做法输入层输入字段是否完整、格式是否符合状态定义打印入口 state检查字段类型、编码、长度、是否包含非法值环境层依赖版本、API Key、网络、系统差异固定 Python 版本和依赖清单本地与生产保持一致参数层并发数、批量数、超时时间、重试次数是否合理先用小参数跑再逐步上调并观察资源占用工具边界层工具是否真的被调用、返回是否被正确处理单独直接调用工具函数绕过 Agent 流程做测试举个例子如果用户总说“Agent 回答风马牛不相及”先不要急着优化提示词。要确认向量检索结果是否为空检索到的片段有没有被正确拼到上下文里模型有没有按检索内容组织回答。很多“模型不聪明”的指控最后都成了“数据管道没通”的锅。6.3 三个高频踩坑点我在实操里至少见过三次同类问题值得单独列出来工具结果被 prompt 写死。调试时为了省 token有人把工具返回结果手动写到 prompt 里上线时忘了删导致模型每次都输出同一段内容。工具结果必须来自真实调用要让输出的内容有据可查。状态字段互相覆盖。两个节点往同一个字段里写不同类型的数据运行时不报错但结果时好时坏。这就是前面说到的命名空间问题。循环节点没有次数上限。一个需要自我修正的 Agent因为工具一直返回失败就一直在原地打转直到预算被耗尽。务必给循环加上最大次数并在达到阈值后切换到兜底节点。7. 选型建议先别急着上多智能体也别轻易放弃 LangGraph7.1 三个方案的边界在哪里做技术选型要比的是“什么场景最合适”而不是“哪个名字更高级”。我把三种常见路线的适用边界整理成一张表方案建议使用场景不建议使用场景只用 LangChain简单的 RAG 问答、固定线性流程、模型封装和工具调用为主多分支、多智能体、循环修正、人工审批、长事务任务LangChain LangGraph需要状态管理、条件路由、多智能体编排、可回放可恢复的 Agent 流程极简任务一个大模型加一个检索器就能完成的场景自研编排层有极强的定制需求、完全私有化基础设施、或团队已有成熟的流程引擎多数团队。自研要处理状态、持久化、并发、可视化、测试成本通常被严重低估有一个经常被讨论的问题是“LangGraph 能不能代替 flowable 这类流程引擎”。我的判断是它们解决的不是同一层问题。传统流程引擎擅长固定规则、可预测、强一致的业务流程LangGraph 擅长模型驱动的动态决策和复杂任务编排。现实项目里两者可以互补固定流程用引擎需要智能判断的节点再接入 Agent。工厂 MES 这类场景更稳妥的做法是先做局部试点把设备数据的读权限和日志链路打通再谈智能调度。7.2 团队技术栈也是一个重要因素LangGraph 是 Python 生态如果你的团队是 Java 为主引入它就等于要维护一套新的运行环境。可以评估的是团队是否愿意长期维护 Python 服务和 Java 主服务之间的通信Agent 的并发压力、状态持久化是否要复用现有中间件有没有现成的模型网关、权限系统和监控体系可以接入有团队用 Spring AI 做 Agent 客户端也有团队用独立的 Python 服务处理 Agent 流程再通过统一 API 暴露给 Java 侧调用。没有绝对正确的答案但一定要选一个团队能长期背得动的方案。7.3 从最小闭环开始别设计一个“宇宙级 Agent”如果你刚接触这块我强烈建议从“一个 Agent 两个工具 一条人工确认路径”开始。先把数据访问、日志、权限、测试这套底座建起来再逐步把节点拆开演化成多智能体结构。很多团队失败不是因为 LangGraph 不够好而是因为他们第一版就想做一个能处理所有业务的超级系统最后因复杂度失控而搁浅。8. 长期判断Agent 开发的门槛早就不是模型能力我见过不少团队在模型选型上反复纠结却很少看到有人认真设计“状态协议”和“失败策略”。但一个企业级 Agent 真正昂贵的地方恰恰是那些不性感的部分状态字段怎么定义、工具故障时怎么办、谁有权调用哪个工具、每一步决策有没有日志、修改之后怎么验证没有把旧功能弄坏。LangChain V1.3 和 LangGraph 的组合最大的价值是把这些“不性感的部分”变成了一套可以被书写、被测试、被维护的工程结构。你写的不再是几段 prompt 和一串函数调用而是一张有状态、有边界、有观测点的流程图。这听起来不如“多智能体”酷但它是稳定性的来源。回到开头那个朋友的团队。他们最后跑通生产并不是换了更贵的模型而是接受了三件事把 Agent 当系统而不是对话把状态当协议而不是临时变量把调试当日常而不是事故。如果今天你的团队只能做一件事那就先别扩展场景把一个最小流程做到“能观测、能恢复、能测试”这比任何架构名词都值钱。