Tracing:完整记录 Agent 每一步

前面几部分,我们已经把一个 Agent Harness 从“会运行”逐渐做成了一个相对完整的工程系统。

我们现在已经有:

Main Loop
State
Tool Calling
Tool Registry
Tool Schema
Error Recovery
Parallel Tool Calling
ContextBuilder
Working Memory
Session
Context Compaction
Long-term Memory
Flask API
Run
Streaming
SQLite
RunGuard
System Reminder
Middleware
Human in the Loop
Workspace / Sandbox
Planner
SubAgent
Skills
AGENTS.md

如果只看能力,这个 Agent 已经很强。

但能力越多,调试越难。

比如用户说,“我让 Agent 修一个 Bug,为什么最后把错误文件改了?”

你如果只保存:

最终答案

那基本没法回答。

又比如一个 Data Analysis Agent 最终结论错了。

你想知道:

到底是 SQL 查错了?
还是模型理解错指标?
还是 Tool Result 被截断了?
还是 Context 里旧信息覆盖了新结果?
还是 SubAgent 汇总时丢了关键结论?

如果没有 Trace,只能靠猜。

所以从这一节开始,我们正式进入,Observability 与 AgentOps。

这一部分第一个核心就是:

Tracing

我们要把一次 Run 完整拆开。

最终形成:

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

每一步记录:

Step
Prompt
LLM Response
Tool
Arguments
Tool Result
Latency
Token
Status

这样当任务失败时,我们不只是看到:

FAILED

而是能完整回答:

第几步失败?
模型当时看到了什么?
模型输出了什么可见动作?
调用了哪个 Tool?
传了什么参数?
Tool 返回什么?
耗时多久?
用了多少 Token?
失败以后有没有重试?

这就是 Trace 的价值。

开场引入

先看一个非常真实的 Coding Agent 失败案例。

用户说,“修复 Flask 项目启动时报的 ImportError,不能修改 tests/,也不要新增依赖。”

最终 Run 状态:

FAILED

你只知道,Agent 跑了太久。

但你不知道为什么。

如果有 Trace,你可能看到:

Step 01
Prompt:
用户目标 + AGENTS.md + python-debug Skill

LLM Response:
读取 app.py

Tool:
read_file

Arguments:
{"path": "app.py"}

Tool Result:
成功

Step 02:

LLM Response:
读取 requirements.txt

Step 03:

LLM Response:
运行 pytest -q

Step 04:

Tool Result:
ImportError: cannot import name settings

Step 05:

LLM Response:
再次读取 app.py

Step 06:

再次读取 requirements.txt

Step 07:

再次 pytest

一直到:

Step 30

你一眼就能看出来,这是重复调用 + 无进展循环。

再比如 Data Analysis Agent。

最终结论:

收入下降来自请求量下降

但用户反馈,“不对,请求量明明没变。”

Trace 一看:

Step 04 query_sql
Tool Result:
request -1%
ecpm -35%

说明 SQL 返回的数据其实已经告诉模型:

请求量基本稳定
eCPM 明显下降

但 Step 05 的模型输出却说:

请求量是主要原因。

这时我们可以明确,问题不在 Tool,不在 SQL,而在模型解释。

这就是为什么 Trace 不是普通 Debug Log。

它是,Agent 每一步决策链的结构化证据。

知识地图

先把这一章要走的路铺开。下面这张原理图按照“为什么需要 Trace → 记录哪些字段 → 数据结构 → Recorder → 持久化 → 排查 → 案例”的顺序,把后面分散的知识点串在了一起。

图片[1]-Tracing:完整记录 Agent 每一步-大赛人网

这里的顺序有一个实际含义:只有先定义好记录对象和字段,后面的持久化、问题定位才有可靠证据可用。读到具体实现时,也可以回到这张图确认当前这一环在整条链路中的位置。

图片[2]-Tracing:完整记录 Agent 每一步-大赛人网

Tracing 在 Harness 中的位置:

图片[3]-Tracing:完整记录 Agent 每一步-大赛人网
© 版权声明
THE END
喜欢就支持一下吧
点赞14 分享
评论 抢沙发
头像-大赛人网
欢迎您留下宝贵的见解!
提交
头像-大赛人网

昵称

取消
昵称

    请登录后查看评论内容