Wiki Notes

Appearance

工具结果校验专题 ​

版本：v1.1

最后更新：2026-07-07

适用对象：需要为 Agent、工作流、RAG、外部 API 调用、审批链路和写操作回执设计工具结果验证、回退和观测体系的产品、平台、算法与工程同学

很多 Agent 系统接入工具后，最容易踩的坑之一不是“不会调工具”，而是：

  • 工具调用看起来成功了
  • 但返回结果其实不可信、不可用、不完整，或者根本不适合继续驱动下一步

这类问题在真实链路里非常常见：

  • 数据库查到了记录，但不是当前租户的记录
  • 搜索接口返回了结果，但没有证据能支撑结论
  • 写操作返回了 success=true，但实际状态没有落库
  • 审批工具给了通过结果，但审批人、审批时间或审批范围不对
  • 外部 API 返回 200，但字段缺失、内容过期、语义冲突

这也是为什么工具系统不能只做“调用前权限控制”，还必须做“调用后结果校验”。

OpenAI 在 Using tools、Structured outputs、Trace grading、Evaluate agent workflows 等文档里反复强调一个思路：

  • 工具调用不是一个黑箱
  • 其输入、过程、输出、评分和后续决策都应该结构化、可校验、可回放

一句话理解：

  • 工具结果不是事实本身，而是待验证的证据对象

1. 什么是工具结果校验 ​

更实用的理解通常是：

  • 在工具返回后，判断结果是否满足继续执行、进入推理、触发写操作或给用户输出的条件

重点不是只看：

  • HTTP 是否 200
  • 函数是否返回成功
  • JSON 是否能 parse

而是要判断：

  • 这个结果能不能被系统安全、正确、稳定地使用

所以工具结果校验本质上是：

  • 对结果的结构、语义、时效、权限边界、状态一致性和业务风险做复核

2. 为什么调用成功不等于结果可信 ​

工具返回“成功”，仍然可能有很多问题。

2.1 结构层问题 ​

  • 字段缺失
  • 类型不对
  • 空对象
  • 枚举值异常

2.2 语义层问题 ​

  • 查询目标和返回目标不一致
  • 返回的记录不是当前任务要找的对象
  • 搜到资料，但并不能支撑要回答的问题

2.3 时效层问题 ​

  • 数据过期
  • 缓存太旧
  • 审批状态已变化
  • 检索到的是旧版本政策

2.4 权限层问题 ​

  • 返回了不属于当前租户的数据
  • 返回了当前角色不该看到的敏感字段
  • 工具读到了超范围内容

2.5 状态层问题 ​

  • 写操作说更新成功，但下游系统状态没变
  • 工单说创建成功，但实际找不到工单
  • 审批说通过，但审批 token 已失效

如果没有结果校验，后续链路会把这些问题继续放大。

3. 哪些工具结果最值得优先校验 ​

虽然所有工具结果都值得校验，但以下几类最应该优先做强校验：

  • 检索与数据库查询结果
  • 外部 API 返回数据
  • 写操作的状态回执
  • 审批结果与策略判断结果
  • 多步骤链路中的中间产物
  • 搜索、RAG、文件解析、网页抓取这类噪声较高的结果

这些结果有一个共同特点：

  • 它们会直接决定下一步是否继续、写什么、发什么、批什么

4. 一个更实用的结果对象模型 ​

很多系统把工具结果直接作为一段自然语言或一坨原始 JSON 丢回模型上下文。

更稳妥的做法通常是先统一成结果对象。

json
{
  "tool": "query_order",
  "request_id": "req_001",
  "status": "success",
  "payload": {
    "order_id": "o_1001",
    "tenant_id": "t_001",
    "refund_status": "pending"
  },
  "metadata": {
    "source": "crm",
    "timestamp": "2026-07-07T10:00:00Z",
    "latency_ms": 320
  },
  "validation": {
    "schema_valid": true,
    "semantic_valid": true,
    "freshness_valid": true,
    "scope_valid": true,
    "risk_level": "low"
  }
}

这个对象至少有三个价值：

  • 让校验规则有统一着力点
  • 让 trace 和日志更容易对齐
  • 让下游节点知道“这是一份已经过什么校验的结果”

如果没有这类 envelope，工具结果校验很容易散在各个节点里，最后谁都说不清哪里在兜底。

5. 一个更实用的校验分层 ​

