普通接口失败时,我们通常检查请求、响应、异常和耗时。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 可观测性最终会形成一条闭环:线上轨迹暴露问题,问题沉淀为评估样本,评估结果约束下一次发布。相比再增加一层“智能”,这种可解释的工程反馈往往更重要。
DISCUSSION