章末自测

题目 1:为什么内存版 SessionManager 和 RunManager 不能算真正持久化?

请从服务重启、多 Worker、多实例和历史查询四个角度解释。

内存对象只存在于当前 Python 进程,服务重启后会重新初始化;Gunicorn 多 Worker 时,每个 Worker 也有各自独立内存,无法天然共享;多实例部署更不可能依赖某一台机器上的 dict。历史 Run、Session 和 Step 还需要跨时间查询、统计和复盘,因此必须落到独立持久化 Store。内存适合做缓存和实时队列,但不适合作为唯一事实来源。

题目 2:五张核心业务表与 run_events 分别解决什么问题?

请说明它们之间的主要关联关系。

sessions 保存一段长期会话;messages 保存某个 Session 内的 Conversation;runs 保存 Session 中一次具体任务执行;steps 保存某个 Run 的多步过程;tool_calls 保存结构化工具调用;run_events 保存面向客户端、可按 ID 重放的产品级事件。核心关系是 Session 一对多 Runs 和 Messages,Run 一对多 Steps、Tool Calls 与 Events。Trace 与 Event 可以来自同一步执行,但粒度和读者不同。

题目 3:编程实现——使用 sqlite3 创建 sessions 与 runs 两张表

要求 runs.session_id 外键关联 sessions.session_id,并启用 foreign_keys。

import sqlite3
from pathlib import Path


db_path = Path(
    "data/demo.db"
)

db_path.parent.mkdir(
    parents=True,
    exist_ok=True,
)

conn = sqlite3.connect(
    db_path
)

conn.execute(
    "PRAGMA foreign_keys = ON"
)

conn.executescript(
    """
    CREATE TABLE IF NOT EXISTS sessions (
        session_id TEXT PRIMARY KEY,
        status TEXT NOT NULL
    );

    CREATE TABLE IF NOT EXISTS runs (
        run_id TEXT PRIMARY KEY,
        session_id TEXT NOT NULL,
        status TEXT NOT NULL,
        FOREIGN KEY (session_id)
            REFERENCES sessions(session_id)
    );
    """
)

conn.close()

print(
    db_path
)
#这段代码已经建立最基础 Session → Run 一对多关系,并通过外键减少无效关联数据。

题目 4:为什么 AgentService 不应该直接写 SQL?

请从职责分离、测试、迁移数据库和事务控制四个方面回答。

AgentService 的主要职责是协调 Session、Run 和 AgentEngine,而不是关心数据库 SQL。如果 Service 直接写 SQL,后面更换 PostgreSQL、增加事务或调整表结构时会影响大量业务代码。通过 SQLiteStore / AgentStore 抽象,Service 只调用 create_run、update_run 等业务化方法。这样存储层可以独立测试,也更容易替换数据库实现和统一事务策略。

题目 5:为什么 Tool Call 适合单独建表,而不是只作为 Message 保存?

请结合后续统计 Tool Error Rate 的需求说明。

Message 主要服务 Conversation History,内容偏文本;Tool Call 则天然结构化,包含 tool_name、arguments、result、status、error、时间等字段。如果只保存成文本 Message,后续统计某个 Tool 调用了多少次、失败多少次、平均耗时等都会很困难。单独 tool_calls 表能直接按工具名称和状态查询,也为 AgentOps 和 Trace 奠定数据基础。

题目 6:如果未来要从 SQLite 切换 PostgreSQL,哪些层最好保持不变?

请说明 Storage Interface 的价值。

理想情况下,AgentEngine、AgentService、SessionManager、RunManager 的核心业务逻辑都不需要变化,它们只依赖统一的 AgentStore 接口。真正变化的是底层 SQLiteStore 被 PostgresStore 替换,包括连接、SQL 方言、连接池、JSON 类型和事务实现。Storage Interface 把数据库差异封装起来,让上层只关心“保存 Session”“创建 Run”“追加 Step”这些业务动作。

题目 7:服务崩溃时 Run 已经写成 running,为什么数据库持久化仍然不能自动保证状态正确?

