Agent 效果不达预期时，如何分析 Bad Case 并确定优化方向？

核心回答

Bad Case 分析的目标是用证据定位偏离，再通过对照验证原因，让优化对应实际故障。可以按四步展开：

1. 明确成功条件：核对用户目标、权限、数据和时间范围，确认预期结果，先分清系统确实做错还是评估判断有误。
2. 沿轨迹取证：串起输入、检索结果、实际发给模型的上下文、工具名称与参数、执行结果和最终答案，找到最早有证据表明偏离预期的环节。
3. 提出假设并验证：说明哪项信息缺失、哪一步传错或做错；保持其他条件不变，用局部替换或单因素对照验证，再修改对应逻辑。
4. 归类并回归：按影响、频率和风险安排修复，用原失败题、未参与调参的同类题和原成功题检查质量、耗时、成本，以及是否引入新错误。

例如“华北”已经被召回，却没有进入生成 SQL 的上下文，就先追踪合并和过滤过程，再通过补回取值做对照；一次恢复只支持这个假设，还要结合数据流和重复结果继续核验。

第一步：先确认“错”在哪里

以电商问数为例：用户问“华北地区销售总额”，系统生成 SQL 并执行成功，但返回空值或空结果。先核实用户权限、时间范围、指标口径和数据版本，确认该条件下确实应该有销售数据；如果实际没有记录，空结果可以是正确结果。还要检查评估器，不能因为答案没匹配固定句式，就把同义的正确回答判错。

对于创建订单、修改文件这类执行任务，还要核对实际结果。例如任务要求订单已经落库，Agent 回复“已创建”或工具返回“成功”，都不能代替订单记录；异步接口还要按约定检查最终状态，再核对订单标识、关键字段和是否重复创建。即使最终结果正确，也要检查有没有跳过必需的确认或误改其他状态。只规定不可省略的业务约束，不把某一条参考调用路径当成唯一正确顺序。

然后用同一个 request_id 找齐这次请求的材料。除了最终 SQL 和数据库返回，还要看原问题、字段/指标/取值三路召回、合并和过滤前后的上下文、实际发给模型的消息，以及各步骤耗时。这样才能区分“资料从未找到”和“找到了但后面没传进去”。记录可观察的输入、输出和状态即可，不需要依赖模型隐藏的思维过程。

Agent 还可能在分支选择、停止条件或工具循环上失败。例如工具已经报错，系统却继续把它当成有效数据总结；或者已经得到结果，仍不断调用同一工具。因此轨迹不仅要记录模型说了什么，还要记录它实际做了什么、何时结束。

第二步：沿着“华北”这条信息追踪

问数链路里，字段说明解决查哪一列，指标定义解决怎么算，字段取值解决过滤条件写什么。假设实际 SQL 使用了 region_name = '华北地区'，而数据中存的是“华北”，就沿着取值的传递过程找证据：

1. 原始数据和取值索引里有“华北”吗？ 原始数据有、索引没有，先检查采集、入库和更新；信息源还没准备好，下游模型无法稳定补救。
2. 本次取值召回返回了吗？ 索引里有但本次没返回，固定索引和问题，检查查询表达、权限/元数据过滤、候选数量和检索结果。只知道“没召回”，还不能直接断定是 Embedding 模型不行。
3. 召回后有没有进入最终上下文？ 对照返回的 column_id/value、合并后的字段 examples、过滤后的 table_infos 和实际模型输入。如果“华北”在某一步消失，就检查那一步的映射或过滤。日志只打印“合并成功”不足以证明内容完整。还要比较发送前的最终消息：合并结果里有“华北”，也可能在后续摘要、预算裁剪或模板组装时丢失；不能拿裁剪前的日志证明模型已经看见它。
4. 模型看到正确取值后，仍写错了吗？ 若最终输入已明确给出“华北”，SQL 却写成“华北地区”，再检查输入是否冲突、提示词是否把真实值用途说清，以及模型对证据的使用。此时比较 Prompt 或模型才有针对性。
5. SQL 条件正确，执行和呈现还对吗？ 如果已经使用“华北”，继续查时间限制、指标额外条件和表关联；数据库返回有数据但最终回答说“没有数据”，问题又可能在结果解析或回答生成。

这里找的是最早已证实的偏离，并不保证每个请求只有一个原因。比如取值缺失和表关联错误可能同时存在，补好一个问题后，还需要继续核验结果。

