[!info] related notes

• 所属 MOC: Tool Calling Engineering MOC
• 相关: Audit Log, Tool Execution

Tool Audit Log

一句话定义

Tool Audit Log 是记录每次工具调用的详细日志。出了安全事件，需要知道”谁在什么时候调用了什么工具、传了什么参数、得到了什么结果”。

核心原理

工具调用应记录什么

• 可信调用者与租户、run ID、逻辑 operation ID、单次 attempt ID；重试与新操作要能区分。
• 工具名与版本、目标资源、授权或审批记录引用。
• 经字段白名单筛选的参数和结果摘要；秘密、令牌和不必要的个人信息不入日志。
• 带时区的事件时间、单调时钟测得的耗时，以及 denied / started / succeeded / failed / unknown 等状态。

风险等级决定审计要求与保留策略，不决定是否可以把全部参数、结果或异常原文写入日志。错误摘要同样需要筛选，避免下游异常回显秘密。

写入边界

鉴权拒绝、开始执行和执行结果是不同事件。HTTP 200 或函数返回不一定证明外部副作用成功；超时后结果未知，也不能直接记成操作未发生。

由执行入口构建审计事件，不让工具参数覆盖可信身份。需要与业务事务一致的事件可使用事务 outbox，再可靠投递到审计存储。外部调用无法共用事务时，保留操作标识与未知状态，通过下游查询或对账补齐结果。

存储与脱敏的通用原则见 Audit Log；本篇只保留工具调用特有的字段和执行边界。

常见坑

1. 只记工具名：缺少目标、操作标识和筛选后的摘要，无法关联审批或重试。
2. 只记最终成功：拒绝、失败和结果未知的尝试丢失，形成不完整的执行历史。
3. 把只读存储当写入方案：写入方需要受限追加权限，更新/删除权限与保留策略应单独控制。
4. 忽略审计写入失败：明确哪些操作必须在审计持久化后才能继续，以及队列失败如何告警和恢复。

参考资料

• Audit Log
• Tool Execution