请说明后续还需要怎样的恢复策略。

数据库只能保证“最后一次写进去的状态不会因为进程退出而丢”,但如果进程在 Run 处于 running 时突然崩溃,数据库仍会保留 running。重启后系统还需要恢复策略,例如扫描长时间未更新的 running Run,把它们标记为 interrupted/failed,或根据 Worker 心跳判断是否仍在执行。因此持久化解决的是数据不丢,状态恢复仍需要额外生命周期机制。

配套教学服务现在增加了 Worker Lease。Worker 必须先原子领取 ready Run,数据库才会把状态改成 running,同时写入 lease_owner、lease_expires_at 和 running 事件;执行过程中产生新进展时续租。另一个服务实例即使连接同一 SQLite,也不能领取已经被占用的 Run,更不能因为看到 running 就直接判定原 Worker 已经死亡。

RunService 启动时会做两类处理:还处于 ready、说明尚未被 Worker 领取的任务可以重新入队;只有租约缺失或已经过期的 running 才会由 recover_incomplete_runs() 原子收口为 failed,并写入 recovered_after_restart 事件。事件保留原状态、WORKER_RESTARTED 错误码和 retryable=true。如果任务已经进入 cancelling,租约失效后则收口为 cancelled,不会再次执行原动作。

注意,这仍叫“安全收口”,还不是“从断点自动续跑”。Lease 只能说明谁在负责、多久没有续租,不能证明崩溃前的最后一个外部动作是否已经生效。因此教学版宁可要求创建新 Run,也不重复有副作用的步骤。生产版还要加入更独立的 Heartbeat、Checkpoint、幂等 Tool 和外部状态对账,才能决定某一步可以重放、跳过,还是必须交给人工处理。

Lease 还必须充当写入栅栏。Worker 提交 completed/failed 时,更新条件不能只有 run_id,还要同时匹配自己的 lease_owner。如果租约已经失效,恢复器可能已经完成收口;迟到的旧 Worker 即使随后拿到结果,也不能把终态重新覆盖。配套 Store 的 finish_claimed_run_with_event() 会检查所有权,并让终态、结果和终态事件继续保持同一事务。

题目 8:为什么 Run 终态和 run.completed 事件应该在同一事务提交?

如果两次独立提交,进程恰好在中间崩溃,会出现什么现象?

两次独立提交可能留下“Run 已 completed,但事件日志没有终态事件”,或者“客户端看到 completed,结果却尚未保存”的半完成状态。把状态、结果和事件放进同一事务后,它们要么一起提交,要么一起回滚。事务完成后再通知 SSE 订阅者读取数据库,通知机制本身不承担保存事实的职责。

进一步阅读

  • SQLite 官方文档:重点了解事务、Foreign Key、WAL 与并发模型。
  • Repository / Data Access Layer:理解为什么业务层不应直接依赖数据库驱动。
  • PostgreSQL:为未来多实例 Agent Backend、JSONB 和复杂查询做准备。
  • MySQL:理解常见服务端关系数据库的连接池、事务和索引。
  • Database Migration:后续真实项目应使用版本化 Schema Migration,而不是手工改表。
  • Connection Pooling:MySQL / PostgreSQL 多请求场景通常需要连接池。
  • Crash Recovery:持久化后仍需解决异常中断 Run 的状态修复。
  • Agent Tracing:后面会把 Step、Tool Call、LLM Call 的字段进一步丰富。

