一条 Step 里的信息不少,如果只看一张长字段表,很容易把输入、输出、动作和指标混在一起。下面把它们围绕同一个 TraceStep 摆开,阅读时可以先认清各组字段的作用。
![图片[1]-小节二:一条 Trace 到底应该记录哪些字段——Prompt、Response、Tool、Latency、Token 一个都不能乱-大赛人网](https://www.dsrw.com/wp-content/uploads/2026/11/image-1749.png)
尤其要区分“工具请求”与“工具返回”,以及“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 和最终状态,而不是只追踪成功的工具步骤。
















请登录后查看评论内容