[!info] related notes

• 所属 MOC: Agent Runtime MOC
• 相关: Run, 状态机

Run State

一句话定义

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

核心原理

状态定义

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 是终态，不应该再转换

参考资料

• Run
• State Machine Agent