工具结果校验通常至少要分成六层，而不是三层。

5.1 传输与执行层 ​

关注：

  • 请求有没有真的执行
  • 有没有超时
  • 有没有异常码
  • 有没有部分失败

这一层解决：

  • 工具到底跑没跑成

5.2 结构层 ​

关注：

  • 字段齐不齐
  • 类型对不对
  • schema 合不合法
  • additionalProperties 是否超出预期

这一层解决：

  • 数据格式能不能稳定进入系统

5.3 语义层 ​

关注：

  • 返回内容是不是回答了当前问题
  • 目标对象是不是当前请求要找的对象
  • 文档、证据、结果之间是否匹配

这一层解决：

  • 结果虽然长得像结果，但它是不是“那个结果”

5.4 时效层 ​

关注：

  • 是否过期
  • 是否旧版本
  • 是否命中过旧缓存
  • 是否来自不再有效的审批或状态

5.5 权限与范围层 ​

关注：

  • 数据是否属于当前租户
  • 字段是否超出当前角色可见范围
  • 返回内容是否包含敏感信息

5.6 风险与一致性层 ​

关注：

  • 返回结果是否与业务规则冲突
  • 多源结果是否互相矛盾
  • 写操作回执和查询结果是否一致

这六层合在一起，才接近真实的“结果可信”。

6. 为什么结构校验远远不够 ​

很多系统做到这里就停了：

  • 工具结果能 parse
  • 字段齐了
  • 就继续往后走

这是最常见的误判来源。

例如：

json
{
  "customer_id": "c_001",
  "name": "张三",
  "status": "active"
}

这个结构完全合法，但仍然可能有问题：

  • customer_id 根本不是当前会话的客户
  • 这是缓存里的旧状态
  • 这个对象来自另一个租户
  • 这个 status=active 与别的系统冲突

也就是说：

  • schema valid 只说明“格式可处理”
  • 不说明“结果可相信”

7. 查询类工具怎么校验 ​

查询工具最容易被误信，因为它们往往没有副作用，看起来风险较低。

但真实系统里，很多错误决策都来自错误查询结果。

7.1 主键和目标对齐 ​

至少校验：

  • 请求里的 customer_id、order_id、ticket_id 是否和返回对象一致
  • 目标是否唯一
  • 是否出现多条高相似结果却没有 disambiguation

7.2 数据范围对齐 ​

至少校验：

  • tenant_id 是否一致
  • project_id 是否一致
  • 当前用户 scope 是否覆盖返回对象

7.3 时效校验 ​

至少校验：

  • 更新时间是否满足 SLA
  • 是否来自旧快照
  • 是否应该强制回源重查

7.4 完整性校验 ​

至少校验：

  • 当前决策所需关键字段是否都在
  • 关键字段是否为空

不要让“查到了点东西”直接被理解为“查到了完整真相”。

8. 检索和 RAG 结果怎么校验 ​

检索类工具最大的问题通常不是格式错，而是：

  • 找到的内容与问题不相关
  • 找到的内容相关，但不足以支撑后续结论
  • 找到的是旧文档、错版本或断章取义片段

更稳妥的做法通常包括：

  • 文档级相关性阈值
  • 证据覆盖检查
  • 时间戳和版本检查
  • 引用存在性检查
  • 片段和答案的一致性检查

一个最小结果对象可以是：

json
{
  "query": "企业版退款是否需要审批",
  "documents": [
    {
      "doc_id": "policy_2026_07",
      "score": 0.89,
      "version": "2026-07",
      "updated_at": "2026-07-01",
      "supports": ["金额超过5000需要审批"]
    }
  ],
  "validation": {
    "relevance_pass": true,
    "freshness_pass": true,
    "evidence_sufficient": true
  }
}

如果这些条件不满足，就不应该让生成节点把结果当作硬事实继续扩写。

9. 写操作回执怎么校验 ​

写操作的危险点在于：

  • 工具说写成功了
  • 但真实世界未必真的变了

这在多系统协同里尤其常见。

9.1 不要只信 success=true ​

更好的做法通常是要求回执至少包含：

  • 操作类型
  • 目标对象
  • 新状态
  • 版本号或 revision
  • server timestamp
  • 操作 ID / transaction ID

9.2 高风险写操作要做写后读确认 ​

例如：

