记录决定，而不是 Prompt：AI Agent 的 trace schema

多数 Agent 日志不是聊天记录，就是一堆模型耗时。两者都回答不了事故复盘真正要问的：谁批准了哪个动作、碰了哪份数据、结果是什么、结果未知时系统做了什么？

Trace 是决策记录。它把用户请求连到 Agent 执行的步骤、调用的工具、改变的状态和允许它的人。它不是 Prompt 的副本。

Prompt 日志不是 trace

Prompt 日志告诉你模型看到了什么，却不会告诉你：

• 动作针对哪个租户或记录；
• 工具调用是执行了、失败了，还是超时了；
• 谁批准了有后果的步骤；
• 外部系统里什么状态变了；
• 重试是否造成了重复效果。

Prompt 原文还是默认不该长期保存的东西。它包含客户消息、检索文档、误粘贴的凭据和个人数据。为每次运行保存它，等于再造一份不受治理的数据副本。

Trace 可以存输入的哈希或脱敏摘要，但它的主要职责是重建决策路径。

决策记录

按 span 思考。一次运行有根 span；每个模型轮次、工具调用、审批和状态变化都是子 span。Schema 应回答五个问题：

问题	Trace 字段
谁在行动？	用户 ID、租户、服务身份、会话
任务是什么？	任务 ID、运行 ID、任务类型、政策版本
Agent 做了什么？	模型/版本、步骤、工具名、参数哈希、结果状态
谁允许的？	审批 ID、审批人、范围、时间
改变了什么？	外部效果状态、资源 ID、前后状态哈希
花了多少？	输入/输出 token、工具费、延迟、重试次数

这些字段刻意围绕决定和效果，而不是文字。它们足够小，可以保留更久；也足够具体，能回答事故复盘。

记录什么，不记录什么

记录：

• 运行与任务标识；
• 用户与租户标识，或假名键；
• 模型与 Agent 版本；
• 工具名、参数哈希、结果状态、耗时；
• 审批 ID、审批人、批准范围；
• 状态变化与外部效果状态；
• 重试次数与原因；
• 成本与延迟；
• 错误类别与恢复动作。

不记录：

• 默认不存完整 Prompt 或完整检索文档；
• 凭据、token、cookie、连接串；
• 客户姓名、邮箱、电话或自由文本笔记，除非有具体且经过审查的需要；
• 含个人数据的原始工具参数；
• 模型思维链。

如果调试确实需要 Prompt 原文，用抽样、短期、受访问控制且脱敏的存储，不要让它成为默认 trace。

案例一：退款 Agent 的未知付款

退款 Agent 调用付款工具，调用超时。运行状态写“失败”，但付款可能已经成功。

有用的 trace 会显示：

1. 工具调用 span，带幂等键和超时错误；
2. 外部效果状态：未知，不是失败；
3. 后续按幂等键查询支付方的 span；
4. 结果：已确认、已拒绝，或仍未知；
5. 仍未知时被通知的人类负责人。

没有外部效果状态，看板记一次失败，客户可能已经收到退款；没有幂等键，操作员无法查询；没有审批 ID，没人知道谁授权的。

Trace 不需要客户消息，它需要付款引用和状态。

反例：把完整 Prompt 存进 trace

一个团队为调试检索问题开启详细 trace，把完整 Prompt 存进第三方观测工具，其中包含客户邮箱和内部政策片段。

调试很成功。三个月后，团队说不清工具里有哪些客户数据、保留多久、谁能搜索。一个隐私请求变成工程项目。

修复不是“关掉 trace”，而是把调试上下文和决策记录分开：

• 决策记录保留哈希、ID、状态和审批；
• 调试上下文抽样、脱敏、受访问控制，只保留几天；
• trace 通过 ID 链接调试记录，而不是复制内容。

这样既保留事故复盘能力，又不建一个影子数据仓库。

最小 schema

一次工具调用的 JSON 记录可以这样开始：

字段	类型	示例
run_id	string	run_01J...
task_id	string	refund-1042
tenant_id	string	tenant_a
step	integer	7
tool	string	payments.refund
args_hash	string	sha256:...
idempotency_key	string	refund-1042-v1
approval_id	string	apr_88
status	enum	ok、error、timeout、denied
effect_status	enum	confirmed、rejected、unknown
resource_id	string	re_123
duration_ms	integer	842
cost_usd	number	0.004

字段名不重要，区分才重要：超时不等于失败，审批不是一行日志，外部效果状态独立于运行状态。

重放与保留

Trace 支持两种重放：

• 决策重放： 重建发生了什么、谁批准、改了什么。只看 trace 就应该能做到。
• 执行重放： 在沙箱里重跑工作流。需要保存输入和安全环境，绝不能再次触发外部效果。

按用途设保留期。决策记录可能需要 90 天或更久；调试上下文应更短。访问按角色控制：客服能看客户案例，但不能看所有租户的 trace。在写入时脱敏，不要等到导出。

不适用边界

这套 schema 适合会读、写、通知或付款的工具型 Agent。它不是完整可观测平台、合规档案，也不能替代应用日志和审计系统。它不捕捉模型推理，也不应尝试。如果团队还分不开决策记录和 Prompt 原文，先从工具调用与审批 span 开始；这是事故复盘的最低要求。一个回答不了“谁批准了这个效果”的 trace，还不是 trace。