当一个 Agent 系统已经开始具备：

  • 多步骤执行流
  • 多轮反馈
  • 冲突确认
  • 质量闸门
  • 自动回炉

你很快就会发现一个新问题：

系统越来越强了，但也越来越难调了。

很多项目做到这一步时，调试方式仍然只有一种：

  • 打印 Prompt

这在单轮调用时还能凑合，但对当前这种多 Agent 系统来说，已经完全不够用了。

这章要讲的就是：

一个真实的 Agent 产品，调试体系到底应该怎么搭。

为什么“只看 Prompt”已经不够了

Prompt 当然重要，但它只能回答一部分问题。

比如你能看到：

  • 最终给模型的 System Prompt 是什么
  • 最终给模型的 User Prompt 是什么

但很多更关键的问题，它回答不了：

  • 这些信息是从哪里来的
  • 为什么这轮会给这个 Agent 这些内容
  • 当前生效反馈是什么
  • 历史冲突有没有真正写回
  • 这次到底用了哪个模型、哪个参数

也就是说：

Prompt 只能告诉你“最后发了什么”，但不能告诉你“为什么会发成这样”。

当前项目为什么后来必须补调试体系

这个项目在早期，调试需求相对简单。
但随着系统能力往前走，问题迅速变复杂：

  • Writer 为什么没按反馈改
  • Reviewer 为什么判成 rewrite
  • 自动回炉后第二次 Reviewer 为什么没触发
  • 冲突确认后，后续上下文到底有没有更新

这些问题如果只靠看 Prompt，效率会非常低。
所以当前项目后来逐步补了一个更完整的调试体系。

第一层：任务级状态和步骤日志

一个多 Agent 产品最基础的调试层，是：

  • 任务状态
  • 当前 Agent
  • 当前步骤
  • 步骤执行记录

当前项目里已经比较完整地记录了：

  • 谁在跑
  • 跑到了哪一步
  • 哪一步失败了
  • 错误类型是什么
  • 是否触发了自动重试

这层能力主要解决的是：

流程有没有按预期走。

如果没有这层，系统连“跑到了哪里”都说不清楚，更别谈调试。

第二层：错误信息和故障面板

只知道“失败了”还不够，系统还必须尽量告诉你：

  • 失败模型是什么
  • 调用端点是什么
  • 错误类型是什么
  • 当前重试到第几次

这也是为什么当前项目在任务详情页里补了故障面板。
虽然它看起来只是 UI 细节，但本质上是把“内部异常”翻译成了“可读的运行状态”。

最近项目还顺手修了一个很实用的点：

  • 当任务成功进入审批点后，旧的错误态会被清空

这样页面就不会继续挂着已经恢复成功的历史故障，避免误导用户。

第三层：Prompt 调试

Prompt 仍然是需要看的，只是不能只看 Prompt。

当前任务详情页里仍然保留了：

  • System Prompt
  • User Prompt

这层最适合回答的问题是：

  • 模型最终看到的文本是不是符合预期
  • 有没有明显漏掉重要信息
  • 有没有把无关内容带进去

这仍然是很有价值的一层。

第四层：LLM Call

后来当前项目又补了一层很关键的信息：

  • LLM Call

它会展示这次调用的关键参数，比如：

  • provider
  • model
  • endpoint
  • temperature
  • timeout_seconds
  • 是否启用工具

这层特别适合排查：

  • 为什么同样的 Agent 这次结果波动很大
  • 为什么自动回炉阶段更稳了
  • 为什么某一步容易超时

换句话说，LLM Call 不是在看“内容”，而是在看“这次到底怎么调的模型”。

第五层：Context Breakdown

这是当前项目调试体系里最值得强调的一层。

它解决的不是“发了什么 Prompt”，而是：

这次上下文到底是怎么拼出来的。

现在页面里可以看到上下文按来源拆分后的结果，比如：

  • 任务基础信息
  • 上游输入
  • 当前生效反馈
  • 活跃问题
  • 规则约束

