这一节的最后一个重点,是为未来迁移做准备。
很多项目第一版:
SQLite
后面业务增长:
PostgreSQL
真正痛苦的不是迁移数据。
而是代码里到处都是:
sqlite3.connect(...)
所以我们提前设计一个抽象接口。
定义 Protocol
Python 可以用:
typing.Protocol
定义 Store 行为。
from __future__ import annotations
from typing import (
Any,
Optional,
Protocol,
)
class AgentStore(
Protocol
):
def create_session(
self,
session_id: str,
status: str = "active",
) -> None:
...
def append_message(
self,
session_id: str,
role: str,
content: str,
) -> None:
...
def create_run(
self,
run_id: str,
session_id: str,
status: str = "ready",
) -> None:
...
def update_run(
self,
run_id: str,
*,
status: str,
start_time: Optional[str] = None,
end_time: Optional[str] = None,
answer: Optional[str] = None,
error: Optional[dict[str, Any]] = None,
) -> None:
...
def append_step(
self,
run_id: str,
step_no: int,
kind: str,
detail: str,
) -> None:
...
def get_run(
self,
run_id: str,
) -> Optional[dict[str, Any]]:
...
然后:
SQLiteStore
实现这套方法。
未来:
PostgresStore
MySQLStore
也实现同样方法。
AgentService 不需要改变
原来:
store = SQLiteStore(...)
未来:
store = PostgresStore(...)
然后:
run_manager = RunManager(
store
)
核心业务仍然一样。
未来真正需要改的通常是什么?
数据库差异主要在:
Connection
SQL Placeholder
Auto Increment
JSON Type
Transaction
Connection Pool
DDL
但如果这些都封装在 Store 内,AgentEngine 不受影响。
为什么 PostgreSQL 后面可能更适合?
Agent 系统未来可能有:
大量 Run
复杂 Trace
JSON 数据
多实例服务
并发写入
统计查询
PostgreSQL 对这类场景很强。
尤其:
JSONB
索引
事务
并发
都很适合。
但这不是现在必须解决的问题。
现在先把:
Store Interface
留好。
重启实验会告诉我们,哪些状态还没有落盘
我们先保存一次 Run,再结束进程、重新创建 Store 并查询。能查到结果,只证明历史记录持久化。接下来让任务停在中间再重启,检查是否还能找到消息、待执行动作和工作区版本。这一步才开始验证执行恢复,不能与普通查询混为一谈。
配套 SQLiteStore 已经包含 sessions、messages、runs、trace_steps、tool_calls 和 run_events。当前 Web Run 主链路会实际写入 Run、Trace、Tool Call 与 Event;Session 和 Message API 已经具备,但还要等会话入口传入 session_id 后才会进入这条主链路。我们把“表已经存在”和“产品流程已经使用”分开描述,避免看到 Schema 就误以为所有数据都自动落盘。
配套实现还把 Run 状态变化与对应事件放在同一事务提交,Trace Step 与其 Tool Call 记录也作为一个工作单元写入。这样状态、事件和执行证据不容易在进程崩溃时只落下一半。
动手验证:用第二个 Store 读回来
写入 Run 与事件后关闭连接,使用相同路径创建新 Store 并读取。再准备旧版本数据库运行升级。参考验收是历史数据保留、升级可重复执行、状态和事件一致。进程崩溃后的动作恢复需要独立测试,不能被这项持久化测试代替。
持久化以后,还要考虑保留期、敏感数据与大结果
“写进数据库”不是终点。Agent 数据常常包含 Prompt、用户输入、Tool 参数、SQL、路径和错误信息,其中可能夹带密钥或个人信息。落盘之前要做字段分级与脱敏,数据库文件也要设置合适的文件权限;生产环境还要结合磁盘加密、访问审计和备份策略。不要因为 SQLite 是本地文件,就默认它天然安全。
数据也不能无限增长。我们可以按类型制定不同保留期:
Run 摘要 保留较久
Trace / Event 按排障窗口保留
Token 增量 短期或不逐条保存
Artifact 按归属、大小和合规策略清理
删除历史行以后,SQLite 文件通常不会立刻缩小;需要在合适的维护窗口评估 VACUUM,不能在请求高峰随手执行。大段 Tool 输出也不适合无限塞进 JSON/TEXT:更稳妥的做法是保存有大小上限的摘要,把完整内容放进 Artifact Store,数据库记录 artifact_id、哈希、大小与归属。
JSON 字段同样要有合同。写入时使用统一序列化策略,读取时处理旧版本字段;无法序列化的对象要么转换为明确结构,要么拒绝写入,不能在不同 Store 方法里各自 default=str 后就当作语义完全可靠。课程项目用 default=str 保证 Trace 教学流程不中断,生产系统还应对关键字段做更严格的 Schema 校验。
















请登录后查看评论内容