AI Agent调试指南：Agent不按预期工作的10个常见原因

Agent调试比传统软件调试难

传统软件——输入X输出Y，不对就查代码。Agent的输出取决于LLM的推理过程，同样的输入可能得出不同的结果。

10个常见问题

1. 工具描述不够清晰 Agent不理解工具是干什么的。修复：给工具加详细的中文描述和用例。

2. 任务指令太模糊 "帮我查一下" → Agent不知道该查什么。修复：具体到"查一下Qwen 2.5的最新版本号和发布日志"。

3. System Prompt太长 Agent在长上下文里迷失重点。修复：关键指令放开头和结尾。

4. 工具太多 Agent有20个工具可选时，选错概率大增。修复：按任务分组，每个任务只暴露相关工具。

5. 上下文窗口溢出 长对话后Agent忘了早期信息。修复：用摘要压缩历史。

6. 错误处理不当 工具调用失败后Agent直接崩溃。修复：加retry逻辑和fallback方案。

7. Few-Shot示例太少 Agent不知道你期望的输出格式。修复：给2-3个完整示例。

8. 温度设置太高 Agent太"有创意"，不按格式输出。修复：把temperature降到0.1-0.3。

9. 缺少中间步骤确认 Agent做关键操作前不确认。修复：加confirmation步骤。

10. 没有日志 出问题不知道Agent内部在想什么。修复：记录Agent的每一步思考过程。

调试工作流

遇到问题 → 查日志（Agent的思考过程）
       → 复现（用相同输入跑2-3次）
       → 定位（工具问题/指令问题/LLM问题）
       → 修复 → 测试 → 上线

总结

Agent调试的黄金法则是加日志看到Agent在思考什么。大部分"Agent不听话"的问题，看了思考链就清楚了——不是Agent笨，是指令没写清楚。