从Demo到生产：企业Agent平台工程化落地的四块关键拼图

去年我给一家制造业客户做内部 AI 中台的技术咨询他们用开源框架搭了一个 Agent 演示系统物流调度、设备维保问答、库存查询三个场景都跑得很漂亮给董事长汇报的时候现场生成报表、自动派单掌声不断。结果进入试用期第一周就崩了——权限模型对不上、API 频控直接打满、Agent 乱调用内部系统把测试库写坏了最后运维同事看到 Agent 相关工单就头痛。这几乎就是“从 Demo 到生产”翻车的标准剧本。我在行业里看了太多类似案例也亲手把好几个 Agent 项目从概念验证推到线上稳定运行。这些年最大的体会是企业 Agent 平台真正缺少的从来不是更聪明的大模型也不是更花哨的框架而是一整套围绕“确定性、可控性、可观测性”的工程化能力。Demo 证明的是“上限”生产交付的是“下限”。把这两者之间的鸿沟填平才是企业 Agent 落地最核心的命题。1. Demo 与生产两个物种的差异1.1 Demo 证明上限生产考验下限很多团队在 Demo 阶段有一个错觉只要 Agent 能理解意图、能调用工具、能生成看起来合理的回答就说明技术路线是通的。但 Demo 场景往往是经过挑选的、数据是干净的、用户量是 1 个人、并发是 0。生产环境完全反过来用户是几百几千个数据是脏的、乱的、缺上下文的API 是会超时的第三方系统是会拒绝连接的提示词是会被用户试探着绕过去的。一个很简单的例子Demo 里你让 Agent“查一下华东区库存”它调一个接口、解析返回、生成表格完事。生产里这个需求会变成“查华东区库存但哪些仓库算华东华东区负责人离职后权限转移了没有接口返回里有三个数据源口径不一致怎么办查询超时了是重试还是降级用户追问‘那华南呢’的时候 Agent 能不能记住刚才的上下文”这些不是模型能力问题而是平台设计问题。模型负责“理解”平台负责“兜底”。兜不住底线再聪明的模型也是花架子。1.2 影响范围变了问题就变了Demo 阶段影响范围是“演示会议室里的几台电脑”生产阶段影响范围是“整个业务部门甚至全公司”。影响范围不同对故障的容忍度完全不同。演示的时候 Agent 回答错了演示人圆一句“这个场景还在优化”就过去了。生产的时候 Agent 算错一个生产领料数量一整条产线的物料计划就乱了这个责任平台方背不起。所以生产级 Agent 平台必须在设计之初就回答几个问题如果 Agent 输出错了系统能在多大范围内自动兜住如果 Agent 失控了怎么在秒级断掉它的工具权限如果 Agent 泄露了数据审计日志能追到哪一层这些问题的答案决定了平台是“能跑的玩具”还是“能用的系统”。我在《从 Demo 到生产》这个主题下反复强调一句话Demo 问的是“它能做到吗”生产问的是“它做错了怎么办”。两者根本不是一个物种。1.3 评判标准从“会不会”变成“值不值”技术团队在 Demo 阶段最容易掉进去的陷阱是沉迷于“模型又变聪明了”。但到了生产阶段业务方只会问三个问题准确率多少响应多快跑一单成本多少评判标准的转变倒逼着平台架构跟着变。为了准确率你需要评测集、回归测试、badcase 管理为了响应速度你需要缓存、路由、模型分级为了成本你需要 token 压缩、模型降级、任务拆分。这些都是 Demo 阶段完全不需要考虑、却在生产阶段决定生死的事情。我见过太多团队Demo 做完了老板一句“挺好上吧”然后团队花了大半年去补课——补可观测性、补权限模型、补错误处理、补灰度发布。本质上是在为“Demo 思维”还债。这篇文章就是希望帮还在这条路上的朋友少走一点弯路。2. 企业 Agent 平台真正缺少的四块拼图2.1 可评测性没有评测体系就没有迭代依据缺少的第一块拼图是可评测性。很多人以为评测就是“找几个人问几个问题看看回答得好不好”。这在大模型评测维度可能够用但在生产 Agent 平台维度远远不够。生产 Agent 评测要回答几个具体问题意图识别准不准工具调用参数对不对多轮对话上下文跟没跟住答案引用来源靠不靠谱边界拒答灵不灵敏我的做法是建三层评测结构。第一层是离线评测集把历史真实请求按场景分类每类标注标准答案或者关键断言用大模型做裁判员自动打分第二层是线上规则校验生产环境里对每一次 Agent 响应跑规则集比如“引用格式是否正确”“是否包含敏感信息”“是否超出权限范围”第三层是用户反馈收集每一轮对话后面挂隐式反馈用户是否复制/点赞/继续追问和显式反馈点踩时留原因。三层里面离线评测集是最容易被忽略、又最该先做的。因为它是唯一能在新版本上线前就预判质量的手段。没有离线评测集的团队每次升级模型或改提示词都是裸奔——你根本不知道这次改动是变好了还是变差了只能上线赌。离线评测集不需要一上来就搞几千条。我的建议是每场景先搞 30~50 条高质量样本覆盖主路径、边界路径、拒答路径各三分之一。先把“底线”守住再谈“上限”。2.2 可观测性Agent 是黑盒生产必须打开它缺少的第二块拼图是可观测性。Agent 系统最恼人的一点是它的执行过程是多步的、动态的、非确定性的。传统接口调用的日志只能告诉你“返回了什么”Agent 系统的观测需要告诉你“为什么它做了这个选择”。如果没有这种观测能力生产环境出问题的时候你连排查的抓手都没有。我给 Agent 平台做可观测性设计时最基本的单位是 trace 而不是 log。一次完整的用户请求从意图识别、上下文检索、工具选择、工具调用、结果解析到最终生成整条链路的每一步都要有 trace span每个 span 要带 input/output 摘要、token 消耗、耗时、模型参数等关键信息。这里有个实操细节trace 的采样率不该是统一的。正常流量按 10% 采样就够了但错误链路和慢链路要 100% 采样。做法是“动态采样”当某个 trace 出现错误标记或者耗时超过阈值时把整条链路的 span 全部保留并上报。这样既控制了成本又保证了排查“坏案例”时有完整数据。此外每个 trace 还应该跟业务维度的元数据打通比如用户 ID、会话 ID、业务场景 ID。否则你只知道“系统报错了”不知道“是哪个客户、在哪个流程、因为哪句话触发的”排查效率会非常低。2.3 安全与权限能力越大责任越大缺少的第三块拼图是安全与权限体系。Agent 跟传统软件最大的不同是它有“手”——能调 API、能改数据、能发消息。这就意味着它的权限边界必须比传统用户体系更严格。我的一个基本原则是Agent 的权限永远采用最小化授权而不是最大化授权。能只读就不要给写权限能查一个库就不要给全库权限能调一个接口就不要给整个服务权限。具体落地时我在平台里做了一层“工具网关”。所有 Agent 能调用的工具都要在网关里登记工具归属的系统、所需的参数、允许的调用者、频率限制、最大执行时间、数据脱敏规则。Agent 调用工具时走网关做鉴权和限流而不是让 Agent 直接对接底层 API。这里有一个我踩过坑后总结出的教训不要让大模型自己决定“要不要调用某个工具”而是让网关告诉它“你能用哪些工具”。也就是说工具清单是在系统层根据用户身份和上下文动态注入给模型的而不是模型在全部工具列表里自己挑。否则你永远不知道 Agent 会不会在某个刁钻对话里调用一个超出当前用户权限的工具。同时Agent 的输出也要过一道内容合规网关。企业环境里数据安全是红线Agent 回答里如果携带了不该出现的字段比如另一个部门的数据、用户手机号、内部 IP必须能在输出层拦截。这道网关不能只靠提示词约束提示词只影响“大概率”网关是在“小概率”事件发生时兜底的。2.4 治理与运营Agent 不是上线就完事缺少的第四块拼图是治理与运营。很多团队把 Agent 当“项目”做做完上线就撤了。但 Agent 本质是“产品”是要持续运营的。模型会升级、业务口径会变、用户会提出新问题、badcase 会积累。没有治理机制Agent 上线三个月后准确率和体验一定会下滑。我推动落地的治理机制包括四个部分。版本管理提示词、工具定义、模型参数都要像代码一样进 Git每次改动有记录、有 diff、可回滚。灰度发布新版本先在内部用户或小流量用户里跑对比核心指标后再放全量。反馈闭环每一条用户点踩或人工纠正都要回流到评测集成为下一轮优化的弹药。定期复盘每两周对 badcase 做一次归类分析看错误集中在意图识别、工具调用、还是生成质量据此安排优化方向。治理机制里最容易被忽略的是“人的介入”。生产 Agent 必须有“人工接管”的开关。当 Agent 在关键业务节点上不确定时应当转人工处理而不是硬着头皮生成。这个开关不仅是安全阀也是数据采集器——每一次人工接管都是一次标注样本。3. 从 Demo 到生产的落地路线图3.1 第一步盘点场景只选“值得做”的不是所有场景都适合从 Demo 推进到生产。我的经验是好场景要同时满足三个特征边界清晰、影响面大、容错空间可控。边界清晰是指任务范围可以被明确描述比如“查询库存”“生成报表”“解答政策”而不是“帮我管理供应链”影响面大是指做好了能明显提升效率或降低成本值得投入容错空间可控是指做错了造成的损失是可控的——查询错了重查就行但财务结算错了就不能接受。我在客户现场最常做的一件事就是帮他们把“想做的场景”和“该做的场景”分开。建议拉一个清单每个场景按上面三个特征打分优先做加权分最高的。宁可只做 2 个场景做到生产级也不要铺 10 个场景全部停留在 Demo 级。3.2 第二步搭评测集先于功能开发搭评测集看起来是“测试团队的事”但在 Agent 项目里它应该是“第一个开发任务”。因为没有评测集你后面做的任何功能都说不清楚“做得好不好”。评测集的搭建分三步。先把历史对话数据和日志翻出来筛选高频场景和典型问题这一步提供了真实输入再给每条样本标注期望行为标注时要区分“确定性期望”和“灵活性期望”确定性期望比如“库存不足时明确提示缺货”灵活性期望比如“回答语气友好”最后设计 badcase 触发集把用户可能问的刁钻问题、越权问题、边界问题都放进去比如“你能帮我删掉这个订单吗”“查一下 CEO 的工资”。评测集建好后要定基线。每次改提示词、换模型、调参数都先跑一遍评测集分数不低于基线才能考虑上线。这就是前面说的“离线评测防线”。3.3 第三步画边界搭权限和工具网关在写业务代码之前先把边界画清楚。这纸边界图要包含Agent 能访问哪些数据源、能调用哪些工具、每个工具的读写属性、调用频控阈值、最大执行时间、敏感字段清单。画好边界后把工具网关搭起来。网关是强制性的不能靠自觉。所有 Agent 的工具调用必须由网关鉴权不管这个 Agent 是内部员工用的还是外部客户用的。网关日志要独立存储与业务日志隔离这样审计时能快速定位“某一次工具调用到底是谁、在什么上下文下发起的”。这块做得好的标志是你随时能回答“如果 Agent 被彻底攻破了最坏能造成什么损失”。如果答案是“说不清”说明边界还没画完。3.4 第四步做可观测性从第一行代码就开始可观测性不要等到上线前才补从第一行代码就开始埋。哪怕是最初的 Demo也要把 trace 结构打出来。因为 trace 的埋点结构一旦定下来后面所有业务开发都要遵循晚了再改会很痛。建议直接用一个成熟的 trace 框架把 span 结构规范化。每个 span 至少包含时间戳、耗时、输入摘要、输出摘要、状态、关联的业务 ID。工具调用的 span 要额外记录目标系统、请求参数、返回码。生成的 span 要记录 token 数和模型名。做好这些之后再配置一套可视化的 trace 查询界面让开发能按会话 ID 或用户 ID 一键查看某个请求全链路。这个界面的价值会在线上出问题时体现得淋漓尽致。3.5 第五步渐进上线用灰度替代“一键发布”生产 Agent 平台千万不要搞“一键全量发布”。我强烈建议走灰度发布的路子哪怕用户量不大。因为 Agent 的行为是非确定性的即使离线评测分数达标线上真实流量里也可能出现评测集没覆盖的情况。灰度是最后的防线。灰度发布至少分三阶段。内部种子用户把 Agent 的入口先开放给项目组成员和业务核心用户目标是把明显的问题暴露在小范围内小流量试用开放到 5%~10% 的真实流量持续观察指标对比灰度和非灰度的效果逐步放量到全量每一档放量后都要留出足够的观察期通常是 2~3 个工作日确认核心指标没有恶化再继续。灰度期间的两个核心指标一个是“人工接管率”反映的是 Agent 应对不了的比例另一个是“用户纠正率”反映的是 Agent 回答了但用户不认可的比例。这两个指标如果有上升趋势就算离线评测分数再高也建议暂停放量。4. 生产环境常见故障与排查实录4.1 故障速查表一个建议打印出来的表我在多家企业落地 Agent 平台的过程中把高频故障整理成了一张速查表。这里分享出来建议团队打印贴在工位上。故障现象常见原因排查手段快速处置Agent 回答“不专业”“偏题”上下文检索召回质量差或者提示词约束不足查看 trace 中检索到的上下文片段检查排序得分调整检索 TopK 或优化排序策略降低温度参数工具调用频繁超时下游系统响应慢Agent 同步等待在 trace 里看工具 span 耗时分布工具调用加超时超时后走降级路径或转人工Agent 出现“幻觉引用”生成阶段对检索内容约束不足排查生成 span 的 prompt 模板和引用约束强约束引用格式未命中检索内容的回答不准给出具体数字用户反馈“回答太慢”模型推理时间长或链路串行步骤多看端到端耗时拆分定位瓶颈引入模型分级简单问题用小模型并行化独立工具调用频控触发导致大量失败多个用户并发时 Trigger 同一工具查看工具网关限流日志动态调整频控阈值为高频场景单独申请配额Agent 多轮对话“失忆”上下文管理策略把关键信息截断了查看会话 span 里历史摘要的生成时机优化摘要策略关键槽位信息做持久化4.2 真实案例复盘一权限模型对不上上线第一天就漏数据有一次给某零售企业做商品咨询 Agent开发阶段大家用的都是测试账号权限模型粗放——所有测试账号都是管理员。上线前我把工具网关的权限策略收紧只保留普通员工的只读权限。结果上线第一天内部员工问“公司采购价是多少”Agent 从商品系统的采购价字段里取到了数据直接返回给了提问者。排查的时候发现商品查询接口在业务层没有区分“销售价”和“采购价”的字段级权限Agent 调用接口拿到完整对象后生成阶段自由选用了字段。这个案例给我一个深刻教训Agent 平台的权限控制必须做到字段级不能做到接口级就收手。如果工具返回的数据里有不该给当前用户的字段应在工具网关做字段裁剪后再返回给模型。也就是“最小必要数据”原则——模型只能看到它完成当前任务所需要的最小数据集合。修复方案是在工具网关加了一层字段过滤配置根据用户角色在接口返回时动态裁剪敏感字段。从那以后我所有的 Agent 项目都默认带这个能力宁可靠网关多裁一遍也不让模型在生成时靠“自觉”避开。4.3 真实案例复盘二评测集没覆盖的边界在生产线上暴露另一个案例是一家制造企业Agent 做生产领料咨询。离线评测集跑得很好准确率 95% 以上。上线后突然接到产线投诉Agent 把“PVC 粒料 A 型”和“A 型 PVC 粒料”当成了不同的物料导致领料指导出现偏差。排查发现评测集里物料名称都是标准表述但产线工人习惯用简写和非标准顺序。Agent 在做实体识别时没有做同义词归一化物料检索召回时把两个相同的物料当成了不同记录还信心十足地给出了不同的库存数。这个故障暴露了评测集建设的一个常见盲区评测集太“干净”没有覆盖真实用户的表述变体。从那之后我建评测集时一定会要求加入“口语化表述”和“非标准简写”样本每类场景至少占 20%。同时给 Agent 平台加了一层“实体归一化”能力——在检索之前先做同义词映射把用户说的各种说法统一成标准物料编码。4.4 真实案例复盘三成本失控一个 Agent 的 token 消耗比一个开发还高还有一个在做客服 Agent 时遇到的成本问题。上线后效果不错但财务算账的时候发现单个 Agent 会话的平均 token 消耗远超预期。原因是系统为了追求回答质量把所有请求都发给了最强的大模型而且每轮回复都把完整的历史上下文全部带上导致 token 呈线性甚至超线性增长。优化做了三件事。模型分级简单意图走小模型复杂推理才走大模型用意图分类器在路由层做分发成本立刻省了 40% 以上。上下文精简对超过 N 轮的会话做历史摘要压缩只保留关键槽位信息和最近两轮的完整内容。缓存对高频问题和常见知识做精确匹配缓存命中就直接返回不再走模型推理。这次经历让我养成了一个习惯每个 Agent 平台上线的第一周我会专门看一张“每会话 token 消耗分布”的表。这张表比任何指标都直观它能告诉你 Agent 到底把你的钱花在哪里了。5. 我现在落地的 Agent 平台架构参考5.1 分层的平台架构长什么样根据上面的经验和方法论我现在搭企业 Agent 平台时会明确分成四个层次。接入层负责多渠道接入和会话管理把 Web、App、IM、工单系统等不同入口统一转成内部会话格式。编排层负责意图识别、任务规划、上下文管理、工具选择这一层是大模型能力集中地也是最需要评测和灰度的地方。能力层就是工具网关统一管理所有 Agent 能调用的内部系统和外部 API做鉴权、限流、裁剪、超时处理。治理层则是横切关注点包括评测系统、trace 系统、审计系统、运营分析系统。每一层的边界必须清晰。最典型的问题是团队容易把编排层的逻辑写进接入层或者把能力层的鉴权逻辑散落到编排层里。边界一旦混了后续的维护和排查会变成灾难。5.2 一次请求在平台里是怎么流动的用户发来“帮我看看华东区仓库 A 类物料的库存”请求进入接入层带上用户身份和会话 ID。编排层先做意图识别判断是“库存查询”再提取参数区域华东物料类别A 类然后向工具层发出查询请求。工具层收到请求后先做鉴权——确认当前用户有华东区库存的查询权限然后做字段裁剪——只保留允许用户看到的字段再调用实际库存系统。拿到结果后返回给编排层编排层把数据组织成语义化的上下文透传给生成模型。生成模型在系统约束下产出一段带数据来源引用的回答。整条链路的每个环节都有 trace span 在记录全程可回放。这套流程看起来不复杂但每个环节都嵌入了 Demo 阶段不会有的保障机制。鉴权、裁剪、超时、缓存、降级、trace、规则校验每一个词背后都是一次生产事故换来的经验。6. 一点经验之谈从 Demo 到生产不只是一个技术升级的过程更是一次思维方式的重构。Demo 做的是“加法”——不断加功能让演示更惊艳。生产做的是“减法”——砍掉不确定性兜住一切可能出错的地方。好的 Agent 平台不是功能最多的平台而是“该出错时不出错、出错时能快速定位、定位后能快速修复”的平台。我个人的一个建议是团队里最好能有一个专门的角色来当“生产环境守门员”。这个人不写业务代码只盯评测集质量、灰度指标、trace 异常、badcase 趋势。很多团队 Agent 项目推进不下去不是因为技术不行而是因为没有人对“生产质量”这件事负总责。有了守门员团队的迭代节奏会稳很多。最后再分享一个小工具层面的心得把 Agent 的每个关键决策点都做成可配置的——提示词模板、工具列表、温度参数、检索 TopK、权限开关。这些配置项全部放到配置中心不要散落在代码里。这么做的好处是运营同学和测试同学也能参与调优而不是每次调整都要找开发改代码、发版本。Agent 平台的工程化程度很多时候就体现在这些“不起眼的配置化”细节里。这些内容是我在多个企业 Agent 项目里反复踩坑、复盘、再落地后沉淀出来的。如果你正在从 Demo 往生产走希望这篇能帮你少走一些弯路。有什么拿不准的地方欢迎在评论区聊一聊我尽量用实际项目经验给出参考。