做过Agent开发的朋友多半都经历过这种崩溃瞬间本地手测跑得顺顺当当的流程一换真实场景就乱套上一秒还在正常调工具下一秒模型开始自说自话甚至在一个错误分支上反复横跳。传统模型评测看的是单点输出的准确率而智能体的行为是一连串由模型决策发散出来的路径从“一个答案对不对”变成了“一串动作最后能不能到达目标”。评估与调试的难度从单点上升到了系统级。这篇内容就顺着Agent学习这条主线聊聊我在智能体评估与调试这件事上踩过的坑、用过的办法以及沉淀下来的一套可复用的流程。1. 为什么智能体比传统模型难调先看清问题本质1.1 传统离线评测与Agent在线行为的维度差传统机器学习模型的评估本质上是“输入-输出”的映射检验给一批标注好的测试样本算准确率、召回率、F1指标稳定、口径清晰。但智能体不是这样。一个Agent收到用户问题后要先理解意图、再规划拆解步骤、决定调哪个工具、传什么参数、拿到结果后还要判断是否足够回答用户、不够的话继续下一步。整个过程是动态、多步、有状态的。这意味着哪怕模型每一步单独看都“及格”串联起来也可能完全失败。常见的例子是我之前做过的一个物流查询Agent单测工具调用时每一步都正确可一旦用户连续追问“那运费呢”“能今天发吗”Agent就把上一轮上下文里的订单号带到了完全无关的工具里。单点指标测不出这种问题只有端到端的、带状态的评测才测得出。所以第一课就是评估智能体不能用传统模型的评测思路必须从“最终任务完成情况”和“过程行为质量”两个维度同时下手。1.2 不确定性从哪里来规划、上下文、工具三层智能体的“随机性”比单模型大得多我习惯把它拆成三层来理解。第一层是规划层。模型决定“先做什么、再做什么”。这里的不确定性在于同一个用户问题可能有多种合理的工具编排顺序模型即便选了一条可行路径也未必是最优的。更麻烦的是当任务复杂时模型可能在某个中间节点做了一个微小偏差的规划后续所有步骤就跟着跑偏了。第二层是上下文层。Agent的对话历史、中间结果、工具返回的原始报文这些信息塞在一起会互相干扰。模型对长上下文的注意力本来就不是均匀的关键信息一旦被淹没行为质量就会快速下降。尤其工具返回一大段JSON时模型经常抓错字段。第三层是工具层。工具本身也有不确定性接口超时、数据返回格式变化、字段为空、下游系统报错。这些都不是模型能控制的但Agent会把工具的错误当成正常上下文继续推理下去错误因此被放大。搞明白这三点再看评估和调试就容易得多所有方法本质上都是在回答一个问题——“不确定性到底是从哪一层混进来的”。2. 评估体系搭建从拍脑袋到可量化2.1 先把目标拆成五个可观测维度很多团队做Agent评估上来就问“准确率多少”这个指标太笼统没法指导优化。我现在的做法是先拆维度每个维度对应一类可观测的行为然后再逐个量化。第一是意图理解也就是模型有没有正确读懂用户要什么。第二是工具选择与参数传递这是智能体最容易翻车的环节。第三是规划与多步执行看任务被拆解得是否合理、步骤顺序对不对、有没有漏步骤。第四是回复质量包括语言是否自然、是否基于真实结果而不是胡编。第五是边界与安全面对用户的不合理请求、敏感信息、误导性追问Agent能不能正确拒绝或引导。五个维度不是并列关系而是有优先级顺序的。意图理解错了后面全错工具参数错了任务必然失败回复质量再高也是正确的废话。所以评估时我会按这个顺序分配权重而不是简单算一个平均分。2.2 指标怎么定从模糊目标到可计算口径维度定了之后要给每个维度定义“可计算的指标”。以工具调用为例我会记录三个指标工具选择准确率、参数完整率、参数准确率。工具选择准确率是模型选对了工具的比例参数完整率是必填参数有没有都传参数准确率是传的值和标准答案是否一致。三个指标分开看定位效率会高很多。有一次我们的Agent在天气查询工具上选择准确率是100%但参数准确率只有68%最后发现是城市字段的解析规则在提示词里描述得不够具体“朝阳区”这种带区县的地址被拆错了。如果只盯一个综合分这种问题很难发现。再比如端到端任务完成率这个指标的难点在于“完成”的定义。我的建议是给每个评测任务预定义“完成状态”成功、失败、部分成功、超时未完成。部分成功也有价值比如用户要查三个订单的物流状态Agent只查到两个这就不是简单的成功或失败。把完成状态做成离散枚举比单纯算一个0到1的分数更贴近真实业务。不少团队还会引入tokens消耗和平均轮数这两个成本指标。Agent完成一个任务用了多少轮对话、吃了多少token直接影响线上成本和延迟。优化前先记录下来改完提示词再对比能直观看到“效果提升是花了多少额外代价换来的”。2.3 测试集构建少而精的用例设计法很多团队一上来就堆几千条测试用例结果评估一次要跑很久而且case质量参差不齐反而干扰判断。我的经验是第一版测试集哪怕只有100到200条也要保证覆盖度和难度分层。覆盖度怎么保证按业务场景横向铺开再按异常类型纵向加深。比如一个客服类Agent至少要有正常咨询、多轮追问、模糊表达、包含多个子任务、工具返回异常、用户不满情绪、超长上下文。每组至少5到10条这样才能看出模型在哪个“角落”里退化。难度分层也很关键。我习惯给每条case打一个难度标签简单、中等、困难。简单case是意图直接、工具明确、上下文干净中等case需要推理或组合两个工具困难case涉及歧义处理、多轮信息修正、错误恢复。每次评估都分层看结果而不是只看总平均。可能总准确率没变但简单case全对、困难case提升明显这其实是进步反之如果困难case没变但简单case掉了一截那可能是提示词改复杂了模型基础能力反而被削弱。提示测试集要像代码一样做版本管理。每条case的内容、标注答案、难度标签都放进一个可审查的目录里改动有记录。否则你永远不知道这周评估结果的波动是因为模型变弱了还是因为测试集被改乱了。3. 调试方法论拿到坏Case就按这三步走3.1 复现与最小化把偶发问题变成稳定问题调试的起点不是看日志而是复现。Agent的问题有个特点很多是偶发的同一段输入跑三次可能两次成功一次失败。这种随机性最容易让人抓狂。我的做法是先固定随机种子和模型参数把温度调成0看看问题是否稳定复现。如果温度0下问题消失了说明是采样随机性导致的这类问题的重要程度一般不高可以放后面处理。如果温度0下依然稳定失败那就进入下一步做最小化用例。最小化的思路是不断删减输入上下文和对话历史直到不能再删为止。举个例子有一个Agent在用户问“帮我取消预约”时总是调用错误工具我把前面所有闲聊历史删掉只保留这一句还是错再把系统提示词里的无关工具描述删掉发现它突然恢复正常了。最后定位到是另一个相似名称的工具让模型产生了混淆。这个过程有点像二分查找熟练之后一个复杂问题通常能在十几分钟内缩成一个十几字的“诱因片段”。这个片段价值极高它可以直接进回归测试集。3.2 Trace全链路追踪让Agent每一步都有据可查没有Trace就没有调试这句话我经常挂在嘴边。传统服务的排查靠日志就够了Agent不行你不仅要知道输入输出还要知道模型当时“打算干什么”“为什么这么干”。所以我会在Agent的每个关键节点都打结构化埋点。埋点至少要覆盖这些环节收到用户消息时的完整消息体每次LLM调用的模型名、参数、System Prompt版本模型输出的原始内容包括有没有工具调用工具执行的入参、出参、耗时、报错信息Agent每轮循环的决策依据和状态快照。这些信息用一个统一的JSON结构打出来我给它起了个名字叫“决策轨迹”。一份典型的决策轨迹大致长这样{ turn: 3, user_message: 那第二个订单呢, context_length: 4821, model_output: { thought: 用户在追问第二个订单需要从历史上下文中提取订单号, tool_call: { name: query_order_status, arguments: {order_id: 20240817-0231} } }, tool_result: { status: success, data: {state: 已签收, delivered_at: 2024-08-19 14:32} } }打了Trace之后很多之前解释不清的诡异行为都能一眼看穿。比如有一次我发现Agent频繁误用工具翻Trace才发现工具的返回里有一个字段叫status而对话历史中用户的情绪状态也被LLM总结成了status字段两个status在上下文里互相污染模型彻底分不清了。没有决策轨迹这类问题几乎不可能定位。3.3 分层归因问题到底出在哪一层同一个坏Case原因可能出在意图理解、工具选择、参数解析、规划编排、上下文管理、提示词、模型能力、工具本身这八种原因里的一种或几种。盲目调提示词是最常见的无效努力。所以我有一条铁律先归因后修改。归因的方法是控制变量。以工具选错为例如果用户意图都被模型理解错了那优先查意图分类和提示词里的角色设定如果意图理解正确但工具选错那要查工具描述是否清晰、工具名称是否有歧义如果工具选对但参数传错要查参数定义和抽取规则如果所有单步都对了但结果还是错的那问题基本出在多步规划上。这里有个容易忽略的点工具端的数据质量也会导致归因误判。我碰到过一次Agent反复调用同一个工具不是因为模型笨而是工具返回的数据本身就是旧缓存。所以归因时也要看一下工具出参是否正常别把所有锅都甩给模型。提醒归因结果要记录成结构化笔记。每次调试写清楚“现象-假设-验证-结论-修改动作-回归结果”。这样坚持一个月你会积累出一张属于自己业务的“故障-原因对照表”后面的调试会越来越快。4. 自动化评测落地从人肉回归到可持续运转4.1 规则评测第一道防线快且便宜全量依赖人工评估不现实所以我会把评估体系分成三层跑在持续集成里。最底层也是最先执行的是规则评测。它的特点是快、稳定、可解释适合拦截那些机械性的错误。规则评测可以查很多东西。工具调用格式是否合法、是否包含了必填参数、参数类型是否匹配、是否调用了被禁止的工具、输出里是否包含明确的错误关键词。这些规则用代码就能写几百行脚本就能覆盖大量基础问题。比如我写过一个检查器专门校验Agent是否遵守了“查询订单必须先验证用户身份”这条业务规则。逻辑很简单如果工具调用序列里出现了query_order_status但前面没有任何verify_identity调用直接判失败。这种规则放进CI里每次改完提示词或工具定义几分钟就能出结果。规则层还有一个重要作用它筛掉了大量低级错误让人工评审的注意力能集中在真正需要判断力的Case上。如果纯靠人去看几百条Case半天时间就搭进去了而且人看久了注意力会明显下降标准也会前后不一致。4.2 大模型当裁判怎么用才不被它骗第二层是用大模型做评委。这里说的不是让模型给分而是让一个裁判模型基于预设的评分标准对Agent的执行过程和结果做结构化评估。裁判模型的提示词需要认真设计否则它会犯三个典型毛病。第一是“宽松倾向”什么都给高分第二是“结果导向”只看最终结果对不对忽略过程是否合规第三是“抄袭答案”如果评测数据里带了参考答案裁判模型可能会照着答案给高分而不是看Agent的真实输出。我的解决办法是少让裁判模型打分数多让它做判断。不要问“这个回答质量如何”而是问“回答是否基于工具返回的真实数据”“是否完整覆盖了用户所有问题点”“是否存在编造信息”。每个问题用是与否来回答最后再按规则组合成总分。这样裁判模型不需要“审美”只需要“核对”准确率会高很多。另外裁判模型和被测Agent不要用同一个模型否则评估置信度会打折扣。我还做过一个增强版把评测输出里的关键实体和历史对话做自动比对比如用户问的三个订单号是否都在最终回复里被覆盖到。这类检查用代码就能做作为裁判模型评分的补充证据两边一致的时候结论才可信。4.3 端到端评测环境让Agent在仿真场景里反复踩坑最接近真实效果的是端到端评测但也是最贵的。我的建议是不要直接连生产环境的真实数据而是搭一套仿真环境工具接口用Mock服务代替返回数据用预制样本业务规则和权限校验也模拟出来。仿真环境的好处是可以构造“真实场景很难自然发生”的边界情况。比如让Agent面对用户反复改口、两个工具返回矛盾数据、一个工具超时另一个正常、历史上下文里同时包含成功和失败的操作记录。这些Case如果在生产环境里等可能几周都遇不到一次但在仿真环境里它们可以被稳定复现和批量构造。端到端评测的指标我一般看三个任务完成率、平均完成轮数、平均token消耗。完成率是核心后两个是效率和成本。一次优化如果完成率提升5个点但token消耗翻倍我会判断为得不偿失。尤其线上有成本压力的项目效率指标一定要纳入考核。注意仿真环境的Mock数据要和真实的工具返回格式保持严格一致。如果Mock报文和真实报文结构不同评测结论在线上根本不成立。我见过一个团队在Mock里把日期格式写成了2024/08/19而线上接口返回的是2024-08-19T14:32:00Z评测通过率虚高一上线立刻被打回原形。5. 高频故障场景与排查手册5.1 工具调用失联参数错了还是选错了工具工具调用类故障是Agent开发中出现频率最高的没有之一。我把它细分成三种独立的现象排查思路完全不同。第一种是工具选错。模型面对多个相似工具时容易混淆。比如“查询运费”和“查询价格”两个工具功能边界模糊模型就会选错。排查方向是工具描述是否清晰、工具名称是否有区分度、工具职责是否有重叠。我通常会在工具描述里写清楚“本工具只负责XX不负责YY”这个“反例描述”对模型帮助很大。第二种是参数漏传。必填参数缺失通常有三类原因用户没有提供、提示词没有要求模型主动询问、参数抽取逻辑漏了。我的经验是当参数缺失时先判断Agent是应该追问用户还是应该用默认值。很多团队为了省轮数让Agent“猜”参数默认值结果猜错造成业务事故。安全策略应该是关键参数缺失时必须追问用户确认而不是自行脑补。第三种是参数解析错误。模型选对了工具、也传了参数但值的格式不对。比如日期写成了“明天”、价格写成了“大约一百块”而工具要求ISO格式和数值类型。这种问题要靠工具参数定义来解决每个参数都写清楚格式要求并在提示词里给出正反例。我在参数描述里加过“bad example”之后参数出错率直接降了一半。5.2 死循环与token爆炸给Agent装上“刹车”Agent进入死循环是另一个经典故障。表现是不断重复调用同一个工具或在一个错误分支上反复兜圈直到token耗尽或成本爆表。定位死循环关键要看Trace里的循环模式。我会在Agent的循环逻辑里加上三个保护机制。第一是最大轮数限制这是底线宁可任务失败也不能无限跑。第二是重复动作检测连续三轮工具调用完全一样就强制中断并要求模型换策略。第三是相似结果检测工具返回的数据如果和上一轮基本一致会触发提醒避免模型在同一个数据上反复“思考”却不动。死循环的根因通常出在提示词上。最常见的是模型收到了工具的错误提示但没被赋予“纠错权限”就会尝试用同样的方法再试一次。解决方法是把“遇到什么情况应该换方案、什么情况下应该停下来向用户求助”写清楚不要只给工具不给使用工具的边界。5.3 幻觉式补全模型在“编”而不是“查”还有一种故障非常隐蔽模型没有调用任何工具直接凭记忆回答了用户。这在Agent场景下是致命的因为用户要的是实时数据而模型给的可能是训练集里的旧知识。我排查这种问题时会先检查规则层如果用户问题涉及的数据类型必须经过工具查询而Agent的响应轨迹里没有工具调用记录直接判失败。在提示词里我会加一条硬性约束凡涉及实时状态、价格、库存、订单等动态信息必须先调用工具查询禁止基于记忆作答。如果模型多次违反就要考虑是不是工具描述没有和这类问题建立明确关联模型压根没意识到“这问题该调工具”。另一种幻觉是“编造工具结果”。模型调了工具但工具返回空值或异常模型为了给用户一个“有用的回复”自行脑补了一组合法数据。这是最危险的行为。对应的解决方案是提示词里明确“若工具返回值不完整或异常必须如实告知用户任何情况下不得编造工具返回内容”同时可以在规则评测里加一条工具返回空值时模型是否明确说明信息不足。5.4 评估本身也可能有Bug小心测试集反噬最后这节说点反直觉的评估系统本身也需要评估。测试集写得不好会把优化方向带进沟里。常见问题有三个。一是测试集和真实用户分布严重偏离比如真实场景里80%都是多轮追问测试集里却有70%是单轮问答评测分数再高也代表不了线上效果。二是答案标注不准确标注人员对业务逻辑理解不一致同一条Case在不同人手里答案不同。三是我前面提过的测试集被反复参考后模型开始“过拟合”测试集——它不是为了做好任务而是为了答对这些题。所以我会定期做两件事一是从线上日志里随机抽样用户问题补充进测试集保持测试集和真实分布的同步二是准备一小批“新鲜Case”每次发布前单独跑一轮不进入常规测试集作为防过拟合的盲测样例。这个习惯帮我抓到过好几次“测试集分数上涨但真实体验下降”的问题。6. 沉淀下来的几个实用习惯6.1 每次改动只动一个变量智能体系统涉及提示词、模型参数、工具定义、上下文策略、评测标准五个变量互相影响。如果一次改了三处出了问题根本不知道是哪处引起的。我现在严格要求自己和团队一次只改一个变量改完立刻跑回归。这看起来慢实际上是最快的路径因为每一步的因果都很清晰。6.2 先保下限再追上限Agent做得很聪明是加分项但稳定可靠是底线。我调优时习惯先确保所有常规场景稳定通过再挑战复杂场景。尤其是那些会让客服、交易、售后出错的场景宁可让Agent说“我不确定需要转人工”也不能让它自信满满地给错误答案。保住了下限再慢慢往上加能力。6.3 把踩过的坑写进回归用例每一个修过的问题都代表系统曾经真实地犯过错。如果不把它变成回归用例同一个坑大概率在未来某个版本里再踩一次。我现在的习惯是修复一个线上问题必须同步提交一条对应的回归测试用例并且标注触发条件和修复说明。这个习惯坚持一段时间之后测试集逐渐变成了一个“踩坑免疫清单”版本发布前跑一遍心里会踏实非常多。Agent的评估与调试本质上就是一个让人和模型、工具、评测系统之间的协作越来越有序的过程值得认真对待。