Agent 真正需要的不是更多日志,而是可解释的轨迹

当 Agent 开始调用工具、修改状态和反复规划,传统日志已经不足以解释一次任务为什么成功或失败。

Read in English →
本篇目录

普通接口失败时,我们通常检查请求、响应、异常和耗时。Agent 的失败更像一段过程:它可能一开始理解错目标,也可能选对工具却给错参数,或者在得到正确结果后又做了一次多余操作。

因此,Agent 的可观测性不能只回答“报错了吗”,还要能还原“它当时知道什么、做了什么、为什么继续”。

把一次任务看成状态变化

我更愿意把 Agent 运行记录成一组事件,而不是一段混杂的文本日志。每个事件至少包含:

  • 任务与运行标识;
  • 当前步骤和状态;
  • 使用的模型、工具及版本;
  • 工具输入、输出摘要和错误类型;
  • 延迟、token 与费用;
  • 决策完成后保留下来的结构化结果。

一个简化的事件可以长这样:

{
  "run_id": "run_20261031_0042",
  "step": 3,
  "event": "tool.completed",
  "tool": "search_documents",
  "latency_ms": 428,
  "result_count": 8,
  "state_after": "evidence_ready"
}

结构化事件的价值,是可以按步骤聚合、比较和重放,而不是只能依靠肉眼搜索一段长日志。

哪些信息值得保留

并不是记录越多越好。完整保存模型输入输出会带来隐私、成本和噪声问题。我会优先保留能够支持判断的信息:提示词版本、工具名称、参数模式、结果摘要、状态变化和明确的错误分类。

对于敏感内容,可以记录哈希、长度、数据类型和经过脱敏的摘要。可观测性的目标是解释系统行为,不是无限复制用户数据。

为失败建立分类

如果所有失败最后都叫 agent_failed,监控几乎没有意义。更有用的分类包括:

  • 目标理解错误;
  • 规划缺失或循环;
  • 工具选择错误;
  • 工具参数无效;
  • 外部服务失败;
  • 证据不足却继续生成;
  • 已经完成却没有停止;
  • 权限或安全策略阻止。

分类不需要一次设计完美。它应该随着真实问题逐渐演化,但必须能让团队知道下一步应该改模型、工具、提示词,还是系统边界。

从单次轨迹走向评估

轨迹本身不是终点。积累到一定规模后,可以比较不同版本在相同任务集上的行为:平均工具调用次数是否下降、无效循环是否减少、成功任务的成本是否稳定、失败是否集中在某种工具或某类输入。

好的 Agent 可观测性最终会形成一条闭环:线上轨迹暴露问题,问题沉淀为评估样本,评估结果约束下一次发布。相比再增加一层“智能”,这种可解释的工程反馈往往更重要。

RELATED WRITING

DISCUSSION

讨论