小节二:一条 Trace 到底应该记录哪些字段——Prompt、Response、Tool、Latency、Token 一个都不能乱

一条 Step 里的信息不少,如果只看一张长字段表,很容易把输入、输出、动作和指标混在一起。下面把它们围绕同一个 TraceStep 摆开,阅读时可以先认清各组字段的作用。

图片[1]-小节二:一条 Trace 到底应该记录哪些字段——Prompt、Response、Tool、Latency、Token 一个都不能乱-大赛人网

尤其要区分“工具请求”与“工具返回”,以及“Token 为零”和“Provider 没有提供 usage”。字段完整不意味着每项都要原样存储;Prompt、Arguments 等内容还需要遵守后面讲的脱敏边界。

一条 Trace 的核心字段可以归纳为:

Step
Prompt
LLM Response
Tool
Arguments
Tool Result
Latency
Token
Status

我们逐个讲。

Step

例如:

step_no = 7

用于顺序复盘。

最好同时有:

step_id

例如:

step_7f3a

方便其他事件关联。

这里要多走一步:step_no 只是 Main Loop 的轮次,不是事件主键。模型在 Step 7 一次返回两个 Tool Call 时,我们至少会得到一条 LLM Event、两条 Tool Event,前面还可能有 Middleware Event。它们的 step_no 都是 7,所以每条事件还需要唯一 event_id,并用单调递增的 sequence 保证同一 Run 内的展示顺序。

关联关系不要靠“相邻两行看起来像一组”。一次模型请求分配 llm_call_id,每个工具请求保留 Provider 给出的 tool_call_id,子事件通过 parent_event_id 指向来源事件。这样即使两个工具并行完成、返回顺序改变,我们仍能准确知道哪个结果属于哪个请求。

Prompt

这里的 Prompt 不是只有用户一句话。

而是:

ContextBuilder 最终送给模型的输入。

可能包括:

System Prompt
AGENTS.md
Skills
Working Memory
Conversation
Tool Results
Current Reminder
Current Task

如果不记录最终输入,后面很难解释,模型为什么会输出这个动作。

但需要注意敏感信息

Prompt 可能包含:

用户隐私
Token
凭据
敏感日志

所以生产系统通常要:

脱敏
截断
分级保存

不能“为了 Trace”把所有秘密永久存下来。

LLM Response

这里建议记录:

模型实际返回给 Harness 的可见输出

例如:

final answer
tool_call
structured output

不要把 Trace 设计成“记录模型不可见的隐藏推理过程”。

工程上真正需要的是:

可观察决策结果

比如:

{
  "type": "tool_call",
  "name": "read_file",
  "arguments": {
    "path": "app.py"
  }
}

这已经足够复盘行为。

Tool

例如:

read_file
run_shell
query_sql

Arguments

例如:

{
  "path": "app.py"
}

这非常关键。

因为 Tool 名没错,不代表参数没错。

很多 Agent Bug 就是:

Tool 选对了
Arguments 选错了

Tool Result

记录:

Tool Observation

但也要考虑:

截断
脱敏
摘要

比如一个 SQL 返回 10 万行。

不应该全部塞 Trace 正文。

可以存:

row_count
schema
sample
artifact pointer

Latency

至少:

llm_latency_ms
tool_latency_ms
step_latency_ms

后面才知道:

慢在哪。

计时也要分清两类时钟。time.perf_counter() 适合计算本进程耗时,不受系统时间回拨影响;UTC 时间戳适合跨服务对齐事件。并行 Tool 的端到端耗时接近关键路径,不是所有 Tool Latency 的简单相加。把二者混用,最后很容易得到一个比用户实际等待时间还长几倍的“总耗时”。

Token

记录:

input_tokens
output_tokens
total_tokens

这是下一章成本监控的直接基础。

Status

例如:

started
completed
failed
blocked
waiting_approval

不要只有:

success = true/false

因为 Agent 中间状态很多。

最好成对记录 started 与 completed / failed。如果进程在模型请求中途崩溃,只保存完成事件会让这次调用像从未发生;有 started 但迟迟没有终态,我们才能识别悬挂、超时或 Worker 丢失。Run 自身也要留下 running、waiting_approval、cancelled、budget_exceeded 和最终状态,而不是只追踪成功的工具步骤。

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

昵称

取消
昵称

    请登录后查看评论内容