跳到主要内容
← 返回AI Agent Engineering|12 周从 Demo 到真实 Agent 系统

AI Agent Engineering · Week 09

09-03|Observability:Agent 到底发生了什么

用 Log、Trace 与 Span 重建一次 Agent 运行,定位模型、Tool、Workflow、审批、延迟与成本问题。

Observability · Tracing · Debugging

Eval 与 Observability 回答不同问题

Eval 判断系统是否达到了预期行为。Observability 重建系统怎样得到这个结果。某条用例失败后,需要知道模型选了哪个 Tool、参数是什么、Tool 返回什么、Workflow 进入哪个 State、是否等待审批,以及时间和成本花在哪里。

一次端到端 Trace

User Input
↓
Model Span
↓ proposal
Tool Call → Tool Result
↓
Workflow / State / Approval
↓
Model Span → Final Output
↓
Outcome + Eval Case ID

图 1|Trace 表示一次完整任务;Span 表示其中一个有开始和结束的操作。

Log、Trace、Span

  • Log:某个时刻发生的结构化事件,如 tool_timeout。
  • Trace:一次端到端请求或业务任务的完整因果链。
  • Span:Trace 中的一段操作,如模型调用、检索、Tool 执行或审批等待。

每个 Span 至少保留类型、开始/结束时间、状态、父子关系、错误分类与安全 metadata。业务关联可使用 requestId、ticketId、refundId、systemVersion 和 evalCaseId;这些 ID 不应直接包含敏感信息。

Trace: support_request_42
Span 1 intent model · 420 ms · 610 tokens
Span 2 order tool · 180 ms · success
Span 3 policy retrieval · 95 ms · 3 chunks
Span 4 approval wait · paused 2 h
Span 5 refund mock · 230 ms · idempotent success
图 2|树形关系区分系统计算时间与人工等待时间,也能定位错误发生在哪一层。

记录足够信息,同时控制数据暴露

Trace 需要 Tool 名称、参数摘要、结果状态、Token、Cost、Latency、State Transition 和 Stop Reason。原始客户消息、订单详情、完整 Prompt 与 Tool payload 可能包含敏感数据。采用 allowlist、脱敏、分级保留与访问控制;调试价值不能成为无限记录的理由。

从失败回到原因

Unsupported Claim 上升时,先通过 evalCaseId 找到失败 Trace,再查看 Retrieval Span 是否返回了正确证据、模型是否引用了证据、输出 Guardrail 是否检测到超出证据。Observability 提供因果线索,修复后仍需 Eval 证明问题消失。

Eval

发现哪类行为失败

Trace

找到具体失败路径

Fix

修改 Prompt / Tool / RAG / Workflow

Regression

固定集重新运行

Monitor

上线后观察同类信号

图 3|Trace 帮助解释,Regression 提供修复证据;两者共同形成可靠性闭环。

Failure Lab

只记录最终回复

为什么诱人: 存储少,查看方便。

为什么失败: 看不到 Tool、检索、审批和重试路径,无法定位错误来源。

更合理设计: 用 Trace 关联关键 Span、State Transition 与 Stop Reason。

把完整 Prompt 和 Tool payload 全部写日志

为什么诱人: 调试信息最完整。

为什么失败: 客户身份、订单和企业知识被复制到新的数据系统,权限与保留范围扩大。

更合理设计: allowlist metadata、敏感字段脱敏、原文分级存储,并限制访问和保留期。

用 Trace 成功代替 Eval 通过

为什么诱人: 每个 Span 都是绿色,系统看起来健康。

为什么失败: 链路技术上成功仍可能调用错误 Tool,或生成无依据结论。

更合理设计: Trace 判断“怎么做”,Eval 判断“做得对不对”,通过 case ID 连接二者。

实践:定义 V0.9 Trace Schema

为订单查询、RAG 回答和退款审批各画一条 Trace。标明 Span、父子关系、业务关联 ID、错误分类、Latency、Token/Cost、脱敏字段和保留策略。

Acceptance Criteria

  • ☐ 一次业务任务拥有稳定 traceId,并关联 systemVersion 与 caseId。
  • ☐ Model、Tool、Retrieval、Workflow 与 Approval 都有可识别 Span。
  • ☐ 错误、Latency、Token、Cost 和 Stop Reason 可查询。
  • ☐ 人工等待时间与系统执行时间能区分。
  • ☐ Trace 不默认保存完整敏感输入输出。
  • ☐ Eval 失败可以定位到具体 Trace,修复后能重新回归。

主动回忆

  1. Trace 与 Span 的关系是什么?
  2. 为什么绿色 Trace 仍可能产生错误业务结果?
  3. 哪些字段适合进入 allowlist metadata?
  4. Eval Case ID 如何帮助回归分析?

下一课把 Dataset、Metrics 与 Trace 连接成可重复 Regression Pipeline,并输出第一份 Reliability Report。

延伸阅读 / Sources

核查日期:2026-10-18。

长期有效的原理: 端到端任务应能沿因果链被重建,同时遵守数据最小化。当前实现方式: SDK exporter 与平台界面会更新,Trace Schema 应保持应用可控。