Tool Trace与离线回归：用四张证据表守护本地Agent稳定性

上个月我把一个本地Agent从“能跑通demo”改到“敢拿它做回归”，核心变化只有一件事：给每轮运行都留下一套完整的Tool Trace。所谓Tool Trace，就是Agent在运行过程中调用了哪些工具、传了什么参数、拿到什么结果、按什么顺序调用；而离线回归，则是把历史运行时留下的trace回放成测试用例，改完代码后重新跑一遍做对比。我把这套机制收敛成了4张证据表，过程比我预想的简单，而且效果出奇稳定。如果你也被“Agent改一处、崩一片”折磨过，这篇文章应该能给你一条可以照抄的本地落地路径。

1. 什么信号让我决定给Agent加Trace

1.1 demo能跑和能维护是两回事

本地Agent项目做到一定阶段，你会明显感觉到一个分水岭：demo阶段，只要模型能把工具调用对，大家就很开心；到了“要长期维护、要迭代功能”的阶段，最痛苦的问题不再是“模型能不能调工具”，而是“上一次它到底怎么调的”。

我印象很深的一次事故：某个工具的参数格式从city_name改成了city_id，我以为只改了一处调用点，结果跑线上场景时，Agent在好几个分支里还在用旧参数。因为工具名没变，日志里只能看到“调用成功”，完全看不出来参数已经悄悄错了。这件事之后我意识到，本地Agent缺的不是更聪明的模型，而是一套能记录“证据”的机制——每次工具调用、每个参数、每个返回结果，都得存下来，而且要在代码版本之间可对比。

1.2 从“看日志”到“留证据”的思路转变

大多数Agent框架和开源项目里，日志都能打印出prompt和response，工具调用的细节往往被折叠起来，或者只留下一行“Action: search_weather”这种级别的内容。真正排查问题时，你会发现自己需要的是更细颗粒度的证据：

• 模型回传的tool_call里，arguments到底带的是什么？
• 这个arguments是用户原话抽取的，还是上一个工具返回后二次加工的？
• 工具的原始返回长什么样？有没有被后续代码截断或改写？
• 多轮对话里，工具结果是在第几轮被消费的？

这些问题，普通日志回答不了，但一张结构化的trace表可以。我后来把所有运行数据按“一次运行、一组调用、一批快照”的模型落进SQLite，排查问题的速度明显上来了。

1.3 顺带解决的问题：Agent评测与回归

一旦有了结构化的trace，你会发现它不只是调试工具，还能当回归测试的输入。之前的做法是人肉点几个用例，看Agent输出是否正常；有了trace之后，我可以把历史上某次“运行良好的完整过程”当作基准，修改完代码后重新跑一遍相同输入，逐条对比工具调用序列和结果差异，不用再靠肉眼盯。

这个思路就叫离线回归：用历史证据回放代替“我猜它能行”。对初级开发者来说，它比搭完整评测平台要轻得多，4张表、几十行代码就能跑起来。

2. Tool Trace的本质：把Agent每一步都变成可回放的证据

2.1 一条够用的Trace应该包含什么

我在设计trace时给自己定了一条标准：拿到一条记录，要能回答“谁、在什么时候、以什么参数、调了什么工具、得到了什么结果、对整个运行产生了什么影响”。对应下来，至少需要这几个字段：

• run_id：一次完整运行的唯一ID，所有trace行都归它管
• seq_no：调用顺序。Agent里工具不是并行就是串行，顺序错位会直接导致排查困难
• tool_name / tool_id：实际调用的工具身份
• input_json：传给工具的原始参数，保留原始结构，不要只记格式化后的文本
• output_json：工具返回的原始结果
• status_code：成功、失败、超时、被中断，四种基本态
• latency_ms：耗时，排查性能问题时特别有用
• error_trace：异常堆栈，失败入参才可能复现

这里有个容易忽略的点：input_json后面我才补上的。最早版本只记录了一个“参数摘要”，排查时还得靠猜。后来改成完整JSON入表，虽然库大了一点，但几乎任何问题都能还原现场。

2.2 工具调用顺序与嵌套：seq_no怎么设计

