[!info] related notes

• 所属 MOC: Agent Runtime MOC
• 运行对象: Run
• 上位模式: Agent 中的状态机

Run State

一句话定义

Run State 是 Agent Run 的状态机定义。它描述了一个 Run 从创建到完成（或失败、取消）的所有可能状态和状态之间的转换条件。

边界：Run 生命周期不是整个 Agent 状态机

Agent 中的状态机 是通用控制模式，可以描述 collecting、reasoning、tool-calling、generating 等业务或执行阶段。

Run State 只关心一个更窄的问题：

一个可追踪的 Run 记录当前处于哪种生命周期状态，以及哪些生命周期转换是合法的？

因此：

• running -> waiting_approval -> running 属于 Run 生命周期；
• “当前正在检索还是调用工具”可以是 Agent 内部子状态，但不一定需要成为持久化 Run State；
• Run State 应稳定、少量、适合作为 API / persistence contract；
• 细粒度执行阶段如果频繁变化，优先作为内部状态或事件，而不是无限扩张 Run State 枚举。

核心原理

状态定义

class RunState(Enum):
    PENDING = "pending"          # 已创建，未开始
    RUNNING = "running"          # 正在执行
    WAITING_APPROVAL = "waiting" # 等待人类审批
    COMPLETED = "completed"      # 成功完成
    FAILED = "failed"            # 执行失败
    CANCELLED = "cancelled"      # 用户取消
    TIMEOUT = "timeout"          # 超时

状态转换图

pending → running → completed
                  → failed
                  → timeout
                  → cancelled
         waiting_approval → running (审批通过)
                         → cancelled (审批拒绝)

转换规则

TRANSITIONS = {
    ("pending", "start"): "running",
    ("running", "complete"): "completed",
    ("running", "fail"): "failed",
    ("running", "timeout"): "timeout",
    ("running", "cancel"): "cancelled",
    ("running", "need_approval"): "waiting_approval",
    ("waiting_approval", "approved"): "running",
    ("waiting_approval", "rejected"): "cancelled",
}

Python 实现

class RunStateMachine:
    def __init__(self, run: Run):
        self.run = run

    def transition(self, event: str):
        current = self.run.status
        key = (current, event)
        if key in TRANSITIONS:
            self.run.status = TRANSITIONS[key]
            self.run.updated_at = datetime.now()
        else:
            raise InvalidTransition(f"Cannot transition from {current} on {event}")

常见坑

1. 不做状态校验: 从 completed 直接跳到 running
2. 不记录状态变化: 无法追踪状态转换历史
3. 终态不可逆: completed/failed/cancelled 是终态，不应该再转换

学习检查

1. 为什么 tool_calling 不一定需要成为持久化的 Run State？
2. Run State 与通用 Agent 状态机分别服务什么稳定边界？
3. 为什么 terminal state 通常应保持不可逆，而 retry 更适合创建新 attempt 或显式 recovery transition？
4. 如果 UI、数据库和 worker 对同一个状态名理解不同，会造成什么契约问题？

参考资料

• Run
• State Machine Agent