工具调用型智能体如何避免重复执行同一个动作

工具调用型智能体要避免重复执行，关键不是要求模型“记住已经做过”，而是把每次有副作用的动作变成一个可持久化、可查询、可复用结果的业务操作。最稳妥的做法是：先生成稳定的 operation_key，再用参数指纹确认请求一致，通过带唯一约束的动作账本争夺执行权，并把同一个幂等键传给真正执行动作的外部工具。

这样，即使模型重试、工作流回放、队列重复投递或多个执行器同时收到任务，后来的请求也不会再次下单、发信或修改数据，而是返回“正在执行”或复用第一次的结果。对于无法提供幂等能力的工具，还要准备状态核对与补偿路径，不能把一次网络超时直接等同于“动作没有发生”。

重复动作为什么不是简单的模型问题

智能体调用工具时，通常跨越模型、编排器、队列、工具网关和外部系统多个边界。任何一层看不到明确结果，都可能触发重试。AWS 的重试文档也提醒：一次调用可能已经完整执行、只执行了一部分，或者根本没有执行；如果继续重试，业务逻辑必须能处理同一事件多次。

常见的重复来源有四类：

• 响应超时：工具已完成动作，但响应在返回途中丢失，编排器把它当成失败。
• 至少一次投递：消息系统为了不丢任务，允许同一消息被再次交付。
• 工作流回放：进程恢复后重新执行未确认完成的节点。
• 并发抢占：两个智能体副本同时判断“这个动作还没有执行”。

因此，只在提示词里写“不要重复调用”并不可靠；只在进程内放一个集合也不够，因为进程重启、多副本部署和租约过期都会绕过内存状态。规模上来以后，去重必须成为工具调用平台的一部分。

先定义什么才算同一个动作

幂等设计的第一步不是建表，而是定义动作身份。一个实用的动作键通常由业务对象、动作类型和上游意图共同组成，例如：

operation_key = tenant_id + conversation_id + business_object_id + action_type + intent_revision
# 中文说明：动作键必须来自稳定业务身份，不能使用每次重试都会变化的时间戳

动作键之外，还要保存参数指纹。参数先按固定规则规范化，例如对象键排序、去掉无业务意义的临时字段，再计算摘要：

import hashlib
import json

def payload_fingerprint(arguments: dict) -> str:
    # 中文说明：固定键顺序和紧凑分隔符，保证相同参数产生相同摘要
    canonical = json.dumps(
        arguments,
        ensure_ascii=False,
        sort_keys=True,
        separators=(",", ":"),
    )
    return hashlib.sha256(canonical.encode("utf-8")).hexdigest()

当同一个 operation_key 携带不同参数再次出现时，系统应该拒绝复用，而不是默默返回旧结果。这个规则能防止智能体在后续轮次改变收件人、金额或目标资源，却意外沿用旧动作键。

用动作账本把重复请求变成状态查询

动作账本是整个架构的核心。它至少保存动作键、参数指纹、工具名、状态、租约持有者、租约到期时间、外部请求标识、结果摘要和错误分类。数据库对 operation_key 建唯一约束，谁先成功插入或抢到过期租约，谁才拥有执行权。

下面是一段简化的 Python 伪实现，重点是数据库的原子操作，而不是本地锁：

def invoke_once(store, tool, operation_key, arguments, worker_id):
    fingerprint = payload_fingerprint(arguments)

    # 中文说明：原子创建记录或读取已有记录，唯一约束挡住并发首写
    record = store.create_or_get(
        operation_key=operation_key,
        payload_fingerprint=fingerprint,
        tool_name=tool.name,
    )

    # 中文说明：同键异参必须立即拒绝，避免复用错误业务结果
    if record.payload_fingerprint != fingerprint:
        raise ValueError("同一动作键对应了不同参数")

    if record.status == "SUCCEEDED":
        # 中文说明：重复请求直接返回第一次持久化的结果
        return record.result

    # 中文说明：租约保证同一时刻只有一个执行器进入工具调用区
    if not store.try_acquire_lease(operation_key, worker_id, ttl_seconds=90):
        return {"status": "RUNNING", "operation_key": operation_key}

    try:
        result = tool.call(arguments, idempotency_key=operation_key)
        # 中文说明：先持久化成功结果，再向上游确认，便于超时后安全复用
        store.mark_succeeded(operation_key, result)
        return result
    except TimeoutError as exc:
        # 中文说明：超时不代表未执行，进入未知状态并交给核对任务处理
        store.mark_unknown(operation_key, str(exc))
        raise
    except Exception as exc:
        # 中文说明：只有明确未产生副作用的错误才能标记为可重试
        store.mark_failed(operation_key, classify_error(exc))
        raise

租约不是删除记录。执行器崩溃后，记录仍然存在，只是租约最终到期。新的执行器接管前，应先检查外部系统是否已经产生结果；如果直接再次调用，租约只解决并发问题，无法解决“第一次已经成功但来不及记账”的窗口。

把幂等键一直传到真正产生副作用的工具

