工具｜Agent 鲁棒性诊断模板

这份模板用于后续每章的现实案例。目标是用观测证据区分模型、Harness、工具、接口、上下文和 Memory 问题。

1. 描述现象

• 用户目标是什么？
• 失败表现是什么？
• 失败是否可以重复？
• 影响哪些任务、用户、版本或环境？

2. 建立假设

假设	示例
模型能力不足	相同上下文下仍无法完成推理或遵循格式
Harness设计问题	循环终止错误、重试放大失败、状态传递丢失
工具契约问题	返回字段缺失、类型改变、错误结果被当成成功
LLM接口适配问题	工具调用协议、消息角色或流式响应处理不一致
上下文管理问题	关键信息被截断、消息顺序错误、噪声过多
Memory检索问题	没召回、召回错误、旧记忆污染、排序不合理
外部依赖问题	超时、限流、权限或网络异常

3. 收集证据

一次任务至少要能够关联以下信息：

task_id → run_id → step_id → model_call / tool_call / retrieval

记录版本、输入摘要、输出状态、耗时、Token、重试次数、截断信息、工具 Schema 和 Memory 候选结果。

4. 做对照实验

• 固定输入和 Harness，只替换模型；
• 固定模型，只替换提示词或工作流版本；
• 使用录制的工具结果，排除外部依赖波动；
• 扩大上下文窗口或移除无关消息；
• 对比不启用 Memory、启用旧策略和启用新策略的结果。

每次只改变一个主要变量，否则无法确定改善来自哪里。

5. 给出判断

结论使用下面的格式：

现象：报告生成偶发缺少关键数据
主要原因：工具返回结构变化，Harness 未校验必填字段
证据：失败全部集中在 tool_version=v2，字段 items 变为 results
排除：相同录制数据下，不同模型均能稳定生成报告
措施：增加 Schema 校验、版本兼容和失败分类

不要只写“可能是模型问题”。没有对照实验和观测证据时，只能称为假设。

---

可观测性工程系列：从前言开始 · 维度与基数 · 鲁棒性诊断模板

原文：LandX