章末自测

题目 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 进度实时推送给客户端。

© 版权声明
THE END
喜欢就支持一下吧
点赞14 分享
评论 抢沙发
头像-大赛人网
欢迎您留下宝贵的见解!
提交
头像-大赛人网

昵称

取消
昵称

    请登录后查看评论内容