《AI Agent 技术原理与架构·运行时、协议与系统架构》2.2 执行语义:事件溯源、持久化执行与幂等副作用

Agent 的一次运行是跨越崩溃、重试与人工审批的长事务,“再跑一遍循环”不是恢复策略。本节把执行语义拆成状态机、事件溯源与持久化执行,区分 at-most-once/at-least-once/exactly-once 的真实边界,并用一个可运行的 W3 重启实验验证 CAS、幂等键与崩溃重试只执行一次副作用。

以下运行 ID、状态、工具键与数字均为教学假设,不构成对任何真实系统、供应商或生产环境的承诺。W3 的“重启服务”是一个用于展示执行语义的最小例子,真实运维系统还需要审批、变更窗口、回滚预案与审计。

一个 Agent 运行五分钟,中间调用了三个工具、等了一次人工审批、写了一次数据库。进程在写数据库之后、返回响应之前崩溃了。重启后,系统应该从哪里继续?

最常见的回答是“重新跑一遍循环”。这个回答在 W1 的只读检索里可能没问题,在 W3 的运维处置里是灾难:重启服务被执行两次,或者退款被提交两次。Agent 的运行不是一个函数调用,而是一个跨越崩溃、重试与人工等待的长事务。 执行语义要回答的,正是这个长事务在故障面前如何保持正确。

这一节讲三件事:用状态机定义合法路径,用事件溯源保存“发生过什么”,用持久化执行与幂等副作用保证“重试不会重复”。最后用一个可运行的 W3 重启实验,把三条语义放在同一个崩溃场景里验证。

三种执行语义

在讨论 Agent 之前,先把三种常见的投递语义说清楚。它们不是 Agent 特有的,而是任何分布式系统都会遇到的选择。

语义保证代价典型场景常见误解
at-most-once最多执行一次,可能丢失丢失后不重试可丢的遥测、非关键通知以为“不重试”就安全
at-least-once至少执行一次,可能重复需要幂等或去重大多数任务队列以为“重试”等于“恢复”
exactly-once端到端恰好一次需要事务、幂等或去重表资金、库存、不可逆操作以为是消息系统的一个开关

关键事实是:exactly-once 通常不是消息系统单独提供的属性,而是“至少一次投递 + 幂等消费/去重”的组合。 消息系统可以保证“同一条消息不被重复投递”在某个范围内成立,但端到端还涉及消费者、外部系统和响应丢失。Agent 的工具调用尤其如此:工具可能已经执行成功,但响应在网络上丢了;此时重试是必要的,但必须保证第二次调用不会产生第二次副作用。

所以,Agent 执行语义的目标不是追求一个抽象的 exactly-once,而是回答三个具体问题:崩溃后系统知道哪些步骤已经完成?重试时哪些动作可以安全重复、哪些必须去重?如果副作用已经发生但状态没推进,怎么把它推进到正确状态?

状态机:先定义合法路径

状态机是执行语义的骨架。它把“一次 run 现在处于什么阶段”写成有限个状态,把“允许怎么走”写成转移表。没有状态机,系统只能靠日志猜;有了状态机,非法路径可以在写入前被拒绝。

W3 的一次重启处置可以用七个状态描述:

状态含义允许转移到终态
CREATED已创建,尚未开始RUNNING、CANCELLED否
RUNNING正在执行WAITING_TOOL、WAITING_APPROVAL、SUCCEEDED、FAILED、CANCELLED否
WAITING_TOOL等待工具返回RUNNING、FAILED、CANCELLED否
WAITING_APPROVAL等待人工审批RUNNING、FAILED、CANCELLED否
SUCCEEDED成功结束无是
FAILED失败结束无是
CANCELLED用户或系统取消无是

这张表有三个设计要点。终态不可再转移:已经 SUCCEEDED 的 run 不能回到 RUNNING,要重做就创建新 run,而不是复活旧的。等待状态是显式的:等待工具和等待审批不是“RUNNING 里的一个 sleep”,而是独立状态,系统重启后才知道“我在等什么”。取消是一等状态:取消不是抛异常,而是一次合法的状态转移,取消后要能回答“已经发生的副作用怎么处理”。

状态转移还需要比较并交换(CAS)。假设两个 worker 同时看到 run 处于 RUNNING,都决定执行下一步。如果没有 CAS,两个 worker 都会执行;有了 CAS,只有一个能成功把 RUNNING 改成 WAITING_TOOL,另一个会收到“期望状态不匹配”的错误,从而放弃或重新读取。

