章末自测

题目 1:Run、Step、Trace、普通日志分别解决什么问题?

请从任务生命周期、过程索引、详细证据和服务运维四个角度解释。

Run 表示一次完整 Agent 任务的生命周期,例如 READY、RUNNING、COMPLETED、FAILED;Step 表示 Run 内的过程序号和阶段;Trace 保存每一步更细的 Prompt、模型可见输出、Tool、参数、结果、Token 和延迟等证据;普通日志则更适合服务启动、HTTP 错误、数据库连接等运维事件。四者有关联,但职责不同。

题目 2:一条完整 Agent Trace 至少应该记录哪些字段?

请说明 Prompt、LLM Response、Tool、Arguments、Tool Result、Latency、Token、Status 各自为什么重要。

Prompt 说明模型当时看到了什么;LLM Response 说明模型返回了什么可见决策;Tool 与 Arguments 说明系统实际准备执行什么;Tool Result 是环境 Observation;Latency 说明慢在哪;Token 用于成本和 Context 分析;Status 说明步骤是完成、失败、阻塞还是等待审批。把这些字段串在同一个 Step 中,才能完整复盘行为链。

题目 3:编程实现——定义一个最小 TraceStep

要求至少包含 run_id、step_no、tool_name、tool_arguments、latency_ms、status。

from __future__ import annotations
from dataclasses import dataclass
from typing import Any, Optional


@dataclass
class TraceStep:
    run_id: str
    step_no: int
    tool_name: Optional[str]
    tool_arguments: Optional[dict[str, Any]]
    latency_ms: float
    status: str


if __name__ == "__main__":
    item = TraceStep(
        run_id="run_demo",
        step_no=3,
        tool_name="read_file",
        tool_arguments={
            "path": "app.py"
        },
        latency_ms=18.6,
        status="completed",
    )

    print(item)
#真实项目可以继续增加 prompt、llm_response、tool_result、tokens 和 error 等字段。

题目 4:为什么 Trace 中最好记录“最终 ContextBuilder 输出”,而不仅是用户原始问题?

请结合 AGENTS.md 和 Skill 漏加载的案例说明。

模型真正看到的输入通常不只是用户一句话,而是 System Prompt、项目规则、Skills、Memory、Conversation、Reminder 等组合。如果只保存用户问题,就无法判断某次违规修改是模型不遵守规则,还是 ContextBuilder 根本没把 AGENTS.md 放进去。记录最终可见上下文能帮助工程师区分 Prompt 构建问题与模型决策问题。

题目 5:为什么 Tool Result 需要截断、脱敏或使用 Artifact 引用?

请从 Context、存储成本、隐私与安全四个方面说明。

Tool Result 可能包含巨量日志、SQL 数据、文件内容甚至凭据。原样永久保存会快速增加数据库和存储压力,也可能把用户隐私或秘密复制到 Trace。更合理的是保存结构化摘要、长度、样本、错误信息和 Artifact 指针,对敏感字段脱敏,对超大内容截断。Trace 要保留证据,但不能成为新的数据泄露源。

题目 6:如何用 Trace 判断一个错误是 Tool 问题还是模型解释问题?

请用收入下降案例说明。

先看 Tool Arguments 是否符合任务,再看 Tool Result 是否已经包含正确事实。如果 SQL 查询字段、时间范围和结果都正确,例如请求量基本稳定、eCPM 明显下降,而下一步 LLM Response 却总结“请求量下降是主因”,说明错误发生在模型解释层;如果 Tool Result 本身就查错日期或指标,则应先修 Tool 或参数生成逻辑。Trace 可以避免修错层。

题目 7:为什么 Tracing 是后续 AgentOps 和 Evaluation 的基础?

请至少给出五个后续可以从 Trace 计算的指标。

Trace 已经记录每个 Step 的 Token、Latency、Tool、Status 和 Error,因此可以进一步计算平均 Steps、输入输出 Token、总成本、平均 LLM 延迟、Tool 调用次数、Tool Error Rate、Retry Rate、重复调用率、成功 Run 的平均耗时、失败原因分布等。Evaluation 还可以比较不同 Prompt、Skill、模型版本的行为差异,因此 Trace 是后续 AgentOps 的原始数据层。

题目 8:为什么 step_no 不能作为 Trace Event 的唯一键?

同一个 Main Loop Step 可能包含 LLM started/completed、多个 Middleware 决策、多个并行 Tool started/completed 和 Approval 事件,它们拥有相同 step_no。应使用 event_id 唯一标识、sequence 排序,再用 llm_call_id、tool_call_id 和 parent_event_id 还原关系。

题目 9:一次 Provider 调用抛出 TimeoutError,完整 Trace 至少应留下哪些事件?