单轮agentic loop里，工具调用通常是顺序执行的，直接给一个自增的seq_no就够了。但如果你做的是多Agent协作、或者一个工具内部会触发另一个工具，那就得加parent_trace_id，形成树结构。

我目前最简方案是只记录线性seq_no，嵌套场景通过parent_id关联。理由很实在：如果一开始就把trace模型做得太重，初级项目很容易陷入设计文档写不完、代码落不了地的窘境。核心原则是“先线性、后嵌套”，等真的需要表达“谁调用谁”时再加一列，而不是一上来就搞图结构。

2.3 哈希字段的价值：快速识别“变了没”

4张证据表里，我几乎每张表都带一个_hash字段，用起来之后才发现它比想象中有用得多。最常见的场景是版本对比：同一工具、同一输入，两次运行的输出hash如果不同，说明工具实现或环境发生了变化，可以直接预警。

计算hash时要用规范化后的JSON。Python里json.dumps(data, sort_keys=True, ensure_ascii=False, default=str)是一个稳定做法，否则{"city":"北京"}和{"city": "北京"}可能被算成两个hash，全是误报。哈希字段不承担“判断对不对”的职责，只负责“快速发现不一致”，语义判断留给回归比较器。

2.4 记录谁：Trace Recorder挂在哪个环节

这块实现有两条路线：一是侵入式，在工具函数入口和出口手动调用record_call；二是框架级，通过装饰器或中间件自动采集。对初级项目我推荐侵入式，理由很直接：装饰器抽象反而会带来学习成本，而且一旦框架升级，你的采集逻辑可能失效。

我给每个工具函数包了一层薄薄的wrapper，函数执行前记录输入，执行后记录输出，异常时记录堆栈。代码量很少，但可控性极强。

3. 四张证据表：表结构、字段与设计取舍

这套结构我一共落成4张表，分别是run_meta、tool_catalog、tool_trace、response_snapshot。名字不一定重要，重要的是每张表解决什么问题。

3.1 表一：run_meta，一次运行的事实表

这是整个证据链的“总纲”，一次Agent运行只对应一行。核心字段如下：

这张表最重要的作用是把“一次运行”锚定成一个可引用的对象。做离线回归时，先在这张表里选出基线run_id，再拿它去关联下面三张表。

3.2 表二：tool_catalog，工具注册表

很多项目会忽略这张表，但它其实非常关键。Agent能调哪些工具、工具的参数Schema是什么，是判断“这次调用是否合法”的基础。它本质上是工具元数据的静态快照。字段包括：

• tool_id：稳定标识，不要用函数名当主键，函数名会改
• tool_name：实际可读名称
• tool_desc：给模型看的描述，也方便人识别
• input_schema：JSON Schema，标明必填参数和类型
• is_deprecated：是否已弃用，弃用工具不会进入新回归基线

这张表的存在，让tool_trace里存的不是孤立的工具名，而是可以联表查询到“这个工具预期该收什么参数”的证据链。

3.3 表三：tool_trace，工具调用轨迹表

这张表是整个Tool Trace能力的核心。前面提过字段，这里补充几个设计细节。

• seq_no：自增序号，用来还原调用顺序。
• input_hash/output_hash：归一化后的哈希，用于快速比较。
• status_code：建议用字符串枚举，如success、error、timeout、interrupted，比数字可读性高。
• latency_ms：记录工具自身耗时，不包含模型等待时间。

CREATE TABLE tool_trace ( trace_id TEXT PRIMARY KEY, run_id TEXT NOT NULL, seq_no INTEGER NOT NULL, tool_id TEXT NOT NULL, tool_name TEXT NOT NULL, input_json TEXT NOT NULL, input_hash TEXT, output_json TEXT, output_hash TEXT, status_code TEXT NOT NULL, latency_ms INTEGER, error_trace TEXT, FOREIGN KEY (run_id) REFERENCES run_meta(run_id) );

我遇到过的典型场景是：同一个run_id下，工具A的输出被塞进工具B的输入。有了这张表，你可以沿着seq_no一步步追踪数据流转，很快看出是哪一步污染了后面的逻辑。

3.4 表四：response_snapshot，模型输出快照表

