AI Agent 排查手册：工程化常见故障与定位思路

这份手册的用法

这份文档不是教程，是排查手册。当 Agent 行为异常时，按下面的分类逐项排查。每条都附了定位步骤和常见原因。

故障分类

1. 输出格式漂移

症状：同样的输入，输出结构不一致，JSON 解析失败或字段缺失。

定位步骤：

1. 检查提示词的“输出格式”段是否被截断
2. 检查上下文是否过长导致格式约束被稀释
3. 检查是否混入了 few-shot 示例与当前格式冲突

常见原因：提示词没版本化、上下文没压缩、few-shot 过时。

2. 工具调用死循环

症状：Agent 反复调用同一个工具，无法收敛到最终答案。

定位步骤：

1. 检查工具的失败回退是否缺失（失败后 Agent 不知道该怎么办）
2. 检查工具返回是否过大，撑爆上下文
3. 检查是否缺少“终止条件”提示

常见原因：回退缺失、返回未裁剪、终止条件模糊。

3. 上下文爆炸

症状：跑几轮后上下文超限，报错或被截断。

定位步骤：

1. 区分长期记忆与当次任务上下文
2. 检查工具返回是否做了摘要或裁剪
3. 检查每轮是否做了上下文压缩

常见原因：记忆全量注入、工具返回全量保留、无压缩机制。

4. 评估无法复现

症状：同一用例昨天通过今天失败，无法判断是改动导致还是模型抖动。

定位步骤：

1. 固定模型版本和采样参数
2. 记录每次评估的工具调用链
3. 对失败用例做最小化复现

常见原因：未固定模型版本、采样参数随机、用例不够最小化。

维护规则

• 每次遇到新故障，先复现再写入本手册
• 每条故障必须包含：症状、定位步骤、常见原因
• 排查完后回填“修复方式”链接到对应文章