# Agent 执行到一半失败，回滚救不了你

> Saga 记下每个已提交步骤的撤销方法，撤销本身也失败时，就交给人工处理。

原文: https://fdetimes.net/zh/guides/saga-pattern-agent-failures-multiple-systems/

设想一个 Agent 正在处理客户的退款申请。它先在库存系统中预留商品，再在 ERP 中创建贷项通知单，最后发送确认邮件。第二步返回错误，但第一步已经提交。库存系统里现在压着一批没人需要的货。

没有哪个事务能同时覆盖这三个系统，所以无从回滚。Saga 正是为这种情况而生：按照 Azure Architecture Center 的说法，一个大操作被拆成一系列本地事务，某一步失败时，Saga 运行补偿事务，撤销此前已完成的步骤。

对前线部署工程师（FDE）来说，这是日常工作，而不是分布式系统理论。Agent 对客户系统的写权限越多，评审中就越早会有人问：执行到一半失败怎么办？本指南用 Python 搭一个小型编排器，让你能给出具体的回答。

## 要构建什么，需要准备什么？

最终得到一个按顺序执行三个步骤的编排器。它记录每一步，遇到瞬时错误时重试，无法继续推进时依据日志补偿，补偿本身失败时把 Saga 标记为待人工审核。你只需要 Python 3 和一个编辑器。

这里所有外部系统都是模拟函数。代码为讲解原理做了简化，不能直接用于生产环境。

## 第 1 步：哪些步骤无法撤销？

写代码之前，先给每个步骤分类。Microsoft 的 Saga 文档把无法撤销的步骤称为关键事务（pivot transaction）：关键事务一旦成功，补偿就失去意义，之后的步骤必须可以一直重试直到完成。

发给客户的邮件是典型例子，因为谁也撤不回来。由此得出的设计规则很明确：不可撤销的步骤，只有在所有重要检查都通过之后才能运行。

```python
STEPS = [
    {"name": "reserve_stock", "kind": "compensable", "undo": "release_stock"},
    {"name": "create_credit_note", "kind": "compensable", "undo": "void_credit_note"},
    {"name": "send_customer_email", "kind": "pivot", "undo": None},
]
```

**检查：**所有 `undo` 为 `None` 的步骤都必须位于列表末尾。如果 Agent 需要在流程中途发邮件，说明这个流程应该拆成两个工作流，各自以一个不可撤销的步骤结尾。

## 第 2 步：边执行边记录每一步的撤销方法

核心机制是记录每一步的信息以及撤销方法。操作失败时，工作流沿着已完成的步骤往回走。日志必须存放在进程内存之外，并在启动时重新读取；否则一次崩溃就会抹掉全部进度。

```python
import json, os

class SagaLog:
    def __init__(self, path):
        self.path = path
        self.entries = []
        if os.path.exists(path):  # 崩溃后重新运行：加载之前的进度
            with open(path) as f:
                self.entries = json.load(f)

    def record(self, step, status, undo=None):
        self.entries.append({"step": step, "status": status, "undo": undo})
        with open(self.path, "w") as f:
            json.dump(self.entries, f, indent=2)

    def is_undone(self, step):
        return any(e["step"] == step and e["status"] == "undone" for e in self.entries)
```

**检查：**调用 `record`，杀掉进程，再用同一路径新建一个 `SagaLog`。`entries` 必须恰好包含你写入的那几行，每行都说明哪一步已完成、用哪个命令撤销。

## 第 3 步：重复调用会不会破坏数据？

重试意味着一个步骤可能执行不止一次，所以每一步都必须是幂等命令。Stripe 是一个真实的例子：对每个幂等键，Stripe 都会保存第一次请求的状态码和响应体，无论成功还是失败，之后凡是使用同一个键的重试，都返回同样的结果。

```python
def idem_key(saga_id, action):
    return f"{saga_id}:{action}"

_seen = {}  # 模拟客户系统按键保存结果
def fake_reserve_stock(key):
    if key not in _seen:
        _seen[key] = {"reserved": 5}
    return _seen[key]
```

**检查：**用同一个键调用两次 `fake_reserve_stock`，库存只能被预留一次。

## 第 4 步：先重试，再补偿

一次短暂的网络抖动，不值得取消整个事务。只有在工作流无法继续推进时才补偿：重试次数已用完，或者明确知道错误不是瞬时的。

```python
class Transient(Exception): pass
class Permanent(Exception): pass

def run_with_retry(fn, key, attempts=3):
    for _ in range(attempts):
        try:
            return fn(key)
        except Transient:
            continue
    raise Permanent(f"重试次数已用完：{key}")

def run_saga(saga_id, steps, systems, log, priority=()):
    done = []
    for s in steps:
        try:
            run_with_retry(systems[s["name"]], idem_key(saga_id, s["name"]))
            log.record(s["name"], "done", s["undo"])
            done.append(s)
        except Permanent:
            log.record(s["name"], "failed")
            # 根据补偿结果返回 "compensated" 或 "needs_human"
            return compensate(saga_id, done, systems, log, priority)
    return "completed"
```

这就是 Microsoft Saga 文档中描述的编排（orchestration）方式：编排器发送请求，保存并解读每个任务的状态，通过补偿事务处理恢复。代价是编排器本身可能成为故障点，这也是日志必须落盘的又一个原因。