最后一张表记录的是“每一轮模型回复了什么东西”，这是和工具调用并行的一条线。Agent的本质是“思考-行动-观察”的循环，所以除了工具调用，模型自身产生的中间推理和最终回答也要留下证据。

字段包括round_index、prompt、response、response_hash、is_final。round_index对应第几轮对话，方便和tool_trace按轮次对齐。

prompt字段我建议存“实际送去模型的那段文本”，而不是存“用户原话”。因为Agent系统里，prompt是会被改写、压缩、加上下文的，只有记录真实发送的内容，才能复现“为什么模型会这么回”。存储体积会变大，但本地场景完全可接受。

3.5 为什么拆成四张表，而不是一张大宽表

初级直觉往往是“一张表存所有字段，查询方便”。我一开始也这么试过，后来发现三个问题：

1. run_meta里一次运行只有一条，却在每条工具调用上重复出现，冗余大。
2. response_snapshot和tool_trace是两个并行序列，塞进一张表很难表达“轮次”与“工具调用顺序”的关系。
3. 四张表拆开后，可以分别做生命周期治理：tool_trace可以定期清理，run_meta长期保留，tool_catalog跟随代码发布更新。

SQLite做四张表完全够用，一张宽表看着省事，后面写对比脚本、写联表查询时会非常别扭。

3.6 从SQLite到更重存储：什么时候该换

本地项目、个人项目，SQLite足够。SQLite的优势是零部署、文件即库、备份简单。如果你发现证据表超过几千万行，或者查询开始出现明显延迟，再考虑迁移到PostgreSQL或DuckDB。

我不建议一开始就上重型数据库。本地Agent最宝贵的不是数据量，而是“完整记录”的习惯。先把四张表的写入逻辑稳定下来，后面迁移只是改connection，逻辑不用动。

4. 离线回归：把过去的运行变成今天的测试集

4.1 回归要解决的核心问题

离线回归想的其实就一句话：我改了一版代码，怎么证明它没有把以前好用的流程搞坏？传统做法是准备一批测试用例，人工看输出。但Agent的输出是模型生成的，随机性大，往往得靠“工具调用是否符合预期”来判断，而不只是看文本。

有了Tool Trace之后，做法就变了：选取一个或多个表现良好的历史run_id作为基线，把它们的完整trace（工具调用序列、输入输出、最终回答）当成测试集的“标准答案”，然后在新代码上重跑相同输入，逐条比对。

这个流程能发现三类问题：

• 工具选择变了：以前调A工具，现在改成调B工具，很可能意味着意图理解逻辑受影响
• 参数变了：同个工具，city_name变成了city_id，说明上游处理逻辑变了
• 结果变了：工具返回不同，可能是脚本逻辑或外部接口变了

4.2 基线选择与快照发布

基线不能随便选。我现在的做法是：每次准备发版之前，先用固定的一批输入跑一遍，人工确认结果没问题，然后把这次运行标记为基线。标记方式可以是给run_meta加一个is_baseline字段，或者用单独一张基线表。

基线输入集不需要很大，10到30条足够。关键是覆盖面：至少包含正常路径、参数缺失路径、工具失败路径、多轮追问路径。这样回归跑完后，能看到每种路径下的变化情况。

4.3 回放比对：工具序列对齐的秘密

最朴素的比对方法是按seq_no逐行对比tool_trace。但实际运行时，新代码可能会多调用一个工具、少调用一个工具，导致seq_no整体错位。这时候需要做“序列对齐”，思路类似文本diff：

• 先按工具名粗对齐，找到相同工具的调用点
• 在一个工具出现多次时，用参数相近度辅助对齐
• 对齐后逐条比较input_hash和output_hash

Python里可以用difflib.SequenceMatcher做基础对齐，要求不高时完全够用。如果项目复杂度上来，再把trace的比较改成基于图的对齐，但初级项目没必要一步到位。

4.4 判定阈值：哪些差异该报警

并不是所有差异都需要人工介入，这是离线回归能落地的关键。我按严重程度分了三档：

文本相似度可以用简单的编辑距离或difflib，也可以接一个本地embedding模型算余弦相似度。我用于快速回归的只是一个词级别相似度阈值，够用就行。