CAS 的本质是:转移的前提是“当前状态仍然是我以为的那个状态”。 在单进程里,它可以用一个锁或原子变量实现;在生产里,它通常对应数据库的条件更新(UPDATE ... WHERE state = 'RUNNING')或行锁。无论实现方式如何,语义必须一致:旧状态写入必须失败,而不是覆盖新状态。

事件溯源:状态是日志的投影

状态机回答“现在在哪”,事件溯源回答“怎么走到这里”。事件溯源把每一次状态变化写成一条只追加的事件,当前状态由事件日志投影得到:

$$
\text{state} = \text{fold}(e_1, e_2, \ldots, e_n)
$$

一次 run 的事件日志可能长这样:

seqkind关键字段含义
1createdworkload=W3, action=restartrun 被创建
2transitionfrom=CREATED, to=RUNNING开始执行
3transitionfrom=RUNNING, to=WAITING_TOOL请求重启
4transitionfrom=WAITING_TOOL, to=RUNNING工具确认返回
5transitionfrom=RUNNING, to=SUCCEEDED健康检查通过

事件溯源带来四个好处:可审计,每一步都有记录,能回答“谁在什么时候把状态改成了什么”;可重放,给定事件日志可以重建任意时刻的状态;可投影,同一份日志可以投影出“当前状态”“每步耗时”“工具调用次数”等多个视图;可恢复,崩溃后读日志就知道走到哪了。

它也有代价,而且经常被低估:存储增长,事件只追加不删除,长任务日志会持续变大;Schema 演进,旧事件必须能被新代码读取,否则历史无法重放;隐私删除,不能简单删掉事件,否则日志出现空洞,需要加密擦除、脱敏或重写;投影性能,每次读状态都重放全部事件会很慢,需要快照或物化视图。

因此,生产系统通常是“事件日志 + 快照”的组合:事件是事实,快照是加速。快照不能替代事件,因为它丢失了“怎么走到这里”的信息;事件也不能替代快照,因为重放全部历史太慢。

持久化执行:确定性重放与副作用隔离

持久化执行(durable execution)把“工作流代码”和“副作用”分开:工作流代码负责控制流,包括顺序、条件分支和重试策略,必须是确定性的;**活动(activity)**负责副作用,包括调用模型、调用工具、写数据库,结果会被记录到日志,重放时直接返回记录的结果。

这条分界线的价值在于:崩溃后,工作流可以从头重放,但因为活动结果已经记录,不会重复产生副作用。它把“恢复”从“重新执行”变成了“重新计算控制流”。

要让重放成立,工作流代码必须避免四类不确定性:

不确定性来源错误写法正确做法
时钟在工作流里直接 now()把时间作为活动结果记录,或由外部传入
随机数在工作流里直接 random()用记录下来的随机种子或活动结果
网络在工作流里直接调用工具把调用封装成活动,记录请求与响应
模型输出在工作流里直接调用模型把模型调用封装成活动,记录完整响应

模型调用是典型的非确定性活动:同样的提示,两次调用可能得到不同结果。持久化执行不要求模型确定,只要求模型调用的结果被记录。重放时,工作流看到的是记录下来的响应,而不是重新调用模型。这也是为什么“record/replay”在 Agent 系统里如此重要:它让一次运行可以被精确复现,而不需要重新花钱、重新等待、重新承担副作用。

持久化执行还有一个容易被忽略的问题:代码版本。工作流代码会升级,但旧的事件历史还在。如果新代码在执行旧历史时走了不同的分支,重放就会失败或产生错误状态。常见做法是版本门(version gate)、为新版本创建新的工作流 ID,或者保持旧代码可运行直到旧历史全部结束。无论选哪种,都必须把“代码版本”当成执行语义的一部分,而不是部署细节。

幂等副作用:唯一键与去重

即使有事件日志和持久化执行,仍然有一个边界问题:副作用已经发生,但结果没有被记录。 比如工具真的重启了服务,但响应在返回前丢失;此时日志里只有“请求重启”,没有“重启成功”。重试是必要的,但重试不能导致第二次重启。

