可靠的 Agent 操作:超时、重试与故障恢复
从一笔电商退款的授权意图追踪到最终核对结果,系统讲解持久化状态、幂等、重试预算与人工接管,并用本地可运行实现验证确认消息丢失和重启后的恢复。
来源与版本详情
本文目录
1. Agent 放弃等待时,退款可能已经成功
客户要求为订单 7 退款 25 美元。模型提出操作,策略服务批准,支付方接受请求;但响应在 Agent 保存成功状态之前丢失。天真的实现报告失败并再次退款。两次模型推理可能都没有错误,业务损失却已经发生。我们的目标是让同一个已批准的业务意图穿过不确定的通信过程,仍保持身份一致,而不是让对话看起来成功。
副作用指改变外部系统的操作。确认消息是传给调用方的证据,缺少消息不能证明操作没有发生。幂等是一种接口契约:对同一个已标识意图的重复提交不会产生额外效果。持久性指状态能在明确的故障模型下存活。这些概念互不等价:持久日志也可以准确记录两笔重复扣款。先修知识是数据库事务、请求响应通信和权限控制。事务保护的是自身数据库内的操作,不会自动覆盖远程 HTTP 调用。
本文适用于创建工单、预留库存、发起已批准退款的 Agent。只读搜索需要新鲜度和重试预算,但通常不需要支付式的效果核对。不可逆、非幂等且没有状态查询接口的操作,需要人工处理或重构集成。下文是原创参考设计;下载程序使用两个本地数据库,不调用真实支付或模型接口。
2. 将规划权限与执行权限分离
规划器输出候选工具名和参数。确定性执行关口校验结构、租户、订单归属、金额与审批有效期。审批前将金额规范为整数最小货币单位:2500 美分等于 25 美元,真实系统还必须记录币种。审批绑定操作 ID、规范化参数摘要及策略版本。改变金额就产生了需要重新审批的新意图;重试同一个意图则保留原 ID。
执行器先持久保存意图,再发送请求。支付方拥有权威效果记录。核对器查询支付方,只根据已验证证据推进本地状态。界面明确区分处理中、已确认、结果未知和已拒绝。工具输出是不可信数据,不能扩大权限或批准下一笔购买。发出新的变更请求前必须重新检查授权;查询既有操作状态则属于另一项能力权限。
架构中有两个独立边界:本地数据库事务与远端支付方事务,中间存在网络间隙。Outbox 可以在本地事务中同时保存业务意图与待派发记录,再至少投递一次;它不能让远端效果与本地事务原子提交。所有变更请求必须经过执行关口。核对路径只读远端状态并留证,不能悄悄触发补偿。
3. 把不确定性建模为状态
发送前持久保存 PREPARED。SUBMITTED 表示请求可能已经发出,不代表对方接受。匹配意图的成功证据允许转为 SUCCEEDED。确认丢失或提交后崩溃产生 UNKNOWN,或者留下必须核对的 SUBMITTED。只有明确拒绝才应标记 REJECTED,超时不是拒绝证据。对方返回未找到时,也要考虑可见性延迟和仍在途的请求;此时能否安全重复同一个 key,取决于明确的幂等契约。
有三个关键崩溃窗口。本地意图提交前,不允许发送。意图提交后、发送前,恢复可以继续同一个操作。远端已提交、本地成功未提交时,恢复必须查远端或重复同一个可去重操作。每次重试生成新 UUID 会破坏最后一个窗口的身份连续性。用已有的业务操作身份派生 key,或者在发送前通过独立的持久步骤保存生成的 key。
取消只在可能的范围内停止后续工作,不能撤销已完成效果。取消与退款提交竞态发生时,应展示核对后的结果,将后续补救视为新的授权操作。补偿有自身业务语义和失败模式,不是原子回滚。LangGraph 当前的容错文档也区分节点重试和外部效果,并把缺失确认视为未知。真实实现需要固定框架版本;本文代码不依赖框架版本。
4. 幂等需要明确的归属、作用域与保留期限
支付方记录可按租户与操作 ID 建唯一键,同时保存意图摘要、终态结果及保留规则。去重和效果必须在该系统自己的边界内原子完成。客户端先查询再无保护地写入是不够的:两个 worker 都可能看到不存在,然后都执行。参考代码使用唯一键和事务;生产支付方必须提供等价契约。
不要用原始 prompt 的哈希,或仅用模型生成的 tool-call ID 作为业务身份。无意义的空格会改变原始哈希,而两笔有意发起、金额相同的退款必须能被区分。对已校验参数规范化,但将操作身份与摘要分开。本例仅摘要订单与整数美分;生产还需纳入币种、账户、操作类型和 schema 版本。同一个 key 出现不同摘要,应报冲突而不是覆盖历史。
保留期限是实质边界。Stripe API v1 文档说明响应重放、参数冲突检查,以及 key 至少保留 24 小时后可清理;API v2 的失败操作语义有所不同。这是特定提供方的契约,不能推广成通用保证。如果恢复周期长于去重保留期,必须停止自动变更,先用持久业务标识核对。必要时保留精简的历史标记或业务账本,key 本身不要包含敏感个人信息。
5. 截止时间与重试预算,防止恢复放大故障
Timeout 限制一次等待,deadline 限制整个操作。剩余预算 R 等于截止时刻 D 减当前时刻 t。为最终状态落盘与返回预留 F 秒。新的尝试需要退避 b、调用超时 T,只有 b+T+F 不大于 R 才能开始。原创算例:总预算 30 秒,已经过去 18 秒,F=2、T=4。如果退避 8 秒,需要 14 秒,不能开始;退避 2 秒则需要 8 秒,能放进剩余 12 秒。进程内使用单调时钟,跨服务传播受限的剩余时长。
先分类再重试。参数错误、权限拒绝和明确业务拒绝不是暂态网络错误。暂态错误使用有限尝试次数、带抖动的指数退避、共享重试预算和依赖并发上限。下式定义 full jitter:尝试序号 i 从零开始,base 与 cap 的单位为秒,延迟在零与该次上限之间均匀抽取。抖动分散请求,不减少允许的尝试总数。
嵌套策略会乘法放大:三层各允许三次尝试,最坏产生 27 次叶子调用。要么指定唯一重试负责人,要么显式约束整棵调用树。假设每次独立失败概率为 0.2,最多三次尝试,期望次数是 1+0.2+0.04=1.24;相关性过载不满足独立假设。即使概率估算失效,预算仍应限制放大。gRPC 的 deadline 传播有助于停止无效下游工作,但应用自己启动的任务也必须配合取消。
公式中 b_0 是基础延迟,b_max 是延迟上限,i 是从零开始的重试序号,A 是尝试次数,m 是最大允许次数,p 是独立的单次失败概率。A、m 为计数,p 无量纲,期望值包含首次尝试。
6. 持久执行与可观测性解决不同问题
图检查点保存控制状态,工具账本记录有身份的效果,审计记录谁批准了什么、哪些证据支持结果,trace 衡量尝试、排队与延迟,四者不能互相替代。LangGraph 区分线程检查点与跨线程 store;内存示例适合开发,但不能证明崩溃持久性。在重放边界保存模型输出或决策,防止恢复时再次询问随机规划器,给同一个审批中途生成不同操作。
记录操作 ID、租户、意图摘要、审批版本、尝试 ID、deadline、远端引用、状态转换与脱敏错误类别。一个业务操作可以有多次网络尝试,两种身份必须分开。观察 UNKNOWN 数量与存留时间、每个已批准意图的效果数、冲突率、重试放大率及核对完成时长。若远端随后确认,不能把此前的网络超时统计成退款失败。日志与保留策略也需要权限保护,因为工具参数可能含个人数据。
多个执行器需要任务租约,并在目标支持时使用 fencing generation。租约过期不会杀死旧 worker;没有 fencing 或提供方幂等时,它仍可能执行。不要把本地互斥锁画出来就称为分布式互斥。本文代码刻意只用单执行器和事务化提供方模型,不实现分布式租约、跨区域切换或真实授权服务。
7. 选择能保住契约的最小恢复机制
只读查询可在 deadline 内重试并标注陈旧数据。具备幂等与状态查询的变更应先核对,再在有效授权下重复同一个 key。只有去重、没有查询的接口,能否通过重发恢复响应取决于提供方的保留期限和错误语义。非幂等且没有可靠状态查询的操作,应停止并交给人工调查。自动重试不能凭空补出缺失的契约。
当大量长运行步骤、定时器和人工审批需要持久编排时,工作流引擎有价值;单次本地纯计算则不需要这种复杂度。事务 outbox 保证本地派发可靠性,saga 定义跨步骤的业务补偿,两者都不能让任意第三方接口变成 exactly-once。退款案例中,只读核对器比让规划器从客户邮件猜测成功、或立即反向支付更安全。
未解决的工程边界包括去重过期、核对时远端不可用、状态 schema 迁移、迟到回调、乱序事件与多区域归属。为意图 schema 编版本,保留每次终态转换的证据,并定义有负责人接手的人工队列。生产验收目标是每种不确定窗口都有明确安全行为,不是承诺 Agent 永不失败。下面实践只验证其中一个有限子集,不认证真实支付集成。
| 机制 | 保护什么 | 不保证什么 |
|---|---|---|
| 检查点 | 工作流状态 | 外部效果只执行一次 |
| Outbox | 本地意图与派发记录 | 跨提供方原子提交 |
| 幂等 key | 同意图去重 | 无限保留或授权 |
| 状态核对 | 远端结果的证据 | 远端接口始终可用 |
实践与验证
Python 3.11+,只用标准库。执行 python3 agent-action-recovery.py,无密钥、网络或真实副作用,无随机性,因此不需要种子。两个临时 SQLite 文件将 Agent 状态与模拟支付方分离;提供方在自身事务中同时提交去重记录和模拟退款,不存在跨两个文件的事务。预期输出 PASS 和 effects=3; duplicate-effects=0。三个效果是 shop 的两个不同操作与另一个租户的一笔操作。断言覆盖确认丢失、重开本地状态、参数冲突、写权限过期、远端提交后的崩溃窗口及重复投递。这不是实际 IAM、进程强杀持久性、网络或退款额度测试。公平对照:在同一丢失确认位置,让基线生成新的操作 ID 再提交,观察多出的效果,然后恢复稳定 ID,保持业务输入与故障位置一致。生产前还应补充延迟可见性、提供方报错、预算耗尽与并发执行器实验。
agent-action-recovery.pypython3 agent-action-recovery.pyPython 3.11+
"""Python 3.11+, standard library. Local teaching model; never contacts a provider."""
import hashlib
import json
import sqlite3
import tempfile
from pathlib import Path
def connect(path):
db = sqlite3.connect(path)
db.execute('PRAGMA synchronous=FULL')
return db
def fingerprint(order, cents):
if type(cents) is not int or cents <= 0:
raise ValueError('positive integer cents required')
return hashlib.sha256(json.dumps([order, cents], separators=(',', ':')).encode()).hexdigest()
class Provider:
"""One transactional SQLite database models the external system's contract."""
def __init__(self, path):
self.db = connect(path)
self.db.executescript('''
CREATE TABLE IF NOT EXISTS refunds (
tenant TEXT, op TEXT, digest TEXT, cents INTEGER,
PRIMARY KEY (tenant, op));
''')
def submit(self, tenant, op, digest, cents):
# Atomic deduplication + effect, not a client-side check-then-act.
with self.db:
self.db.execute('BEGIN IMMEDIATE')
old = self.db.execute('SELECT digest FROM refunds WHERE tenant=? AND op=?',
(tenant, op)).fetchone()
if old and old[0] != digest:
raise ValueError('provider key conflict')
if not old:
self.db.execute('INSERT INTO refunds VALUES (?,?,?,?)',
(tenant, op, digest, cents))
return {'state': 'succeeded', 'digest': digest}
def status(self, tenant, op):
row = self.db.execute('SELECT digest FROM refunds WHERE tenant=? AND op=?',
(tenant, op)).fetchone()
return None if row is None else {'state': 'succeeded', 'digest': row[0]}
def count(self):
return self.db.execute('SELECT COUNT(*) FROM refunds').fetchone()[0]
class AgentExecutor:
def __init__(self, path, provider):
self.db, self.provider = connect(path), provider
self.db.execute('''CREATE TABLE IF NOT EXISTS operations (
tenant TEXT, op TEXT, digest TEXT, order_id TEXT, cents INTEGER,
state TEXT, PRIMARY KEY(tenant,op))''')
self.db.commit()
def state(self, tenant, op):
row = self.db.execute('SELECT state FROM operations WHERE tenant=? AND op=?',
(tenant, op)).fetchone()
return row[0] if row else None
def mark(self, tenant, op, state):
with self.db:
self.db.execute('UPDATE operations SET state=? WHERE tenant=? AND op=?',
(state, tenant, op))
def execute(self, tenant, op, order, cents, *, authorized, lose_ack=False,
crash_after_provider=False):
digest = fingerprint(order, cents)
row = self.db.execute('SELECT digest,state FROM operations WHERE tenant=? AND op=?',
(tenant, op)).fetchone()
if row and row[0] != digest:
raise ValueError('same operation ID with different intent')
if row and row[1] == 'succeeded':
return 'succeeded'
if not row:
if not authorized:
return 'blocked'
with self.db:
self.db.execute('INSERT INTO operations VALUES (?,?,?,?,?,?)',
(tenant, op, digest, order, cents, 'prepared'))
# Reconcile first, even if permission to create a new effect has expired.
# This demo assumes a separate permission to inspect this tenant's status.
result = self.provider.status(tenant, op)
if result:
if result['digest'] != digest:
raise ValueError('status intent mismatch')
self.mark(tenant, op, 'succeeded')
return 'succeeded'
if not authorized:
return 'blocked'
# A missing status alone is NOT proof of no effect. Safe repeat here depends
# on Provider.submit's durable atomic idempotency contract, with no expiry.
self.mark(tenant, op, 'submitted')
self.provider.submit(tenant, op, digest, cents)
if crash_after_provider:
raise RuntimeError('injected crash after provider commit')
if lose_ack:
self.mark(tenant, op, 'unknown')
return 'unknown'
self.mark(tenant, op, 'succeeded')
return 'succeeded'
def run():
with tempfile.TemporaryDirectory() as folder:
root = Path(folder)
provider = Provider(root / 'provider.sqlite')
client = AgentExecutor(root / 'agent.sqlite', provider)
assert client.execute('shop', 'refund-1', 'order-7', 2500,
authorized=True, lose_ack=True) == 'unknown'
assert provider.count() == 1
client.db.close()
client = AgentExecutor(root / 'agent.sqlite', provider)
assert client.execute('shop', 'refund-1', 'order-7', 2500,
authorized=False) == 'succeeded'
assert provider.count() == 1
try:
client.execute('shop', 'refund-1', 'order-7', 3000, authorized=True)
raise AssertionError('changed intent accepted')
except ValueError:
pass
assert client.execute('shop', 'refund-2', 'order-8', 500,
authorized=False) == 'blocked'
try:
client.execute('shop', 'refund-3', 'order-9', 700,
authorized=True, crash_after_provider=True)
except RuntimeError:
pass
assert client.state('shop', 'refund-3') == 'submitted'
client.db.close()
client = AgentExecutor(root / 'agent.sqlite', provider)
assert client.execute('shop', 'refund-3', 'order-9', 700,
authorized=True) == 'succeeded'
# Direct duplicate delivery exercises provider-side atomic deduplication.
d = fingerprint('order-9', 700)
provider.submit('shop', 'refund-3', d, 700)
assert provider.count() == 2
# Distinct tenant namespace: same op is a different operation.
assert client.execute('shop-2', 'refund-3', 'order-9', 700,
authorized=True) == 'succeeded'
assert provider.count() == 3
client.db.close()
provider.db.close()
print('PASS: lost acknowledgement, restart, conflict, expired permission, crash window, duplicate delivery, tenant namespace')
print('effects=3; duplicate-effects=0; no network; deterministic; no random seed needed')
if __name__ == '__main__':
run()
原创模拟面试题,非公司真题
超时为何不能证明退款失败?
提示
区分效果提交与响应送达。
答案与分析
提供方可能先提交,响应随后丢失。保留未知状态并核对,不要生成新的业务意图。
图检查点能保证支付 exactly-once 吗?
提示
找出两个事务边界。
答案与分析
不能。外部效果发生后,恢复仍可能重跑节点。必须依赖提供方原子幂等契约或可靠核对程序。
审批过期应阻止核对吗?
提示
区分只读权限与变更权限。
答案与分析
它应阻止新的写操作。状态查询可在另一项有效权限下继续;示例明确假设此权限存在。状态返回不能续期审批。
重复操作何时会重新变得不安全?
提示
检查保留期、参数与作用域。
答案与分析
去重过期、换了 key、意图改变或跨越约定命名空间时。应停止并核对,而不是静默生成替代 key。
评分:1 分解释超时与幂等;2 分识别不确定性;3 分运行并解释恢复;4 分设计故障对照;5 分明确保留期、授权与多 worker 边界。
预测、检验与证据记录
展开答案前先预测一个结果;练习后记录差异和迁移测试。记录仅存本地,在不同语言版本间共用。
打开记录/导出/清除 →数学复核范围逐篇记录,不代表完成论文实证复现;可在笔记中记录疑似错误。 复核范围
参考资料与延伸学习
- AWS · Making retries safe with idempotent APIshttps://aws.amazon.com/builders-library/making-retries-safe-with-idempotent-APIs/
- AWS · Timeouts, retries and backoff with jitterhttps://aws.amazon.com/builders-library/timeouts-retries-and-backoff-with-jitter/
- AWS · Transactional outboxhttps://docs.aws.amazon.com/prescriptive-guidance/latest/cloud-design-patterns/transactional-outbox.html
- LangGraph · Fault tolerancehttps://docs.langchain.com/oss/python/langgraph/fault-tolerance
- LangGraph · Persistencehttps://docs.langchain.com/oss/python/langgraph/persistence
- Stripe · Idempotent requestshttps://docs.stripe.com/api/idempotent_requests
- gRPC · Deadlineshttps://grpc.io/docs/guides/deadlines/