4.5 回归报告长什么样

回归脚本最终输出一张差异清单即可，我习惯按run_id分组展示：

• 本轮回归输入“查一下北京的天气再帮我定个闹钟”
• 基线run_id = 1a2b...
• 新run_id = 9c8d...
• 对比结果：tool序列一致；tool_catalog对齐成功；两个参数变化：city_name → city_id；结论：P1，需人工确认

有这张报告，你甚至可以把它放在CI里，每次代码提交自动跑一遍基线集，有P0直接阻断。

5. 初级最小实现：30分钟跑通一版

5.1 技术选型与目录结构

我用的是最朴素的组合：Python + SQLite + 普通工具函数。没有用任何Agent框架，因为框架会引入额外的执行模型，反而干扰对Tool Trace的控制。

目录结构大概是这样：

local_agent/ ├── tools/ │ ├── weather.py │ └── alarm.py ├── recorder/ │ ├── schema.sql │ └── trace_recorder.py ├── regression/ │ ├── baseline_manager.py │ └── compare_trace.py ├── agent.py └── main.py

recorder/trace_recorder.py是核心模块，负责四张表的写入；regression/compare_trace.py负责读trace并输出差异清单。

5.2 TraceRecorder实现要点

用Python写一个最小可用的TraceRecorder并不复杂。核心代码我拆成三部分：连接管理、run生命周期管理、工具调用记录。

import json import sqlite3 import hashlib import uuid from datetime import datetime, timezone def _hash_text(text: str) -> str: return hashlib.sha256(text.encode("utf-8")).hexdigest()[:16] class TraceRecorder: def __init__(self, db_path: str): self.conn = sqlite3.connect(db_path) self.run_id = None self._seq = 0 def start_run(self, user_input: str, model_name: str, model_params: dict): self.run_id = str(uuid.uuid4()) self.conn.execute( "INSERT INTO run_meta(run_id, start_time, user_input, model_name, model_params, status) " "VALUES(?, ?, ?, ?, ?, 'running')", (self.run_id, datetime.now(timezone.utc).isoformat(), user_input, model_name, json.dumps(model_params, ensure_ascii=False, default=str)) ) self.conn.commit() def _normalize_json(self, data) -> str: return json.dumps(data, ensure_ascii=False, sort_keys=True, default=str) def record_call(self, tool_name: str, input_data: dict, output_data, status_code: str, latency_ms: int, error_trace: str = None): self._seq += 1 input_json = self._normalize_json(input_data) output_json = self._normalize_json(output_data) self.conn.execute( "INSERT INTO tool_trace(trace_id, run_id, seq_no, tool_name, input_json, " "input_hash, output_json, output_hash, status_code, latency_ms, error_trace) " "VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)", (str(uuid.uuid4()), self.run_id, self._seq, tool_name, input_json, _hash_text(input_json), output_json, _hash_text(output_json), status_code, latency_ms, error_trace) ) self.conn.commit()

代码里有个容易踩的细节：所有JSON序列化都要走同一个_normalize_json方法，否则哈希值会漂移。另外，如果工具调用是并发的，请把连接改成线程本地，或者干脆加一个锁，保证self._seq不会错乱。

5.3 回归比较器实现要点

比较器的核心逻辑是读两次run的trace，按seq做对齐后逐条比较。最小实现如下：

def load_trace(conn, run_id: str): rows = conn.execute( "SELECT seq_no, tool_name, input_json, output_json, input_hash, output_hash, status_code " "FROM tool_trace WHERE run_id = ? ORDER BY seq_no", (run_id,) ).fetchall() return rows def compare_run(conn, baseline_id: str, new_id: str): old = load_trace(conn, baseline_id) new = load_trace(conn, new_id) diffs = [] for i in range(max(len(old), len(new))): if i >= len(old): diffs.append(("extra_call", new[i][1])) continue if i >= len(new): diffs.append(("missing_call", old[i][1])) continue if old[i][1] != new[i][1]: diffs.append(("tool_changed", old[i][1], new[i][1])) continue if old[i][4] != new[i][4]: diffs.append(("input_changed", old[i][1], old[i][3], new[i][3])) continue if old[i][5] != new[i][5]: diffs.append(("output_changed", old[i][1], old[i][3], new[i][3])) return diffs

