《AI Agent 技术原理与架构·运行时、协议与系统架构》2.1 状态机:状态、转移、守卫

Agent 的一次任务用状态机表达,才有资格谈执行语义。状态机由三件事组成:状态、事件驱动的转移、守卫。守卫是转移的业务前提,失败时状态不变并留下原因。实验实现一个 W3 审批状态机,演示守卫校验、非法事件拒绝,说明 2.2 的事件溯源与幂等副作用为什么要建立在状态机之上。

以下状态、事件、守卫规则与审批场景均为教学假设,不构成对任何真实系统、供应商或生产环境的承诺。审批的"2 级权限"是讲解用的简化,真实合规流程会有更多约束,但"守卫失败状态不变并留下原因"这一条不变。

2.2 将用事件溯源、持久化执行与幂等副作用讲执行语义。这一节先打地基:为什么执行语义要建立在状态机之上,以及状态机最容易被写错的三块——状态、转移、守卫。

很多 Agent 运行时把"任务进行到哪一步"存成一个字符串字段,然后在代码里散落 if status == "..." 判断。这看起来简单,但正是 2.2 要讲的故障(副作用已发生未记录、重放重复执行)的温床。状态机把"状态"“什么事件允许发生"“转移的前提"显式建模出来,让非法转移在入口就被拒绝,而不是在下游爆炸。

状态机三件事:状态、转移、守卫

状态是任务的语义快照。 一个 W3 审批任务,状态可以是 PENDING(待审批)、APPROVED(已批准)、EXECUTED(已执行)、REJECTED(已拒绝)。状态要覆盖所有业务上有意义的阶段,并且互斥——一个任务同时处于两个状态就是 bug。

转移是事件驱动的。 状态不会自己变,它由事件触发:approve 事件把 PENDING 推向 APPROVED,execute 事件把 APPROVED 推向 EXECUTED。每个(状态, 事件)组合要么有一条已定义的转移,要么是非法事件。

守卫是转移的业务前提。 这是最容易被忽略的一块。approve 事件在 PENDING 上不是无条件生效的——审批人的级别够不够?execute 事件在 APPROVED 上也不是无条件生效的——是否已审批、计划是否有效?守卫是一段返回(是否通过, 原因)的判定:守卫失败时状态不变,转移被拒绝,并留下拒绝原因。

三者的关系可以写成一张表:

元素回答的问题失败的表现
状态任务现在处于哪个语义阶段出现未定义状态
事件什么外部信号推动转移事件没有对应转移 → 非法
守卫这个转移当前是否合法守卫拒绝 → 状态不变,记录原因

为什么守卫必须显式建模

守卫如果不在状态机里显式建模,通常会散落在调用方代码里,出现两种坏味道:

  1. 守卫绕过。 某个调用方直接改状态字段(task.status = "EXECUTED"),绕过了守卫,未审批的任务直接执行。状态机把守卫绑在转移上,让"直接改状态"成为不可能——状态只能通过 dispatch 改变。
  2. 守卫重复且不一致。 三个调用方各自写一份"能否执行"的判断,稍有出入就是三个口径。守卫集中定义在转移表里,只存在一份。

第 2 种坏味道尤其值得注意:Agent 运行时里,一个动作的合法性判断(能不能调用这个工具、能不能执行这个步骤)会在多个地方出现。把守卫收拢到状态机的转移定义里,是消除"多处判断口径不一致"的直接手段。

最小实验:W3 审批状态机

实验实现一个通用的 StateMachine(状态 × 事件 → 守卫 + 目标状态),再用它构造一个 W3 审批机,跑一组事件序列。

# file: agp_lab/state_machine.py | write
# tier: 3
# verify: python3 -m unittest tests.test_state_machine
"""状态机:状态、事件、守卫与非法转移。

2.2 用状态机讲执行语义(事件溯源、幂等);这里补上守卫
(guard)这一块:状态 × 事件 →(守卫,目标状态)。守卫是
转移的业务前提,守卫失败时状态不变,转移被拒绝并留下原因。

本模块实现一个 W3 审批状态机,演示事件驱动转移、守卫校验
与非法事件拒绝三件事。
"""
from __future__ import annotations

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


class State(str, Enum):
    PENDING = "PENDING"
    APPROVED = "APPROVED"
    EXECUTED = "EXECUTED"
    REJECTED = "REJECTED"


