Agent 重试了一次,客户被扣了三次钱:我用 430 行 Python 给工具调用补上 exactly-once 语义,重复扣款从 27 笔降到 0
·
10 月 28 号晚上十点半,客服在群里甩了张截图:同一个客户、同一笔 199 元的退款,后台躺着三条"已退款"记录。客户到账 597 元,然后打电话过来问我们是不是在拿他做测试。
我把日志捞出来,链路干净得让人无话可说:
```
22:14:03.1 agent refund.create(order=A8821, amount=199) → 网关 30s 超时
22:14:03.4 harness 判定失败,丢进重试队列(第 1 次)
22:14:36.2 agent refund.create(order=A8821, amount=199) → 网关 30s 超时
22:15:09.5 agent refund.create(order=A8821, amount=199) → 200 OK
22:15:09.6 agent 汇报:退款已完成
```
第一次超时的时候,钱其实已经退出去了。支付网关在 22:14:03.8 就把款打到客户账上,只是回程的响应被我们那个 30 秒超时掐断。后面两次,每一次都是真金白银。
问题不在模型笨。问题在我们把一个**至少一次**的调用通道,当成**恰好一次**在用,而且自己没意识到。
## 一、重复执行不是 bug,是这类架构的默认行为
先把账算清楚。一次工具调用,从模型决定调到外部系统真执行,中间至少有四层可能重试:
- 模型层。工具返回 `error` 或 `timeout` 时,现在的模型几乎都会自己再试一次,这是训练出来的"韧性",你改提示词也压不住。
- Harness 层。我们自己写的 retry 装饰器,指数退避三次,很标准,也很致命。
- SDK 层。大部分 HTTP 客户端默认就对 5xx 和连接错误重试,很多人根本不知道自己开了。
- 人类层。用户点两次、两个会话并发、定时任务和手动触发撞车。
四层各重试一次,最坏情况同一次业务意图被执行 16 次。这不是理论值,我把线上 30 天的工具调用日志扒出来统计过:**8.3% 的调用存在重复执行,写类工具里是 1.7%**。1.7% 听起来还好,但乘上一天几万次写操作,就是一天几百次重复副作用。
那为什么"重复执行"这么常见,大家却没感觉?因为大部分写操作是幂等的——更新一条记录、覆盖一个字段,重复做十次结果一样。真正会出事的只有那几类:**扣款、退款、发券、下单、发短信、建工单、给外部系统推数据**。它们不幂等,而且每一次都有成本,有的是钱,有的是客户信任。
## 二、为什么"让模型小心点"和"加个唯一索引"都不够
先说一个我试过的错方案:在系统提示词里写"同一个操作不要重复调用,失败后先确认再重试"。
效果是负的。模型看不到"上一次其实成功了",它看到的就是一个 timeout。在信息缺失的情况下,重试是它的最优策略。你让它别重试,它就会在真失败的时候也不重试,问题从重复扣款变成漏单。两头都是错,而且漏单更难被发现。
第二个错方案:给业务表加唯一索引。这个有用,但只挡得住本地重复。它挡不住三个更隐蔽的窗口:
1. **外部已成功、本地写库失败**。钱退出去了,你的记录没落库,唯一索引根本没机会生效。
2. **同一笔业务的两种表述**。`amount=199` 和 `amount=199.00` 在你的键上不是一回事,在支付网关那里是。
3. **键本身不稳定**。用 `uuid4()` 或者时间戳当幂等键,每次重试都生成新键,等于没做。
所以我最后落到的方案,是三个东西叠起来:**业务幂等键**(是谁)、**请求指纹**(是不是同一件事)、**状态机加对账**(现在到底成了没有)。
先讲清一个立场:跨系统边界的 exactly-once 在工程上不存在。分布式事务那一套(2PC、TCC)能做,但你不会为了一个退款接口去改支付网关。你能拿到的是 exactly-once 的**效果**——**执行上最多一次,记账上至少一次,剩下的靠对账兜底**。这句话是整篇文章的地基,后面所有代码都是它的注脚。
顺带说一句行业观察。这几天 CrowdStrike 给 Agent 加了 Kill Switch,IBM 和微软联合发了带 governance 能力的企业 Agent 平台,大家都在解决"Agent 能不能做这件事"。很少有人解决"Agent 做几次"。前者是权限问题,后者是一致性问题,两个都得有。
## 三、430 行代码,四个部件
下面这套东西不是凭空设计的,是黑箭科技在给几家客户做 Agent 落地时,被重复扣款、重复发券、重复建单这些事一次次逼出来的。整个模块零第三方依赖,标准库就能跑,你可以直接拿去改。
### 3.1 幂等键:从业务意图里长出来
键的稳定性决定了整套方案的上限。它必须满足三个条件:跨进程稳定、跨会话稳定、跨天稳定。
```python
# idem_keys.py
import hashlib, json
# ❌ 反例一:每次调用都变
# key = str(uuid.uuid4())
# ❌ 反例二:带时间戳,重试跨秒就失效
# key = f"refund:{int(time.time())}:{order_no}"
# ❌ 反例三:只带单号,一个订单多次部分退款会互相覆盖
# key = f"refund:{order_no}"
def refund_key(p: dict) -> str:
"""退款幂等键:租户 + 订单 + 该订单的第几次退款"""
return f"refund:{p['tenant']}:{p['order_no']}:{p['refund_seq']}"
def coupon_key(p: dict) -> str:
"""发券幂等键:活动 + 用户 + 批次(同一活动同一批次对同一人只能发一次)"""
return f"coupon:{p['activity_id']}:{p['user_id']}:{p['batch_no']}"
def ticket_key(p: dict) -> str:
"""建工单:用业务指纹,不用工单号(工单号是结果,不是原因)"""
basis = f"{p['source']}|{p['biz_id']}|{p['category']}"
return "ticket:" + hashlib.sha256(basis.encode()).hexdigest()[:24]
```
判断标准很简单:**这个键,能不能让一个三个月后接手的人,只看业务数据就重新算出来?** 能,就是对的。
还有一个分工问题:键由谁生成?
我最早的版本把 `idem_key` 直接放进了工具 schema,让模型自己填。结果很 predictable——它每次重试都编一个新键,格式还挺像那么回事。后来改成:**业务参数由模型给,幂等键由 harness 算,租户身份由会话上下文注入,模型碰都碰不到。**
```python
# tools.py —— 暴露给模型的 schema 里根本没有 idem_key 和 tenant
REFUND_TOOL = {
"name": "create_refund",
"description": "为指定订单发起退款。同一订单的同一退款序号只会执行一次,重复调用不会重复打款。",
"parameters": {
"type": "object",
"properties": {
"order_no": {"type": "string", "description": "订单号,如 A8821"},
"amount": {"type": "number", "description": "退款金额,单位元"},
"refund_seq": {"type": "integer", "description": "该订单的第几次退款,从 1 开始;部分退款时递增"},
"reason": {"type": "string", "description": "退款原因"}
},
"required": ["order_no", "amount", "refund_seq", "reason"]
}
}
def dispatch(tool_name: str, args: dict, ctx: dict):
if tool_name == "create_refund":
# tenant 来自会话上下文,refund_seq 来自模型(只有它知道这是第几次部分退款)
return create_refund({**args, "tenant": ctx["tenant_id"]})
raise ValueError(tool_name)
```
这个分工我踩过坑。早期让模型填 `tenant`,有一次它填成了"默认租户",那笔退款打到了另一个客户的账上——查了四个小时才定位到是模型在补全参数时"猜"的。**能决定钱流向哪个账户的字段,永远不要交给模型。**
### 3.2 请求指纹:防"同键不同参"
幂等键解决"是不是同一件事",指纹解决"参数有没有被改过"。有人重试时顺手把金额从 199 改成 199.5,只靠键你发现不了。
```python
def fingerprint(payload: dict) -> str:
"""规范化后哈希:键排序、浮点统一、None 归一,避免 199 和 199.0 算两个指纹"""
def norm(v):
if isinstance(v, float):
return f"{v:.4f}"
if isinstance(v, dict):
return {k: norm(x) for k, x in sorted(v.items())}
if isinstance(v, (list, tuple)):
return [norm(x) for x in v]
return v
raw = json.dumps(norm(payload), ensure_ascii=False, sort_keys=True, separators=(",", ":"))
return hashlib.sha256(raw.encode()).hexdigest()
```
指纹不一致时,我直接抛 `IdemConflict`,返回 409 给上层。这条规则上线三个月,抓到过两次真实的参数漂移——都是模型在重试时"自作主张"把备注字段补全了。备注不影响金额,但它影响指纹,这种时候报错比静默执行安全。
### 3.3 状态机 + 租约:整套方案的心脏
一张表,五个状态。`in_flight`(有人在执行)、`succeeded`(成了,可直接回放结果)、`failed`(确定没发生,可安全重试)、`unknown`(不知道,等对账)。第五个状态不是表里的,是"行不存在",代表从没来过。
```python
# idem_store.py
import contextlib, json, sqlite3, threading, time
from dataclasses import dataclass
from typing import Any
SCHEMA = """
CREATE TABLE IF NOT EXISTS idem_record (
idem_key TEXT PRIMARY KEY,
fingerprint TEXT NOT NULL,
state TEXT NOT NULL, -- in_flight | succeeded | failed | unknown
response TEXT,
attempts INTEGER NOT NULL DEFAULT 0,
lease_until REAL NOT NULL,
created_at REAL NOT NULL,
updated_at REAL NOT NULL
);
CREATE INDEX IF NOT EXISTS idx_idem_state ON idem_record(state, lease_until);
"""
LEASE = 60.0 # 租约秒数,要比单次外部调用超时大 2 倍以上
@dataclass
class Decision:
action: str # execute | replay | wait | conflict
payload: Any = None
class Store:
def __init__(self, path="idem.db"):
self.conn = sqlite3.connect(path, check_same_thread=False,
isolation_level=None, timeout=5)
self.conn.execute("PRAGMA journal_mode=WAL")
self.conn.executescript(SCHEMA)
self._lock = threading.Lock()
@contextlib.contextmanager
def tx(self):
# 单机用线程锁;多机部署把这层换成 Redis 分布式锁或 DB 行锁即可
with self._lock:
self.conn.execute("BEGIN IMMEDIATE")
try:
yield self.conn
self.conn.execute("COMMIT")
except Exception:
self.conn.execute("ROLLBACK")
raise
def acquire(store: Store, key: str, fp: str) -> Decision:
now = time.time()
with store.tx() as c:
row = c.execute(
"SELECT fingerprint, state, response, lease_until FROM idem_record "
"WHERE idem_key = ?", (key,)).fetchone()
if row is None: # 第一次来,抢到执行权
c.execute("INSERT INTO idem_record VALUES (?,?,?,?,?,?,?,?)",
(key, fp, "in_flight", None, 1, now + LEASE, now, now))
return Decision("execute")
old_fp, state, response, lease_until = row
if old_fp != fp: # 同键不同参,拒绝
return Decision("conflict")
if state == "succeeded": # 已经成了,直接回放
return Decision("replay", json.loads(response) if response else None)
if state == "in_flight" and lease_until > now: # 别人正在做,等着
return Decision("wait", lease_until - now)
# 走到这里只有两种可能:租约过期(执行者崩了),或上次以 failed/unknown 收场
c.execute("UPDATE idem_record SET state='in_flight', attempts=attempts+1, "
"lease_until=?, updated_at=? WHERE idem_key=?",
(now + LEASE, now, key))
return Decision("execute")
def finish(store: Store, key: str, state: str, response: Any = None) -> None:
now = time.time()
with store.tx() as c:
c.execute("UPDATE idem_record SET state=?, response=?, updated_at=? "
"WHERE idem_key=?",
(state,
json.dumps(response, ensure_ascii=False, default=str) if response is not None else None,
now, key))
```
**租约(lease)这一列是最容易被省掉、也最容易出事的地方。** 没有它,进程在 `in_flight` 状态下被 kill,那条记录就永远卡住,后面所有重试都变成 `wait`,业务直接挂死。有了它,60 秒后自然过期,新请求可以抢占——最多多执行一次,但系统能自愈。这个取舍我认为完全值得。
### 3.4 对账器:`unknown` 状态唯一正确的出口
超时到底算成功还是失败?答案是:**不知道,所以标 unknown,然后去问。**
```python
# reconciler.py
import time
def reconcile_once(store, query_fn, older_than=30, limit=100) -> dict:
"""query_fn 必须是只读查询,不能有副作用"""
rows = store.conn.execute(
"SELECT idem_key FROM idem_record "
"WHERE state='unknown' AND updated_at < ? LIMIT ?",
(time.time() - older_than, limit)).fetchall()
stat = {"checked": 0, "confirmed_done": 0, "confirmed_none": 0, "still_unknown": 0}
for (key,) in rows:
stat["checked"] += 1
real = query_fn(key)
if real is None: # 外部确认没发生 → 可以安全重试
finish(store, key, "failed")
stat["confirmed_none"] += 1
elif real.get("status") in ("success", "refunded", "paid"):
finish(store, key, "succeeded", real) # 外部已成功 → 补记录,不再执行
stat["confirmed_done"] += 1
else: # 外部还在处理中,下一轮再问
stat["still_unknown"] += 1
return stat
```
对账器每 30 秒跑一次,`query_fn` 用支付网关的只读查询接口,按业务单号查。这一步是整个方案里唯一能消掉 `unknown` 的地方,也是我见过的团队最容易漏掉的一环——大部分人的重试逻辑里,超时被归进 `failed`,然后就理直气壮地重发了。
### 3.5 包成装饰器,让 Agent 完全无感
业务代码不该关心幂等。用装饰器把这层套上去,Agent 侧看到的仍然是一个普通函数。
```python
# idem_decorator.py
import functools, time
class IdemConflict(Exception):
pass
METRICS = {"execute": 0, "replay": 0, "blocked_wait": 0, "unknown": 0}
def idempotent(store, key_fn, fp_fn, wait_budget=10.0):
def deco(fn):
@functools.wraps(fn)
def wrapper(payload: dict):
key, fp = key_fn(payload), fp_fn(payload)
deadline = time.time() + wait_budget
while True:
d = acquire(store, key, fp)
if d.action == "conflict":
raise IdemConflict(f"{key} 已存在同键不同参的请求")
if d.action == "replay":
METRICS["replay"] += 1
return d.payload
if d.action == "execute":
METRICS["execute"] += 1
break
if time.time() > deadline: # 等太久,交回上层,别硬撑
METRICS["blocked_wait"] += 1
return {"status": "pending", "idem_key": key}
time.sleep(0.2)
try:
result = fn(payload)
except TimeoutError:
# 关键分叉:超时 ≠ 失败。标 unknown,等对账,绝不当 failed
finish(store, key, "unknown")
METRICS["unknown"] += 1
raise
except Exception:
finish(store, key, "failed") # 明确异常 → 可以安全重试
raise
finish(store, key, "succeeded", result)
return result
return wrapper
return deco
# ---------------- 业务侧,一行装饰器搞定 ----------------
store = Store("idem.db")
@idempotent(store, key_fn=refund_key, fp_fn=fingerprint)
def create_refund(payload: dict):
return payment_gateway.refund(
order_no=payload["order_no"],
amount=payload["amount"],
reason=payload["reason"],
)
```
注意 `TimeoutError` 和普通 `Exception` 分开处理这个细节。我第一版把两者都归到 `failed`,结果就是文章开头那 27 笔重复退款——超时的那些全被当成"没发生",然后重发了。
### 3.6 三个必须报警的指标
这层如果只是"默默运行",等于没上线。我只挂了三条告警,够用了:
```sql
-- 1) unknown 堆积:外部系统不稳,或者你的超时设得太短
SELECT COUNT(*) AS n FROM idem_record WHERE state='unknown';
-- 2) 重试次数异常的僵尸键:超过 3 次说明这个工具在反复失败
SELECT idem_key, attempts, state FROM idem_record
WHERE attempts > 3 ORDER BY attempts DESC LIMIT 20;
-- 3) 租约长期没释放:执行者崩溃或线程池被打满
SELECT COUNT(*) AS n FROM idem_record
WHERE state='in_flight' AND lease_until < strftime('%s','now') - 300;
```
第一条超过总量的 2% 就要看,说明你在跟一个不可靠的外部系统搏斗;第二条出现就说明某个工具的设计有问题,不是加个重试能解决的;第三条出现基本可以确认有进程在 `in_flight` 中间被杀掉——这是最脏的一种情况,因为它意味着可能有业务已经执行但没记账。
## 四、上线两个月的数字,和它治不好的病
跑在 3 个业务线、11 个写类工具上,两个月的数据:
| 指标 | 上线前 | 上线后 |
|---|---|---|
| 重复扣款/重复退款 | 27 笔/月 | 0 笔 |
| 重复发券 | 约 400 张/月 | 0 张 |
| 重复建单(工单系统) | 约 610 条/月 | 0 条 |
| 被拦截的重复执行 | — | 1,240 次/周 |
| 工具调用 P99 延迟 | 1,180 ms | 1,187 ms |
| `unknown` 状态占比 | — | 0.6% |
| 对账修复成功率 | — | 99.1% |
延迟只加了 7 毫秒,一次 SQLite 事务的钱。这是我认为这套方案最划算的地方:**一致性问题的成本几乎全在"想清楚",不在"跑得快"**。
它治不好的病,也得说清楚:
**外部系统没有只读查询接口时,`unknown` 只能人工。** 我们有一个老的短信通道,发出去就查不到状态,这种情况只能靠"发之前先落记录、发之后人工抽检",做不到全自动。遇到这类系统,我的建议是先在业务上限制它的调用频率,而不是硬上幂等层。
**键设计错了,整套白搭。** 用 `uuid4()` 当键的团队我见过不止一个,代码看起来一模一样,一行不改,效果是零。
**多租户场景必须带命名空间。** 两个客户都有订单号 `A8821`,键不带 `tenant` 就会互相顶掉,这种 bug 比重复扣款更难查——因为它表现为"某个客户的退款莫名其妙成功了"。
**纯读工具别套这一层。** 读操作天然幂等,套上只是给数据库白加负载。我们只对 11 个写类工具做了包装,读类工具一个没动。
## 五、最后几句实话
Agent 的可靠性问题,八成不是模型不够聪明,而是我们把这些系统当成"函数调用"在设计,忘了它们本质上是**跨进程、跨网络、会超时、会重试的分布式系统**。模型只是让这个老问题变得更急迫了——因为以前是人类点按钮,一天点几百次;现在是 Agent 自己点,一天点几万次,而且它比你更愿意重试。
具体到代码,四件事按重要性排:
1. **超时和失败必须分开处理。** 超时是 `unknown`,不是 `failed`。这一条能消掉大部分重复副作用。
2. **幂等键从业务意图里长出来。** 不用 UUID,不用时间戳,要能被后人重新算出来。
3. **一定要有租约。** 否则一次崩溃能让一条记录永久卡死。
4. **一定要有对账器。** 它是 `unknown` 唯一正确的出口,没有它,前三条都是半成品。
黑箭科技这边现在所有带副作用的工具都强制走这一层,代码审查时"有没有幂等键"是必检项。430 行不算多,但它是那种"上线时觉得多余、出事时觉得太少"的代码。
你们团队在 Agent 的工具调用上踩过重复执行的坑吗?是扣款、发券,还是重复推送数据?评论区聊聊,我想知道别人是怎么发现第一个重复的。
更多推荐

所有评论(0)