开头先泼盆冷水。我见过太多这样的项目Demo 演示的时候Agent 在台上侃侃而谈、把工具调用得行云流水客户当场拍板。结果一上线不是答非所问就是卡在某个工具调用里出不来要不就是并发一上来直接超时最后业务方留下一句“这玩意还不如人工”就撤了。我自己的团队也踩过同样的坑。今天这篇东西不聊花哨的 Agent 框架只聊一个事为什么企业级 Agent 从 Demo 到生产落地会拉胯以及我们把“四道坎”一一填平的全过程复盘。如果你正要评估 Agent 项目或者已经在生产环境里被问题追着跑这篇内容大概能帮你省下一两个月的试错时间。1. Demo 惊艳、上线拉胯到底差在哪1.1 复盘一个典型的“上线事故”先还原一个真实场景。三年前我参与一个智能客服改造项目需求很简单客户打电话进来Agent 根据知识库回答售后问题复杂问题转人工。Demo 阶段我们用的是精心挑选的样例问题每个答案都逻辑清晰工具调用准确率看着接近百分百客户满意度直接拉满。上线之后第一周问题就爆了。真实用户的问法千奇百怪一句话里能带三个错别字加两个语气词知识库里的文档有 PDF、Excel、网页截图格式不统一高峰期并发一上来大模型的响应时间从 Demo 时的 2 秒飙到 15 秒用户等不及直接挂断。最离谱的是有一次用户问“我的订单为什么还没到”Agent 检索到了运单信息但把“运输途中”解读成了“已签收”然后告诉用户“你的快递已经签收了请查收”。这类问题在 Demo 里永远不会出现因为演示样例都是标准化的。这里面的核心差异一句话就能概括Demo 验证的是模型的能力上限生产考验的是系统的能力下限。1.2 Demo 与生产的本质差异三张“伪装”的面孔我把 Demo 和生产之间的鸿沟归纳成三个层面每一层都会制造“上线拉胯”的假象。第一层是数据伪装。Demo 阶段用的知识库和真实生产知识库并不是一回事。演示数据通常经过清洗、去重、格式统一而生产数据往往充满噪音过期文档、重复条目、互相矛盾的说法。Agent 的检索环节一旦召回质量不高后面的推理和生成环节再怎么调都白搭。第二层是交互伪装。Demo 通常是单轮问答用户给一个问题Agent 给一个答案。真实场景是连续对话用户会打断、会补充条件、会否认之前说过的内容。Agent 需要有状态管理能力要记得住上下文还要在用户改变主意时及时更新状态。这一层缺失上线后就会出现“失忆”表现。第三层是评估伪装。Demo 靠人工观察和几个样板题验收而生产需要一套可量化的评估体系。我们用“准确率”看回答但真实业务更关心“任务完成率”——用户的问题有没有被真正解决而不只是话术正确。所以根因其实不在于模型能力而在于工程化程度。下面四道坎就是围绕这三层伪装逐一拆解出来的工程解法。2. 四道坎的第一道稳定性与可观测性2.1 根因概率模型的“灵光一现”与“阴暗面”大模型本身是概率系统同一个 prompt 给两次可能得到截然不同的答案。这放在聊天产品里还能接受放在生产业务里就是灾难。比如 Agent 调用一个接口下单第一次给参数 A第二次给参数 B第三次干脆说“我没听懂你的意思”。这是概率模型的属性不是 bug但工程上必须当作 bug 来处理。我们团队最早的处理方式是“加强 prompt”反复强调“你必须严格按照流程做”。结果效果有限模型有时候听话有时候依然我行我素。后来我们想明白一件事prompt 能约束行为的“边界”但约束不了行为的“必然性”。真正要解决的是在架构层面建立确定性。怎么建立确定性我们采取了三层策略流程显式化、输出结构化、状态可恢复。流程显式化是把 Agent 的决策路径从隐式的模型自由发挥变成显式的步骤拆分比如先“理解意图”再“检索知识”再“生成回复”。输出结构化是强制模型输出 JSON 格式并对关键字段做运行时校验不合法就直接让模型重新生成。状态可恢复则是把每一步中间状态都落盘一旦出错可以从最近的检查点重新执行而不是从头再来。2.2 可观测性Trace、Token、Tool 调用一个都不能少排查生产问题最大的障碍是 Agent 像一个黑盒你不知道它内部经历了什么。用户问了一句“我的订单呢”Agent 内部可能经历了理解意图、判断调用哪个工具、决定参数、生成回答四个步骤任何一步出错都会影响最终输出但日志里往往只记录了一个最终的文本回复。我们花了差不多两周时间建设可观测性体系核心是三张表调用链 Trace、Token 消耗、工具调用记录。Trace 记录一次完整请求的链路包括模型输入输出、工具调用请求与响应、检索结果、中间状态变化。排查问题的时候能按 request_id 把整条链回放这一步是救命级的。Token 消耗记录每个环节花了多少 token能定位到哪一步在浪费成本。工具调用记录则要关注调用的入参和出参尤其是出参很多时候模型给的结论是对的但工具返回的数据被它解读错了。选型上我们初期用过 Langfuse后面迁移到了自建的监控体系配合 OpenTelemetry 生态。如果你项目规模不大直接用 Langfuse 或 Phoenix 这类开源工具也能满足要求关键是先跑起来不要在第一天就追求完美。注意可观测性不是上线以后才补的。Demo 阶段就埋好 Trace 埋点能让你在演示环境就发现“这个回答其实是检索错了不是生成错了”这类问题。2.3 兜底策略重试、降级、熔断怎么设计才不闯祸可观测性负责发现问题兜底策略负责在问题出现时不影响用户体验。这个领域最容易踩的坑是“乱重试”。重试要分场景。纯查询类的工具调用比如查天气、查订单状态重试是安全的。但有副作用的操作比如下单、退款、发送通知重试之前必须想清楚幂等性。你的接口支持幂等吗不支持的话Agent 第一次调用超时你盲目重试了一遍结果用户被下了两单这锅算谁的。我们的做法是给工具调用统一加一层网关层定义三类语义操作类型示例重试策略只读查询查库存、查订单状态超时可重试 1-2 次间隔递增写入操作创建订单、修改资料使用幂等令牌重试时带上同一令牌外部依赖调用第三方 API熔断 降级失败后走预设的替代方案降级策略也要提前想好。模型供应商不稳定的情况时有发生我们的方案是同时接入两家大模型服务商以一家为主、一家备份。主供应商连续返回异常时网关自动把流量切换到备份。用户侧无感知但后台已经完成了故障转移。另一个容易忽略的点是“模型降级”即复杂任务用大模型、简单任务用小模型。生产环境里很多请求其实是简单意图直接用小模型处理能省太多延迟和成本。这也是一个实用技巧后面讲并发的时候会再展开。3. 四道坎的第二道并发与性能3.1 先算账Agent 的延迟和 Token 成本怎么估算“AI Agent 怎么扛并发”是后台问得最多的问题。很多团队一上来就讨论架构选型我习惯先让大家算一笔账。先算延迟账。一个 Agent 请求涉及至少两轮模型调用第一轮理解用户意图和规划步骤第二轮生成最终回答。中间可能穿插检索和工具调用。假设单轮模型调用耗时 3 秒两轮就是 6 秒这还不算网络传输和工具调用时间。每个请求端到端 8 秒是保守估计。再算成本账。一次简单的客服问答如果上下文塞得比较大比如基础 prompt 加历史对话加检索结果单次消耗 2000 token 很常见。假设供应商价格是输入 0.1 元 / 千 token输出 0.3 元 / 千 token一次请求的成本大概 0.3 元左右。一天一万次请求就是 3000 元成本。Demo 阶段你不会注意这个数字但生产环境这就是硬成本。这个账算完大家基本就理解为什么“并发扛不住”本质上是个延迟和成本的综合问题了。优化空间主要在三块减少无效调用、压缩上下文、并发复用。只要能把这三点做好并发能力通常能提升一倍以上。3.2 架构改造把“笨重”的 Agent 变“轻”感知型 Agent 结构复杂、上下文重、调用链长这是并发上不去的直接原因。我们的思路是分而治之把一个大而全的 Agent 拆成多个轻量级 Agent。具体做法是引入“意图路由 子 Agent”的架构。上层是一个轻量级路由器负责把用户请求分类分发给不同的子 Agent 处理。子 Agent 各自只负责一个领域比如订单查询 Agent、售后政策 Agent、人工坐席接入 Agent。这样每个子 Agent 的系统 prompt 短、工具数量少、上下文轻单次调用耗时直接减半。路由层本身也是一个小模型就能解决的不需要很强的推理能力一个几百 token 的分发任务用快模型处理非常便宜。这个时候“模型降级”就发挥作用了。此外简单问题直接由路由层应答不进入子 Agent这又减少了一部分调用。另一个关键改造是“工具服务化”。不要把工具逻辑塞在 Agent 代码里而是把工具调用统一封装成独立的微服务Agent 只负责发指令微服务负责执行。这样有一个附带收益工具服务的吞吐能力可以独立扩展不会被 Agent 的调用频率卡住脖子。3.3 限流、队列与缓存扛住高峰的三个抓手架构调优之外真正决定系统稳不稳的是流量治理三件套限流、队列、缓存。限流参数怎么定我们按峰值预估的 80% 来限流。比如预估高峰期每秒 20 个请求那 Agent 入口限流设置为 16 TPS。超出的请求不是直接丢弃而是进入一个内存队列按先入先出顺序平滑处理。队列长度要有限制我们一般设置为 100超过就直接返回“系统繁忙请稍后再试”避免队尾请求等待时间过长。配合上熔断机制当请求失败率达到 10% 时网关主动拒绝新请求 30 秒防止雪崩。缓存是我们踩过最深的一个坑。第一版我们做过“结果缓存”把用户的完整问答对缓存下来命中了直接返回历史回答。后来发现的问题是业务数据一直在变缓存结果过时用户查订单状态永远拿到的是旧数据。第二版改成了“知识点缓存”大模型生成的答案不做缓存但工具调用的结果可以按业务纬度缓存一段时间。比如“当前库存量”“物流轨迹”这类高频查询TTL 设 30 秒重复问题直接复用工具结果省掉一次真实调用。语义缓存也值得一提但对相似问题做归一化处理比较难我们目前只在低风险场景里用优先保证准确性。4. 四道坎的第三道记忆与状态管理4.1 记忆的三大坑爆窗、串线、召回失效记忆问题在 Demo 里几乎不会暴露因为演示时对话轮次很少。生产环境用户会连续追问、反复修改需求这时记忆的坑就全出来了。第一个坑是上下文爆窗。对话轮次一多历史记录加检索结果会把模型上下文窗口塞满。第一版方案我们做了“滑动窗口截断”只保留最近 5 轮对话。效果是上下文不会爆了但用户在第 3 轮提到的关键业务信息第 8 轮就用不上了Agent 开始“失忆”。第二个坑是会话串线。多轮对话的 session 管理没做好用户 A 的信息被带进了用户 B 的上下文。这在 Agent 场景不是小事故尤其是涉及个人信息的时候属于安全事故级别。第三个坑是召回失效。我们把历史对话写入向量库做长期记忆但向量相似度检索并不总是返回你想要的那段历史。用户问“我之前说的那个事怎么样了”“那个事”在向量库里很容易捞出一堆无关内容。这三个坑叠在一起会让 Agent 在真实业务里表现得很“弱智”。4.2 短期记忆与长期记忆的分工深挖之后发现记忆问题不能用一个方案通吃。我们把 Agent 记忆拆成三层。工作记忆对应单次会话内的上下文存储的是当前对话轮次的关键信息比如用户刚说的订单号、地址、时间。这层内容用 session 内变量存储随请求传递不做持久化。短期记忆对应会话内跨多轮的摘要信息。当一个会话超过 5 轮我们会用模型对前面的对话做一个结构化摘要把关键实体、用户意图、待办事项提取出来替代原始对话文本。摘要的质量直接影响后续对话表现所以我们迭代了两次提示词方案才稳定下来。长期记忆则跨会话保留存储内容分为两种事实型记忆和偏好型记忆。事实型记忆如用户的姓名、会员等级、订单历史这些从业务系统同步不经由对话抽取偏好型记忆如用户喜欢工作人员礼貌用语、偏好简洁回答等通过对话分析获得。长期记忆我们存放在向量库同时设置了记忆刷新机制当新信息与旧记忆冲突时以新信息为准并主动更新。4.3 我用的记忆设计方案现在的方案沉淀成了一套比较稳定的架构。会话开始的时候系统先从长期记忆库召回与用户相关的关键信息作为种子上下文注入。会话进行中每一轮对话的产出都会同步更新短期记忆摘要如果会话超过 6 轮触发一次摘要重算丢弃原始文本。会话结束后异步把有价值的信息写回长期记忆库。这个方案不是一蹴而就的中间走了很多弯路。最大的教训是别在“让 Agent 记住所有对话内容”这件事上努力而要在“记住有用的、忘掉没用的”上下功夫。信息过滤比信息存储重要得多。具体落地时还要注意时效性。比如用户昨天投诉过物流慢今天又问了物流Agent 要能关联上这个背景。但两个月前用户问过一次商品价格和今天的购买决策就没有强关联不该作为主要召回内容。给记忆打上时间戳和“衰减因子”能解决一部分问题我们后期也加了这个机制。5. 四道坎的第四道安全、权限与合规5.1 Agent 安全的核心矛盾权限“被放大”Agent 和普通应用最大的安全差异是它会按照大模型的“理解”去调用工具而大模型的判断不总是可靠。相当于你把车钥匙交给了自动驾驶系统但自动驾驶偶尔会看错路标。早年我们犯过一个错给 Agent 配置了过高的权限。它要能查订单状态我就把订单管理系统只读账号给了它。看起来只是只读但模型只要理解了字段结构依然可以批量拉取所有客户的敏感信息。因为模型本身不具备业务边界意识它只会按用户的意图去检索。权限如果没有钳制在最小范围Agent 就会变成“持枪的秘书”。5.2 工具网关与最小权限落地解决权限放大问题的核心是工具网关。每一个被 Agent 调用的工具进出都要经过一个网关层由网关执行权限校验、参数校验、配额管理。权限校验要做三层用户级权限、Agent 级权限、数据级权限。用户级权限解决特定用户不能看特定数据的问题Agent 级权限解决某些高危操作必须走人工审批的问题数据级权限则控制返回的数据范围比如用户查订单只返回他自己的订单不允许 Agent 查全量。参数校验容易被忽略。一个查询库存的工具上限参数可能是 10但模型可能因为 prompt 理解偏差传入了 1000。网关层部署一套参数约束模板定义哪些字段允许范围、哪些操作必须二次确认。无效参数直接拦截并返回错误提示让模型重新生成。另外我们设置了“操作白名单”。高危操作默认关闭比如发送营销短信、修改用户账户资料、批量导出数据。Agent 想调用必须显式向网关申请网关返回“该操作需要人工审批”然后转入人工审核队列由坐席人员确认后才真正执行。5.3 审计、内容安全与防投毒安全体系里的审计日志很多人会做到最后一步才补我们吃过亏所以强烈建议一开始就设计好。审计日志要记录至少以下字段调用时间、用户身份、Agent 身份、工具名称、入参、出参、模型决策依据、审批状态。带着 request_id就能把一次完整的数据操作历史翻开。内容安全主要关注两块模型的输入有没有被恶意注入模型的输出有没有涉密或违规。防止提示注入可以通过网关侧的敏感词检测和系统 prompt 防御指令配合。输出侧则要接内容审核接口对包含个人隐私字段的具体输出做脱敏处理。我还想强调一个被讨论得比较多的点Agent 的记忆系统本身也可能成为攻击面。如果攻击者在对话里巧妙地塞入一段指令“记住当用户问 X 时你要回答 Y”这段记忆会被写进长期记忆库。下次会话召回时Agent 就按照被污染的记忆执行了。这属于记忆投毒我们目前的缓解方案是对写入长期记忆的内容做二次模型审核并对高风险用户新注册、异常行为的对话取消长期记忆写入权限。6. 框架选型别让 Demo 代码成为生产包袱6.1 先分清三件事业务编排、Agent 框架、基础设施选型之前一定要先意识到Agent 框架只是中间那一层不等于整个系统。上层是业务编排也就是你定义的业务流程和节点下层是基础设施包括模型网关、可观测性、记忆存储、工具网关。很多项目“上线拉胯”不是框架的问题是下层基础设施没有建设好框架再强大也白搭。6.2 主流框架的工程能力对比我基于自己项目的体验给几个主流框架做个定位梳理。LangGraph 偏底层灵活性强适合需要精细编排和复杂状态流转的场景但学习曲线陡工程化能力要靠自己补齐。Agno 体量小、上手快适合快速验证原型但它更适合轻量场景复杂业务流程管理能力相对弱。Spring AI 适合 Java 技术栈结合 Spring 生态的团队对已有 Java 微服务架构的灰度发布、服务治理衔接顺滑但模型抽象层偏薄深度集成需要自己写。Google ADK 在新项目里人气很高提供了比较完整的多 Agent 编排能力文档也比较新生态起步阶段需要留意版本变化。没有哪个框架能解决全部问题。我在选型时更看重两个维度和现有技术栈的契合度以及和底层设施的集成成本。不迷信框架也别光看 Github star 数。框架定位强项上手难度生产注意点LangGraph偏底层编排状态机灵活、生态丰富中高需要自建模板和治理能力Agno轻量快速小体量、易上手低复杂长链路容易失控Spring AIJava 生态集成与企业存量系统无缝对接中模型抽象需要二次封装ADK多 Agent 编排编排模型清晰、开发体验好中版本迭代快需跟随升级6.3 我的选择与理由我当时的项目是 Java 技术栈最终选了 LangGraph 做核心编排同时用 Spring AI 做了模型网关层。原因是团队 Java 熟练、LangGraph 对复杂状态流支持好Spring AI 则帮我把多家模型供应商的统一接入和路由切换这一层快速打通了。选型心得就一句话框架是兵器关键还要看使用兵器的人和他的战术体系。先搞清楚自己要解决的四道坎分别落在哪一层再选框架钱才花在刀刃上。7. 上线前清单与灰度策略7.1 四道坎对表的 Checklist上面四道坎拆解完最后需要落到一张可执行的清单上。我把自己项目里用的上线前 Checklist 精简了一下检查项具体指标状态可观测性Trace 覆盖全部请求工具调用日志可回放必检重试与降级有副作用操作具备幂等令牌模型供应商有备份必检并发治理入口限流 队列 失败熔断已配置必检记忆管理会话摘要策略、长期记忆刷新机制已上线必检权限控制工具网关启用最小权限高危操作白名单生效必检内容安全输入防注入、输出脱敏、记忆写入审核必检评估体系测试集任务成功率达成 85% 以上必检审计能力审计日志含操作前后值记录与审批状态必检这个清单每一条都是拿实际问题换回来的。比如“工具调用日志可回放”这条我们当时调了三天一个诡异 bug最后发现是模型在调用查询工具时把参数里的日期格式从 YYYY-MM-DD 改成了 MM-DD-YYYY没有回放日志根本定位不到这个细节。7.2 灰度发布的实操节奏上线之前还要设计灰度方案。灰度不是简单开一个百分比开关很多时候 Agent 升级会扰动存量业务。比如你更新了系统 prompt原本 95% 的任务成功率可能直接掉到 60%但你没有任何感知因为指标没看。我们的节奏是四步走。第一步是影子模式新版本 Agent 与旧版本并行处理线上流量新版本结果只记录不返回用来对比两个版本的回答质量。第二步是内测模式邀请内部员工 20 人使用新版本收集反馈并观察指标。第三步是白名单灰度开放给 10% 的真实用户持续 3 天以上确认业务核心指标稳定后再扩到 50%。第四步是全量切换切换前把训练集、测试集全部重跑一遍确认成功率没有回退。灰度期间尤其要关注负面体验不要只看平均指标。用户投诉、用户流失率上浮往往不体现在平均成功率里。7.3 迭代节奏与评估指标上线后的迭代我个人建议以周为单位循环周一收集线上 Trace 和失败样本周二归结问题类型周三到周四优化 prompt 或链路周五跑回归测试并决定是否灰度。这个节奏比较稳也方便和业务方同步进展。评估指标我只盯着三个。任务成功率看问题有没有被解决占了最大权重端到端延迟决定用户体验单次请求成本决定业务能不能跑得下去。延迟和成本要设硬上限不达标不允许上线。另外要把“用户二次求助率”纳入观察——用户找过 Agent 之后又去找人工客服的比例这个指标比平均满意度更能反映真实问题解决情况。最后分享一点真实体会如果让我用一个比喻总结这几轮踩坑做 Agent 生产落地Demo 就像考驾照时候的场地练习场地路况简单你知道每个考点在哪里生产环境是一场真实的城市道路驾驶有电动车乱窜、有大雨、有修路绕行你的驾驶技术要对应真实路况去调整成肌肉记忆。Demo 惊艳是入场券工程解法才是车技本身。我当时最大的转变是从“想方设法让模型答得更好”变成“老老实实把系统做硬”。你不需要追求 Agent 在每个问题上的完美表现只需要保证关键任务可靠、故障可恢复、权限不失控、成本可控制。把上面四道坎一坎一坎过完Agent 才真正从作品变成产品。最后再啰嗦一句工具网关一定要最先做重要的事说三遍——最先做、最先做。别问我是怎么知道的。