首页
学习
活动
专区
圈层
工具
发布
社区首页 >专栏 >把 Agent 的工具调用关进可回滚的边界:幂等键、dry-run 与执行审计

把 Agent 的工具调用关进可回滚的边界:幂等键、dry-run 与执行审计

原创
作者头像
老王说技术
发布于 2026-11-16 13:54:03
发布于 2026-11-16 13:54:03
110
举报

最近在维护一个每天定时跑的自动化任务:它会打开网站、采集状态、再按结果去写内容。跑得久了会发现,真正让人紧张的从来不是「这次有没有做对」,而是「重试一次会不会做两遍」。读操作重跑基本无害,写操作重跑一次就可能发出两篇文章、提交两次表单、覆盖一份别人刚改过的文件。

Agent 接的工具越多,这个问题越突出。模型侧的推理可以重来,外部世界的副作用不能。这篇文章把我在这个场景里沉淀下来的一套边界拆开讲:怎么给工具标副作用、怎么让计划和执行分离、幂等键怎么设计、审计日志最少要记什么、以及失败之后怎么回滚。不涉及任何具体产品的性能数字,命令和结构都可以直接照着改。

一、先给每个工具标副作用等级,别等出事再分类

很多团队的工具清单只有「名字 + 参数 + 描述」,这不够。至少补一个 effect 字段,把工具分成四类:

等级

含义

典型例子

重试策略

read

无副作用,可任意重放

查询、读取页面、列目录

直接重试

plan

只产出计划,不落地

生成 diff、构造待提交对象

直接重试,计划可丢弃

write_idempotent

有副作用但带幂等键,重放收敛

按 key 写入、带唯一约束的创建

可重试,必须带同一 key

write_unsafe

有副作用且无法去重

发消息、发布内容、转账、删除

禁止自动重试,只能人工确认

关键是最后两类要分开。如果把它们混成「写操作」,要么你会因为怕重复而什么都不敢重试,要么会因为统一重试而制造事故。

一个可以直接用的最小结构:

代码语言:yaml
复制
tools:
  - name: fetch_page
    effect: read
    timeout_s: 20
  - name: build_diff
    effect: plan
  - name: upsert_record
    effect: write_idempotent
    idempotency_key: "task_id + target_id + content_sha256"
  - name: publish_post
    effect: write_unsafe
    requires: human_confirm

requires: human_confirm 不是一句注释,要在执行器里真的拦一道:到达这个工具时暂停、把计划打印出来、等显式确认再放行。我在自己的自动化里,所有对外发布的动作都归在这一类;采集和草稿生成则全在前三类,所以掉登录、超时这些失败可以随便重跑,不会污染外部状态。

二、dry-run 不是打印一句「将要执行」

常见的假 dry-run 是这样:

代码语言:python
复制
def publish(title, body, dry_run=False):
    if dry_run:
        print(f"will publish: {title}")   # 只打印了标题
        return
    api.publish(title, body)

这没有价值,因为你验不了真正要写出去的内容。有效的做法是把「生成计划」和「执行计划」拆成两个独立函数,让 dry-run 和真实执行走同一个计划对象:

代码语言:python
复制
from dataclasses import dataclass
import hashlib, json

@dataclass(frozen=True)
class Action:
    tool: str
    effect: str
    args: dict
    key: str          # 幂等键

    def digest(self) -> str:
        raw = json.dumps(self.args, sort_keys=True, ensure_ascii=False)
        return hashlib.sha256(raw.encode()).hexdigest()[:16]

def plan(tasks) -> list[Action]:
    """纯函数:只读输入,不碰外部世界,可反复调用。"""
    actions = []
    for t in tasks:
        args = {"title": t["title"], "body": t["body"]}
        actions.append(Action(
            tool="publish_post",
            effect="write_unsafe",
            args=args,
            key=f"{t['task_id']}:{hashlib.sha256(t['body'].encode()).hexdigest()[:12]}",
        ))
    return actions