## 第 5 步：按什么顺序补偿？补偿失败怎么办？

默认按执行顺序倒序撤销，但这并非硬性要求。对不一致最敏感的数据存储应当最先撤销。在这个例子里，财务 ERP 大概比仓库更重要。

补偿同样可能失败。因此系统需要记录进度，以便从失败的确切位置继续。有时它必须停下来，交给人处理，并发出说明原因的告警。

```python
def compensate(saga_id, done, systems, log, priority=()):
    ordered = sorted(reversed(done), key=lambda s: s["name"] not in priority)
    for s in ordered:
        if log.is_undone(s["name"]):
            continue  # 之前的运行中已补偿，跳过
        try:
            run_with_retry(systems[s["undo"]], idem_key(saga_id, s["undo"]))
            log.record(s["name"], "undone")
        except Permanent as e:
            log.record(s["name"], "needs_human", str(e))  # 为简洁起见，把原因存在 undo 字段里
            return "needs_human"  # 停下来，等待人工审核
    return "compensated"
```

返回状态很容易被忽视。如果补偿中途停下，`run_saga` 仍然报告 "compensated"，调用方就会以为一切都已清理干净，而仓库里其实还压着货。所以 `needs_human` 必须是一个独立的状态，调用方可以检查它并据此触发告警。

**检查：**让 `create_credit_note` 抛出 `Permanent`。日志必须依次显示 `reserve_stock` 完成、`create_credit_note` 失败、`reserve_stock` 已撤销；`run_saga` 必须返回 `"compensated"`，且邮件始终没有发出。再让 `release_stock` 也失败：日志必须停在 `needs_human`，`run_saga` 必须返回 `"needs_human"`。修好 `release_stock`，用同一文件新建一个 `SagaLog`，再次调用 `compensate`：已标记为 `undone` 的步骤会被跳过，只补偿未完成的步骤。

## 第 6 步：两个 Saga 涉及同一个客户

假设一位客户接连发来两个请求。如果两个 Saga 并行处理同一个订单，其中一个的补偿步骤可能插进另一个的正向步骤之间。顺序护送（Sequential Convoy）模式的做法是按订单 ID 之类的键给消息分组。每组内部按顺序处理，不同组之间仍然并行。

这种做法的陷阱是毒消息（poison message）。一条反复失败的消息会堵住同一会话中排在它后面的所有消息。你需要统计投递次数，超过重试阈值后把消息移入死信队列。示例代码没有实现这一点，但在生产环境中不要省掉。

## 常见错误

最常见的错误是把补偿当成撤销按钮。Wikipedia 将补偿事务定义为一个新事务，用于撤销某个已提交事务的影响，这一点使它有别于回滚。

补偿也不会让系统回到最初的状态。它必须考虑并发进行的工作，而这部分逻辑取决于具体应用。

**要点:** 补偿步骤是一个新事务，不是撤销按钮。

第二个错误是忘了 Saga 缺少隔离性。原步骤的结果在补偿之前就对其他系统可见，因此可能出现更新丢失或脏读。常见的应对办法有几种：语义锁（应用层的标记，表示某条记录正在更新）、可交换的更新，以及写入前重新读取值。

第三个错误来自 Agent 本身。对于含糊或影响重大的情况，工作流应当暂停，等待人工审核。不要让 LLM 决定是否补偿。让编排器按规则决定，Agent 只负责提建议。

## 这项技能在客户现场是什么样子？

第一周不要急着写编排器。先和客户的运维团队坐下来，逐个询问 Agent 要写入的 API：是否接受幂等键？撤销命令是什么？撤销失败时谁有权介入？这张答案表就是你的 `STEPS`。

阅读 FDE 岗位描述时，留意“multi-system workflows”“ERP/CRM integration”“agents with write access”这类说法。简历上一句“为退款 Agent 设计 Saga：隔离关键步骤，每次写入都带幂等键，补偿失败时有升级处理流程”，比任何“具备分布式系统经验”的说法都更有分量。

Agent 总有一天会执行到一半失败。事故过后，客户记住的是你能否立刻打开一份日志文件，说清哪些步骤已执行、哪些已补偿、哪些在等待人工审核。

**本周动手试试:**

- 挑一个你正在做的 Agent 工作流，列出它对外部系统的每一次写入，并把每一次标记为可补偿、关键步骤或可重试。
- 运行本指南中的编排器，故意让第二步永久失败，再让补偿也失败，每次运行后读一遍 saga_log.json。
- 确认客户的 API 是否支持幂等键。如果不支持，直接在设计文档中写明重复调用的风险。

## 信源

- [Compensating Transaction Pattern - Azure Architecture Center | Microsoft Learn](https://learn.microsoft.com/en-us/azure/architecture/patterns/compensating-transaction)

- [Saga Design Pattern - Azure Architecture Center | Microsoft Learn](https://learn.microsoft.com/en-us/azure/architecture/patterns/saga)

- [Sequential Convoy Pattern - Azure Architecture Center | Microsoft Learn](https://learn.microsoft.com/en-us/azure/architecture/patterns/sequential-convoy)

- [Idempotent requests | Stripe API Reference](https://docs.stripe.com/api/idempotent_requests)

- [Compensating transaction - Wikipedia](https://en.wikipedia.org/wiki/Compensating_transaction)
