AI Agent Engineering · Week 09
09-03|Observability:Agent 到底发生了什么
用 Log、Trace 与 Span 重建一次 Agent 运行,定位模型、Tool、Workflow、审批、延迟与成本问题。
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
Log、Trace、Span
- Log:某个时刻发生的结构化事件,如
tool_timeout。 - Trace:一次端到端请求或业务任务的完整因果链。
- Span:Trace 中的一段操作,如模型调用、检索、Tool 执行或审批等待。
每个 Span 至少保留类型、开始/结束时间、状态、父子关系、错误分类与安全 metadata。业务关联可使用 requestId、ticketId、refundId、systemVersion 和 evalCaseId;这些 ID 不应直接包含敏感信息。
记录足够信息,同时控制数据暴露
Trace 需要 Tool 名称、参数摘要、结果状态、Token、Cost、Latency、State Transition 和 Stop Reason。原始客户消息、订单详情、完整 Prompt 与 Tool payload 可能包含敏感数据。采用 allowlist、脱敏、分级保留与访问控制;调试价值不能成为无限记录的理由。
从失败回到原因
Unsupported Claim 上升时,先通过 evalCaseId 找到失败 Trace,再查看 Retrieval Span 是否返回了正确证据、模型是否引用了证据、输出 Guardrail 是否检测到超出证据。Observability 提供因果线索,修复后仍需 Eval 证明问题消失。
发现哪类行为失败
找到具体失败路径
修改 Prompt / Tool / RAG / Workflow
固定集重新运行
上线后观察同类信号
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,修复后能重新回归。
主动回忆
- Trace 与 Span 的关系是什么?
- 为什么绿色 Trace 仍可能产生错误业务结果?
- 哪些字段适合进入 allowlist metadata?
- Eval Case ID 如何帮助回归分析?
下一课把 Dataset、Metrics 与 Trace 连接成可重复 Regression Pipeline,并输出第一份 Reliability Report。
延伸阅读 / Sources
核查日期:2026-10-18。
- OpenAI Agents SDK:Tracing。用于核对当前 Trace、Span 与敏感数据配置。
- OpenAI Agents SDK:Tracing reference。用于核对 Trace processor 与导出边界。
- OpenTelemetry:Traces。用于核对 Trace、Span 与父子关系的通用概念。
长期有效的原理: 端到端任务应能沿因果链被重建,同时遵守数据最小化。当前实现方式: SDK exporter 与平台界面会更新,Trace Schema 应保持应用可控。