题目 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 必须先原子领取
readyRun,数据库才会把状态改成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 数据层。
















请登录后查看评论内容