def apply(actions, ledger, confirm=lambda a: True) -> list[dict]:
    results = []
    for a in actions:
        if ledger.done(a.key):          # 幂等闸门
            results.append({"key": a.key, "status": "skipped_duplicate"})
            continue
        if a.effect in ("write_unsafe",) and not confirm(a):
            results.append({"key": a.key, "status": "awaiting_confirm"})
            continue
        ledger.begin(a.key)             # 先落"进行中"
        try:
            out = dispatch(a.tool, a.args)
            ledger.commit(a.key, out)   # 再落"完成"
            results.append({"key": a.key, "status": "committed"})
        except Exception as e:
            ledger.fail(a.key, str(e))  # 不能留悬空状态
            results.append({"key": a.key, "status": "failed", "error": str(e)})
    return results

这里有三个容易被忽略的点:

  1. plan() 必须是纯函数。它不读时钟、不发请求、不改全局变量,否则 dry-run 和真实执行会算出不同的计划,你验的就不是你发的。
  2. apply() 里先 begin 再执行。崩溃在中间时,账本里留的是「进行中」而不是「什么都没发生」,重启后能明确知道要人工核对哪一条。
  3. 确认回调作用在具体 Action 上,而不是整批任务。这样「前三个自动放行、第四个需要确认」这种混合策略才做得出来。

dry-run 阶段就直接调用 plan(),把每个 Action 的 tool / effect / key / digest 打印或落盘比对。真实执行前再 plan() 一次,比较两次 digest 是否一致;不一致说明外部状态在中间变了,应该重新走一遍计划。

三、幂等键怎么设计才真的去重

幂等键最常见的错误是用「当前时间」或「随机 UUID」——每次重跑都不同,等于没有。另一个极端是用「任务名」——同一任务第二天再跑会被误判成重复。

可用的组合是:key = 业务标识 + 目标标识 + 内容指纹

  • 业务标识:哪个任务、哪次运行(如日期 + task_id)。保证「今天」和「明天」是两个键。
  • 目标标识:写到哪儿(记录 ID、文章 ID、目标 URL)。保证同一任务写多个目标时互不干扰。
  • 内容指纹:对规范化后的内容做 sha256。保证内容改了会生成新键,而不是把旧结果复用到新内容上。

指纹前一定要做规范化:JSON 用 sort_keys=True、统一换行符、去掉尾部空白、把 Markdown 里的临时时间戳剔除。否则同一份内容因为一个空格就换了键,去重形同虚设。

还要区分「去重」和「幂等」:

  • 去重是执行器发现 key 已存在就跳过——这解决重放。
  • 幂等是服务端对同一 key 的重复请求返回同一结果——这解决网络超时后不知道到底成没成。

客户端超时是最麻烦的情形:请求发出去了,响应没回来,你不知道对方写没写。这时不要盲目重试,正确姿势是带同一个 key 重试一次,并让服务端按 key 收敛。如果服务端不支持,就退回到查询:先查目标状态,再决定是否补发。我的自动化里对「发布」这类动作就是这么做的——提交后先去详情页确认是否已存在,确认没有才补,绝不因为「没看到成功提示」就再发一遍。

四、执行审计的最小字段集

出问题后能不能复盘,全看日志记了什么。下面这几个字段是我认为不能再砍的下限:

代码语言:json
复制
{"ts":"2026-11-16T09:12:03+08:00","run_id":"2026-11-16","step":4,"tool":"publish_post","effect":"write_unsafe","key":"2026-11-16:article:9c1a42","args_digest":"9c1a428a","status":"committed","attempt":1,"elapsed_ms":812,"result_ref":"article/2784475","error":null}

字段

为什么必须有

run_id + step

能把一次运行的全部动作串起来,定位「第几步开始不对」

key + args_digest

判断是否重复、是否内容被中途改过

effect

事后统计「这次到底碰了几个不可重试的写操作」

status

只允许 planned / begun / committed / failed / skipped_duplicate / awaiting_confirm 这几种枚举

attempt

区分首次失败和重试失败

result_ref