text
调用 update_refund_status
 -> 收到 success
 -> 再调用 query_refund_status
 -> 确认状态真的从 pending 变成 approved

9.3 多系统写入要做最终一致性校验 ​

例如：

  • CRM 更新成功
  • 但通知系统没同步
  • 审批系统没落记录

这时就不能只看第一个系统回执。

对于高风险业务动作，结果校验本质上也是事务校验。

10. 审批结果怎么校验 ​

审批工具的危险点不在于“有没有回结果”，而在于：

  • 这个审批结果是不是当前任务、当前对象、当前版本对应的有效审批

至少应校验：

  • approval_id 是否存在
  • approval_subject 是否匹配当前对象
  • approved_by 是否具备相应角色
  • approved_scope 是否覆盖当前动作
  • approved_at 是否仍在有效窗口内
  • approval_version 是否对应当前数据版本

否则会出现：

  • 旧审批批新动作
  • 批了 A，系统误以为批了 B
  • 部分审批被当成全量审批

这类错误非常隐蔽，但后果往往很重。

11. 外部 API 结果怎么校验 ​

外部 API 的主要问题通常来自：

  • 供应商不稳定
  • 字段语义变化
  • 局部返回
  • 限流和降级返回
  • 时间差和缓存差

因此更稳妥的校验通常包括：

  • schema 版本检查
  • 关键字段 presence 检查
  • 状态码与业务码双重检查
  • partial_result / degraded 标记识别
  • provider timestamp 检查
  • fallback supplier 对比

不要把 200 响应自动理解成“完整正确业务结果”。

12. 工具结果也需要做输出过滤和脱敏 ​

这一点和工具权限沙箱是前后配套关系。

很多问题出在：

  • 工具调用本身合法
  • 但返回结果把不该看到的字段也带回来了

例如：

  • 原始用户手机号
  • 内部标签
  • 审批备注
  • 密钥片段
  • 其他租户的关联字段

更稳妥的做法通常是：

  • 工具原始结果先进入 validator
  • validator 过滤掉不必要字段
  • 下游节点只看到允许的裁剪版结果

也就是说：

  • 工具结果校验不仅判断“能不能用”
  • 还要决定“能把哪些部分拿去用”

13. 为什么结构化输出会显著降低校验成本 ​

OpenAI Structured outputs、Anthropic Increase output consistency 和 LangChain structured output 相关文档都体现了一个很重要的工程经验：

  • 结构化输出不是为了看起来整齐
  • 而是为了让系统更容易做确定性校验

如果工具结果经过结构化规范：

  • 可以直接做 schema 校验
  • 可以直接做字段级风控
  • 可以更容易做 trace grading
  • 可以更容易做自动回归评测

反过来，如果工具结果总是一大段自然语言：

  • 校验逻辑会越来越脆
  • 复盘也会越来越难

14. 结果校验不一定全靠规则，也可以混合 grading ​

确定性规则很重要，但不一定覆盖所有语义问题。

更成熟的做法通常是混合两类校验器：

14.1 确定性校验器 ​

适合检查：

  • schema
  • 枚举值
  • 范围
  • 时间戳
  • scope
  • 版本
  • 状态转换

14.2 Judge / grader ​

适合检查：

  • 结果是否回答了当前任务
  • 引用是否真的支撑答案
  • 多文档汇总是否遗漏关键约束
  • 计划与回执是否语义一致

OpenAI Trace grading 和 Evaluate agent workflows 的意义就在这里：

  • 很多中间步骤质量，需要通过结构化评分而不是仅靠人工肉眼检查

但要注意：

  • grader 只能补语义层，不应替代强规则校验

15. 工具结果校验如何进入流程控制 ​

更好的做法通常不是“校验失败就直接报错”，而是给出明确的流程分支。

15.1 通过 ​

  • 进入下一步
  • 允许写入状态
  • 允许继续推理

15.2 可重试失败 ​

例如：

  • 网络抖动
  • 局部字段缺失
  • 短暂 provider 错误

可进入：

  • 控制次数的重试

15.3 可降级失败 ​

例如：

  • 检索证据不足
  • 写操作回执缺关键字段

可进入：

  • 换工具
  • 用更保守路径
  • 改成只给建议不自动执行

15.4 需人工接管 ​

例如：

  • 高风险写操作结果冲突
  • 审批与对象不匹配
  • 多源数据互相矛盾