这段代码没有做复杂的序列对齐，但已经能覆盖最常见的回归场景。有对齐需求时，把上面load_trace后的列表作为参数传给difflib.SequenceMatcher即可。

5.4 第一次跑回归的完整步骤

如果你是第一次搭，我建议按这个顺序操作：

1. 先把你现有Agent的每次工具调用打点，写入tool_trace，此时不看对比，只求数据稳定入库。
2. 手动运行5到10个固定输入，人工确认输出正常，把这些run_id标记为基线。
3. 随便改一处代码，比如在工具调用间插入一个日志，再跑一遍相同输入。
4. 执行compare_run，观察差异清单。
5. 不断给对比器补规则，直到它能准确区分“预期变化”和“意外变化”。

整个过程一天内可以完成。比起直接搭一个在线评测平台，这套方案的启动成本低很多。

6. 跑通之后我踩过的坑与调整

6.1 并发运行导致的trace串行问题

本地Agent不一定只是单用户、单线程跑。我一开始把TraceRecorder设计成模块级单例，结果两个并发任务交替写同一个run_id，tool_trace里乱成一团。修复方法是多加一个参数：所有写入都带上当前run_id，并且在录制工具调用时给连接加锁。SQLite本身也支持WAL模式，写入并发时不容易锁库。

建议在schema初始化时执行一句PRAGMA journal_mode=WAL;，能减少不少无谓的database is locked报错。

6.2 模型输出随机性：比文本、不比字符

最早跑回归时，我用的是“最终回答完全一致”作为通过标准，结果被模型随机性坑惨了。同一个输入、同一套工具，两次运行的措辞不可能完全一致。后来我调整为：工具调用序列和重要参数一致算通过，最终回复只做语义相似度检查。

如果你也不想引入embedding模型，一个零依赖的替代方案是：把回复里的数字、地名、时间等关键实体抽出来，比较实体集合是否一致——这招在真实项目中往往比编辑距离更可靠。

6.3 证据表的生命线：采样与保留

四张表不是无限增长的。我现在的策略是：

• run_meta：长期保留，记录每一次运行的生命周期
• tool_trace：只保留最近30天，历史版本用基线表单独锁定
• response_snapshot：保留最近7天，只对基线运行长期存档
• tool_catalog：每次发版归档一份，保留最近10个版本

基线数据单独备份，不跟普通trace混在一起，这样回归结果不会因为老数据被清理而失效。

6.4 并不是所有差异都要修

这条可能是最有价值的体会。跑离线回归的头几天，我几乎每个P1差异都想修，后来发现有些“差异”其实是数据变化导致的正常结果。比如天气查询工具返回的温度，昨天和今天不一样，这不是代码bug，是客观事实变化。

所以离线回归真正要盯的是“不应该变的变了”和“应该变的没变”。前者代表代码逻辑被意外破坏，后者代表新功能没有真正生效。理解这一点之后，对比器的告警策略会大幅收敛。

6.5 安全与隐私：Trace里也是敏感数据

既然记录的是完整输入输出，那用户的隐私信息、工具返回的敏感内容都会落进SQLite文件。本地项目虽然没有云端传输风险，但也要注意文件权限、备份加密、以及不要把带敏感信息的trace直接塞进git仓库。

我在.gitignore里排除了trace.db，只在需要调试时用本地副本。如果需要分享trace给同事做回归分析，会先跑一个脱敏脚本，把手机号、姓名、地址替换成占位符。这个习惯建议所有做本地Agent的人都养成。

最后想多说一句

Trace机制真正改变我的，不是工具本身，而是工作方式。以前改Agent代码，心里只有“大概能行”；现在改完代码，手边有一批历史基线可以立刻验证“到底行不行”。4张证据表加一个小型离线回归脚本，让初级开发者也能获得接近专业评测体系的安全感。如果你现在正好在维护一个本地Agent，而且被反复改坏功能折磨，不妨从今晚开始，给代码加一个简单的TraceRecorder，把工具调用痕迹留下来。跑完一轮回归，你会回来感谢自己。