给智能体的文档转换接口加上审计回执
作者为文档转 Markdown 接口加入不可变审计日志,记录带时间戳的请求 ID、输入哈希和处理耗时。智能体可以在后续步骤引用请求 ID,失败时也能据此追查对应输入。
AI 深度解读
一个接收 URL、返回 Markdown 的转换 API,在 AI 智能体(Agent)开始循环处理数千份文件之后,暴露了一个问题:转换失败再跑一次,作者从记录里分不清这是重试,还是同一份文件被重复提交了。
作者给每次转换加上审计记录,随后观察到 Agent 开始把转换 ID 当回执,保存下来,再交给下游步骤。这篇最值得读的地方,是它把一个日常工程问题讲清楚了:当 AI 把多个工具串起来跑,每一步都得能回答「这份结果是哪次请求产出的」。
同一份文件跑了两遍,日志能告诉你什么
最初的 API 只接收 URL、返回文本,没有记录谁提交了什么。调试单次请求时,眼前的 URL 和报错往往就够用了。等 Agent 在循环里处理数千份文件,同一个地址可能出现好几次,光看结果很难还原发生过哪些调用。
作者加了一份不可变审计日志,为每次请求生成带时间戳的 ID,并把输入哈希、处理耗时与响应一起保存。ID 用来定位某一次执行,哈希用来比对输入,耗时提供这次执行花了多久的信息。
这里有两个容易混淆的问题。两次调用的输入是否相同,可以用哈希来比对,前提是知道哈希算的是什么。第二次调用是不是第一次的重试,要看调用方有没有留下关联。原文没交代哈希针对 URL 还是文件内容,也没提到是否记录了重试关系。
为什么 Agent 会把转换 ID 传给下游
作者观察到,Agent 会保存转换 ID,并在下游提示词里引用它。比如转换结果接下来要做摘要,那么摘要阶段带上这次转换的 ID,排查时就多了一个能指回上游执行的线索。流程越长,这个线索越有用,因为出问题的那一步和最初提交文件的地方可能已经隔了好几层。
按作者的描述,转换失败时,Agent 可以把错误对应到触发它的具体输入。原文没有说明输入是否另行保存,也没有说明 Agent 如何用 ID 查回记录。工程上,哈希只能用来比对,无法恢复原始文件。要定位失败时的文件版本,还得有地方能查到当时的输入。
我的判断
这篇最扎实的建议,是给每次工具调用一个能贯穿上下游的 ID。普通应用日志如果已经有请求 ID,而且能从下游记录查回上游请求,也能解决一部分排查问题。不可变审计日志多提供了一项保证:记录一旦写入,后续仍可按原样核对。原文没有展开这项保证是怎么实现的。
作者报告的是上线后的行为观察。文章没有给出上线前后的故障定位耗时、重复处理率,也没有用普通日志或调用链追踪做对照。Agent 开始引用回执是有用的经验,至于这套设计能省下多少排查时间,原文没有量化。
能拿来做什么
- 如果你用 Node 写批量文档转换脚本,把每次转换的 ID 和处理耗时写进任务结果。后续摘要或入库时带上这个 ID,方便从产物追到具体调用。
- 如果你需要区分重试和重复提交,在任务记录里保留稳定的任务 ID,并给每次执行单独分配 ID。排查时可以按任务聚合,再逐次查看执行结果。
- 如果文档 URL 指向的内容会更新,明确输入哈希的计算对象。需要核对失败时的文件内容时,记录一个能够找回当时版本的引用。