Agent 可观测性：从最终答案追到每一步发生了什么
# Agent 可观测性：从最终答案追到每一步发生了什么
理解日志、指标和 Trace 的分工，为模型调用、工具、检索、审批和状态变化建立统一追踪，并形成系统化排障路径。
# 先记住一句话
评测告诉你系统好不好，可观测性告诉你这一次为什么好或坏；Agent 必须把模型、检索、工具、状态和审批串进同一条 Trace。
# Logs、Metrics 和 Traces
三者关注的范围不同：Log 是一条具体事件，Metric 是一段时间内汇总出的数字，Trace 则把一次任务经过的多个步骤按时间和因果关系串起来。
| 类型 | 回答什么 | Agent 示例 |
|---|---|---|
| Logs | 某一时刻发生了什么 | 参数校验失败、审批被拒绝 |
| Metrics | 整体趋势怎样 | 完成率、P95 延迟（95% 请求不超过的耗时）、每任务成本 |
| Traces | 一次请求经过了哪些步骤 | 模型 → 搜索 → 重排 → 工具 → 模型 |
# Trace 层级
trace：一次用户任务
├── span：上下文组装
├── span：模型决策
├── span：RAG 检索
│ ├── query rewrite
│ ├── vector search
│ └── rerank
├── span：tool call
├── span：approval wait
└── span：完成验收
2
3
4
5
6
7
8
9
10
每个 Span（一次局部操作）记录开始结束时间、状态、父子关系、模型/Prompt/工具版本、输入输出摘要和错误分类。所有异步 Worker（后端任务执行单元）共用同一个 traceId，并用 parentSpanId 表达哪一步触发了哪一步。
# 需要记录的字段
traceId、taskId、threadId、用户匿名标识；- 模型、参数和 Prompt/Skill 版本；
- 工具名、参数摘要、输出大小、耗时和重试；
- 检索查询、候选数、命中文档 ID 和重排结果；
- 每轮状态、停止原因、审批和恢复；
- Token、费用、缓存命中和端到端延迟；
- 错误类型和可重试性。
不要默认记录完整 Prompt、文档、密钥或个人数据。使用脱敏、采样、字段 allowlist、访问控制和保留期限。
# 一条有效排障路径
- 先看任务最终状态和停止原因；
- 定位第一处偏离预期的 span；
- 确认正确上下文是否进入模型；
- 检查模型选择、工具参数和 observation；
- 检查权限、超时、重试和状态更新；
- 用相同输入和固定版本复现；
- 把问题沉淀为评测用例，而不是只修一条日志。
# 贯穿项目的例子
用户说 “答案引用错了”。Trace 显示检索已经返回正确文档，但重排把旧版本放在第一位；因此根因是元数据时间权重，而不是 Prompt。修复排序后，把 “新旧版本冲突” 加入 RAG 回归集。
# 高频面试题与回答
回答顺序：先说结论，再解释原因，最后补一个例子或工程边界。不要逐字背诵，记住这条表达主线即可。
1. 30 秒回答：怎样排查 Agent 失败参考答案
我会先给整次任务一个统一的 traceId，再把 Context 组装、模型调用、检索、工具、审批和状态更新记录成一条时间线。排查时先看最终为什么停止，再从前往后找到第一处偏离：是资料没传给模型、模型选错工具、工具执行失败，还是状态没有更新。修复后把这次失败脱敏加入评测集，防止以后再次出现。
2. 有完整日志为什么还需要 Trace？参考答案
日志是一条条分散的事件，Trace 则把同一次任务里的模型调用、工具和服务请求按父子关系和时间顺序串起来。这样不仅能看到 “发生了什么”，还能看到 “哪一步导致了后面的失败”，特别适合并行或运行时间很长的 Agent。
3. 怎样观察 Agent 是否陷入无效循环？参考答案
我会监控几个明显信号：同一个工具用近似参数反复调用、状态一直不变、相同错误连续出现，或者 Token 持续增加但任务没有进展。命中阈值后自动中断并告警，同时保留当前状态，方便人工检查或继续。
4. 为什么不能保存全部 Prompt 方便调试？参考答案
因为完整 Prompt 里可能包含用户隐私、内部文档、工具结果甚至敏感字段，全部长期保存会扩大泄漏范围。应该根据数据等级决定是否脱敏、抽样和保留多久；高敏感场景可以只保存哈希、统计信息和受控的数据引用。
# 接下来学什么
下一篇学习 Agent 生产化，重点理解怎样把质量与追踪能力放进真实流量、并发、预算、发布和故障恢复流程中。