1. 演示与上线之间的鸿沟到底在哪做智能体项目的人几乎都经历过同一个尴尬场景会议室里投屏演示用户输入一句话智能体流畅地调用工具、检索知识库、生成结构化结果领导点头客户鼓掌。两周后上线真实用户输入了一句带错别字、夹杂口语、意图模糊的话智能体要么答非所问要么在工具调用环节卡死要么把内部字段直接吐给了用户。演示很美上线就废。这个问题不是某一个框架的锅也不是模型能力不够。根子在于演示环境是一个被精心裁剪过的封闭世界而上线环境是一个充满噪声、边界模糊、状态不可控的开放世界。两者之间的差距需要用一套系统性的评估清单来弥合而不是靠上线后打补丁。我前后参与过十几个智能体从原型到生产的落地项目涉及客服、销售辅助、制度问答、数据分析等场景。踩过的坑足够写一本错题集。这篇文章不聊虚的就把我实际用来做上线前评估的那份清单拆开讲包括每个评估项背后的逻辑、具体的测试方法、常见的失败模式以及怎么在设计阶段就把这些问题规避掉。适合正在做智能体开发、准备把原型推向真实业务场景的从业者参考也适合需要评审智能体项目质量的技术负责人。核心关键词就三个智能体、Agent、评估清单。但我要讲的不是一份打勾就完事的表格而是一套贯穿设计、开发、测试、上线全流程的评估思维。2. 为什么演示环境天然会骗人2.1 演示环境的三个“温室效应”演示环境之所以让智能体看起来很美是因为它同时具备三个温室条件。第一输入是被驯化过的。演示时用的query通常是开发者自己写的语法完整、意图明确、没有歧义。比如“帮我查一下上个月的销售数据并按区域汇总”这句话放在任何智能体里都能跑通。但真实用户会说“上月卖得咋样分地方给我看看”甚至只说“销售数据”剩下的靠智能体去猜。第二工具返回是理想化的。演示时调用的API返回的是干净的JSON字段齐全、格式统一、没有空值。真实环境里上游接口可能超时、可能返回半截数据、可能字段类型和文档不一致。智能体如果没做容错直接就把异常当正常数据处理了。第三对话轮次是短的。演示通常两三步就出结果但真实场景里用户会追问、会改需求、会中途插入无关信息。智能体的记忆管理和上下文窗口在长对话里会迅速劣化。注意如果你的智能体只在“单轮、干净输入、理想返回”的条件下测试过那它本质上还是一个demo不具备上线资格。2.2 上线后暴露的典型失败模式我把实际项目中遇到的失败模式归了类大致有这么几种意图漂移用户说了三句话智能体只抓住了最后一句前面的约束条件全丢了。工具幻觉智能体编造了一个不存在的工具名或者给工具传了错误的参数格式。知识库越界检索到了不该检索的文档把内部流程、敏感字段返回给了无权限用户。死循环工具调用失败后反复重试没有退出条件烧完token才停。格式崩溃要求输出JSON结果模型输出了带markdown代码块的JSON下游解析直接报错。上下文溢出长对话把历史消息全塞进prompt超出模型窗口后行为不可预测。这些失败模式在演示环境里几乎不会出现因为演示环境不会触发这些边界条件。评估清单的价值就是把这些边界条件显式地构造出来在测试阶段就逼出问题。2.3 评估清单的设计原则我设计这份清单时遵循了三个原则。原则一以失败为驱动不以功能为驱动。不是列“智能体支持哪些功能”而是列“智能体在哪些情况下会失败”。功能清单让人安心失败清单让人清醒。原则二每个评估项都要有可执行的测试用例。不能只写“检查意图识别是否准确”而要写“用20条带歧义的query测试统计意图识别准确率低于85%则不合格”。原则三评估要覆盖全链路不只是模型输出。智能体的质量等于模型能力乘以工程实现质量。工具调用的稳定性、状态管理的正确性、异常处理的完备性这些工程层面的问题往往比模型本身更致命。3. 智能体上线前评估清单全拆解3.1 意图理解与输入鲁棒性评估这是第一道关也是最容易翻车的地方。用户输入不会按照你预设的模板来所以必须测试智能体在噪声输入下的表现。我的测试方法是构造一个“脏输入测试集”包含以下几类输入类型示例考察点口语化表达“帮我瞅瞅上周卖了多少”非正式用词的理解错别字/谐音“查一下小受数据”容错能力意图模糊“数据”是否会主动澄清多意图混合“查销售数据顺便把报表发给张三”意图拆分与优先级否定与修正“不是上个月是这个月”上下文修正能力无关插入“今天天气不错对了帮我查下库存”噪声过滤评估标准不是“全部答对”而是“在答不对的时候行为是否可接受”。比如意图模糊时智能体应该主动追问而不是瞎猜多意图混合时应该能识别出主意图并询问次要意图的处理方式。实操心得我通常要求意图识别的准确率在干净测试集上达到95%以上在脏测试集上达到80%以上。低于这个线说明prompt设计或者意图分类逻辑有问题需要回去改而不是靠上线后收集badcase慢慢调。3.2 工具调用与外部依赖评估智能体区别于普通聊天机器人的核心就是它能调用外部工具。但工具调用也是最容易出工程问题的地方。评估工具调用我关注四个维度第一工具选择的准确性。给智能体10个工具用户的问题应该触发哪一个我见过太多智能体在工具选择上犯低级错误比如用户问“退款政策”它去调了“订单查询”工具。测试方法是给每个工具构造5-10条应该触发它的query统计选择准确率。第二参数提取的完整性。工具需要3个参数智能体只提取了2个剩下一个靠默认值。如果默认值恰好是错的结果就错了。测试时要故意省略某些参数看智能体是否会主动追问。第三工具返回异常的处理。这是最容易被忽略的。我通常用mock工具来模拟以下异常# 模拟工具返回异常的几种情况 mock_responses { timeout: {error: request timeout, code: 504}, empty: {data: None, code: 200}, malformed: {data: not a json string, code: 200}, partial: {data: {field1: value1}, code: 200}, # 缺少field2 rate_limit: {error: too many requests, code: 429} }智能体遇到这些返回时应该有明确的降级策略超时重试几次重试间隔多少重试失败后是告知用户还是走备用方案这些策略必须在评估阶段就确定下来。第四工具调用的并发与顺序。有些场景需要并行调用多个工具有些需要串行。如果智能体把本该串行的调用并行了会导致数据依赖错误。测试时要构造有依赖关系的工具调用链观察执行顺序。3.3 知识库检索与事实一致性评估RAG架构的智能体知识库检索质量直接决定回答质量。评估检索环节我关注三个指标召回率应该被检索到的文档实际检索到了多少。测试方法是构造问题-文档对统计命中率。精确率检索到的文档里有多少是真正相关的。精确率低会导致智能体被无关信息干扰。排序质量最相关的文档是否排在前列。如果最相关的文档排在第五位而prompt只取前三那就等于没检索到。除了检索指标还要评估事实一致性。智能体是否严格基于检索到的内容回答还是自己编造了内容我通常用“对抗性测试”来检验故意问一个知识库里没有答案的问题看智能体是老实说“不知道”还是编一个看起来合理的答案。注意知识库越界是一个严重的安全问题。如果知识库里混入了权限分级文档必须测试低权限用户是否能通过智能体检索到高权限内容。这个测试不能省。3.4 多轮对话与状态管理评估单轮对话的智能体好做多轮对话的智能体才是真实场景。多轮对话的核心难点是状态管理哪些信息需要记住哪些需要遗忘哪些需要覆盖。我设计的多轮测试场景包括信息继承第一轮说了“查北京的数据”第二轮说“换成上海”智能体是否知道要替换的是地点而不是其他参数。指代消解第一轮提到“订单A”第二轮说“把它取消”智能体是否知道“它”指订单A。话题切换用户从“查库存”切换到“查物流”再切回“查库存”之前的上下文是否还在。长对话衰减进行20轮对话后智能体是否还记得第3轮提到的约束条件。状态管理的评估没有捷径就是构造长对话脚本人工检查每一轮的输出是否符合预期。我通常会写一个自动化测试脚本把对话脚本和预期输出都定义好跑完看通过率。3.5 输出格式与下游兼容性评估智能体的输出往往要对接下游系统格式不对下游就崩。这个问题在演示时看不出来因为演示时人眼看输出格式差点也能理解。但下游系统是机器差一个字符都不行。评估输出格式我关注结构化输出的稳定性要求JSON就必须是纯JSON不能带markdown代码块标记不能有多余的解释文字。字段完整性约定的字段一个都不能少即使值为空也要有默认值。类型正确性数字就是数字字符串就是字符串不能混。长度限制输出是否超出下游系统的字段长度限制。测试方法是把智能体输出直接喂给下游系统的解析函数看是否报错。我通常要求连续100次调用的格式合规率达到100%因为下游系统不会容忍偶发失败。3.6 性能与成本评估智能体上线还要算经济账。响应太慢用户会跑成本太高老板会砍。性能评估的核心指标指标合格线测量方法首token延迟 2秒从用户发送到第一个字符返回完整响应时间 10秒从用户发送到完整响应结束工具调用耗时 3秒/次单个工具调用的平均耗时并发承载按业务定压测工具模拟并发请求成本评估要算清楚每次对话的token消耗包括prompt token和completion token。如果用了RAG还要算检索的向量化成本。我见过一个项目演示时效果很好一算成本发现每次对话要花3块钱业务根本承受不起。实操心得优化成本最有效的手段不是换更便宜的模型而是精简prompt和减少不必要的工具调用。我通常会把prompt里冗余的示例删掉把工具描述压缩到最简往往能省30%以上的token。4. 评估清单的落地执行方法4.1 建立自动化评估流水线评估清单不能靠人工手动跑必须自动化。我的做法是搭一条评估流水线每次智能体有改动就自动跑一遍。流水线的基本结构测试集管理把前面说的脏输入测试集、工具异常测试集、多轮对话脚本都存成结构化文件YAML或JSON。执行引擎写一个脚本读取测试集逐条调用智能体收集输出。断言与评分对每条输出做断言检查比如格式是否合规、是否包含预期关键词、是否触发了正确的工具。报告生成输出通过率、失败case详情、耗时统计。这套流水线不需要多复杂一个Python脚本加一个CI任务就能跑起来。关键是坚持每次改动都跑而不是上线前才跑一次。4.2 灰度发布与线上监控评估清单再全也覆盖不了所有线上情况。所以上线必须灰度先放1%的流量观察真实表现。线上监控要盯的指标异常率工具调用失败、格式解析失败、超时等异常的比例。用户反馈用户是否重复提问、是否主动结束对话、是否点了“不满意”。成本波动单次对话成本是否突然升高可能意味着出现了死循环。延迟分布P99延迟是否超出预期。灰度期间发现的badcase要反哺到测试集里让评估流水线越来越强。4.3 评估清单的迭代维护评估清单不是一成不变的。业务在变用户在变失败模式也在变。我通常每个季度review一次清单把线上新出现的失败模式加进去把已经稳定通过的测试项降低优先级。维护清单时要注意不要只加不减。清单太长会导致评估成本过高最后没人愿意跑。保持清单在“能覆盖主要风险”和“执行成本可接受”之间平衡。5. 常见问题与排查技巧实录5.1 智能体在测试环境正常上线后频繁超时这是最常见的问题之一。原因通常是测试环境的工具响应快线上环境的工具响应慢或者不稳定。排查思路先看是模型推理慢还是工具调用慢。如果是工具慢给工具调用加超时和重试如果是模型慢考虑换更快的模型或者优化prompt长度。我遇到过一次排查半天发现是线上环境的向量检索用了冷启动的实例第一次查询特别慢预热后就正常了。5.2 智能体偶尔输出格式错误但复现不了偶发的格式错误通常和输入长度有关。输入接近模型上下文窗口上限时模型的行为会变得不稳定。排查方法是记录每次格式错误时的输入token数如果集中在某个阈值附近就说明是上下文窗口的问题。解决办法是截断历史消息或者做摘要压缩。5.3 工具调用参数偶尔传错参数传错往往是prompt里的工具描述不够清晰。模型在参数提取时依赖工具描述中的字段说明如果说明模糊模型就会猜。解决办法是把工具描述写得更明确包括字段类型、格式要求、示例值。我通常会在工具描述里加一句“如果用户没有提供该参数不要猜测直接询问用户”。5.4 多轮对话中智能体“失忆”失忆通常是状态管理逻辑的问题。检查两点一是历史消息是否被正确传递给了模型二是历史消息是否超出了窗口限制被截断了。如果是截断导致的需要做历史摘要把早期对话压缩成简短摘要保留关键信息。5.5 知识库检索到无关内容检索到无关内容先看是检索算法的问题还是知识库本身的问题。如果知识库里混入了大量无关文档再好的检索算法也救不了。解决办法是先在知识库层面做清洗和分类给文档打标签检索时按标签过滤。问题现象可能原因排查动作解决方向上线后超时工具响应慢分别测模型和工具耗时加超时重试或换模型偶发格式错误上下文接近上限记录错误时token数截断或摘要历史参数传错工具描述模糊检查工具描述字段补充字段说明和示例多轮失忆状态管理缺陷检查历史消息传递修复状态逻辑或加摘要检索无关知识库脏检查知识库文档质量清洗知识库加标签过滤5.6 独家避坑技巧最后分享几个我在实践中总结的、文档里不会写的技巧。技巧一用“最差输入”做冒烟测试。每次部署后不要用正常输入测试直接用最脏、最模糊、最长的输入跑一遍。如果最差输入都能扛住正常输入就没问题。技巧二给智能体加“退出机制”。任何循环调用都要有最大次数限制任何工具调用都要有超时。我见过一个智能体因为工具一直返回错误反复重试了200次烧了几十块钱的token。技巧三把评估清单变成开发规范。不要等开发完了才评估而是在设计阶段就把评估项作为需求写进文档。比如“智能体必须支持意图模糊时主动追问”这条直接写进需求开发时就不会漏。技巧四保留每次评估的快照。每次跑评估流水线把输入输出都存下来。这样当线上出现问题时可以回溯对比快速定位是哪次改动引入的。这套评估清单和方法我在多个项目里反复打磨过。它不能保证智能体上线后零问题但能保证你不会在演示很美、上线就废的循环里反复挣扎。智能体从概念演示走向工程化落地靠的不是更炫的demo而是更扎实的评估和更严谨的工程实现。