把 Agent 失败拆成可操作的层次
“Agent 没完成任务”不是根因。多步骤系统会在不同层次失败，而每一层需要不同负责人和修复方式。
意图理解系统误解了目标、约束、对象或完成条件。
规划步骤顺序错误、遗漏必要步骤，或选择了不合适的策略。
工具调用了错误工具、参数无效、结果解析失败或发生超时。
权限与状态缺少授权、会话状态过期，或外部系统状态与假设不一致。
验证Agent 没有检查结果是否满足目标，就宣布完成。
沟通任务其实成功了，但输出没有解释结果、限制或下一步。
从“预期路径和实际路径第一次出现差异的地方”开始调查，而不是只盯着最后一句回答。
同时收集客户证据和执行证据
客户证据回答：用户原本想做什么、失败如何影响工作、是否有替代方案、后果是什么。执行证据回答：Agent 选择了什么计划、调用哪些工具、每步输入输出、权限状态、延迟、重试与错误。
反馈入口应绑定稳定的 Run ID 或 Trace ID，并附上 Agent 版本、模型、Prompt、工具集合、发布版本、账户、用户角色和工作流。不要让用户描述这些机器已经知道的信息。
一套可重复的失败调查流程
- 用用户自己的话记录目标和预期完成状态。
- 还原实际执行时间线，包括计划、工具、状态与输出。
- 标记第一个与预期不一致的步骤，而不是最后一个错误。
- 判断失败是确定性的、数据相关的，还是偶发环境问题。
- 评估影响范围：工作流、账户、版本、模型和用户群。
- 选择修复：Prompt、规划、工具 Schema、权限处理、确认步骤或 UX。
- 把案例保存为可回放的 Eval，并在生产用户群中验证恢复。
如果团队无法重放真实请求，也应保留足够的脱敏标识，让工程师能在受控系统中定位执行。
不要把所有 Agent 失败混成一个主题
按失败阶段、工具、工作流、版本和客户群聚类。相同的最终抱怨可能来自完全不同的原因；不同的用户表述也可能都指向一个工具参数变更。
- 版本后突然增长：优先检查回归。
- 只集中在一个账户：检查权限、数据形态和定制配置。
- 只发生在长任务：检查状态丢失、上下文截断和超时。
- 执行成功但用户仍不满意：检查成功标准和最后的沟通。
- 低频但影响高价值流程：不要被总量掩盖。
验证恢复，而不只是修掉异常
- 从失败发生到定位第一个错误步骤的时间。
- 报告中具有 Run ID 或 Trace ID 的比例。
- 高影响失败的复现率和负责人覆盖率。
- 修复后同类工作流的完成率与人工接管率。
- 相同客户群的重复报告率。
- 真实失败转化为回归 Eval 的比例。
异常消失不代表用户问题已经解决。最终验证应包含工作流行为和代表性用户的结果确认。