先有 Run running 和 llm.started,再有携带异常类型、耗时与 llm_call_id 的 llm.failed,最后有 Run failed 或对应的可恢复状态。如果只有最外层 FAILED,就无法判断请求是否真正发出、等待了多久,也无法区分 Provider 超时和 Tool 失败。

题目 10:如何避免 Trace 自己成为敏感信息泄露源?

在落盘前按字段标注和规则脱敏,截断大文本,把完整大结果放入受控 Artifact;同时实施租户与项目所有权校验、最小查看权限、加密、访问审计和保留删除策略。正则只能提供基础防线,不能替代数据分类与权限治理。

题目 11:两个 Tool 并行执行时,成本指标和耗时指标应如何计算?

模型 Token 只归属产生这批 Tool Call 的一次 LLM Event,不能复制到每条 Tool Event。Tool 调用次数按不同 tool_call_id 统计;资源工作量可以看各 Tool Latency 之和,端到端耗时则看从 Step 开始到全部结果就绪的墙钟时间,通常接近关键路径而不是简单求和。

进一步阅读

在进入资料列表前,我们先把课程 Trace 和 OpenTelemetry 对上一次。两者不是替代关系:TraceRecorder 负责保存课程运行时的完整业务事实,OpenTelemetry 负责把跨服务观测字段送进统一 Collector。直接让核心循环依赖某个 OTel SDK,会把教学模型、采样配置和部署环境绑在一起;更稳的是先经过一个薄映射层。

配套项目中的 trace_step_to_otel() 会把 Run、LLM 与 Tool 事件分别映射为 invoke_agent、chat 和 execute_tool,并保留 event、parent、llm_call 和 tool_call 关系:

from agent_harness.observability.otel import trace_to_otel


spans = trace_to_otel(
    trace.list_steps(run_id)
)

for span in spans:
    print(
        span.name,
        span.parent_event_id,
        span.attributes,
    )

映射层默认不复制 Prompt、Tool Arguments 和 Tool Result。原因很实际:这些字段既可能很大,也很可能带有代码、业务数据或凭据。Token、模型名、Tool 名、调用 ID 和低基数错误类型足够支持大多数聚合;确实需要内容观测时,也应经过显式开关、脱敏、长度限制和访问控制。

OpenTelemetry 的 GenAI Semantic Conventions 仍在独立仓库持续演进,所以这里提供的是可测试的 Span DTO,不冒充完整 OTLP Exporter。接入 SDK 时,只需要把 DTO 转成真实 Span;课程内部 Trace 格式和业务证据不必跟着 Collector 版本变化。可对照 OpenTelemetry GenAI Agent Spans 与 GenAI 属性注册表 查看当前字段定义。

  • Distributed Tracing:理解 Trace、Span、Parent/Child 关系。
  • OpenTelemetry Concepts:了解标准化 Trace / Metric / Log 思想。
  • Structured Logging:日志为什么也应该包含 run_id、step_id。
  • Agent Observability:模型、Tool、Context、Policy 多层可观测。
  • Redaction / Data Governance:Trace 中敏感数据的脱敏和保留策略。
  • Latency Profiling:区分 LLM Latency、Tool Latency、Queue Time。
  • Token Accounting:下一节会进一步统计 Token、成本与耗时。
  • Agent Evaluation:Trace 如何成为 Benchmark 的执行证据。

术语表

  • Tracing:对一次 Agent Run 的执行过程进行结构化记录,使每个 Step 的输入、输出、Tool、延迟、Token 与状态都可追踪。
  • TraceStep:Trace 中最基本的执行单元,通常对应 Agent Main Loop 的一次决策或动作阶段。
  • Run Trace:以 run_id 为根,把一次完整任务中的所有 Step 串起来形成的执行轨迹。
  • LLM Event:一次模型调用相关事件,包括输入消息、可见输出、Token、Latency 和状态。
  • Tool Event:一次工具执行相关事件,包括 Tool 名、Arguments、Result、Latency、Status 与 Error。
  • Event ID:每条 Trace Event 的唯一标识,不能用可能重复的 step_no 代替。
  • Sequence:同一 Run 内用于稳定排序的递增序号,服务重启或并发写入时仍需保持一致。
  • Correlation ID:把同一次逻辑调用的 started、completed、failed 和重试关联起来的 ID,例如 llm_call_id、tool_call_id。
  • Parent Event / Span:表示事件或 Span 的直接上游,用来构建 Run、SubAgent、LLM 与 Tool 的父子树。
  • Redaction:在 Trace 落盘前移除或替换凭据、隐私和敏感字段。
  • Trace Sampling:按策略选择保留哪些 Run 的详细轨迹;尾部采样可以在知道最终状态后优先保留异常 Run。
  • Latency:一次模型调用、Tool 调用或完整 Step 所花费的时间,是性能分析的重要指标。
  • Token Usage:模型调用消耗的 input_tokens、output_tokens 与 total_tokens,是成本、Context 和效率分析基础。
  • Observability:系统通过 Trace、Metric、Log 等数据,让内部运行状态可以被理解、定位和评估的能力。

