Token Lab搜索

可靠的 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.py
python3 agent-action-recovery.py
Python 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 边界。

预测、检验与证据记录

展开答案前先预测一个结果;练习后记录差异和迁移测试。记录仅存本地,在不同语言版本间共用。

打开记录/导出/清除 →

数学复核范围逐篇记录,不代表完成论文实证复现;可在笔记中记录疑似错误。 复核范围

参考资料与延伸学习

继续学习:Agent 调度