Agent 平台为什么要保存 Trace 和 Evidence：从一次检索到受控 Action

1. Agent 说“订单异常”，依据在哪里

假设用户提出一个任务：

查询最近的异常订单，结合处理规则给出原因，并提交人工复核。

这句话包含三类工作：查询结构化订单、检索规则文档、调用业务动作。如果平台最后只保存一段回答，就无法回答：用了哪版数据，检索到哪些规则，SQL 返回了什么，谁允许它提交复核？

完整链路可以表示为：

text9 行

User Request
  → Agent Run
  → Retrieval
  → SQL / Tool Call
  → Evidence
  → Proposed Action
  → Permission Check
  → Business API
  → Action Record

Agent 的价值不仅是生成文字，还包括把目标拆成步骤。平台的责任是让这些步骤受到权限、状态和证据约束。

2. 六个容易混在一起的对象

对象	回答的问题
Context	当前一次模型调用看到了什么
State	工作流现在执行到哪一步
Memory	哪些信息需要跨运行保留
Trace	请求经过了哪些组件和工具
Evidence	哪些数据直接支撑当前结论
ActionRecord	最终改变了什么业务状态

Context 受到模型上下文窗口约束，可以由系统指令、用户输入、检索结果和工具返回组成。State 需要持久化当前节点、重试次数和等待审批状态。Memory 是经过选择后跨运行保留的信息，不应把所有历史消息都无限保存。

Trace 描述执行路径，Evidence 表达结论依据。一次 SQL 调用可以出现在 Trace 中，但只有被结论实际引用的返回行才属于这次结论的 Evidence。

3. AgentRun 是平台里的稳定身份

一次运行可以保存：

text9 行

AgentRun
  id
  project_id
  user_id
  agent_version
  input_hash
  status
  started_at
  finished_at

每一步保存为 RunStep：

text10 行

RunStep
  run_id
  sequence
  type
  status
  input_ref
  output_ref
  started_at
  finished_at
  error_code

大段提示词、文档片段和工具结果可以存入受控对象存储，关系数据库只保存引用、摘要、版本和权限。敏感原文不能未经筛选直接写入日志。

agent_version 还要连接提示词、工具清单、模型配置和工作流版本。否则两次运行结果不同时，很难知道平台改了什么。

4. Trace 解决调用路径，不能代替业务记录

OpenTelemetry 将 Trace、Metric 和 Log 作为不同信号。一次 Agent Run 可以建立根 Span，再为检索、模型调用、SQL 和工具调用建立子 Span：

text6 行

agent.run
  ├─ rag.retrieve
  ├─ llm.generate_plan
  ├─ tool.query_orders
  ├─ llm.summarize
  └─ tool.submit_review

Trace 适合定位耗时和错误传播。采样后，某些 Trace 可能不会长期保留；业务审批和写操作记录却需要按业务要求完整保存。

因此：

text2 行

Telemetry Trace → 可观测性与诊断
ActionRecord     → 业务事实与审计

两者通过 run_id、trace_id 和 action_id 关联。不能只依赖 Trace 后端保存业务动作结果。

OpenTelemetry 的 GenAI 语义约定仍在演进。文章引用属性时要标记版本和稳定状态，平台内部字段不必与未稳定约定强绑定。

5. Evidence 要能回到原始来源

Agent 判断异常订单时，可能使用：

text3 行

订单查询结果：order_id、status、amount、updated_at
规则文档：document_version、chunk_id、page
工具结果：tool_name、request_hash、response_ref

Evidence 记录来源标识、版本、提取范围和内容摘要。页面可以展示用户有权查看的证据，敏感字段继续脱敏。

只保存模型生成的引用文本不够，因为文本可能被截断或改写。引用需要指向当时使用的数据快照或文档版本。

如果数据源持续变化，还要决定 Evidence 保存快照、内容哈希还是可重放查询。选择取决于审计要求、成本和数据保留政策。

6. 提议动作与执行动作要分开

Agent 可以提出：

json6 行

{
  "action": "submit_order_review",
  "orderId": "order-1042",
  "reasonCode": "AMOUNT_RULE_MISMATCH",
  "evidenceIds": ["ev-18", "ev-19"]
}

这是结构化提议，不代表动作已经执行。Java Action Gateway 继续完成：

当前用户是否有订单范围权限。
订单状态是否允许进入人工复核。
原因编码是否属于允许集合。
Evidence 是否来自本次运行且仍可访问。
幂等键是否已经产生过同一动作。
当前风险等级是否要求人工审批。

校验成功后，业务服务在事务中修改状态并写入 ActionRecord。Agent 不能通过提示词绕开这些规则。

7. Tool 成功返回仍可能没有完成目标

工具返回 HTTP 200，可能只表示请求被受理。异步动作还会经历：

text3 行

PROPOSED → APPROVAL_REQUIRED → ACCEPTED → RUNNING
                                   ├─ SUCCEEDED
                                   └─ FAILED

Agent Run 可以进入等待状态，由事件或用户审批继续唤醒。Kubernetes 重建运行 Agent 的 Pod，只恢复进程环境；工作流能否继续取决于持久化 State、幂等工具和外部动作状态。

调用超时也不代表动作没有发生。重试前应使用幂等键查询原结果，避免重复提交人工复核。

8. 评估对象不应只有最终答案

最终答案正确，执行路径仍可能越权或浪费资源。可以分别评估：

text5 行

答案：结论是否正确、引用是否支撑
检索：是否找到需要的文档和数据
轨迹：工具选择、参数和步骤是否合理
动作：权限、状态和幂等规则是否满足
运行：耗时、错误、重试和资源使用

评估数据要固定输入、数据版本、Agent 版本和期望约束。线上用户反馈可以形成新的评估样本，但不能直接等同于正确答案。

9. Java 平台可以形成怎样的边界

text11 行

Agent Runtime
  → 规划、模型调用、工具选择

Java Platform
  → 身份、权限、任务状态、Action 校验、幂等、审计

Data Systems
  → MySQL、StarRocks、Milvus、对象存储

Observability
  → Trace、Metric、Log

Java 服务把工具定义成有限的业务能力，避免给 Agent 一个任意 SQL 或任意 HTTP 出口。每个工具声明输入、权限、超时、幂等和返回状态。

Agent 平台需要保存的远超聊天记录。Context 支撑当前推理，State 支撑恢复，Memory 支撑跨运行信息，Trace 支撑诊断，Evidence 支撑结论，ActionRecord 支撑业务责任。它们各回答一个问题，平台才既能解释过程，又能留下依据。

参考资料

← 返回文章