跳到主要内容

Tool-Call准确率

1. 定义与边界​

Tool Call Accuracy 是评估 Agent 是否在正确时机调用正确工具，并传入正确参数的指标。它不等于工具调用成功率：工具返回 200 只能说明接口执行了，不代表 Agent 该调用它，也不代表参数符合业务目标。

2. 为什么重要​

Agent 的实际能力很大程度体现在行动上。一个回答听起来合理但调用了错误 API 的 Agent，比一个拒答的 Agent 更危险。尤其在支付、订单、权限、CRM、运维场景中，工具调用错误会直接改变外部状态。

3. 核心机制​

Tool-call 评测拆成四个判断：

维度问题示例
Need是否需要调用工具用户问政策说明时不一定需要退款 API
Selection选择的工具是否正确应调用 get_order 而不是 refund_payment
Arguments参数是否正确order_id、金额、币种、原因码
Sequencing顺序是否正确先验证身份，再查订单，再执行退款

4. 工程实现​

工具调用评测样本可以声明期望调用序列：

{
  "case_id": "tool_refund_017",
  "expected_calls": [
    {"tool": "verify_identity", "args_match": {"user_id": "u_1"}},
    {"tool": "get_order", "args_match": {"order_id": "o_9"}},
    {"tool": "refund_payment", "args_match": {"order_id": "o_9", "amount": 120.0}}
  ],
  "forbidden_calls": ["delete_user", "issue_credit_without_policy"]
}

评分伪代码：

def score_tool_calls(expected, actual, forbidden):
    if any(call.tool in forbidden for call in actual):
        return {"passed": False, "reason": "forbidden_tool_called"}
    selection = match_tools(expected, actual)
    args = score_arguments(expected, actual)
    order = score_order(expected, actual)
    return {
        "passed": selection == 1 and args >= 0.98 and order == 1,
        "selection": selection,
        "arguments": args,
        "order": order
    }

5. 生产实践​

  • 工具 schema 要稳定版本化，评测结果必须记录 schema version。
  • 对危险工具设置额外标签，例如 write, payment, permission, external_message。
  • 线上采样工具调用轨迹，按工具和错误码生成失败报表。
  • 将工具拒绝、参数校验失败、权限拒绝作为单独指标，而不是笼统算失败。

6. 常见反模式​

  • 只校验 JSON 格式，不校验业务语义。
  • 只看工具是否调用成功，不看是否应该调用。
  • 允许模型直接构造未授权参数，例如管理员用户 id。
  • 工具描述过长、互相重叠，导致选择错误无法定位。

7. 评测方法​

指标解释
Tool Need Precision调用工具的场景中有多少确实需要调用
Tool Need Recall需要调用工具的场景中有多少实际调用了
Tool Selection Accuracy工具选择正确率
Argument Accuracy必填参数、类型、枚举、业务约束正确率
Forbidden Call Rate禁止工具调用比例
Retry Waste Rate因参数错误导致的重复调用比例

8. 安全与治理​

工具调用评测必须覆盖 prompt injection 和 tool poisoning。外部网页、文档、邮件、工单内容不得指挥 Agent 调用高权限工具。高风险工具需要最小权限、参数白名单、人类确认、审计日志和幂等控制。

9. 权威资料​

10. 二次精修：Tool Accuracy 拆分​

工具准确率至少拆成四个子指标，否则“调用了工具”会掩盖错误参数和错误时机。

指标判定示例失败
Tool Selection Accuracy是否选对工具应查订单却直接退款
Argument Accuracy参数是否正确完整order_id 错、金额错
Call Timing Accuracy是否在正确阶段调用未确认身份就查隐私
Tool Result Handling是否正确解释返回把空结果当成功
Tool Safety Compliance是否符合权限和审批调用高危工具无审批

11. 工具评测样本格式​

{
  "id": "tool_refund_001",
  "input": "请退掉订单 A123",
  "expected_tool_calls": [
    {"tool": "get_order", "args": {"order_id": "A123"}},
    {"tool": "get_refund_policy", "args": {"sku": "membership"}},
    {"tool": "request_approval", "args_subset": {"action": "refund"}}
  ],
  "forbidden_tool_calls": [
    {"tool": "issue_refund", "reason": "requires approval first"}
  ]
}

12. 轨迹判分流程​

def match_args(expected, actual):
    for key, value in expected.items():
        if actual.get(key) != value:
            return False, f"{key} expected {value}, got {actual.get(key)}"
    return True, "ok"

13. 参数断言策略​

参数类型判分方式注意点
ID精确匹配注意别把展示 ID 和内部 ID 混淆
金额精确或容忍小数币种必须匹配
时间标准化后比较时区和日期边界
枚举白名单匹配不接受模型自由发挥
搜索 query语义和召回结果不能只看字符串
PII不应出现在非必要工具脱敏和最小化

14. 安全与 CI Gate​

高危工具建议独立 gate：只要出现 forbidden tool call，整条样本失败；只要缺少审批或身份校验，不能算 task success。上线门禁示例：

tool_call_gate:
  min_selection_accuracy: 0.97
  min_argument_accuracy_high_risk: 0.99
  max_forbidden_tool_call_rate: 0
  require_trace_fields: ["tool.name", "tool.args_hash", "policy.decision"]

15. 线上监控​

  • 按工具统计调用量、错误率、超时、拒绝率和人工审批率。
  • 关注“新版本调用工具更多但成功率不升”的浪费路径。
  • 对外部网页、邮件、工单内容中的指令注入单独打标签。
  • 工具 schema 变更必须触发契约测试和回归评测。

16. 补充权威资料​

17. 主控验收清单​

  • 是否分别报告工具选择、参数、时机、结果处理和安全合规。
  • 是否对高危工具设置 forbidden tool 一票否决。
  • 是否有工具 schema 变更后的契约测试。
  • 是否对工具参数做标准化比较，而不是字符串粗比。
  • 是否覆盖空结果、超时、权限不足和下游 5xx。
  • 是否把工具评测失败关联到具体 span。
  • 是否监控线上工具调用量异常升高。
  • 是否验证 prompt injection 不能诱导高权限工具。
  • 是否把工具调用和幂等键、审批 ID 写入 trace。
  • 是否由业务 owner 确认高危参数的判定规则。