前言

在使用 AI Agent 完成自动化任务时，我们经常希望它能够在遇到错误后自动重试。

例如：

• 上传文件失败后自动重传。

• 调用 API 超时后重新请求。

• Git 仓库推送失败后再次提交。

• 云资源创建失败后重新执行。

• 应用发布接口没有响应时再次尝试。

自动重试确实能够提高系统处理临时故障的能力。

但是，我在研究自动化工作流时发现一个容易被忽略的问题：

如果第一次请求实际上已经执行成功，只是客户端没有收到成功响应，那么第二次重试会发生什么？

例如，一个 AI Agent 调用应用发布接口。

服务器已经成功创建作品，但返回结果时网络发生超时。

Agent 误以为发布失败，于是再次调用发布接口。

最后可能出现两个内容完全相同的作品。

从 AI Agent 的角度看，它只是在努力完成任务；但从业务系统的角度看，它已经造成了重复操作。

解决这一问题，需要理解一个重要的软件工程概念：

幂等性（Idempotency）。

本文将从实际场景出发，介绍幂等性的基本原理、常见实现方式，以及如何让 AI Agent 在自动重试时避免重复创建资源。

一、什么是幂等性？

幂等性是指一个操作执行一次和执行多次，对系统产生的最终业务效果相同。

例如，将某个任务的状态设置为已完成：

PUT /tasks/123/status

{
  "status": "completed"
}

在不考虑额外审计记录等副作用的情况下，重复执行这个状态设置操作，任务最终仍然处于已完成状态。

但是，创建一条新记录通常不同：

POST /tasks

{
  "title": "学习 Python"
}

如果服务端每收到一次请求就创建新任务，那么重复执行两次便可能得到两条相同记录。

这里有一个重要区别：

请求参数相同，不代表请求天然具有幂等性。

幂等性必须通过 API 语义或者服务端的去重机制得到保障。

对于 AI Agent，这一点尤其重要。

因为它不像传统程序那样总是严格执行固定流程，而是可能根据错误信息自主决定是否再次调用工具。

二、AI Agent 为什么容易出现重复执行？

假设 AI Agent 正在完成一个自动化发布任务。

正常流程：

用户授权发布 → Agent 调用发布接口 → 服务端创建作品 → 返回作品 ID → Agent 报告成功。

但如果网络出现问题：

用户授权发布 → Agent 调用发布接口 → 服务端创建作品成功 → 响应丢失 → Agent 判断超时。

此时，Agent 面临一个难题：

第一次操作到底成功了，还是失败了？

如果直接重试，有可能重复创建作品。

如果不重试，又可能导致任务未完成。

这个场景说明：

网络超时只能证明客户端没有及时获得结果，不能证明服务端没有执行操作。

同样的问题也会出现在订单创建、消息发送、云资源申请以及自动化文件处理等业务中。

因此，一个可靠的 AI Agent 不应该简单地把所有超时都理解为失败。

三、最常见的解决方案：幂等键

一种常见方法是为每次业务操作分配一个唯一的幂等键，也叫 Idempotency Key。

例如，第一次提交：

POST /api/publish
Idempotency-Key: publish-project-20261020-001
Content-Type: application/json

{
  "projectName": "Demo App"
}

如果请求超时，Agent 再次提交时，仍然使用相同的幂等键：

POST /api/publish
Idempotency-Key: publish-project-20261020-001
Content-Type: application/json

{
  "projectName": "Demo App"
}

服务端收到请求后，先查询是否已经处理过这个幂等键。

如果此前已经成功完成操作，就返回之前的处理结果，而不是再次创建资源。

例如：

{
  "success": true,
  "projectId": "project-10086",
  "alreadyProcessed": true
}

这样，AI Agent 即使因为网络问题重复请求，也不会因此产生第二个项目。

需要强调：

幂等键必须在重试之间保持不变。

如果 Agent 每次重试都重新生成一个 UUID，那么服务端可能认为每次都是全新的操作，去重机制也就失去了意义。

四、动手实践：用 Python 和 SQLite 实现简单幂等处理

下面通过一个最小示例，演示如何防止重复创建项目记录。