可进入：

  • human review
  • 工单升级

15.5 拒绝继续 ​

例如：

  • 结果越权
  • 结果明显不可信
  • 工具返回敏感内容超范围

这时应该明确停住，而不是继续让模型“猜着往下走”。

16. 一个更实用的失败处理策略示例 ​

json
{
  "validator": "query_order_result",
  "if": [
    {
      "condition": "schema_valid == false",
      "action": "retry_once"
    },
    {
      "condition": "scope_valid == false",
      "action": "hard_fail"
    },
    {
      "condition": "freshness_valid == false",
      "action": "force_refetch"
    },
    {
      "condition": "semantic_valid == false",
      "action": "fallback_to_human_review"
    }
  ]
}

有了这种显式策略，流程控制就不会只靠模型即时发挥。

17. 为什么结果校验必须可回放 ​

如果只记录“校验失败”，却不保留：

  • 原始工具输出摘要
  • 命中的校验规则
  • 当前任务上下文
  • 触发的降级动作

后面几乎无法回答：

  • 是工具坏了
  • 还是 validator 太严
  • 是 schema 变了
  • 还是租户边界规则写错了

所以结果校验本身也应该进入 trace。

建议至少记录：

json
{
  "tool": "search_policy",
  "result_id": "res_001",
  "schema_valid": true,
  "semantic_valid": false,
  "scope_valid": true,
  "freshness_valid": true,
  "validator_decision": "fallback_to_human_review",
  "reason_codes": ["evidence_not_sufficient"]
}

没有这层记录，就很难做长期优化。

18. 线上应该监控哪些指标 ​

18.1 基础质量指标 ​

指标用途
validation_pass_rate总体通过率
schema_fail_rate格式问题有多常见
semantic_fail_rate语义问题有多常见
freshness_fail_rate过期数据问题有多常见
scope_fail_rate越权或范围错误有多常见

18.2 流程指标 ​

指标用途
retry_after_validation_fail校验失败后重试率
fallback_rate降级率
human_review_after_validation_fail校验失败后人工接管率
hard_fail_rate强停率

18.3 业务相关指标 ​

指标用途
bad_write_after_validation_pass校验通过后仍发生错误写入的比例
unsupported_claim_rate检索工具通过后仍产生无证据结论的比例
stale_decision_rate旧结果驱动错误决策的比例
cross_tenant_result_leak_rate跨租户结果泄露率

如果不监控这些指标，结果校验很容易只成为代码里的几行 if。

19. 结果校验应该进入评测集 ​

这类能力不该只在线上出事后再修。

建议离线评测集至少覆盖：

  • 缺字段结果
  • 错对象结果
  • 跨租户结果
  • 过期结果
  • 冲突结果
  • 写操作“假成功”结果
  • 审批对象不匹配结果
  • 检索证据不足结果

每条样例可设计成：

json
{
  "case_id": "tool_val_014",
  "tool": "query_customer",
  "input": {
    "tenant_id": "t_001",
    "customer_id": "c_100"
  },
  "result": {
    "tenant_id": "t_002",
    "customer_id": "c_100"
  },
  "expected_decision": "hard_fail",
  "reason": "cross_tenant_scope_mismatch"
}

这种样例对回归特别有价值，因为它们直接覆盖系统最痛的失败模式。

20. 不同工具类型的校验重点 ​

工具类型校验重点
检索 / 搜索相关性、证据覆盖、版本、时间
数据库查询主键对齐、scope、完整性、时效
写操作回执、状态变更、幂等、写后读
审批审批人、审批范围、审批时间、版本
外部 APIschema 版本、partial/degraded、provider 时间戳
文件解析文件对应关系、页码、字段抽取完整性、敏感信息
浏览器 / UI 自动化页面目标对齐、元素确认、动作回执、截图复核

不要用一套 validator 通吃所有工具。

工具类型不同，可信条件也不同。

21. 结果校验和工具权限沙箱是什么关系 ​

可以把二者理解成前后两道防线。

调用前 ​

解决：

  • 能不能调
  • 用什么权限调
  • 在什么环境里调

调用后 ​

  • 工具结果校验

解决：

  • 回来的东西能不能信
  • 哪些字段可以继续用
  • 失败后怎么处理

前者不做，容易乱调。

后者不做，容易乱信。

两道防线缺一不可。

