Agent Guide 问题排查

Agent 的问题不一定来自模型。先判断故障发生在哪一层，再决定是补上下文、修工具、调整权限，还是更换模型与流程。

先记录五类证据

证据	需要记录什么
任务	原始目标、输入、限制和验收标准
模型	模型版本、参数、调用次数和成本
上下文	实际提供的规则、历史、检索片段和工具返回值
工具	工具名、参数、返回值、错误和权限
环境	运行平台、依赖版本、网络和凭据状态

按现象定位

Agent 不理解任务

先检查目标是否可执行、输入是否完整、输出格式是否明确。不要先急着换模型。

Agent 重复或陷入循环

检查是否缺少停止条件、工具错误是否被正确返回、上下文是否持续保留了失败轨迹。

Agent 调用了错误工具

检查工具描述、参数示例、工具数量和当前权限。必要时减少工具范围，让模型先完成小任务。

Agent 给出看似正确但无法核验的结果

增加来源、引用和验收步骤；把“生成答案”拆成“检索事实、形成判断、输出结论”。

多 Agent 协作越来越混乱

检查角色边界、交付格式、共享上下文和失败回退。先退回单 Agent 基线，确认拆分确实带来收益。

通用排查顺序

复现问题 → 保存完整轨迹 → 定位层次 → 只改一个变量 → 重新验收 → 记录结论