外部产生的实体 ID 或链接,回滚和补录都要靠它

error

只记错误类型和消息,不记 token、cookie、正文全文

两个纪律:

  • 只记指纹不记正文。审计日志经常被同步到日志平台,把文章全文、表单内容写进去等于变相泄露。需要复查时用 args_digest 回查本地草稿。
  • 日志按行追加写 JSONL,不要边跑边覆盖。写到本地文件再异步上报,即使上报失败也不丢现场。

有了这份日志,「今天到底发了什么」不再靠猜:把 status=committed 且 effect=write_unsafe 的行过滤出来就是当日对外动作清单;和站点实际列表比对,差集就是需要人工核对的部分。这也顺带解决了另一个常见困扰——按周结算的平台,提交和到账之间有时延,只要日志里明确记了「已提交」和「结果链接」,就不会因为分数没立刻变化而重复去发一遍。

五、回滚分三层,别指望一个 undo

层级

能回滚什么

做法

计划层

还没执行的动作

直接丢弃 plan() 结果,零成本

本地层

文件、草稿、账本状态

改动落在独立工作区,一次提交,git reset 或删目录即可

外部层

已发布的内容、已发出的消息

通常无法撤回,只能删除/更正 + 留痕说明

所以工程上的重点不是「怎么撤」,而是把不可逆动作尽量往后推:采集、生成、校验、写草稿全放在本地层,只有最后一步跨到外部层。跨出去之前做一次完整校验——内容长度、关键段落、指纹与草稿一致、当日是否已提交过。我在发文场景里会做正文的逐字节比对,就是为了防止编辑器把内容改写后还照发。

对确实跨出去的动作,把 result_ref 记牢,需要更正时能直接定位,不用靠标题去搜。

六、一份可以直接照跑的自测清单

  1. 同一份输入连续 plan() 两次,断言两次 digest 完全一致。
  2. 对同一批 Action 连续 apply() 两次,断言第二次全部返回 skipped_duplicate,且外部实体数量不变。
  3. 模拟 commit 前抛异常,断言账本状态是 failed 而不是悬空的 begun。
  4. 模拟客户端超时(请求已发出、响应丢失),断言走的是「带同 key 重试」或「先查询再决定」,而不是无 key 重发。
  5. 把 write_unsafe 的确认回调设为恒 False,断言日志里是 awaiting_confirm,且外部零变更。
  6. 改一个字节的内容重新 plan(),断言 key 和 args_digest 都变了。
  7. 检查审计日志里不含正文、不含凭据。

这七条跑通,才敢让任务进入无人值守。

七、五个反模式

  • 统一重试所有工具:把发布和查询用同一套 retry,是重复提交最常见的来源。
  • 用时间或随机数当幂等键:看起来有 key,实际每次都新。
  • dry-run 只打印标题:验不了真正要写的内容,等于没验。
  • 先执行后记账:进程崩了就永久丢失一次副作用,重启必然重复。
  • 把「没拿到成功响应」当成「一定没成功」:这是重复发布的经典诱因,正确做法是先查状态。

小结

Agent 工程化里,模型能力决定上限,边界设计决定下限。把工具按副作用分级、计划与执行分离、幂等键由业务语义生成、审计记指纹不记正文、不可逆动作尽量后置,这套东西不复杂,但能让你在定时任务跑第 30 天的时候还敢让它自己继续跑。

顺便留一个开放问题:如果规则文件(AGENTS.md)或工具清单本身被改了,怎么自动发现 Agent 的行为悄悄回退了?这比单次执行的幂等更难,欢迎在评论区聊聊做法。

原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。

如有侵权,请联系 cloudcommunity@tencent.com 删除。

目录
  • 一、先给每个工具标副作用等级,别等出事再分类
  • 二、dry-run 不是打印一句「将要执行」
  • 三、幂等键怎么设计才真的去重
  • 四、执行审计的最小字段集
  • 五、回滚分三层,别指望一个 undo
  • 六、一份可以直接照跑的自测清单
  • 七、五个反模式
  • 小结
问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档