并且每一项还能看到来源字段。

这会显著提升你排查这类问题的效率：

  • 为什么这轮还在看旧反馈
  • 为什么冲突确认后的结论没进上下文
  • 为什么 Writer 看到了这个字段但 Reviewer 没看到

相比只看最终 Prompt，这层信息更接近真正的工程问题。

第六层：Quality Gate

当系统引入质量闸门后，调试层也必须把它展示出来。
否则你会看到：

  • Reviewer 给了一段长审稿意见

但不知道流程为什么会：

  • 继续
  • 修订
  • 重写

所以当前项目后来把 Quality Gate 也展示进了调试区和审核区。

现在页面上能直接看到：

  • 结论
  • 原因
  • 必改项
  • 详细审核意见

这让“质量判断”从隐式逻辑变成了显式信息。

第七层：上下文快照

当前项目还保存了：

  • task_context_snapshots

它的价值不在于实时看，而在于：

  • 出问题后能回看
  • 多轮修订时能复盘
  • 关键节点状态可以被保留下来

这和步骤日志是互补关系：

  • 步骤日志回答“发生了什么”
  • 快照回答“那一刻系统整体是什么状态”

当前项目的调试体系，本质上在回答哪几类问题

如果总结一下，你会发现当前这套调试体系实际上分别在回答三种不同问题。

1. 流程问题

回答：

  • 任务现在在哪
  • 哪一步失败了
  • 有没有重试

这靠的是：

  • 任务状态
  • 步骤日志
  • 故障面板

2. 调用问题

回答：

  • 这次到底调用了哪个模型
  • 参数是什么
  • 超时怎么设置的

这靠的是：

  • LLM Call

3. 上下文问题

回答：

  • 为什么模型会看到这些信息
  • 哪些上下文是当前生效的
  • 哪些信息来自哪里

这靠的是：

  • Prompt 调试
  • Context Breakdown
  • 快照

最近这个项目还补了什么非常实战的调试能力

除了展示能力本身，当前项目最近还做了一些很实战的事情。

1. 自动回炉链路的真实验证

项目不是只把逻辑写出来，而是：

  • 真实构造“明显跑题的草稿”
  • 跑出 rewrite
  • 验证自动回炉
  • 验证第二次 Reviewer
  • 验证最终进入 revision_done

这说明调试体系不仅要看页面，还要配合实际任务做全链路验证。

2. 自动化测试开始补齐

项目已经把几条最容易被改坏的链路固化成测试，例如：

  • 自动回炉完整闭环
  • 自动回炉参数
  • 冲突确认写回有效上下文

这其实是调试体系向更成熟阶段发展的标志：

从“靠人看页面排查”，开始走向“用测试锁住关键语义”。

一个很重要的经验

做 Agent 调试时，最容易犯的错误是：

把所有问题都归因于 Prompt。

但当前项目的经验恰恰说明，很多问题更可能出在：

  • 状态没写对
  • 恢复语义没写对
  • 有效反馈没更新
  • 参数没按预期传
  • 页面显示的是旧错误状态

这就是为什么调试体系必须是分层的，而不能只靠一层 Prompt 可视化。

这一章的结论

一个真实的 Agent 产品，至少应该有这几层调试能力：

  • 任务状态和步骤日志
  • 错误信息和故障面板
  • Prompt 调试
  • LLM Call
  • Context Breakdown
  • Quality Gate
  • 上下文快照

当前项目已经基本把这套骨架搭起来了，这也是它从“能跑”走向“可维护”的关键原因之一。

下一章往哪里接

到这里，这套“开发 Agent 入门教程”其实已经从产品、流程、上下文、反馈、质量闸门一路讲到了调试体系。

如果继续往下写，最自然的下一批主题会是：

  • 自动回炉与失败重试怎么设计
  • Agent 项目怎么补自动化测试
  • 什么时候值得拆更多 Agent
  • 什么时候值得开始平台化

这些内容就更偏“第二阶段工程化”了。