EXPLAIN 通过也不能证明业务正确。它能发现部分语法、表名或字段问题，却不知道“华北地区”是不是正确业务取值。遇到 Unknown column 也一样：先看正确字段是否进入上下文、是否被过滤掉，再看模型写出的字段名或别名，不能直接跳到“换模型”。

第三步：用对照验证原因，再选择改法

假设证据显示：取值召回已返回“华北”，但最终输入缺少它。可以保持问题、其他材料、模型和提示词不变，只把缺失取值补回最终输入，观察 SQL 和查询结果是否恢复。这个实验检查的是“缺少该取值是否影响结果”，随后还要检查合并/过滤代码和状态，才能确定实际修复位置。补回时只使用本次权限和版本下应当可用的取值，不把评测参考答案或无权读取的资料混入输入。

人工补入是诊断对照，不是生产链路已经修好的证据。修复合并或裁剪逻辑后，要撤掉人工注入，从原问题重新走正常链路，核对“华北”能否自然进入最终输入，以及 SQL 和查询结果是否正确；否则可能只是用人工提示绕过了故障。

一次补入后答对只是支持这个假设，不能单独证明唯一根因。生成有随机性，补入信息也可能恰好绕过别的缺陷。可以固定可保存的输入和工具返回，对随机环节重复运行；再用其他地区的同类问题检查修复是否有效。若实验结果不支持假设，就回到轨迹继续找，而不是把猜测写成结论。

优化也要跟原因对应：取值漏入库就修数据更新；映射时丢值就修合并逻辑；正确证据已经齐全但持续不用，再比较上下文组织、提示词或模型；工具异常则检查超时、接口和异常分支。如果检索链路异常并触发降级，还要记录本次实际使用的路径；配置上写着混合检索，不代表这次真正执行了混合检索。一次同时换切块、检索器、Prompt 和模型，即使结果变好，也很难知道是哪项改动起作用。

这套方法可以迁移到非 RAG 的 Agent：工具选错，看选择时有哪些可用工具和信息；参数错，核对参数来源和校验；工具返回对但结论错，核对结果解析与生成。表面症状负责引导取证，具体修改仍由证据决定。

第四步：把修复放回固定样本中验证

把 Bad Case 记录成“问题和预期、实际结果、关键轨迹、验证过的原因、修复方案”，再按原因聚类。优先处理影响范围大、出现频繁的问题；低频但可能造成严重错误动作的问题也应优先。不要只按出现次数排序，也不必把相同根因的几十条失败逐条独立调 Prompt。

回归至少要同时看三类样本：原失败题验证是否修好，未参与调参的同类题验证是否解决一类问题，原成功题检查有没有回退。对比时固定数据/知识库快照、模型配置和评分规则；随机环节报告重复结果。只在原失败题上变好，可能只是针对那一道题调出来的效果。

最终还要比较任务成功、错误类型分布、耗时和成本。工具调用更少未必更好，可能只是提前退出；平均分提高也可能掩盖某类高风险问题变差。相关题目：如何设计 RAG 评估方案和指标？。

追问：复现不了或日志不全怎么办？

离线复现不了线上问题怎么办？ 先对比数据版本、用户权限、缓存、时间条件和外部服务响应。能保存线上工具返回时，可固定这些返回重放后续流程，再单独检查工具链；重放涉及写入动作时应在隔离环境替换执行，避免重复操作。一次未复现不等于问题不存在，缺少哪些证据就补哪些观测。

召回服务报错，可以当成“没找到”继续回答吗？ 两者含义不同：服务异常表示本次没有取得有效查询结果；查成功但无记录才是有效业务结果。可以设计降级，但应保留异常状态并避免把失败伪装成空数据。在问数流程中，SQL 校验失败可以进入校正分支；校正后是否再校验、最多重试几次，需要明确设计。教程现有流程校正后直接执行，带次数上限的再校验是可增加的改进。

工具超时，就能认定动作没执行吗？ 不能。超时只说明调用方没有按时拿到结果，远端可能已经完成，也可能仍在执行。排查写操作时，要把调用记录与外部业务标识、执行状态、幂等键对应起来；先查状态，或按服务端支持的幂等约定处理。日志中的“超时”“取消”不能直接改写成“未创建订单”，也不能据此盲目重放。

对应教程

参考资料