解决办法是幂等键:为每个副作用生成稳定键(通常由 run_id、步骤 ID、动作和资源标识组成);执行前先查这个键是否已有结果,有就直接返回;没有才执行副作用,并把结果持久化到键上;只有结果持久化成功后,才向调用方确认。

这里的关键是键不能包含 attempt 或时间戳。如果键里带了重试次数,每次重试都会生成新键,去重就失效了。键要表达的是“这是哪一次逻辑动作”,而不是“这是第几次尝试”。

键的写法是否稳定问题
run-w3-001:restart:1是推荐:run + 动作 + 资源
run-w3-001:restart:attempt-2否重试会生成新键,去重失效
restart:2026-11-08T09:20:00否时间戳变化,无法去重
user-42:restart否跨 run 冲突,可能误去重

幂等键不是万能的。它依赖一个持久、可靠、可查询的键存储;如果键存储本身丢了,去重就失效。它还依赖外部系统愿意配合:如果外部系统不支持幂等键,也不提供查询接口,端到端 exactly-once 就无法保证,只能靠对账、补偿或人工核对。架构评审时必须把这一点写清楚,而不是假设“加了幂等键就安全了”。

崩溃场景枚举

把崩溃点逐一列出来,是检查执行语义最有效的方法。下面以 W3 的重启为例:

崩溃点已发生的事实重试时的正确行为依赖的机制
副作用之前什么都没发生重新执行无
副作用之后、结果持久化之前服务已重启,键上没有结果重新执行,但外部系统必须按幂等键去重;否则只能对账外部幂等 + 对账
结果持久化之后、状态转移之前键上有结果,状态仍是 WAITING_TOOL读取键上的结果,推进状态,不重复执行幂等键 + 事件日志
状态转移之中事件可能已写入,也可能没有用 CAS 重新读取状态;已写入则继续,未写入则重试转移CAS + 事件日志
成功之后、响应返回之前状态已是 SUCCEEDED返回已成功,不重新执行终态不可变

这张表说明:“重试”本身不是恢复策略;恢复策略是“知道哪些事实已经发生,并只补做没发生的部分”。 事件日志负责“知道”,幂等键负责“不重复”,CAS 负责“不覆盖”。

最小实验:W3 重启

下面的实验把状态机、事件溯源、CAS 和幂等副作用放在一个最小实现里。它不依赖数据库、消息队列或工作流引擎;所有状态在内存里,方便观察。生产系统需要把事件日志和键存储换成持久化实现,但语义不变。

# file: agp_lab/execution_semantics.py | write
# tier: 3
# verify: python3 -m unittest tests.test_execution_semantics
"""事件溯源、比较并交换(CAS)与幂等副作用的最小实现。

这个模块不实现工作流引擎,只把三条执行语义写成可测试的代码:

1. 状态转移必须合法,终态不可再转移;
2. 状态由事件日志投影得到,重放必须得到同一结果;
3. 副作用由唯一键去重,崩溃后重试不能执行第二次。
"""
from __future__ import annotations

from dataclasses import dataclass
from enum import Enum
from typing import Any, Callable


class RunState(str, Enum):
    CREATED = "CREATED"
    RUNNING = "RUNNING"
    WAITING_TOOL = "WAITING_TOOL"
    WAITING_APPROVAL = "WAITING_APPROVAL"
    SUCCEEDED = "SUCCEEDED"
    FAILED = "FAILED"
    CANCELLED = "CANCELLED"


TRANSITIONS: dict[RunState, set[RunState]] = {
    RunState.CREATED: {RunState.RUNNING, RunState.CANCELLED},
    RunState.RUNNING: {
        RunState.WAITING_TOOL,
        RunState.WAITING_APPROVAL,
        RunState.SUCCEEDED,
        RunState.FAILED,
        RunState.CANCELLED,
    },
    RunState.WAITING_TOOL: {RunState.RUNNING, RunState.FAILED, RunState.CANCELLED},
    RunState.WAITING_APPROVAL: {RunState.RUNNING, RunState.FAILED, RunState.CANCELLED},
    RunState.SUCCEEDED: set(),
    RunState.FAILED: set(),
    RunState.CANCELLED: set(),
}


class IllegalTransition(Exception):
    """状态转移违反状态机或 CAS 前置条件。"""


@dataclass(frozen=True)
class Event:
    seq: int
    run_id: str
    kind: str
    payload: dict[str, Any]


