以下运行 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 的事件日志可能长这样:
| seq | kind | 关键字段 | 含义 |
|---|---|---|---|
| 1 | created | workload=W3, action=restart | run 被创建 |
| 2 | transition | from=CREATED, to=RUNNING | 开始执行 |
| 3 | transition | from=RUNNING, to=WAITING_TOOL | 请求重启 |
| 4 | transition | from=WAITING_TOOL, to=RUNNING | 工具确认返回 |
| 5 | transition | from=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。
这个实验刻意省略了三件事,生产系统不能省:
- 持久化:事件日志和键存储都在内存里,进程退出就丢;生产要用数据库或日志系统。
- 并发:实验是单线程的;生产里多个 worker 可能同时处理同一个 run,CAS 必须落到数据库的条件更新或行锁。
- 外部幂等:实验里的副作用是一个本地函数;生产里的工具可能不支持幂等键,需要额外的对账或补偿。
架构判据
执行语义是否合格,可以用八条判据检查:
| 判据 | 合格的样子 | 不合格的样子 |
|---|---|---|
| 状态机 | 状态、转移、终态显式定义 | 靠 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 崩溃恢复:重放、补偿与故障注入 。
常见错误与边界
- 把重试当恢复。 重试只能解决“没执行”的情况;如果副作用已经发生,重试会制造第二次副作用。
- 把 exactly-once 当消息属性。 消息系统可以提供至少一次或至多一次;端到端恰好一次需要幂等、去重或事务,不能只靠一个开关。
- 在工作流里直接读时钟或随机数。 重放时这些值会变,控制流会走出不同分支;必须把它们记录成活动结果或外部输入。
- 幂等键包含 attempt。 每次重试生成新键,去重直接失效;键要标识逻辑动作,不是尝试次数。
- 先确认成功,再持久化结果。 崩溃会留下“外部已成功、内部不知道”的状态;正确顺序是先持久化结果,再确认。
- 忽略事件 Schema 与隐私删除。 事件只追加不等于可以永远不删;旧事件要能重放,用户数据要能按合规要求删除或擦除。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。