案例分析二:Coding Agent 失败以后,如何通过 SQLite 还原“失败前最后发生了什么”?

场景背景

Run:

run_bugfix_009

执行过程:

Step 1 读取项目
Step 2 读取 app.py
Step 3 运行 pytest
Step 4 发现 ImportError
Step 5 检查 requirements.txt
Step 6 Tool 执行超时

服务随后崩溃。

如果只有日志文件

你可能要在几十 MB 日志里搜索:

run_bugfix_009

才能拼出过程。

有结构化数据库

查询:

SELECT *
FROM runs
WHERE run_id = 'run_bugfix_009';

看到:

failed
TimeoutError

再查:

SELECT *
FROM steps
WHERE run_id = 'run_bugfix_009'
ORDER BY step_no;

看到 6 步。

再查:

SELECT *
FROM tool_calls
WHERE run_id = 'run_bugfix_009';

看到:

read_file
run_shell
read_file

具体参数和结果都存在。

结果

你不需要猜,“Agent 失败前最后做了什么?”

数据库已经给出结构化证据。

迁移到 Trace

后面的 Tracing 章节会把这些字段继续做细:

具体参数和结果都存在。

结果
你不需要猜,“Agent 失败前最后做了什么?”

数据库已经给出结构化证据。

迁移到 Trace
后面的 Tracing 章节会把这些字段继续做细:

而本章的核心业务表与事件日志,就是未来 Trace 数据层的第一版骨架。

常见误区

误解: Python dict 已经能保存 Session 和 Run,所以只要服务不重启,就不需要数据库。
正解: 真实服务不会永远不重启,而且生产环境通常还有多 Worker、多实例、发布升级和异常恢复。进程内 dict 只能作为运行时缓存,不能作为唯一事实来源。Session、Run、Message、Step 等业务历史需要落到独立持久化层,才能跨进程和跨重启继续存在。

误解: 为了简单,把 Session、Run、Step、Tool Call、Message 全塞进一张表的 JSON 字段最好。
正解: 小 Demo 可以这样做,但后面查询“某个 Run 的 Tool Calls”“某个 Session 的消息”“失败 Run 的平均 Step 数”会很困难。把稳定实体拆表,既便于关系约束,也方便索引、统计和后续 AgentOps。真正不固定的扩展字段才适合 JSON。

误解: SQLite 是文件数据库,所以没有事务,也不适合保存 Agent 状态。
正解: SQLite 支持事务、外键和 SQL 查询,非常适合单机或中小规模 Agent Backend 的第一版持久化。它的主要限制在高并发写、多实例和大规模场景,而不是“不能持久化”。课程选择 SQLite 是为了降低部署门槛,同时保留完整数据库思想。

误解: 既然最后可能换 PostgreSQL,现在直接在 AgentService 里写 sqlite3 也没关系,以后再重构。
正解: 真正容易形成技术债的就是这种“以后再抽象”。一旦 SQL 散落在 Route、Service、Manager 中,迁移数据库会牵动整个系统。现在只要多加一个 Store 接口,就能把数据库实现隔离起来。未来换 PostgresStore 时,AgentEngine 和大部分 Service 都不需要改。

误解: Tool Result 已经写在 messages 里,所以不需要单独的 tool_calls 表。
正解: Conversation Message 和 Tool Execution Record 的用途不同。messages 服务模型上下文与会话恢复;tool_calls 更适合保存 tool_name、arguments、result、status、error 等结构化执行信息,后续可统计工具调用次数、错误率和耗时。两者可以关联同一 Run,但不应该完全混为一类。

误解: 只要 Run 最终状态写入数据库就够了,Step 和 Message 不重要。
正解: 只有最终 completed/failed,只能知道结果,无法解释过程。Agent 的价值和问题往往都发生在多步执行中。Steps、Tool Calls、Messages 才能让我们复盘“怎么走到这个结果”,也为 Streaming 恢复、Tracing、Evaluation 和 Debug 提供基础。因此 Run 结果与执行过程都值得持久化。

误解: with sqlite3.connect(...) as conn 退出后一定会关闭连接。
正解: 这个上下文只承诺事务提交或回滚,不负责关闭连接。我们需要在 finally 中显式 close(),或者使用自己的连接上下文管理器。测试数据量小时看不出问题,请求多起来后才可能暴露文件句柄和连接生命周期混乱。

误解: 开启 WAL 后,SQLite 就能承受任意数量的并发 Worker 写入。
正解: WAL 改善的是读写并行,并没有取消 SQLite 的单写入者边界。保持事务短小、设置合理的 busy_timeout,并监测锁等待;当多实例写入成为常态时,再迁移服务端数据库。

误解: 更新记录统一使用 INSERT OR REPLACE 最省事。
正解: SQLite 的 REPLACE 更接近“删除旧行,再插入新行”,可能影响外键、触发器和未显式提供的字段。创建用 INSERT,更新用 UPDATE;确实需要幂等写入时,再明确设计 ON CONFLICT DO UPDATE 的冲突键和字段范围。

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

昵称

取消
昵称

    请登录后查看评论内容