这一步特别关键。Run 已经不再只是一个普通对象,而是一个带生命周期的业务对象,所以状态转移一定要有“门卫”。先看图。
![图片[1]-小节三:实现 RunManager——状态转换必须由程序控制,而不是随便改字符串-大赛人网](https://www.dsrw.com/wp-content/uploads/2026/11/image-1613.png)
如图所示,Run 从 created 到 running,再到 completed、failed 或 cancelling -> cancelled,都应该沿着明确规则前进。真正负责推动这些状态变化的,是 RunManager 这样的管理器,而不是业务代码到处随手写 run.status = "completed"。这样设计的好处很直接:状态边界更清楚,非法跳转更容易被拦下来,后面也更方便做审计、重试和恢复。
Run 对象有了以后,下一步不能让业务代码到处:
run.status = "completed"
和 SessionManager 一样,我们需要:
RunManager
统一负责:
create
start
add_step
complete
fail
get
list
为什么要统一状态转换?
因为状态不是随便跳的。
例如不应该:
COMPLETED → RUNNING
也不应该:
FAILED → COMPLETED
除非未来显式设计 retry run。
所以 RunManager 可以校验。
可以先把本节状态表写死,而不是把转换规则散落在多个 if 中:
![图片[2]-小节三:实现 RunManager——状态转换必须由程序控制,而不是随便改字符串-大赛人网](https://www.dsrw.com/wp-content/uploads/2026/11/image-1614.png)
注意 cancelling 和 cancelled 不是一个状态。前者只是系统收到了停止意图,工具或外部请求可能还没停;后者才表示执行器确认不会继续推进。
完整可运行 RunManager
这段代码已经建立了真正生命周期:
READY
↓
RUNNING
↓
COMPLETED
不要把内部可变 Run 直接交出去
如果 get_run() 返回管理器内部的同一个对象,调用方仍然可以绕开规则执行 run.status = "completed"。教学版为了篇幅直接返回对象,工程版更稳的做法是返回深拷贝、不可变快照或只读 DTO,所有修改仍必须经过 Manager。
课程项目中的完整实现位于 agent_harness/service/run_lifecycle.py,它增加了线程锁、状态枚举、终态保护、取消确认、Owner 查询边界和版本冲突检查:
from agent_harness.service.run_lifecycle import (
RunManager,
)
manager = RunManager()
created = manager.create_run(
session_id="sess_demo",
owner_id="user_demo",
)
running = manager.start_run(
created.run_id,
expected_version=created.version,
)
manager.add_step(
running.run_id,
kind="reason",
detail="理解任务",
)
completed = manager.complete_run(
running.run_id,
result={"answer": "done"},
)
print(completed.status.value)
expected_version 解决的是过期写入:两个请求都读到版本 1,第一个把 Run 更新到版本 2,第二个再拿版本 1 覆盖时必须报冲突。进程内锁只能保证同一时刻不把字典写坏,不能判断某个调用方依据的状态是否已经过期,这两类问题不要混在一起。
失败怎么处理?
Agent Engine 如果异常:
Provider timeout
Tool error
MaxSteps exceeded
Service 应:
run_manager.fail_run(...)
而不是只让 Python Exception 往上冒。
因为即使最终 HTTP 返回 500,Run 也应该留下失败记录。
为什么这是可靠性的基础?
如果异常发生后 Run 仍停在:
RUNNING
前端以后查询就会永远认为任务还在运行。
所以失败路径必须显式:
RUNNING → FAILED
并设置:
end_time
error
失败收口最好放在离状态存储最近、又能覆盖完整执行链的位置。只在 Route 捕获异常,Worker 或定时任务入口仍可能漏记;只在 Engine 内捕获,又可能看不到调度失败。通常由 Service / Worker Runner 使用 try/except/finally 统一推动 Run,Route 只把已有状态转换成 HTTP 响应。
















请登录后查看评论内容