DEV Community

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

Posted on

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

#opensource #ai #programming

这两年 AI 编程工具变化很快。

从 Copilot 式的代码补全，到 Claude Code、Codex、OpenCode、Cursor、Cline 这类 Agent 工具，AI 已经不只是“帮你补几行代码”了。它可以读项目、改文件、跑命令、调用工具、分析报错，然后继续下一轮。

但 Agent 越像一个“会干活的人”，问题也越明显：

它出错的时候，你很难判断它到底错在哪里。

很多人遇到 AI 编程工具跑偏时，第一反应是改 prompt。

比如：

你要更认真一点。
不要偷懒。
必须先读代码再修改。
不要乱改无关文件。

这些提示有时有用，但更多时候只是把问题往后推。

因为真正的问题可能根本不在你写给它的那句话里，而在它实际发给模型的完整请求里。

为什么只看最终回答不够？

一个 AI Agent 完成任务，通常不是一次请求结束。

它的流程更像这样：

用户提出任务
-> 模型收到 system prompt、上下文、工具列表
-> 模型决定调用某个工具
-> 本地执行工具，比如读文件、搜索代码、运行命令
-> 工具结果再进入下一轮模型请求
-> 模型继续判断
-> 直到给出最终回答或修改代码
Enter fullscreen mode Exit fullscreen mode

我们在终端或编辑器里看到的，通常只是这个过程的一小部分。

最终回答只能告诉你“它做了什么”，但很难告诉你“它为什么这么做”。

比如下面这些问题，只看最终回答基本看不出来：

  • 它到底有没有看到关键文件？
  • 它看到的是完整上下文，还是被截断后的上下文？
  • 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 继续
Enter fullscreen mode Exit fullscreen mode

如果中间某一环丢了，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 prompt

system prompt 是 Agent 行为的底层约束。

很多看似“模型自己决定”的行为，其实是 system prompt 影响的。

比如：

  • 它为什么总是先写计划？
  • 它为什么不直接执行命令？
  • 它为什么遇到某类文件不修改？
  • 它为什么要反复确认？

这些可能都和 system prompt 有关。

2. messages

messages 决定模型当前能看到什么。

重点不是“这个 Agent 曾经读过什么”，而是：

当前这一轮请求里到底包含了什么？

这两个问题不一样。

Agent 本地读过一个文件，不代表后续每一轮模型请求都带着这个文件。

3. tools schema

如果 Agent 没有调用你期望的工具，先不要急着骂模型。

可以先看：

  • 工具是否真的出现在 tools 里？
  • 工具描述是否清楚？
  • 参数 schema 是否合理？
  • 是否有多个类似工具让模型混淆？
  • provider 是否支持这种 schema？

4. 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 prompt
  • messages
  • tools schema
  • tool calls
  • tool results
  • request / response body
  • token / cache / cost
  • latency
  • turn-to-turn diff

也就是说，它关心的不是“再帮你写一段代码”，而是“让你看清 Agent 到底是怎么工作的”。

一个典型使用场景

假设你让 Claude Code 修一个 bug。

它最后确实改了代码，但你觉得改得很奇怪。

这时你可以不急着重跑，而是打开 ccglass 看这几件事：

  1. 第一轮请求里有没有带上相关文件？
  2. system prompt 有没有影响它的修改策略？
  3. 它调用了哪些工具？
  4. 每个工具返回了什么？
  5. 哪个 tool result 进入了下一轮？
  6. 修改代码前，它是否真的看到了测试失败信息？
  7. 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 这类工具，可以试试 ccglass：

https://github.com/jianshuo/ccglass

它解决的不是“让 AI 更聪明”，而是让使用者更清楚地知道：

AI 到底看到了什么，又基于什么做出了下一步。

Top comments (0)