只在智能体平台内部去重，还不能覆盖最后一公里。假设外部下单接口已经成功，但执行器在写回动作账本之前崩溃；恢复后仅看本地记录仍可能再次下单。因此，最理想的情况是外部工具也接受同一个幂等键，并对同键请求返回原结果。

Stripe 的官方 API 文档就是典型例子：创建或更新对象时可以提供幂等键，重复请求会复用首次请求的状态码和响应体；如果同一个键对应的参数不同，服务端会拒绝误用。AWS 的 Durable Functions 也用 execution name 防止重复启动，并在回放时返回已检查点的步骤结果。

外部工具不支持幂等键时，可以按风险从低到高选择替代方案：

状态必须区分运行中、成功、失败和未知

很多重复执行来自过于粗糙的状态设计。只记录“成功/失败”会把超时、连接中断和进程崩溃全部归入失败，然后自动重试。更安全的状态至少包括：

• PENDING：记录已创建，还没有取得执行权。
• RUNNING：某个执行器持有未过期租约。
• SUCCEEDED：结果已持久化，后续请求直接复用。
• RETRYABLE_FAILED：能证明没有产生副作用，可以按退避策略重试。
• UNKNOWN：外部动作可能已经发生，必须先查询或人工核对。
• COMPENSATED：原动作已发生，但后续通过撤销、退款或反向记录完成补偿。

动作记录还应保存 payload_fingerprint、lease_owner、lease_expire_at、tool_request_id、result_digest 和 error_class。这些字段让系统能回答三个关键问题：请求是否相同、当前谁有执行权、外部世界到底留下了什么证据。

关键取舍：去重窗口、存储成本和人工接管

动作账本不能无限增长，但过早清理又会让旧重试重新执行。保留时间应至少覆盖上游最大重试周期、队列最长滞留时间和业务允许的回放窗口。高风险动作可以长期保留动作键与结果摘要，低风险只读动作则可以使用较短 TTL。

另一个取舍是等待还是快速返回。重复请求遇到 RUNNING 时，可以轮询原动作、订阅完成事件，或立即返回动作状态地址。不要让第二个请求另起一条工具调用。对于 UNKNOWN，系统应停止自动重试，先用外部业务标识查询；查询不到且动作不可逆时，交给人工确认通常比盲目重放更安全。

上线后要观察哪些信号

是否避免重复执行，不能只看工具调用报错率。建议至少记录以下指标：

• dedupe_hit_total：重复请求命中已有动作记录的次数。
• payload_conflict_total：同键异参被拒绝的次数。
• lease_contention_total：多个执行器争抢同一动作的次数。
• unknown_outcome_total：结果不确定、需要外部核对的次数。
• compensation_total：进入补偿或人工接管的次数。
• result_reuse_latency：重复请求复用旧结果所需时间。

验收时可以主动注入三类故障：工具完成后丢弃响应、两个执行器并发提交同一动作、保存结果前终止执行器。正确结果不是“完全没有错误”，而是动作账本中只有一个业务操作身份，外部系统没有多出第二份副作用，重复请求能拿到原结果或明确进入 UNKNOWN 核对流程。

落地清单

1. 为每个有副作用的工具定义稳定业务动作键，不用时间戳充当去重身份。
2. 规范化参数并保存指纹，同键异参立即拒绝。
3. 用持久化动作账本和唯一约束代替进程内集合。
4. 通过短租约解决并发所有权，但不要把租约误当成完成证据。
5. 把同一幂等键传到外部工具；不支持时准备业务唯一标识和结果查询。
6. 把超时归为未知结果，先核对再决定重试或补偿。
7. 结果先落库再向上游确认，重复请求统一复用第一次结果。
8. 用去重命中、同键冲突、租约竞争、未知结果和补偿次数持续观察。

工具调用型智能体无法仅靠一次模型推理获得“恰好执行一次”的保证。真正可靠的边界来自业务动作身份、持久化状态、原子所有权和外部系统协作。把重复调用设计成一次状态查询，而不是再做一次动作，才是从演示走向生产的关键。

相关问题

幂等键可以直接使用模型生成的 UUID 吗？
单次调用可以生成 UUID，但同一业务意图的重试必须复用原键。如果每次重试都生成新 UUID，服务端无法识别它们是同一个动作。

租约到期后是否可以立即重试工具？
不能一概而论。先检查外部请求标识或业务对象是否已经存在；只有能证明前一次没有产生副作用时，才进入自动重试。

读工具也需要动作账本吗？
纯读取通常不需要强一致账本，但昂贵查询、限流接口或结果必须与后续决策一致时，使用短期缓存和稳定请求键仍然有价值。

动作失败后能否复用失败结果？
可以，但要区分确定失败与未知结果。确定的参数错误可以缓存；暂时性故障可以按策略重试；网络超时等未知结果必须先核对外部状态。

参考资料

• AWS Lambda 重试行为：https://docs.aws.amazon.com/lambda/latest/dg/invocation-retries.html
• AWS Durable Functions 幂等说明：https://docs.aws.amazon.com/lambda/latest/dg/durable-execution-idempotency.html
• Stripe 幂等请求：https://docs.stripe.com/api/idempotent_requests