为什么 Agent 需要新的可观测性
传统软件的可观测性通常围绕请求链路展开：HTTP 状态码、接口耗时、数据库查询、错误日志以及 CPU、内存、队列长度等资源指标。对确定性系统来说，这些指标足以定位绝大部分问题。
AI Agent 不一样。一个 Agent 可能先理解用户意图，再检索文档、调用工具、读取记忆、重写计划、再次调用模型，最后生成答案。一次请求是否成功，不只取决于接口是否返回 200，还取决于它是否拿到了正确证据、是否调用了正确工具、是否把工具结果解释正确、是否按业务规则行动。
因此，生产级 Agent 的可观测性不能只停留在日志和延迟，而要能回答一个核心问题：这个答案是怎么来的，证据在哪里，工具为什么被调用，失败发生在哪一步。
一句话理解 Agent Observability
Agent Observability 可以概括为：把 Agent 的每一次推理、检索、工具调用、记忆读写、评测和最终输出，记录成可追踪的执行链路。
User Intent → Agent Plan → Retrieval Span → Tool Call Span
→ Model Call Span → Memory Span → Evaluation Span
→ Final Answer → Audit Trail它的目标不是收集更多日志，而是让每个关键决策都能被解释、复现、评估和回归测试。
核心知识结构
可以把 Agent 可观测性拆成 6 个模块来理解。
1. Trace 与 Span
Trace 表示一次完整任务链路，span 表示链路中的一个步骤。一个 Agent trace 通常包含 model span、retriever span、tool span、memory span 和 evaluation span。OpenTelemetry 将自身定位为 vendor-neutral 的开源可观测框架，提供 traces、metrics、logs 与上下文传播能力，GenAI semantic conventions 已覆盖 input/output messages、retrieval documents、tool definitions、tool call arguments/results、evaluation score、cache tokens 等字段——这意味着行业正在把 LLM 调用、工具调用和评测结果纳入统一的 telemetry schema。
2. Prompt 与模型调用
模型调用不应只记录耗时，还要记录以下维度：
| 字段 | 说明 |
|---|---|
| prompt_version | 追踪 Prompt 变更对行为的影响 |
| model | 模型名称与版本 |
| temperature / top_p | 采样参数 |
| input_tokens / output_tokens / cache_tokens | Token 用量与缓存命中率 |
| structured_output_schema | 结构化输出约束 |
| finish_reason | 终止原因（正常结束、长度截断、内容过滤等） |
| error | 模型调用层面的错误信息 |
3. Retrieval Evidence
RAG 失败常常不是模型问题，而是证据问题。Retriever span 应记录 query、document id、score、rank、metadata、source 以及该文档是否进入最终上下文。这样当最终答案不可靠时，团队可以直接定位到检索环节。
4. Tool Call Provenance
工具调用需要记录 tool name、tool definition version、arguments、result、error、retry、approval status 和 side effect。只有完整记录工具调用的来龙去脉，才能判断工具是否被误用，参数是否来自用户授权，结果是正确解读还是被模型曲解。
5. Memory Lineage
长任务 Agent 会读写 memory。如果 memory 被污染，后续步骤会持续受影响。因此要记录 memory 来源、写入原因、读取位置和影响范围，形成完整的记忆血缘。
6. Online Evaluation
上线后的 Agent 需要持续评测。Trace 应能附加 LLM-as-a-Judge 分数、人工标签、安全检查、格式检查和业务成功指标。2026 年《From Agent Traces to Trust》综述指出，final-answer accuracy 不能解释输出如何产生、证据如何支撑结论、工具调用是否合理、memory 如何影响后续决策，因此需要 evidence tracing 与 execution provenance。
为什么传统日志不够
传统日志通常能告诉你：某个接口何时被调用，返回了什么状态码，耗时多久。
但 Agent 失败时，你更需要回答这些问题：
- 用户真实意图是什么？
- Agent 是否误判了任务类型？
- 检索出来的文档是否相关？
- 工具是否该被调用？参数是否来自用户授权？
- 工具返回是否被正确理解？
- 最终答案中的关键结论是否有证据支持？
- 当前失败是否和某个 prompt version 或模型版本有关？
如果没有结构化 trace，这些问题只能靠人工翻对话、查日志、猜测模型行为，效率极低。2026 年 AgentTrace 论文提出从 operational、cognitive、contextual 三个层面捕获 Agent 结构化日志，正是为了解决这一难题。
推荐流程：从 Trace 到可回归样本
一个生产级 Agent 可观测流程可以这样设计：
- 用户请求进入 Agent runtime，创建
trace_id和session_id - 每次模型调用生成 model span
- 每次检索生成 retrieval span，记录候选文档与最终上下文
- 每次工具调用生成 tool span，记录参数、结果和副作用
- 每次 memory 读写生成 memory span，记录来源和用途
- 最终回答生成 answer span，关联证据和工具结果
- 在线 evaluator 对 trace 打分或贴标签
- 失败 trace 进入 annotation queue 或人工复核
- 高价值失败样本进入 regression dataset
- 新 prompt、新模型、新工具上线前必须跑回归
这条链路的关键在于闭环：trace 不是为了事后观赏，而是为了进入评测、修复和发布流程。
Trace Schema 应该记录什么
一个简化的 Agent trace schema 可以这样设计：
trace:
trace_id: tr_20260625_001
session_id: sess_9182
user_intent: "查询订单退款状态"
agent_name: customer_support_agent
agent_version: "2026-06-25"
prompt_version: refund_v7
model_calls:
- model: strong-reasoning-model
input_tokens: 8200
output_tokens: 640
latency_ms: 1800
temperature: 0.2
retrieval_spans:
- query: "refund policy order 9182"
documents:
- doc_id: refund_policy_v3
rank: 1
score: 0.91
used_in_answer: true
tool_spans:
- tool_name: get_order_refund_status
tool_version: v2
arguments:
order_id: "9182"
result_status: success
side_effect: false
evaluations:
- name: faithfulness
label: pass
score: 0.92
- name: tool_relevance
label: pass
score: 1.0这个结构的重点不是字段多，而是能把用户意图、证据、工具和最终答案连接起来，形成一条可审计的决策链路。
关键指标：不要只看平均延迟
Agent 生产监控至少要看 8 类指标：
| 指标类别 | 关注点 |
|---|---|
| Task Success Rate | 任务是否真正完成，而不只是模型是否生成了回答 |
| Tool Call Accuracy | 是否调用了正确工具，参数是否正确，是否存在无关调用或漏调用 |
| Retrieval Quality | Context Precision、Context Recall、document rank、citation coverage、evidence usage |
| Evaluation Score | helpfulness、faithfulness、safety、format compliance 的持续记录 |
| Cost & Token Usage | 按 workflow、tool、model、tenant、prompt version 拆分 token 与成本 |
| Latency Breakdown | 拆分 retrieval latency、tool latency、model latency、queue time、evaluation latency |
| Failure Mode Distribution | 检索失败、工具失败、参数失败、模型幻觉、权限失败、格式失败、安全失败 |
| Regression Delta | 每次模型、prompt、tool schema、retriever 参数变化后的基线与质量对比 |
隐私与成本：可观测性也需要边界
Agent trace 很有价值，但也很敏感。它可能包含用户输入、工具返回、私有文档、订单数据、代码片段、业务规则和个人信息。生产环境应做到：
- 敏感字段脱敏
- 高风险工具结果默认摘要化
- 按租户隔离 trace
- 限制 trace 查询权限
- 设置数据保留周期
- 对导出和分享做审计
- 对 LLM evaluator 输入做隐私过滤
此外，不是所有 trace 都必须完整评测。高流量系统可以采用分层策略：
- 100% 采集基础指标
- 抽样采集完整 prompt-response 对
- 高风险任务全量保留关键 trace
- 对 10%–20% 流量运行在线 evaluator
- 失败样本进入人工复核队列
生产落地 Checklist
上线前建议逐项检查：
- 是否为每次 Agent 任务生成
trace_id和session_id - 是否拆分 model、retrieval、tool、memory、evaluation spans
- 是否记录
prompt_version、model、参数、tokens、latency 和错误 - 是否记录检索文档的 id、score、rank、source 和是否被使用
- 是否记录工具 definition version、arguments、result、retry 和 side effect
- 是否把最终答案中的关键结论关联到证据或工具结果
- 是否有在线 evaluator 和人工复核队列
- 是否把失败 trace 转成 regression dataset
- 是否对 prompt、模型、工具、retriever 变更跑回归测试
- 是否有 PII 脱敏、权限控制和数据保留策略
- 是否按 workflow、tenant、model、prompt version 拆分成本和质量指标
- 是否能从 dashboard drill down 到单条失败 trace
结论
Agent Observability 的本质，是把不可预测的 Agent 行为变成可追踪、可解释、可回归的工程对象：
- Trace 记录任务链路
- Span 记录关键步骤
- Evidence 解释答案依据
- Tool provenance 解释行动来源
- Evaluation 量化质量
- Regression dataset 防止修复后再次失败
对工程团队来说，最实用的原则是：不要等用户说”这个 Agent 不靠谱”才去翻日志。应该让每一次失败都能被定位到具体环节，让每一次修复都能沉淀为评测样本。只有当 Agent 的证据、工具、记忆和输出都可观测时，它才能从 Demo 走向可运营的生产系统。