class EventStore:
    """只追加的事件日志;run 的当前状态由投影得到,不单独保存。"""

    def __init__(self) -> None:
        self._events: list[Event] = []
        self._seq = 0

    def append(self, run_id: str, kind: str, **payload: Any) -> Event:
        self._seq += 1
        event = Event(self._seq, run_id, kind, dict(payload))
        self._events.append(event)
        return event

    def events(self, run_id: str | None = None) -> list[Event]:
        if run_id is None:
            return list(self._events)
        return [event for event in self._events if event.run_id == run_id]

    def project(self, run_id: str) -> RunState | None:
        state: RunState | None = None
        for event in self.events(run_id):
            if event.kind == "created":
                state = RunState.CREATED
            elif event.kind == "transition":
                state = RunState(event.payload["to"])
        return state

    def transition(
        self,
        run_id: str,
        expected: RunState,
        target: RunState,
        reason: str = "",
    ) -> RunState:
        current = self.project(run_id)
        if current != expected:
            raise IllegalTransition(
                f"CAS failed: {run_id} is {current}, expected {expected}"
            )
        if target not in TRANSITIONS[current]:
            raise IllegalTransition(f"illegal: {current} -> {target}")
        self.append(
            run_id,
            "transition",
            **{"from": current.value, "to": target.value, "reason": reason},
        )
        return target


@dataclass(frozen=True)
class ToolResult:
    key: str
    value: Any
    execution_no: int


class IdempotentExecutor:
    """以唯一键去重副作用;重复调用返回第一次的结果。"""

    def __init__(self) -> None:
        self._results: dict[str, ToolResult] = {}
        self.executions = 0

    def execute(self, key: str, action: Callable[[], Any]) -> ToolResult:
        if key in self._results:
            return self._results[key]
        self.executions += 1
        value = action()
        result = ToolResult(key, value, self.executions)
        self._results[key] = result
        return result

    def get(self, key: str) -> ToolResult | None:
        return self._results.get(key)


def demo() -> dict[str, Any]:
    """模拟 W3 的一次重启:副作用完成后、状态确认前崩溃,再重试。"""
    store = EventStore()
    executor = IdempotentExecutor()
    run_id = "run-w3-001"
    side_effect_calls = 0

    store.append(run_id, "created", workload="W3", action="restart")
    store.transition(run_id, RunState.CREATED, RunState.RUNNING, "accepted")
    store.transition(run_id, RunState.RUNNING, RunState.WAITING_TOOL, "restart requested")

    def restart_service() -> str:
        nonlocal side_effect_calls
        side_effect_calls += 1
        return "restarted"

    first = executor.execute(f"{run_id}:restart:1", restart_service)
    # 模拟崩溃:副作用已经发生,但还没有把 WAITING_TOOL 推进到 RUNNING。
    retry = executor.execute(f"{run_id}:restart:1", restart_service)
    store.transition(run_id, RunState.WAITING_TOOL, RunState.RUNNING, "tool ack recovered")
    store.transition(run_id, RunState.RUNNING, RunState.SUCCEEDED, "health check passed")

    return {
        "events": store.events(run_id),
        "final_state": store.project(run_id),
        "side_effect_calls": side_effect_calls,
        "executions": executor.executions,
        "same_result": first == retry,
    }


if __name__ == "__main__":
    result = demo()
    print(f"{'seq':<4}{'kind':<12}{'from':<18}{'to':<18}{'reason'}")
    for event in result["events"]:
        payload = event.payload
        print(
            f"{event.seq:<4}{event.kind:<12}"
            f"{payload.get('from', '-'):<18}"
            f"{payload.get('to', payload.get('action', '-')):<18}"
            f"{payload.get('reason', '')}"
        )
    print(f"final_state={result['final_state'].value}")
    print(f"side_effect_calls={result['side_effect_calls']}")
    print(f"executor.executions={result['executions']}")
    print(f"same_result={result['same_result']}")

运行:

cd private/labs/agp-lab
python3 -m agp_lab.execution_semantics

输出:

seq kind        from              to                reason
1   created     -                 restart
2   transition  CREATED           RUNNING           accepted
3   transition  RUNNING           WAITING_TOOL      restart requested
4   transition  WAITING_TOOL      RUNNING           tool ack recovered
5   transition  RUNNING           SUCCEEDED         health check passed
final_state=SUCCEEDED
side_effect_calls=1
executor.executions=1
same_result=True