Guard = Callable[[dict[str, Any]], tuple[bool, str]]


@dataclass(frozen=True)
class Transition:
    guard: Guard
    target: State


class StateMachine:
    """事件驱动的状态机:dispatch 返回(新状态, 是否成功, 原因)。"""

    def __init__(self, table: dict[tuple[State, str], Transition]) -> None:
        self.table = table
        self.state: State | None = None
        self.rejections: list[str] = []

    def reset(self, initial: State) -> None:
        self.state = initial
        self.rejections = []

    def dispatch(self, event: str, context: dict[str, Any]) -> tuple[State | None, bool, str]:
        assert self.state is not None
        key = (self.state, event)
        if key not in self.table:
            reason = f"illegal event '{event}' in {self.state.value}"
            self.rejections.append(reason)
            return self.state, False, reason
        transition = self.table[key]
        ok, reason = transition.guard(context)
        if not ok:
            self.rejections.append(reason)
            return self.state, False, reason
        self.state = transition.target
        return self.state, True, "ok"


def w3_approval_machine() -> StateMachine:
    """W3 审批状态机:PENDING → APPROVED → EXECUTED,附守卫。"""

    def guard_approve(ctx: dict[str, Any]) -> tuple[bool, str]:
        level = ctx.get("approver_level", 0)
        return level >= 2, "需要 2 级审批权限"

    def guard_execute(ctx: dict[str, Any]) -> tuple[bool, str]:
        approved = ctx.get("approved", False)
        plan_ok = ctx.get("plan_ok", False)
        return approved and plan_ok, "需已审批且计划有效"

    return StateMachine({
        (State.PENDING, "approve"): Transition(guard_approve, State.APPROVED),
        (State.PENDING, "reject"): Transition(lambda _ctx: (True, ""), State.REJECTED),
        (State.APPROVED, "execute"): Transition(guard_execute, State.EXECUTED),
        (State.APPROVED, "reject"): Transition(lambda _ctx: (True, ""), State.PENDING),
    })


def demo() -> dict[str, Any]:
    """运行一组事件序列,返回每一步的结果。"""
    machine = w3_approval_machine()
    machine.reset(State.PENDING)
    events: list[dict[str, Any]] = []

    events.append({"event": "approve", "ctx": {"approver_level": 1}})
    events[-1]["result"] = machine.dispatch("approve", {"approver_level": 1})

    events.append({"event": "approve", "ctx": {"approver_level": 3}})
    events[-1]["result"] = machine.dispatch("approve", {"approver_level": 3})

    events.append({"event": "execute", "ctx": {"approved": True, "plan_ok": False}})
    events[-1]["result"] = machine.dispatch(
        "execute", {"approved": True, "plan_ok": False}
    )

    events.append({"event": "execute", "ctx": {"approved": True, "plan_ok": True}})
    events[-1]["result"] = machine.dispatch("execute", {"approved": True, "plan_ok": True})

    events.append({"event": "approve"})
    events[-1]["result"] = machine.dispatch("approve", {})

    return {"events": events, "state": machine.state.value, "rejections": machine.rejections}


if __name__ == "__main__":
    result = demo()
    for item in result["events"]:
        state, ok, reason = item["result"]
        print(
            f"{item['event']:<10} -> {state.value:<10} ok={ok:<5} reason={reason}"
        )
    print(f"final_state={result['state']}")
    print(f"rejections={result['rejections']}")

运行:

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

输出:

approve    -> PENDING    ok=0     reason=需要 2 级审批权限
approve    -> APPROVED   ok=1     reason=ok
execute    -> APPROVED   ok=0     reason=需已审批且计划有效
execute    -> EXECUTED   ok=1     reason=ok
approve    -> EXECUTED   ok=0     reason=illegal event 'approve' in EXECUTED
final_state=EXECUTED
rejections=['需要 2 级审批权限', '需已审批且计划有效', "illegal event 'approve' in EXECUTED"]