示例只使用 Python 标准库，不需要安装额外依赖。

先创建一个数据库表，用于保存请求标识、请求内容摘要以及生成的项目 ID。

import sqlite3

DB = "projects.db"

with sqlite3.connect(DB) as conn:
    conn.execute("""
        CREATE TABLE IF NOT EXISTS submissions (
            request_key TEXT PRIMARY KEY,
            payload_hash TEXT NOT NULL,
            project_id TEXT NOT NULL
        )
    """)

这里最重要的是：

request_key TEXT PRIMARY KEY

它保证同一个请求标识在数据库中只能存在一条记录。

接下来实现一个创建项目的方法：

import hashlib
import sqlite3
import uuid
from contextlib import closing

DB = "projects.db"

def create_project(request_key, project_name):
    if not request_key or not project_name:
        raise ValueError("请求标识和项目名称不能为空")

    payload_hash = hashlib.sha256(
        project_name.encode("utf-8")
    ).hexdigest()

    new_id = str(uuid.uuid4())

    with closing(sqlite3.connect(DB, timeout=5)) as conn:
        with conn:
            conn.execute("""
                INSERT OR IGNORE INTO submissions
                (request_key, payload_hash, project_id)
                VALUES (?, ?, ?)
            """, (request_key, payload_hash, new_id))

            saved = conn.execute("""
                SELECT payload_hash, project_id
                FROM submissions
                WHERE request_key = ?
            """, (request_key,)).fetchone()

    if saved[0] != payload_hash:
        raise ValueError("同一幂等键不能用于不同请求")

    return saved[1]

这个方法具有几个特点：

第一，首次创建时，数据库保存项目 ID。

第二，相同请求再次提交时，主键约束阻止重复插入。

第三，如果有人使用相同幂等键提交不同的项目名称，程序会拒绝操作，避免错误复用请求标识。

现在测试一下：

key = "create-project-001"

first = create_project(key, "AI Demo")
second = create_project(key, "AI Demo")

print("第一次创建：", first)
print("第二次请求：", second)
print("ID 是否相同：", first == second)

预期结果：

第一次创建：某个 UUID
第二次请求：同一个 UUID
ID 是否相同：True

需要说明，这个示例只实现了本地数据库记录创建的幂等性。

如果创建项目的过程中还需要调用外部云平台接口，就不能仅凭数据库插入成功判断远端操作已经完成。

外部调用需要配合额外的状态管理与结果核对。

五、最容易犯的错误：只在客户端禁止重复点击

有些开发者会通过禁用按钮来防止重复操作。

例如：

button.disabled = true;

这种方法能够减少用户连续点击造成的重复请求。

但是，它无法处理：

• 网络超时后的自动重试。

• 页面刷新后重新提交。

• 多个 Agent 同时执行同一任务。

• 不同服务器上的并发请求。

• 服务端已成功但客户端未收到响应。

因此，前端按钮禁用只能改善交互体验，不能替代服务端幂等性。

真正关键的去重能力，应该由能够协调并发请求的服务端或持久化存储层保障。

六、仅有幂等键还不够：并发执行怎么办？

假设两个 AI Agent 同时收到相同任务。

Agent A 查询数据库，发现任务不存在。

Agent B 同时查询数据库，也发现任务不存在。

随后两个 Agent 都尝试创建项目。

如果只采用“先查询，再插入”的普通逻辑，就可能发生竞争条件。

正确做法是让数据库的唯一约束参与最终裁决。

例如：

CREATE UNIQUE INDEX idx_request_key
ON submissions(request_key);

当两个请求同时尝试插入相同幂等键时，数据库应确保最多只有一个成功创建对应记录。

不过，在真实系统中，还需要考虑事务隔离、锁等待和异常处理等问题。

如果涉及多个服务、消息队列或远端 API，单一数据库约束可能不足以覆盖整个业务流程。

这也是为什么复杂系统常常需要配合任务状态机和可靠消息处理机制。

七、AI Agent 自动重试应该遵循什么规则？

并不是所有错误都适合立即重试。

例如：

其中，网络超时最值得注意。

对于只读取数据的接口，重试通常相对简单。

