小节四:实现 TraceRecorder——真正把 AgentEngine、Provider、ToolExecutor 串起来

到代码实现时,最关键的问题是“在哪个组件记录什么”。把 Recorder 的接入点放进一次完整调用链,比单独记住几个 record_*() 方法更容易理解。

图片[1]-小节四:实现 TraceRecorder——真正把 AgentEngine、Provider、ToolExecutor 串起来-大赛人网

Engine 负责步骤与状态,Provider 负责模型请求和可见响应,ToolExecutor 负责工具调用与结果。Recorder 的职责是汇集证据,而不是代替这些组件做决策;记录失败的分支也不能把执行过程一起丢掉。

现在正式实现一个最小:

TraceRecorder

先存内存,保证完整可运行。

这段代码虽然还是 Fake Provider。

但最小 Trace 链路已经跑通。它适合先看清记录流程,还没有处理并发、对象快照、重复事件和敏感数据,不能直接拿去保存生产请求。

记录时先做快照

messages、Tool Arguments 和 Result 往往是可变字典或列表。如果 Recorder 只是保存引用,Main Loop 后续追加消息后,第一步的 Prompt 也会跟着变化。安全做法是在 record() 边界深拷贝,返回和查询时也不要把内部对象引用直接交出去。

配套 TraceRecorder 会为同一 Run 分配递增 sequence,拒绝重复 event_id,并使用锁保护进程内并发写入。持久化 Recorder 重新创建后,会从 SQLite 读取最后一个 sequence 再继续,避免服务重启后从 1 重新编号。跨进程并发仍需要数据库序列、队列或遥测后端提供原子排序,内存锁解决不了多 Worker 竞争。

脱敏必须发生在落盘之前

不要先把原始 Prompt 写进 SQLite,再指望查询接口帮忙打码。只要原文已经落盘,备份、管理员查询和错误日志都可能复制它。Recorder 应在持久化边界统一处理:

敏感键替换为 [REDACTED]
Bearer Token 与常见 API Key 模式脱敏
单个字符串超过上限时截断
大结果改存受权限控制的 Artifact

关键词和正则不可能识别所有秘密,因此还需要数据分类、调用方字段标注、访问控制、加密与保留周期。配套实现提供的是教学版默认防线,不是完整的隐私识别系统。

Trace 自己也可能失败

数据库锁、磁盘满、序列化错误都可能让 Recorder 写入失败。这里需要明确策略:审计强约束场景可以 fail closed,缺少关键审计就停止高风险动作;普通诊断场景可以把事件放进有界缓冲区并上报 trace_dropped,但不能无限占内存,也不能悄悄假装记录成功。

还有一个容易忽视的顺序:先完成脱敏和序列化验证,再执行不可逆 Tool,能减少“副作用已经发生,证据却无法保存”的窗口。真正的 exactly-once Trace 与 Tool 事务通常需要 Outbox 或统一事件存储,这超出了当前内存 Recorder 的范围。

真正 AgentEngine 中怎么接?

核心就是:

Step 开始
↓
记录 Prompt
↓
调用 Provider
↓
记录 LLM Response / Token / Latency
↓
若有 Tool Call
    调 Middleware
    调 Tool
    记录 Tool Result
↓
Step 完成
↓
TraceRecorder.record()

失败也要记录

例如 Tool 抛:

FileNotFoundError

不能因为异常就不写 Trace。

更应该:

status = failed
error = FileNotFoundError

这才有复盘价值。

配套 AgentEngine 现在会分别记录 Run、LLM、Policy、Approval 与 Tool 事件。Provider 抛异常会留下 llm.failed,Tool 抛异常会留下对应 tool_call_id 的 tool.failed,Middleware 拒绝会留下规则 ID、风险等级和策略版本;取消、预算耗尽与最终完成也各有 Run 终态。这样我们不会只看到外层一句 FAILED。

一次模型返回多个工具时,模型 Token 只放在 llm.completed,Tool Event 的 Token 为零。Metrics 再按调用 ID 对完成或失败事件去重,started 事件只用于生命周期诊断,不重复计费。这个小约定会直接影响下一节的成本数据,值得在这里先钉牢。

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

昵称

取消
昵称

    请登录后查看评论内容