智能体数据存储模块怎么记录工具事件？保存建议、执行与结果三个阶段

智能体说“准备查询”不等于工具已经执行。存储模块应分别记录建议、开始和结果，让读者回查哪次动作真的得到业务回应。

开发AI工具运行记录模块的读者。本文使用 Python 3.11 或以上版本的标准库，先验证一组人工构造的小样本。AI 负责提出实现或解释差异，结果由本地检查决定；这里没有把模型回答当成真实运行结果。

保存可追溯的工具事件前，先定规则

示例用run_id与seq作为唯一键，stage固定suggested、started、result。不能覆盖旧事件来伪装最终成功。

结果事件包含ok字段，ok为False也是一条真实结果。判断完成需要存在result且明确成功，不能只看阶段数。

对照模型对话与工具记录时，以工具真实回传为执行证据；模型生成的解释是另一类材料。

给 AI 的输入要包含什么

把下面这份输入说明和你的实际样本一起交给可用的 AI 编程助手。示例只含虚构数据；对真实材料先去除账号凭据和个人信息。

设计只读查询工具事件表：run_id/seq/stage/ok/detail，主键run_id+seq，stage白名单。保存suggested、started、result(False)三行，最终状态应失败。不要编造post_id等外部状态。

要求模型保留检查条件，并把它认为缺少的业务定义列出来。若回答改变了输入字段、忽略异常分支或直接删除原材料，先要求修正，再运行。提示词的作用是缩小任务范围，验收仍以代码和数据为准。

保存并运行最小验证程序

下方程序把关键规则和验证用例放在同一个可复跑示例中，便于先理解输入如何变成输出，再用它检查 AI 给出的实现。

新建一个空目录，把下面代码保存为 check.py，在该目录打开终端，运行 python -X utf8 check.py。代码自带示例输入，不需要安装第三方库。

import sqlite3
db=sqlite3.connect(':memory:')
db.execute("create table events(run_id text, seq integer, stage text check(stage in ('suggested','started','result')), ok integer, detail text, primary key(run_id,seq))")
rows=[('r1',1,'suggested',None,'lookup'),('r1',2,'started',None,'dispatched'),('r1',3,'result',0,'permission denied')]
with db: db.executemany('insert into events values(?,?,?,?,?)',rows)
events=db.execute('select seq,stage,ok from events where run_id=? order by seq',('r1',)).fetchall()
assert events[-1]==(3,'result',0)
final='failed' if events[-1][1]=='result' and events[-1][2]==0 else 'unknown'
assert final=='failed'
print('events',events)
print('final',final)

怎样判断结果符合要求

记录按序号保留三个阶段，final为failed。建议和开始事件都不能覆盖真实permission denied结果。

下方是这份最小示例在本地执行得到的输出。它验证示例程序与断言的关系，不代表任何 AI 模型一次就能生成同样代码，也不构成性能或生产可靠性结论。

events [(1, 'suggested', None), (2, 'started', None), (3, 'result', 0)]
final failed

这张示例表不实现完整状态机；正式运行还需约束started不能先于suggested等非法迁移。

detail只保存简短诊断，敏感原始结果需受控保存与引用。

哪些失败必须停下来处理

丢失结果或超时应记录unknown，需要查远端状态，不能自动重发有副作用调用。

审计记录必须关联执行者与资源归属，本例不涉及多用户权限，不能直接当生产审计方案。

接入自己的任务前再核对一次

按项目现有状态机接入，不新建一套相互矛盾的成功口径。

为同一run_id回放事件并核对实际工具结果，失败原因要能从存储中定位。

资料与适用范围

SQLite表约束与参数化插入支持结构化事件记录；事件业务含义由系统定义。以下链接核对于 2026-10-03；运行环境及额外依赖按本文前述说明。

• https://docs.python.org/3.11/library/sqlite3.html

相关基础可阅读 MCP 服务怎么记录日志？把协议消息、诊断日志和业务审计分开保存。本文的重点是保存可追溯的工具事件，可以把两项检查作为不同步骤保留。