22. 常见反模式 ​

22.1 只看成功码 ​

表现：

  • 返回 200 或 success=true 就默认继续

后果：

  • 错对象、旧数据、越权结果一路带入下游

22.2 结构通过就当语义通过 ​

表现：

  • 只做 JSON schema 校验

后果：

  • 看起来“合法”的错结果混进流程

22.3 写操作没有写后读确认 ​

表现：

  • 只信工具回执

后果：

  • 误以为状态已更新

22.4 校验失败后没有降级策略 ​

表现：

  • 要么直接崩，要么继续猜

后果：

  • 用户体验和系统安全都差

22.5 校验日志缺失 ​

表现：

  • 只知道失败了，不知道为什么

后果：

  • 无法复盘，无法优化

22.6 原始结果整段塞回模型 ​

表现：

  • 不过滤、不脱敏、不裁剪

后果：

  • 敏感数据泄露
  • 上下文污染

23. 优化工具结果校验的常见手段 ​

23.1 统一 envelope ​

  • 所有工具返回先进入统一结果对象

23.2 强 schema ​

  • 能结构化就不要散文返回

23.3 分类型 validator ​

  • 检索、查询、写操作、审批分别定义不同规则

23.4 关键结果做交叉验证 ​

  • 高风险场景可用第二数据源、二次查询或人工复核

23.5 高风险写操作做写后读 ​

  • 尤其是不可逆动作

23.6 结果裁剪后再进模型 ​

  • 只传必要字段

23.7 用 grading 补语义层 ​

  • 规则做硬边界
  • grader 做语义补充

这样结果校验才会既稳又可扩展。

24. 一个可执行的落地流程 ​

24.1 先列出关键工具 ​

盘点：

  • 哪些工具最常驱动关键决策
  • 哪些工具最常触发高风险写操作

24.2 给每个工具定义结果 envelope ​

包含：

  • payload
  • metadata
  • validation
  • reason_codes

24.3 为每类工具编写 validator ​

至少区分：

  • query validator
  • retrieval validator
  • write receipt validator
  • approval validator

24.4 把 validator 接进流程分支 ​

明确：

  • pass
  • retry
  • fallback
  • human_review
  • hard_fail

24.5 做 trace 和指标 ​

记录：

  • 失败原因
  • 触发策略
  • 后续分支

24.6 建回归集 ​

把线上高频失败样例沉淀成评测数据。

这样结果校验才会从“临时补丁”变成长期能力。

25. 推荐搭配阅读 ​

26. 落地检查清单 ​

  • 是否为关键工具定义了统一结果 envelope，而不是原始结果直接下传？
  • 是否把校验拆成结构、语义、时效、权限范围和一致性多层？
  • 是否对查询结果做对象对齐、scope 对齐和时效检查？
  • 是否对高风险写操作做写后读确认或交叉验证？
  • 是否对审批结果校验审批对象、范围、角色和时间窗口？
  • 是否在校验失败时定义了 retry、fallback、human_review 和 hard_fail 分支？
  • 是否保留了原始结果摘要、规则命中和 validator 决策，支持回放？
  • 是否对工具结果做字段级裁剪和脱敏，再送回模型？
  • 是否把结果校验失败样例沉淀成评测集？
  • 是否监控 schema、semantic、freshness、scope 等失败分布？

27. 推荐资源 ​

以下资源在 2026-07-07 检查时可访问，适合作为工具结果校验、结构化返回、轨迹评分与流程评测的官方参考。

OpenAI ​

Anthropic ​

LangChain / LangGraph ​

28. 最后总结 ​

工具结果校验不是“调用成功后的附加判断”，而是 Agent 系统判断现实世界信号是否可信的核心关口。

它真正要解决的问题是：

  • 这个结果是不是当前对象的结果
  • 这个结果是不是当前时间点仍然有效
  • 这个结果是不是在当前权限范围内
  • 这个结果是不是足以支持下一步动作
  • 这个结果失败后系统应该如何退让

如果这些问题没有被机制化，系统就会陷入一种很危险的状态：

  • 工具调用越来越多
  • 但系统其实并不知道自己拿回来的是什么

更成熟的做法，是把工具结果当成结构化证据对象，围绕它做多层校验、流程分支、日志回放和持续评测。

这样 Agent 才不是“调完就信”，而是先验证、再使用、再留下可复盘证据。