AI Agent 出问题时，不要只看最终回答：一次请求级调试的思路

AI Agent 出问题时不要只看最终回答一次请求级调试的思路这两年 AI 编程工具变化很快。从 Copilot 式的代码补全到 Claude Code、Codex、OpenCode、Cursor、Cline 这类 Agent 工具AI 已经不只是“帮你补几行代码”了。它可以读项目、改文件、跑命令、调用工具、分析报错然后继续下一轮。但 Agent 越像一个“会干活的人”问题也越明显它出错的时候你很难判断它到底错在哪里。很多人遇到 AI 编程工具跑偏时第一反应是改 prompt。比如你要更认真一点。不要偷懒。必须先读代码再修改。不要乱改无关文件。这些提示有时有用但更多时候只是把问题往后推。因为真正的问题可能根本不在你写给它的那句话里而在它实际发给模型的完整请求里。为什么只看最终回答不够一个 AI Agent 完成任务通常不是一次请求结束。它的流程更像这样用户提出任务 - 模型收到 system prompt、上下文、工具列表 - 模型决定调用某个工具 - 本地执行工具比如读文件、搜索代码、运行命令 - 工具结果再进入下一轮模型请求 - 模型继续判断 - 直到给出最终回答或修改代码我们在终端或编辑器里看到的通常只是这个过程的一小部分。最终回答只能告诉你“它做了什么”但很难告诉你“它为什么这么做”。比如下面这些问题只看最终回答基本看不出来它到底有没有看到关键文件它看到的是完整上下文还是被截断后的上下文system prompt 里有没有某条规则影响了它工具 schema 是不是描述不清导致它选错工具tool result 有没有进入下一轮哪一轮开始 token 暴涨provider 返回的 400 到底是模型问题还是请求格式问题它是不是每一轮都重复带入了大量无效上下文这些都属于“请求级问题”。AI Agent 的常见问题其实可以分层看我现在更倾向于把 AI Agent 的问题分成几层而不是笼统地说“模型不行”。第一层模型没有看到该看的东西这是最常见的问题之一。你以为 Agent 已经读了某个文件但实际发给模型的请求里没有那段内容。或者它读过但后续请求里没有保留。于是模型只能基于不完整上下文做判断结果自然不稳定。这种时候继续强调“请仔细阅读代码”没有太大意义。你真正要确认的是关键上下文有没有进入下一轮请求第二层工具列表或工具描述有问题Agent 能调用工具并不代表它会正确调用工具。模型看到的是一组工具 schema包括工具名、描述、参数结构。如果工具描述太模糊模型可能不知道什么时候该用。如果参数结构太复杂模型可能生成错误参数。如果工具太多模型也可能选错。这类问题在 MCP、插件、子任务工具越来越多以后会更明显。第三层tool call 和 tool result 没有正确闭环一个正常的工具调用闭环应该是assistant: tool_use tool: tool_result assistant: 根据 tool_result 继续如果中间某一环丢了Agent 就会开始出现奇怪行为。比如工具没有真正执行但模型以为执行了tool result 太长进入下一轮后污染上下文多个 tool_result 顺序错了tool_use 和 tool_result 没有正确配对provider 要求的消息格式和客户端保存的格式不一致这类 bug 最难靠肉眼看最终回答判断。你必须看到真实的请求和响应。第四层token 和成本问题很多人用 AI 编程工具时一开始只关心效果。但一旦使用频率上来token 成本就会变成实际问题。尤其是 Agent 场景里token 并不只花在最终回答上。大量 token 可能花在system prompt工具 schema历史消息文件内容搜索结果命令输出tool result子 Agent 的上下文有时一次任务很贵不是因为最终回答很长而是因为某一轮请求带了巨大的上下文。所以看 session 总成本还不够最好能看到每一次请求的 token 使用。请求级调试应该看什么如果一个 AI Agent 跑偏我通常会先看这几类信息。1. system promptsystem prompt 是 Agent 行为的底层约束。很多看似“模型自己决定”的行为其实是 system prompt 影响的。比如它为什么总是先写计划它为什么不直接执行命令它为什么遇到某类文件不修改它为什么要反复确认这些可能都和 system prompt 有关。2. messagesmessages 决定模型当前能看到什么。重点不是“这个 Agent 曾经读过什么”而是当前这一轮请求里到底包含了什么这两个问题不一样。Agent 本地读过一个文件不代表后续每一轮模型请求都带着这个文件。3. tools schema如果 Agent 没有调用你期望的工具先不要急着骂模型。可以先看工具是否真的出现在 tools 里工具描述是否清楚参数 schema 是否合理是否有多个类似工具让模型混淆provider 是否支持这种 schema4. tool call / tool result这一层最适合排查 Agent 为什么做错。你可以看模型选择了哪个工具传入了什么参数工具返回了什么返回结果有没有进入下一轮下一轮模型有没有基于这个结果继续如果这里断了后面再怎么调 prompt 都不稳定。5. token / cache / cost / latency这些指标能帮你判断问题发生在哪一轮。比如哪一轮 input token 突然升高哪一轮 tool result 特别大cache 有没有命中哪个模型最贵哪个请求延迟最高失败请求有没有 usage 信息这比只看“今天花了多少钱”有用得多。ccglass 解决的就是这一层最近我发现了一个开源工具ccglass。项目地址https://github.com/jianshuo/ccglass它不是另一个 AI 编程助手而是一个本地观测工具。简单说它会在本地启动一个代理和 Dashboard让你看到 Claude Code、Codex、OpenCode、CodeBuddy、Qoder 等工具实际发给模型的请求。你可以看到system promptmessagestools schematool callstool resultsrequest / response bodytoken / cache / costlatencyturn-to-turn diff也就是说它关心的不是“再帮你写一段代码”而是“让你看清 Agent 到底是怎么工作的”。一个典型使用场景假设你让 Claude Code 修一个 bug。它最后确实改了代码但你觉得改得很奇怪。这时你可以不急着重跑而是打开 ccglass 看这几件事第一轮请求里有没有带上相关文件system prompt 有没有影响它的修改策略它调用了哪些工具每个工具返回了什么哪个 tool result 进入了下一轮修改代码前它是否真的看到了测试失败信息token 是不是在某一轮突然暴涨如果你能回答这些问题调试 Agent 就从“感觉不对”变成了“证据链不对”。它和普通抓包工具有什么区别很多人会问这是不是 Charles、mitmproxy、Proxyman 也能做某些情况下可以但 AI 编程 Agent 有几个麻烦点不一定遵守系统代理有些客户端走自定义 base URL有些使用 OpenAI / Anthropic 兼容接口有些 provider 的 streaming 格式不一样有些工具调用信息需要按 Agent 语义展示而不是只看 HTTP 包ccglass 的目标不是替代通用抓包工具而是专门围绕 AI Agent 请求结构做展示。它会把 system、messages、tools、tool call、tool result、usage、cost、diff 这些东西整理成适合调试 Agent 的视图。为什么我觉得这件事会越来越重要AI 编程工具的发展方向很明显Agent 会越来越自动。它们会读更多文件调用更多工具跑更长任务甚至调度子 Agent。这当然会提高效率。但如果没有观测能力复杂度也会一起上升。以后我们遇到的问题可能不再是这段代码补全得对不对而是为什么这个 Agent 在第 7 轮调用了这个工具为什么它把这个 tool result 带到了后面 12 轮为什么这次任务花了 30 万 token为什么同样的任务换 provider 就失败为什么上下文压缩后它丢了关键约束这些问题都需要请求级视角。结语我觉得 AI 编程工具接下来的一个重要方向不只是让 Agent 更强而是让 Agent 更可观察。只看最终回答就像只看程序崩溃后的最后一行日志。真正要调试复杂系统还是要看输入、输出、中间状态和调用链。AI Agent 也是一样。如果你也在用 Claude Code、Codex、OpenCode、CodeBuddy、Qoder 这类工具可以试试 ccglasshttps://github.com/jianshuo/ccglass它解决的不是“让 AI 更聪明”而是让使用者更清楚地知道AI 到底看到了什么又基于什么做出了下一步。