实验模拟的崩溃点是:工具副作用已经执行,WAITING_TOOL → RUNNING 的状态转移还没有发生。重试时使用同一个键 run-w3-001:restart:1,执行器直接返回第一次的结果;因此 side_effect_calls=1,executor.executions=1,两次结果相同。随后状态从 WAITING_TOOL 推进到 RUNNING,再到 SUCCEEDED。

这个实验刻意省略了三件事,生产系统不能省:

  1. 持久化:事件日志和键存储都在内存里,进程退出就丢;生产要用数据库或日志系统。
  2. 并发:实验是单线程的;生产里多个 worker 可能同时处理同一个 run,CAS 必须落到数据库的条件更新或行锁。
  3. 外部幂等:实验里的副作用是一个本地函数;生产里的工具可能不支持幂等键,需要额外的对账或补偿。

架构判据

执行语义是否合格,可以用八条判据检查:

判据合格的样子不合格的样子
状态机状态、转移、终态显式定义靠 if/else 和日志猜状态
CAS每次转移校验期望状态先查再改,两个 worker 都能写
幂等键每个副作用有稳定唯一键重试就重新执行
结果持久化副作用结果先落盘再确认先返回成功,再异步写日志
活动隔离模型/工具调用封装成活动并记录工作流里直接调用网络
确定性工作流不直接读时钟/随机数重放时走出不同分支
版本事件 schema 与工作流版本可演进升级后旧历史无法重放
审批与取消作为事件处理,可恢复内存里等待,重启即丢

这八条不需要一次性全做到。W1 的只读检索可以只做状态机与幂等键;W3 的不可逆操作至少要做状态机、CAS、幂等键、结果持久化和审批事件。判据的作用是让“做到什么程度”变成一个有依据的决定,而不是一句“我们加了重试”。

小结

  • Agent 的一次运行是长事务,不是函数调用;“重新跑一遍循环”不是恢复策略。
  • at-most-once、at-least-once、exactly-once 是三种不同的保证;端到端 exactly-once 通常靠“至少一次投递 + 幂等/去重”实现。
  • 状态机定义合法路径,终态不可再转移;CAS 保证并发下只有一个 worker 能推进状态。
  • 事件溯源把状态变成日志的投影,带来可审计、可重放、可投影、可恢复;代价是存储、Schema 演进、隐私删除和投影性能。
  • 持久化执行把控制流与副作用分开:工作流确定性重放,活动结果记录后复用。
  • 幂等键必须稳定,不能包含 attempt 或时间戳;它依赖持久键存储与外部系统配合。
  • 崩溃场景要逐点枚举;“重试”不是策略,“知道哪些事实已经发生”才是。

下一节会把崩溃恢复展开:重放、补偿与故障注入分别验证什么,以及哪些故障是执行语义解决不了的。

阅读导航:上一节:2.1 状态机:状态、转移、守卫 · 下一节:2.3 崩溃恢复:重放、补偿与故障注入 。

常见错误与边界

  1. 把重试当恢复。 重试只能解决“没执行”的情况;如果副作用已经发生,重试会制造第二次副作用。
  2. 把 exactly-once 当消息属性。 消息系统可以提供至少一次或至多一次;端到端恰好一次需要幂等、去重或事务,不能只靠一个开关。
  3. 在工作流里直接读时钟或随机数。 重放时这些值会变,控制流会走出不同分支;必须把它们记录成活动结果或外部输入。
  4. 幂等键包含 attempt。 每次重试生成新键,去重直接失效;键要标识逻辑动作,不是尝试次数。
  5. 先确认成功,再持久化结果。 崩溃会留下“外部已成功、内部不知道”的状态;正确顺序是先持久化结果,再确认。
  6. 忽略事件 Schema 与隐私删除。 事件只追加不等于可以永远不删;旧事件要能重放,用户数据要能按合规要求删除或擦除。

继续阅读

探索更多技术文章

浏览归档,发现更多关于系统设计、工具链和工程实践的内容。

全部文章 返回首页

「books」更多文章

  1. 《大规模分布式计算深入解析》15.3 落地:从 Neo4j 到自研图引擎
  2. 《大规模分布式计算深入解析·图计算与图数据库内核》 · 目录与学习路径(45 篇)
  3. 《大规模分布式计算深入解析》15.2 十一卷主线:从切分到图