前面几部分,我们已经把一个 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 每一步-大赛人网](https://www.dsrw.com/wp-content/uploads/2026/11/image-1745.png)
这里的顺序有一个实际含义:只有先定义好记录对象和字段,后面的持久化、问题定位才有可靠证据可用。读到具体实现时,也可以回到这张图确认当前这一环在整条链路中的位置。
![图片[2]-Tracing:完整记录 Agent 每一步-大赛人网](https://www.dsrw.com/wp-content/uploads/2026/11/image-1746.png)
Tracing 在 Harness 中的位置:
![图片[3]-Tracing:完整记录 Agent 每一步-大赛人网](https://www.dsrw.com/wp-content/uploads/2026/11/image-1747.png)
















请登录后查看评论内容