题目 1:为什么 Session 和 Run 必须拆成两个概念?
请以“分析 Bug → 修改代码 → 完整验证”为例,说明它们之间的一对多关系,以及如果共用一个 ID 会带来什么问题。
这三个动作共享同一段用户上下文,因此可以属于同一个 Session;但它们是三个明确的任务执行阶段,每一次都有自己的开始时间、结束时间、Step、成功失败和错误,所以应该建立三个 Run。如果 session_id 与 run_id 共用,三次执行的状态、耗时、错误与 Trace 会混在一起,无法回答“到底哪一次失败”或“哪一次最慢”。
题目 2:Run 的 start_time、end_time 和 status 应该如何配合?
请分别说明 READY、RUNNING、COMPLETED、FAILED 时这些字段的典型状态。
READY 表示 Run 已创建但尚未开始,此时 start_time 和 end_time 通常为空;进入 RUNNING 时写入 start_time,end_time 仍为空;进入 COMPLETED 或 FAILED 时写入 end_time。失败时还应保存结构化 error。这样客户端和监控系统可以通过状态和时间字段准确计算等待时间、执行耗时与最终结果。
题目 3:编程实现——设计一个最小 Run 数据类
要求包含 run_id、session_id、status、start_time、end_time、steps、error,并使用 dataclass。
from __future__ import annotations
from dataclasses import (
dataclass,
field,
)
from typing import Any
@dataclass
class Run:
run_id: str
session_id: str
status: str = "ready"
start_time: str | None = None
end_time: str | None = None
steps: list[dict] = field(
default_factory=list
)
error: dict[str, Any] | None = None
if __name__ == "__main__":
run = Run(
run_id="run_demo",
session_id="sess_demo",
)
print(run)
#真实系统还可以继续增加 answer、usage、metadata,但本章核心字段已经齐全。
题目 4:为什么 Run 状态转换最好通过 RunManager,而不是业务代码直接 run.status = "completed"?
请从合法状态转换、时间字段、一致性与未来持久化说明。
如果任意业务代码都能直接修改 status,很容易出现 COMPLETED 又变 RUNNING、结束时忘记写 end_time、失败时忘记 error 等问题。RunManager 可以统一校验状态转换,同时更新时间、写数据库和 Trace。以后底层从内存切 SQLite 或 PostgreSQL,调用方仍然只调用 start_run、complete_run、fail_run,不需要关心持久化细节。
题目 5:POST /api/v1/runs 与 GET /api/v1/runs/{run_id} 分别负责什么?
请说明为什么 POST 适合创建任务,而 GET 适合查询状态。
POST
/api/v1/runs用于创建一个新的 Agent Run,并提交 session_id、message 等执行参数,因此会产生新的业务资源;GET/api/v1/runs/{run_id}不创建新任务,只读取已有 Run 的当前状态、时间、Steps 和 Error。这样的 API 分离让未来异步执行非常自然:POST 立即返回 run_id,客户端再用 GET 查询进度。
题目 6:为什么一次 Agent 异常不能只返回 HTTP 500?
请结合“幽灵 running 任务”解释。
HTTP 500 只能告诉当前客户端这次请求失败,却不能自动修改已经创建的 Run。如果异常发生前 Run 已被标记为 RUNNING,而异常后没有 fail_run,那么后续 GET 查询会一直看到 running,形成幽灵任务。正确做法是捕获异常并保证 Run 进入 FAILED,写入 end_time 和 error,再根据情况返回 HTTP 错误或 Run 对象。
题目 7:RunStep 和后面的 Trace 有什么区别?
请说明为什么本章先设计轻量 Step,而后面仍然需要完整 Tracing。
RunStep 主要让 Run 知道执行到第几步、属于什么类型、发生了什么简单事件,适合快速状态展示。完整 Trace 会记录更细的 Prompt、LLM Response、Tool Arguments、Tool Result、Latency、Token 和 Status,用于故障复盘与评估。可以把 Run 看作任务生命周期,RunStep 看作轻量过程索引,Trace 则是详细执行证据。
题目 8:为什么 cancelling 和 cancelled 必须分开?
请结合“Tool 已经开始写文件、用户此时点击取消”的时间线说明。
cancelling表示取消请求已经记录,但执行器尚未确认停止。已经开始的 Tool 可能无法立即中断,文件写入也可能已经发生;此时直接标为cancelled会给用户错误保证。执行器应在安全边界检查信号,记录已经发生的影响,确认不会继续推进后再进入cancelled。如果任务已经先完成,则保留completed。
题目 9:两个请求都基于 version=4 更新同一个 Run,会发生什么?
第一个合法更新把版本推进到 5。第二个请求仍携带
expected_version=4,Manager 或数据库的 compare-and-set 应拒绝它并返回冲突,要求重新读取。线程锁只能让两次写入依次发生,无法识别第二个请求使用了过期状态;版本检查解决的是另一层问题。
题目 10:服务重启后发现一个两小时前的 running Run,能直接从最后一步继续吗?
不能只凭状态直接继续。先检查 Worker Lease、Heartbeat 和动作日志,确认原执行器是否已失效,再判断最后一个 Tool 是否真正提交、是否产生副作用、是否支持幂等重试或外部状态查询。只读动作可能安全重试;付款、发消息、删除文件等动作可能需要对账或人工恢复。数据库保留了状态,但没有替系统完成恢复决策。
进一步阅读
- Task Lifecycle / Job Model:理解长任务为什么需要独立状态对象。
- REST Resource Design:理解 POST 创建资源、GET 查询资源的接口设计。
- Finite State Machine:Run 状态转换本质上可以看作有限状态机。
- Async Job API:为后面把同步 Run 升级为异步 Worker 做准备。
- Observability / Tracing:Run 与 Step 会在后续成为 Trace 的组织骨架。
- Idempotency:真实任务创建 API 还会考虑重复提交与幂等。
- Persistence:下一阶段 SQLite 会让 Run 在进程重启后仍可查询。
- SSE:下一节会把 Run 的执行进度实时推送给客户端。
术语表
- Run:Session 中一次具体 Agent 任务执行的生命周期对象,拥有独立 run_id、状态、时间、Steps 与错误信息。
- Run ID:唯一标识某一次任务执行的 ID,可用于查询状态、关联 Trace、日志、Token 和性能指标。
- Run Status:描述任务当前生命周期阶段的状态,例如 ready、running、completed、failed,后续还会扩展 waiting_approval。
- Run Step:Run 中一个轻量执行步骤,用来描述 Agent 在某一步进行了 Reason、Tool Call、Observation 或其他动作。
- Start Time:Run 真正开始执行的时间,用于区分任务创建与实际执行,并支持耗时统计。
- End Time:Run 进入 completed 或 failed 等终态时记录的结束时间。
- Structured Error:Run 失败时保存的结构化错误信息,通常包含类型与可读消息,完整 traceback 则留在服务端日志或 Trace。
- RunManager:统一管理 Run 创建、开始、加 Step、成功、失败和查询的组件,避免业务代码随意修改任务状态。
- Created At:Run 被系统创建并接受的时间;与 Start Time 的差值可以衡量排队等待。
- Terminal Status(终态):任务不会再继续推进的状态,例如 completed、failed、cancelled、budget_exceeded。重试应创建新 Run,而不是改写终态。
- Cancelling:取消请求已收到、但执行器尚未确认停止的过渡状态,不等同于已经取消。
- Optimistic Concurrency(乐观并发):更新时携带读取到的版本号,版本已变化便拒绝旧写入,避免不同请求静默覆盖状态。
- Worker Lease / Heartbeat:执行器定期证明自己仍负责某个 Run 的机制,用于在服务崩溃或重启后识别孤儿任务。
- Retry Lineage(重试谱系):通过 retry_of 或 parent_run_id 关联多次执行尝试,同时保留每个 Run 的独立终态和证据。
本章总结
这一节,我们把上一章里只是一个字符串的:
run_id
真正升级成了,有生命周期的 Agent Run。
这是 Agent Backend 非常重要的一步。
因为真实 Agent 执行不是:
函数调用一下
得到字符串
结束
而是:
创建任务
开始执行
经过多个 Step
可能调用多个 Tool
可能失败
最终结束
所以我们设计了:
run_id
session_id
status
start_time
end_time
steps
error
其中最重要的概念边界是,Session 和 Run 完全不同。
Session 管:
一段持续上下文
Run 管:
这段上下文里某一次具体任务执行
于是:
Session
├─ Run 1:分析
├─ Run 2:修改
└─ Run 3:验证
就变得非常自然。
我们还定义了最基础状态:
READY
RUNNING
COMPLETED
FAILED
并实现:
RunManager
让状态转换统一通过:
create_run
start_run
add_step
complete_run
fail_run
get_run
工程版 RunManager 还把 Owner 边界、版本冲突、取消请求与取消确认纳入同一套规则。状态不只要“能变化”,还要沿着允许的边变化;终态不可逆,失败重试创建新 Run,并保留与原 Run 的关联。
而不是让业务代码随便:
run.status = "whatever"
这样以后加入:
SQLite
Trace
Human Approval
Retry
都更容易保持一致。
本节还正式实现两个 API:
POST /api/v1/runs
GET /api/v1/runs/{run_id}
前者负责创建任务。
后者负责查询任务。
虽然当前示例仍然同步执行,但 API 和数据模型已经为异步做好了准备。
未来完全可以改成:
POST /runs
↓
立即返回 run_id
Worker
↓
后台执行
GET /runs/{run_id}
↓
查询状态
客户端协议几乎不用推翻。
我们还特别处理了失败路径。
如果 Agent 抛异常,不能只让 HTTP 返回 500。
必须保证:
RUNNING
↓
FAILED
同时写:
end_time
error
否则前端会看到一个永远 running 的“幽灵任务”。
持久化也不是终点。服务重启后,数据库里的 running 可能已经失去 Worker,需要 Lease、Heartbeat 和动作日志帮助恢复;遇到有副作用的 Tool,不能只看最后一个 Step 就直接重跑。生命周期模型把问题暴露出来,恢复策略才有可靠落点。
如果你现在能够清楚解释,“为什么 Session 不能直接当 Run?”
并且可以自己实现:
Run
RunStep
RunManager
POST /runs
GET /runs/{run_id}
那么这一章最核心的能力就已经掌握了。
下一节,我们会继续解决一个真实用户体验问题,Run 在执行 30 秒、60 秒甚至几分钟时,用户怎么实时看到它正在干什么?
答案就是,Streaming。
下一节我们会正式使用 SSE,把:
正在读取项目
正在运行测试
发现错误
正在重试
这种 Run 进度实时推送给客户端。

















请登录后查看评论内容