但对于创建、删除、支付、发布等会改变外部状态的操作，应该先确认系统是否提供了幂等键或操作状态查询功能。

如果没有可靠的去重能力，就不能保证重复调用不会产生额外副作用。

八、为什么应用发布特别需要幂等性？

AI Agent 自动发布应用时，通常需要调用多个外部服务。

例如：

1. 推送 GitCode 仓库。

2. 上传封面。

3. 上传作品介绍材料。

4. 创建作品记录。

5. 关联活动。

6. 返回发布链接。

其中有些操作可以安全重试，有些则可能创建新的外部资源。

例如，作品发布接口返回 HTTP 201，通常说明服务端成功创建了资源。

这时如果 AI Agent 因为没有正确记录响应，再次执行同一个发布流程，就可能出现重复作品。

因此，我认为一个合理的发布 Agent 至少应该记录：

• 当前项目的唯一标识。

• 本次发布操作的幂等键。

• 是否已经获得作品 ID。

• 远端查询得到的实际发布状态。

• 是否存在尚未确认结果的请求。

如果已经得到明确的作品 ID，就应该优先查询该作品状态，而不是重新提交创建请求。

如果请求结果未知，也应该先尝试通过平台提供的正式接口查询。

不能把“我没有收到成功消息”直接等同于“服务端没有成功”。

九、进一步优化：使用任务状态机

对于多步骤 AI Agent，可以设计简单的状态机。

例如：

PENDING
   |
   v
VALIDATING
   |
   v
SUBMITTING
   |
   v
SUCCEEDED

异常场景可以增加：

UNKNOWN_RESULT
FAILED_RETRYABLE
FAILED_FINAL

其中，UNKNOWN_RESULT 特别重要。

它代表请求结果尚未确认。

例如，客户端调用创建接口时超时，但尚不知道远端是否已经创建资源。

此时不应该立即认定失败，而应该进入结果核对流程。

完整的逻辑可以是：

请求超时 → 标记 UNKNOWN_RESULT → 查询远端状态 → 找到已有资源则记录成功 → 确认未创建且允许重试时再继续执行。

这类状态管理机制，也有助于 AI Agent 在长任务中断后恢复执行。

不过，状态机记录本身也必须持久化，否则程序重启后仍然可能丢失重要进度。

十、如何测试幂等性是否真正生效？

只测试“第一次提交成功”，远远不够。

建议至少设计以下几个场景。

测试一：同一个请求连续提交两次。

预期只创建一个业务资源。

测试二：第一次请求成功，但模拟响应丢失。

第二次请求应该恢复已有结果，而不是重新创建。

测试三：相同幂等键携带不同参数。

预期拒绝请求，避免错误复用。

测试四：两个请求同时执行。

预期不会产生两个相同资源。

测试五：服务重启后再次提交。

预期仍然能够找到历史执行记录。

测试六：外部 API 超时。

预期进入结果核对或明确的未知状态，而不是无限重试。

真正可靠的幂等性设计，不是只让正常场景通过，而是能够正确处理网络异常、并发以及任务中断。

十一、总结

随着 AI Agent 开始执行越来越多的实际操作，自动重试逐渐成为提高任务完成率的重要机制。

但自动重试也可能引入新的风险。

尤其是在文件上传、云资源创建、应用发布和其他有副作用的业务场景中，重复执行可能导致资源重复、状态混乱，甚至产生额外成本。

通过本文的讨论，可以总结出几个重要原则：

第一，同一业务操作在重试时应该使用稳定的幂等键。

第二，服务端需要通过数据库约束或其他可靠机制实现去重。

第三，网络超时不能直接认定业务执行失败。

第四，并发请求和外部 API 调用需要单独考虑。

第五，AI Agent 必须保存执行状态，并对未知结果进行核实。

我认为，未来的 AI Agent 不仅需要具备自动执行任务的能力，还需要具备安全恢复任务的能力。

一个优秀的 AI Agent，不只是能够在失败后重新尝试，更应该知道什么时候不该重新执行。

只有把自动重试、幂等性、状态管理和结果验证结合起来，才能真正构建稳定、可控、可恢复的 AI 自动化系统。