把工具调用做成可观测的：日志、回放与重试

工具调用出错可能藏在参数、时序、权限与幂等里。本文给出该记的 10 项日志、离线回放的做法、重试的三条边界、四个该报警的指标与最小落地顺序。

工具调用是"黑盒里最多暗门"的一段

模型回答错了，你还能看输入输出；**工具调用错了，问题可能藏在参数、时序、权限、幂等**里。

所以要专门为它做可观测：**日志要结构化、失败要能回放、重试要有边界**。

1. 请求 id（串起同一任务的多次调用）；

2. 工具名与**版本**；

3. 参数（**脱敏后**的原文）；

4. 参数来源（模型生成 / 规则补全 / 用户输入）；

5. 校验结果（通过 / 哪条规则不过）；

6. 权限判定（允许 / 拒绝 / 需要确认）；

7. 耗时（分：排队、执行、返回）；

8. 结果摘要（成功/失败 + 关键字段，不要整包）；

9. 是否重试、第几次；

10. 副作用是否落库（以及幂等键）。

**关键是 4 与 10**：前者决定"是模型的错还是规则的错"，后者决定"能不能安全重试"。

保存**足够复现的输入**（脱敏后的参数 + 当时的工具版本 + 相关上下文片段）；

提供**离线回放**命令：同一输入重跑该工具（对**只读**工具可直接跑；写操作要打到沙箱）；

回放结果与线上结果对比，判断是"工具偶发"还是"逻辑错"。

没有回放能力，工具出错只能靠猜。

**只重试幂等的**（读、查询、幂等写）；非幂等操作要先确认再用补偿；

**区分可重试错误**（超时、5xx、限流）与不可重试错误（参数错、权限拒绝）；

**限制次数与总时长**（例如 2 次 / 10 秒），并把"已经重试过"写进日志。

同时要防**重试放大**：重试会让并发与成本翻倍，必须纳入容量与预算（见容量规划那篇）。

**工具失败率**（分工具、分错误类型）；

**参数校验拒绝率**（升高通常意味着模型输出漂移或提示词改了）；

**重试率**与**重试后成功占比**（后者低说明重试没意义）；

**写操作被拒绝/待确认的比例**（权限与安全策略是否过紧或过松）。

1. 先把上面 10 项日志补齐（半天，收益最大）；

2. 加只读工具的离线回放；

3. 给写操作加幂等键与"意图→执行→确认"两阶段；

4. 最后加指标与告警。