五步事件对应五类转移行为:

  1. approve(approver_level=1)→ PENDING,ok=0:守卫拒绝,理由"需要 2 级审批权限”。注意状态没变,还是 PENDING。守卫失败不消耗事件。
  2. approve(approver_level=3)→ APPROVED,ok=1:审批人级别够了,转移成功。
  3. execute(approved=True, plan_ok=False)→ APPROVED,ok=0:计划无效,守卫拒绝,状态仍是 APPROVED。
  4. execute(approved=True, plan_ok=True)→ EXECUTED,ok=1:前提齐了,转移成功,终态。
  5. approve 在 EXECUTED 上 → EXECUTED,ok=0:这个事件在终态上没有定义转移,触发"illegal event"拒绝。非法事件与守卫失败是两种拒绝:前者是(状态, 事件)不在转移表里,后者是转移存在但前提不满足。

rejections 把三次拒绝的原因都留下了。这正是 2.2 需要的:一切状态变迁(包括被拒绝的尝试)都可追溯,才能谈事件溯源。

一个细节值得点破:非法事件的报错文案 illegal event 'approve' in EXECUTED 是运行时自动生成的,不是手工文案。这意味着只要转移表完备,任何未定义的组合都会被自动以统一格式拒绝,不需要给每个非法组合单独写分支。

状态机建模的收益,要到恢复场景里才真正显现。崩溃后系统要回答"我在哪一步、这一步还能不能走”,状态机的显式状态让这个问题可以直接回答;如果是散落的字符串字段,就只能靠日志猜。状态机不只是开发期的整洁,更是运维期的可恢复性。 2.3 的崩溃恢复矩阵之所以能逐点枚举,前提就是状态是有限且显式的。

状态机的持久化位置是另一个架构决策。把当前状态存在内存里,恢复时就要从事件日志重放(见 2.2);把状态直接存数据库,恢复时读一条记录就行,但要处理"状态已更新但事务未提交"的窗口。两种方案一个重放成本高、一个写放大,生产上通常按状态的重要性混合使用——关键状态落库,热状态走重放。状态机模型选对后,落哪个存储、怎么恢复,是紧随其后的两个决定。

状态机的守卫(guard)要集中在状态定义里,而不是散落在各处理函数。守卫决定"这个事件在这个状态能不能发生",散落写在每个 handler 里,同一个规则会有多份实现、互相漂移。集中定义后,测试也可以按"状态×事件×守卫"枚举:每个格子要么允许转移、要么拒绝,行为完全可预期。

守卫集中方式优点缺点
状态定义里集中规则唯一,可枚举测试状态文件变大
各 handler 分散贴近实现规则漂移、难以审计

架构判据

状态机建模是否合格,用五条判据检查:

判据合格的样子不合格的样子
状态互斥每步有且仅有一个状态状态散落为多个字符串字段
转移显式(状态, 事件)有明确的转移表靠 if 语句散落判断
守卫集中前提在转移定义里,只此一份合法性判断在调用方重复
非法事件拒绝未定义组合被自动拒绝并记录未定义组合静默通过
变迁可追溯每次 dispatch 结果(含拒绝)被记录状态直接赋值,无记录

判据里最后一条是通往 2.2 的桥:变迁可追溯。 状态机只建模还不行,还要记录每一次(状态, 事件, 结果),这才构成 2.2 事件溯源的数据基础。

小结

  • 状态机由状态、事件驱动的转移、守卫三件事组成;守卫失败状态不变并留下原因。
  • 守卫必须集中建模在转移定义里,消除散落在调用方的重复判断与口径不一致。
  • 非法事件(未定义转移)与守卫失败(前提不满足)是两种拒绝,运行时都能自动记录。
  • 每次 dispatch 的结果都被记录,才构成 2.2 事件溯源与幂等副作用的基础。

阅读导航:上一节:1.3 依赖方向与架构不变量 · 下一节:2.2 执行语义:事件溯源、持久化执行与幂等副作用 。

常见错误与边界

  1. 直接改状态字段。 状态只能通过 dispatch 改变;直接赋值绕过了守卫,是执行语义失效的头号来源。
  2. 把守卫散落在调用方。 三个调用方三份"能否执行",口径迟早分裂;守卫要收拢到转移表。
  3. 不记录被拒绝的尝试。 守卫拒绝和非法事件都要进 rejections;否则审计时说不清"为什么没执行"。
  4. 给每个非法组合写分支。 转移表完备后,非法组合由运行时统一拒绝,不需要手工枚举。
  5. 状态机不能替代执行语义。 状态机只保证转移合法;副作用是否幂等、崩溃后如何恢复,是 2.2 的范畴。

继续阅读

探索更多技术文章

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

全部文章 返回首页

「books」更多文章

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