本章总结

回头看这张知识回顾图,可以把整章压缩成一条思路:Trace 记录发生了什么;Run / Step / Events 提供结构;Recorder 负责跨组件收集;持久化让证据留得下来;最后才能逐层定位故障。

图片[1]-章末自测-大赛人网

做到这里,Trace 才不只是“多几条日志”,而是能支撑后续排查、评估与审计的运行证据。

这一节,我们终于开始解决一个复杂 Agent 系统必然会遇到的问题,出问题以后,到底发生了什么?

Agent 越复杂:

Planner
SubAgent
Skills
AGENTS.md
Middleware
Approval
Tool
Memory

参与的组件越多。

如果只看到:

Run = FAILED

几乎没有调试价值。

所以我们引入,Tracing。

最终希望形成:

Run
 ├─ Step 01
 ├─ Step 02
 ├─ Step 03
 └─ Step 04

每一个 Step 都能够回答:

模型看到了什么?
模型返回了什么可见决策?
调用哪个 Tool?
Arguments 是什么?
Tool Result 是什么?
耗时多久?
用了多少 Token?
最终状态是什么?

这一章最重要的第一条原则是,Run 是任务,Step 是过程,Trace 是证据。

普通日志可以告诉你:

接口 500
数据库连接失败

但 Trace 能告诉你:

第 7 步为什么选了这个 Tool
为什么传这个参数
为什么下一步又重试

第二条原则是,Trace 要结构化。

只有字段化记录:

run_id
step_no
tool_name
latency_ms
input_tokens
status

后面才能统计:

平均 Steps
Token
成本
Tool Error Rate
Retry Rate
Latency

第三条原则是,Trace 要记录最终可见输入和输出,而不是只记录用户问题。

因为模型真正看到的是:

System Prompt
AGENTS.md
Skills
Memory
Conversation
Reminder
Tool Results

如果这些没记录,后面就无法判断:

是模型没遵守规则
还是 ContextBuilder 根本没加载规则。

第四条原则是,Trace 不应该依赖隐藏推理。

工程系统真正需要保存的是:

模型收到的可见输入
模型返回给 Harness 的可见输出
结构化 Tool Call
Arguments
Observation
状态变化

这些已经足够支持绝大多数复盘和评估。

第五条原则是,失败 Step 和成功 Step 都要记录。

很多错误不是发生在最后一刻。

而是前面某个看似成功的动作:

成功读了错误文件
成功执行了错误 SQL
成功修改了不该修改的文件

一步步积累出来的。

所以必须记录完整 Run。

我们实现了:

TraceStep
TraceRecorder
SQLiteTraceStore
PersistentTraceRecorder

把:

Prompt
LLM Response
Tool
Arguments
Tool Result
Latency
Token
Status

真正落到结构化数据中。

现在一条 Trace 还会带上:

event_id
sequence
event_type
llm_call_id
tool_call_id
parent_event_id
payload_digest

它们让同一 Step 中的模型、策略、审批和并行 Tool Event 能够准确关联。started 与 completed / failed 成对出现,取消、预算耗尽和最终答案也有 Run 终态;模型 Token 只记录一次,不会复制到每条 Tool Event。

记录边界同样重要。Recorder 在保存时深拷贝可变对象,先脱敏和截断,再写入 SQLite;大结果使用 Artifact 引用。生产环境还要继续补租户隔离、加密、访问审计、保留删除和按 Run 采样,因为 Trace 本身就是一份高敏感度的执行证据。

并且通过 Coding Agent 和 Data Analysis Agent 两个案例,看到 Trace 最重要的价值,它能告诉你错在哪一层。

可能是:

Context Error
LLM Decision Error
Argument Error
Tool Error
Policy Error
Interpretation Error
Orchestration Error

这比一句:

“Agent 做错了。”

有价值得多。

从这一章开始,我们终于拥有了,可复盘的 Agent。

下一节,我们会直接利用 Trace 中已经记录的:

input_tokens
output_tokens
latency
tool_calls
steps

继续做,Token、成本与耗时监控。

也就是说,下一节我们会开始回答:

一次 Agent 任务到底花了多少 Token?
调用了多少次模型?
调用了多少次 Tool?
跑了多久?
平均每一步多慢?

这就是 AgentOps 真正开始落地的地方。

© 版权声明
THE END
喜欢就支持一下吧
点赞5 分享
评论 抢沙发
头像-大赛人网
欢迎您留下宝贵的见解!
提交
头像-大赛人网

昵称

取消
昵称

    请登录后查看评论内容