我见过太多Agent项目Demo惊艳全场一上生产系统就满地找牙。这个现象跟Agent的架构设计强相关尤其是多智能体协作很多坑在Demo阶段根本不会暴露出来。今天想借这个标题把我自己从零做Agent、再到拆成多智能体、最后落到生产系统的完整思路和踩坑记录整理一遍。这篇文章适合两类人一是已经用LangChain、LangGraph这类框架做出过Demo、正准备往工程化方向走的开发者二是手里有几个Agent原型、想搞清楚“多智能体到底怎么拆、怎么通信、怎么编排”的架构师。内容不会只讲概念会把每个决策背后的为什么讲清楚也会给可以直接抄作业的配置和步骤。1. Agent架构为什么不能照搬Demo代码1.1 Demo和真正的Agent系统差的不是代码量先看一个最常见的Demo长什么样一个Python脚本从控制台读用户输入拼一个prompt丢给大模型模型决定调用某个函数函数跑完再给模型结果最后打印答案。整个过程在内存里完成状态变量放在局部失败就CtrlC重跑模型密钥写死在环境变量里。这套东西在演示时没有任何问题但几乎每个环节到生产都会变成事故。我自己整理过一个对照表每次做技术方案评审都会拿出来用维度Demo阶段生产系统要求用户规模只有你一个人多用户同时访问会话必须隔离状态存储内存变量持久化存储可恢复、可追溯可观测性print和断点全链路trace、结构化日志、指标监控失败处理重跑一遍自动重试、降级兜底、人工干预安全假设输入可信恶意输入、提示注入、越权调用都必须防成本几乎可以忽略每任务成本能被量化、被控制评估肉眼看输出离线回归集 线上指标双轨验证这里说的“架构”不是简单的代码目录结构而是整个系统的运行时骨架调用链怎么走、状态流怎么动、容错边界画在哪、后续演进怎么扩展。Demo代码往往是一条直线生产系统则必须是一张网网上的每个节点都要有兜底逻辑。1.2 Agent的“能力边界”到底在哪里做生产系统前建议先把Agent的能力边界想清楚。不是所有任务都适合交给Agent自由发挥模型有推理能力的上限工具有执行能力的边界记忆有获取和更新的成本。这三个因素共同决定了Agent能扛住什么场景。一个很典型的例子让Agent做“查询天气并推荐穿衣”很容易但让Agent做“根据上百页财报判断公司经营风险”就很难不是模型不会推理而是上下文塞不下、检索不精准、输出不可验证。生产系统不会等Agent硬着头皮跑完而是在任务进入之前就先做分流判断哪些进Agent主流程、哪些走规则引擎、哪些直接回复“抱歉无法处理”。这个“拒绝策略”在Demo阶段几乎没人写但生产环境必须有否则边界外的任务会把token消耗和用户等待时间一起拖垮。1.3 从“函数调用”到“系统设计”的思维转变Demo的本质是“本地触发”本地调用、本地输出、本地观察。生产系统的本质是“服务”外部请求进来经过鉴权、限流、排队再由Agent处理结果写回存储整个过程可能异步完成。思维转变发生在几个细节上。入口不再只是一个main函数而是要处理HTTP请求、消息队列、定时任务等多个来源模型返回的不再是直接展示的文本而是要解析出结构化动作工具调用失败不能再直接抛异常而是要转成模型能理解并继续执行的错误信息。我见过很多团队把这个转变理解成“加一个FastAPI壳子”但真正的差别在于状态、失败和并发这些非功能性的东西这些才是生产系统的地基。2. 单体Agent架构的核心模块拆解2.1 五层结构接入层、编排层、模型层、记忆层、工具层不管最终要不要拆成多智能体先把单体Agent的分层做扎实是最稳妥的路径。我习惯把Agent系统拆成五层每一层只做一件事接入层统一处理来自API、IM机器人、Webhook、定时任务的请求完成用户认证、参数校验转换成内部统一的任务格式。编排层决定“下一步干什么”持有Agent的主循环逻辑。最常见的是ReAct模式也就是“思考-行动-观察”循环复杂任务可以用Plan-and-Execute先整体规划再逐步执行。模型层封装所有大模型调用统一请求和响应的数据结构负责流式输出、重试、结构化解码、token计量。记忆层管理短期记忆当前对话上下文和长期记忆跨会话的知识、用户偏好、历史事实。工具层注册Agent可调用的外部能力包括搜索、代码执行、API调用、数据库查询统一鉴权、参数校验和结果清洗。这五层对应到代码上就是五个清晰的功能边界互相之间不建议跨层引用。很多容易崩的Agent项目问题就出在编排层直接写模型调用、模型层又掺杂业务状态最后改一个需求牵一发动全身。2.2 模型层别把大模型当成唯一的“数据库”生产环境里最常被低估的是模型层。很多Demo直接在业务代码里调openai.chat.completions.create看起来简单但一旦涉及换模型、加流式、做重试代码就到处都是补丁。模型层的核心价值是“适配和隔离”。适配是指对不同供应商的模型做统一接口支持把同一个请求路由到不同模型隔离是指业务代码永远只和本地的LLMClient打交道不直接依赖某个SDK。这样做的好处很实际某天你发现GPT-4太贵、换一个便宜的模型只需要改模型层的路由配置业务编排一行都不用动。结构化输出是另一个必须提前考虑的工程点。不要指望模型返回的JSON永远是合法JSON生产环境一定要用强制手段。目前最可靠的是function calling或者JSON mode部分模型还能用constrained decoding。我在项目中的做法是所有Agent决策都定义为强类型的JSON Schema解析失败就重试一次再失败就进入降级分支。这个机制在Demo阶段可有可无但在生产环境是每天的日常。2.3 记忆与上下文管理上下文窗口不是内存条很多人把上下文窗口当成内存条觉得只要没到上限就随便塞。实际跑过生产就知道token变多之后模型会忽略中间的关键信息也就是所谓的“迷失在中间”。而且每次请求都要重发全部历史延迟和成本线性上涨最后账单比Agent的产出还吓人。记忆层要做的是分级管理。当前轮对话的上下文控制在窗口的30%以内超过部分做摘要压缩把对话历史转成阶段性结论跨会话的用户偏好、知识片段存进向量库按需检索召回业务状态比如订单号、审批流程ID则从外部存储查询不塞进系统提示词。这里分享一个我自己实践过的策略每轮对话结束时把当前状态打包成一个快照包括任务目标、已完成步骤、未决问题、关键实体。下一轮不是重发全部原始消息而是把这个快照作为场景起点。这一招能把长对话的token开销砍掉一半以上还能缓解上下文污染。2.4 工具层每次工具调用都是一次外部IO工具层是最像传统后端工程的地方。Agent怎么描述工具、怎么传参数、怎么处理返回值都应该有严格的规范而不是让模型自由发挥。我的做法是给每个工具写一份“运行手册”里面包含工具功能描述、参数Schema、触发条件、错误代码、示例返回。模型通过function calling拿到这份手册后决定是否调用。参数校验必须在模型层之后、真实IO之前做防止模型捏造或者传错参数。工具返回值要标准化成功、失败、部分成功都要有明确的机器可读状态。还有一个容易踩的坑工具权限。给Agent挂一个“能执行任意命令”的终端工具和把服务器root密码贴在工位上没有区别。生产环境要坚持最小权限原则高危操作单独加审批流工具的调用记录要进审计日志。近几年MCPModel Context Protocol这类标准协议越来越普及建议新工具优先按MCP方式暴露天然具备权限边界和统一描述格式。3. 多智能体拆、分、聊、管3.1 什么时候才需要多智能体以及什么时候不需要不是所有项目都该上多智能体。我见过的最离谱的误用是三个Agent互相争论“这个用户问题该怎么分类”折腾了8000多个token结果一个简单分类函数几毫秒就能跑完。多智能体真正适用的场景有几个特征任务本身可以拆成多个职责边界清晰的子任务子任务之间存在信息并行或流水线协作单个Agent的上下文装不下所有专业知识和工具不同角色需要独立的状态和记忆。比如工单处理系统就很典型一个Agent负责客户沟通另一个负责查知识库还有一个负责生成最终解决方案它们各自维护自己的工具和上下文互不干扰。反过来如果任务就是一个问答、一次单工具调用、或者需要严格保持全局一致性的事务就别拆。多智能体带来的消息风暴、通信延迟、状态一致性协调成本最终都是从用户能感知的响应时间和错误率里扣钱的。3.2 三种主流编排模式对比多智能体的编排模式基本逃不出下面三种编排模式工作方式适用场景主要风险Supervisor主管一个主管Agent负责任务分解、分配和结果汇总worker执行具体子任务任务边界清晰、需要收敛决策主管成为性能瓶颈和单点故障Peer-to-peer对等多个Agent地位平等相互之间直接发消息协作高度动态的协作任务消息无序、容易变成“聊天室”Hierarchical层级上级主管拆任务子主管再拆worker在底层执行大规模、复杂任务链路深、延迟放大、追踪困难Supervisor模式最适合绝大多数业务系统。它实现的不是“多智能体”而是“多角色”主管Agent更像一个项目经理它不干活只负责拆解、追踪和验收。LangGraph里的supervisor节点、AutoGen的group chat两种方案我都试过前者更适合工程落地因为状态机和条件转移是显式的。Peer-to-peer模式看着高级但坑极多。多个Agent对“下一步做什么”有不同判断如果没有终止条件会互相唤醒、无限循环。除非你的场景天然是开放式的多角色讨论否则不建议作为主干方案。3.3 多智能体通信协议像设计微服务一样设计Agent多智能体系统确实很像微服务但这个类比里最重要的一点常被忽视微服务之间用定义好的API契约通信多智能体之间也得有消息契约而不是直接把自然语言文档抛来抛去。我建议每个跨Agent消息都带上元信息消息ID、发送方、接收方或订阅主题、任务ID、消息类型请求、响应、事件、命令、时间戳、负载格式版本。发送方把结果写成结构化事件发布到总线订阅方按需消费这就是典型的事件驱动架构。好处是节点之间解耦还能回放重试。如果直接点对点调用系统会退化成一张无法理清的调用网。多Agent的状态管理也要借鉴分布式系统的思路。共享记忆不建议所有Agent都读同一个全局变量区而是按Agent分区再通过消息做同步。写冲突要用版本号兜底。某个Agent在处理期间失败重启了状态从哪恢复、已经发出的消息会不会重复执行这些问题必须在设计阶段给出答案。3.4 多智能体协作中的一致性、冲突与优先级两个Agent意见相左的时候谁说了算生产环境不能靠模型临场辩论要提前定规则。我的经验是三层兜底第一层每个Agent在prompt里写清楚自己的决策边界和可接受的不确定级别第二层主管Agent对所有结果做最终裁决第三层系统层面设置超时和默认路由超时未决自动进入人工处理队列。外部系统调用的一致性问题更隐蔽。比如一个Agent负责生成邮件内容另一个Agent负责发送邮件网络抖动导致发送结果丢失重试时就会重复发邮件。解决办法是给每笔外部操作生成幂等键接收方靠幂等键去重。这个细节在Demo阶段没人会想但它直接决定了生产事故的数量级的。4. Demo到生产必须补齐的六项工程能力4.1 可观测性删除所有print换成结构化traceAgent系统的调试难度远超传统服务因为每一步都有模型主观判断错误不会像普通异常那样有清晰的堆栈。生产环境的Agent必须做到让每一轮决策可以被回放模型收到什么prompt、输出了什么、选择了哪个工具、传了什么参数、拿到什么结果、下一步转移到了哪个节点。我现在的做法是给每个任务分配一个trace_id从入口一直贯穿到所有模型调用和工具调用。祖业测日志、指标、收费数据全部挂在trace_id下面。工具选型上LangSmith很方便但更通用的是OpenTelemetry把Agent的LLM调用和工具调用都手动埋点这样能复用公司已有的可观测性基础设施。不要迷信某一款工具关键是把事件模型定好。4.2 可靠性与容错模型是会失败的工具是会挂的Demo阶段调用模型失败的概率很低所以你感觉不到重试机制的必要性。到了生产环境模型服务超时、限流、返回畸形内容几乎是每天都会发生的。我的建议是三层容错超时控制、重试退避、降级兜底。参数可以参考这个经验表调用对象超时时间重试策略降级动作大模型LLM调用30秒最多2次指数退避返回预设兜底话术外部工具API10秒最多1次把错误状态交给模型决策消息队列消费5秒3次退避进入死信队列人工处理Agent主循环本身也要有步数上限。我习惯设置为10到15步超过就终止并生成阶段性总结而不是无限跑下去。很多所谓“Agent死循环”本质就是缺这一步。4.3 安全与护栏防注入、防越权、防泄漏Agent的开放性和安全性天然冲突生产环境必须把安全当成第一需求。最常见的威胁是提示注入用户输入里的一段恶意文本试图让Agent忽略系统提示、执行危险操作。防注入不能靠一句“Ignore previous instructions”而是要分层防御。第一层入口做输入过滤识别并隔离明显的命令注入和敏感信息请求第二层系统提示词中加入安全规则明确哪些动作永远不允许执行第三层工具调用按最小权限配置高危操作如发邮件、删除数据、支付操作单独决策甚至加一道人工审批第四层所有Agent输出过一遍敏感信息检查防止把数据库里的隐私内容合成进回复。这个领域现在演进非常快搜索“Agent安全”能看到的资料已经不少但核心还是把权限边界画清楚而不是指望模型凭空变安全。4.4 成本控制token不只是钱也是延迟很多Demo项目根本没有成本概念一个任务轻松烧掉几万token感觉无所谓。上生产之后第一笔账单就让人清醒。要控制成本首先得能算清账任务成本等于输入token单价乘数量加上输出token单价乘数量再加上工具调用次数乘以单次调用成本包括外部API的费用和内部算力开销。实操上有三板斧。第一板斧是缓存最有效的是语义缓存用户问题经过向量化后和近期问题比对相似度超过阈值就直接复用上一次的回答大模型一次都不需要调用。第二板斧是模型分级简单分类或者信息抽取用便宜的小模型复杂推理才调用旗舰模型。第三板斧是上下文瘦身也就是前面讲的快照摘要机制这个在长会话场景下成本差异非常显著。我自己项目里的经验优化后单任务token开销能下降60%以上。4.5 评估体系没有评测集你根本不知道上线后是变好还是变坏Demo靠感觉生产靠指标。没有固定的评估集你会发现每次调优都像是在碰运气。上线前建议先建一个黄金评测集收集200到500条真实任务每一条标注期望结果和允许的行为边界比如是否必须调用某个工具、是否允许拒绝回答。评估分成两个维度。结果评估直接判断最终输出的质量可以人工标注也可以用强模型当裁判LLM-as-judge过程评估关注模型是走了几步才完成任务、是否调用错误工具、是否卡在死循环、是否产出违规内容。上线后还要盯线上指标任务成功率、用户主动反馈率、平均对话轮数、单任务成本。评测集和线上指标构成了双轨任何prompt调整或者模型升级都要先跑回归再决定要不要上线。4.6 部署与发布灰度、回滚、配置分离很多人把Agent部署想象成部署普通Web服务实际上更复杂的地方在于一个版本的行为由模型权重和prompt共同决定任何一个变化都需要纳管。模型版本要做映射一个产品版本明确绑定模型ID和prompt版本prompt要像代码一样进仓库每次修改都有Diff记录可供回滚。发布时建议先做灰度让新版本处理5%到10%的线上流量对比旧版本的任务成功率和成本数据。配置分离也很关键模型API key、工具URL、超时时间、步数上限这些参数全部放配置中心不能散落在代码和部署脚本里。这样出问题时调整一个配置就能快速止血而不是重新发版。5. 实操案例一个客服工单助手如何从Demo进化到生产5.1 原始Demo一个跑通了的Python函数我拿自己做过的一个客服工单助手举例。最早的Demo是一个两百行左右的Python脚本接收用户问题拼接一个包含客服话术规范的prompt调用大模型模型判断需要查工单库就执行一个search_ticket()函数把结果再丢回模型生成回答。这个Demo在人肉演示时效果不错但上线第一天就暴露了三个问题并发用户稍多脚本直接阻塞会话状态在内存里用户换一台设备就丢了历史模型偶尔把一个不存在的工单编号编造成“已处理”没有任何校验。这三个问题都属于Demo不背锅、生产躲不掉。5.2 第一次重构服务化、持久化、队列化第一次重构做了三件事。第一用FastAPI包了一层HTTP服务每个用户请求带session_id第二对话记录和任务状态写进Redis超时后异步持久化到数据库第三引入消息队列RabbitMQ用户请求先进入队列Worker进程从队列拉任务处理完回调结果。改完后并发问题解决了但架构上还是“单智能体”一个Worker里跑的是一个完整Agent知识库检索、工单分类、答复生成全在一个上下文里。表现是prompt越来越长模型在多个任务间来回切换经常出现分类错误。5.3 第二次重构拆成主管加三个专用Agent第二次重构决定拆多智能体。整体结构是这样的Router/Dispath Agent主管负责理解用户意图决定把任务分配给哪个下游Agent并汇总最终回复。Classifier Agent分类专用只做一件事判断工单的紧急程度和类别输出一个标准分类结果。Knowledge Agent知识检索专用负责搜索内部知识库召回相关文档输出引用列表。Solution Agent方案生成专用拿到分类结果和知识片段后生成最终答复方案。编排框架选的是LangGraph因为它的状态图和条件边很直观适合主管模式的落地。核心代码结构是这样from langgraph.graph import StateGraph, END g StateGraph(WorkflowState) g.add_node(dispatcher, dispatcher_agent.run) g.add_node(classifier, classifier_agent.run) g.add_node(knowledge_search, knowledge_agent.run) g.add_node(solution_generator, solution_agent.run) g.add_edge(dispatcher, classifier) g.add_edge(dispatcher, knowledge_search) g.add_edge(classifier, solution_generator) g.add_edge(knowledge_search, solution_generator) g.add_edge(solution_generator, END) app g.compile()这里有两个关键决策。第一分类和知识检索设计成并行执行因为两者互不依赖并行能节省用户感知的响应时间第二Solution Agent只有在拿到分类结果和知识片段之后才启动保证生成答案有依据不会凭空编造。拆完之后效果最明显的不是准确率而是稳定性和可调试性每个Agent都有独立的prompt和工具问题定位范围大幅缩小。分类出错了直接看Classifier Agent的trace知识召回不准只调Knowledge Agent的检索策略。6. 常见问题与排查技巧实录6.1 踩过的坑和对应解法下面这些问题是多智能体项目里最常出现的我按真实项目经验整理成速查表现象根因排查与解法两个Agent互相回复退化成聊天室没有行为边界和终止条件每个Agent指定明确职责定义输出schema主循环设最大轮数模型虚构工具执行结果工具返回未被严格校验工具层每一步做返回值校验失败状态必须传给模型用户上下文串了会话状态未隔离所有记忆和缓存key必须带上session_id同一笔任务邮件发了两遍重试机制覆盖了外部副作用每次外部操作生成幂等键接收端去重模型升级后行为突变缺少评估集回归固定黄金评测集上线前全量回归Agent卡在一个节点反复调用同一个工具工具结果没有消除触发条件给工具调用增加“调用历史”反馈禁止相同参数重复执行6.2 再多说几条独家经验第一条给每个Agent决策的过程都生成独立trace_id。排查多Agent问题时最大的痛苦是不知道哪一步决策出了问题。有了trace_id就能把模型输入、工具参数、输出结果串成一条完整证据链。第二条消费队列消息前先做幂等。幂等表里记录每个task_id的处理状态重复消费直接跳过。这个机制能挡住大量分布式环境下的重复执行风险。第三条Agent的主循环要设步数上限这个前面提过但我还想强调上限值最好小一点。一开始用20步实际跑下来一个简单的工单任务平均只需要4到5步超过10步的任务基本都是走偏了不如提前终止。第四条把“人工审批”作为一个工具暴露给Agent。当Agent面对高危操作时它不应该自己决定执行而是调用一个approval工具推送审批请求给人工。等人工确认后Agent再继续后续流程。这个模式对比“自动执行”来说安全性提升巨大而且不会阻塞整体架构。我个人的体会是Agent系统从Demo到生产本质上是一场从“无限循环”到“有界服务”的转变。Demo里你可以容忍模型跑偏、容忍结果不确定、容忍token超支生产环境里每一样都会变成事故或者账单。如果让我重新做一个Agent项目我会从第一天就建评测集、埋成本监控、画好权限边界而不是等系统上线后再追着事故去补这些能力。希望这篇拆解能帮你在做架构决策时省几个月的弯路。