术语表

  • 持久化(Persistence):把运行时数据保存到独立存储介质,使服务重启、进程退出后数据仍然存在。
  • SQLite:嵌入式关系数据库,数据库通常存放在单个文件中,Python 标准库可直接通过 sqlite3 使用,非常适合 Agent Backend 第一版持久化。
  • Storage Interface:业务层依赖的统一存储抽象,定义 create_run、append_step 等能力,而不暴露具体 SQLite、MySQL 或 PostgreSQL 实现。
  • Repository / Store:封装数据库读写、SQL、事务和数据转换的组件,使 AgentService、RunManager 等上层逻辑与数据库驱动解耦。
  • Foreign Key:用于约束表之间关系的外键,例如 runs.session_id 必须引用已经存在的 sessions.session_id。
  • Tool Call Record:某次工具执行的结构化记录,通常包含工具名、参数、结果、状态、错误和时间,可用于 Trace 与 AgentOps。
  • 事实来源(Source of Truth):系统认为最权威的数据来源。对于历史 Session、Run、Step,持久化数据库通常比某个 Worker 内存更适合作为事实来源。
  • Crash Recovery:服务异常退出后,根据持久化状态恢复或修正未完成任务的过程,例如处理遗留 running Run。
  • Schema Migration:按版本、按顺序演进数据库结构,并保留已有数据的升级机制。
  • WAL(Write-Ahead Logging):SQLite 的日志模式之一,可以改善读写并发,但仍然保留单写入者边界。
  • Unit of Work:需要保持一致的一组数据库操作,例如 Run 终态、结果与终态事件,应在同一事务中提交。

本章总结

这一节,我们终于给 Agent Backend 加上了真正的数据层。

前面虽然已经有:

SessionManager
RunManager
RunStep
Streaming Event

但它们很多都只存在:

Python 内存

服务一重启:

全部消失。

这一章引入:

SQLite

正式把:

sessions
runs
steps
tool_calls
messages
run_events

写进数据库。

这是整个服务化部分非常关键的一步。

因为从现在开始,Agent 的历史不再依赖某一个 Python 进程活着。

我们首先明确:

内存

和:

持久化

职责不同。

内存适合:

当前运行对象
Event Queue
缓存

数据库适合:

Session History
Run History
Messages
Steps
Tool Calls

然后我们设计了五张核心业务表,并为 Streaming 增加 run_events 事件日志。

sessions:

保存会话

runs:

保存一次任务生命周期

steps:

保存 Run 多步执行

tool_calls:

保存结构化 Tool 执行

messages:

保存 Conversation History

run_events:

保存带游标、可断线补发的产品级事件

这些表之间形成:

Session
 ├─ Messages
 └─ Runs
      ├─ Steps
      ├─ Tool Calls
      └─ Run Events

这其实已经是后面完整 Trace 数据模型的雏形。

我们还实现了完整:

SQLiteStore

并让它能够:

create_session
append_message
create_run
update_run
append_step
append_tool_call
get_run
list_steps
list_messages
save_event / list_events

数据库文件:

data/agent.db

即使 Python 服务退出,重新启动以后仍然可以读取。

但这一节更重要的设计,不只是会用 SQLite。

而是我们没有让:

AgentService
RunManager
AgentEngine

直接依赖:

sqlite3

我们保留了:

AgentStore

接口思想。

所以未来可以:

SQLiteStore
      ↓
PostgresStore

或者:

MySQLStore

而上层业务基本不需要重写。

这就是一个真实 Backend 很重要的工程习惯,业务层依赖能力,不依赖具体数据库。

我们还补齐了几个很容易被忽略的边界:连接退出时明确关闭;每个连接开启外键和等待超时;WAL 改善本机读写并发;Schema 通过 migration 演进;Run 状态与事件同事务提交;大结果、敏感数据和历史记录都有保留与清理策略。

到这里,第4部分已经形成:

Flask API
 ↓
AgentService
 ↓
Session / Run
 ↓
Streaming
 ↓
SQLite Persistence

Agent Server 已经从:

只能运行

逐渐变成:

可以被调用
可以被查询
可以实时观察
可以跨重启保存

当然,持久化之后也会出现新问题。

例如服务突然崩溃时,数据库里可能还留着:

status = running

这说明,数据不丢,不等于状态一定正确。

后面随着 Tracing、AgentOps 和安全控制加入,我们会继续完善:

状态恢复
异常任务处理
Trace
成本
权限

但从这一章开始,我们已经拥有了一个真正能“记住自己做过什么”的 Agent Backend 数据层。

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

昵称

取消
昵称

    请登录后查看评论内容