工具调用成功率评估
基准说明
本文档中的指标定义与基准参考值系基于行业最佳实践汇编的参考指南，并非学术基准或官方认证标准。
基准参考值范围为经验值，实际表现因应用场景、模型版本、工具集规模及评估方式的不同而存在显著差异。
建议读者根据自身业务场景和数据分布自行调整评估阈值，不宜直接套用本文档中的数值作为绝对标准。
当引用外部 benchmark（如 ToolBench、BFCL、AgentBench 等）时，其数据来源和评测条件已在相应章节标注，请注意核对其原始论文或官方仓库以获取最新信息。
工具调用是 Agent 能力的核心支柱。从工具选择、参数填充到执行恢复，每个环节的准确率都直接影响 Agent 的最终表现。
1. 工具选择准确率 (Tool Selection Accuracy)
定义
Agent 在面临多个可用工具时，准确选择出最合适工具的比例。这是 Agent 工具调用的第一道关卡。
计算方法
工具选择准确率 = (正确选择工具的次数 / 总工具调用次数) × 100%分类评估：
- 精确匹配：Agent 选择的工具与标注工具完全一致
- 功能等价：Agent 选择的工具功能等价于标注工具（允许同功能不同名称）
- 拒绝正确：Agent 正确判断无需调用任何工具
基准参考值
| 工具集规模 | 入门水平 | 良好水平 | 优秀水平 |
|---|---|---|---|
| 少量工具 (3-5个) | 85% | 93% | 98%+ |
| 中等工具集 (5-15个) | 75% | 88% | 95%+ |
| 大型工具集 (15-30个) | 65% | 80% | 90%+ |
| 动态工具集 (30+) | 55% | 72% | 85%+ |
评估工具/框架
- BFCL (Berkeley Function Calling Leaderboard)：函数调用排行榜，标准化评估工具选择能力
- ToolBench / ToolLLM：大规模工具使用评测
- Gorilla OpenFunctions Leaderboard：API 函数调用基准
- LangSmith Dataset Testing：创建工具选择测试集进行回归测试
实际应用案例
案例：智能客服 Agent 的工具选择优化
- 场景：15 个工具（查订单、改地址、退货、优惠券、积分查询等）
- 初始选择准确率 78%，主要混淆：查订单 vs 查物流
- 优化方案：工具描述中加入 boundary case 示例 + 相似工具区分指南
- 优化后：工具选择准确率提升至 93%，Top-3 召回率 99%
2. 参数填充准确率 (Parameter Filling Accuracy)
定义
Agent 成功识别并正确填充工具调用所需参数的准确率。包括参数名称匹配、值类型正确性、必填参数完整性和参数值合理性。
计算方法
参数准确率
参数准确率 = (参数填充完全正确的工具调用数 / 总工具调用数) × 100%细粒度参数指标
参数名匹配率 = (正确命名的参数数 / 总参数数) × 100%
参数值正确率 = (值完全正确的参数数 / 总参数数) × 100%
必填参数完整率 = (完整填写必填参数的工具调用数 / 总工具调用数) × 100%
参数格式合规率 = (符合类型/格式要求的参数数 / 总参数数) × 100%常见错误类型：
| 错误类型 | 描述 | 占比建议 |
|---|---|---|
| 参数名称错误 | 使用了不存在的参数名 | ~15% |
| 参数类型错误 | 传入了错误类型（字符串vs整数） | ~25% |
| 必填参数遗漏 | 未提供必需参数 | ~30% |
| 参数值格式错误 | 日期格式、枚举值拼写错误 | ~20% |
| 参数值不合理 | 逻辑上不正确（如负数价格） | ~10% |
基准参考值
| 参数场景 | 入门 | 良好 | 优秀 |
|---|---|---|---|
| 简单参数（1-3个基本类型） | 85% | 92% | 98%+ |
| 中级参数（3-5个含枚举/对象） | 72% | 85% | 95%+ |
| 复杂参数（5+个含嵌套对象） | 60% | 75% | 88%+ |
评估工具/框架
- JSON Schema Validator：自动验证参数结构和类型
- Pydantic：Python 类型校验 + 自动转换
- Instructor：结构化输出约束参数生成
- TypeChat：类型安全的 LLM 输出约束框架
- 自定义 Unit Test：为每个工具编写参数填充单元测试
实际应用案例
案例：数据分析 Agent 的 SQL 查询参数填充
- 问题：Agent 频繁拼错数据库表名和字段名（参数填充准确率 68%）
- 引入 Schema 注入（将数据库 Schema 作为工具描述上下文）
- 参数填充准确率从 68% → 91%，表名准确率 98%，字段名准确率 93%
3. 执行成功率 (Execution Success Rate)
定义
工具调用被正确发起并成功得到有效响应的比例。反映 Agent 在"选择并填充后，能否顺利执行"这一环节的能力。
计算方法
执行成功率 = (执行成功的工具调用数 / 总工具调用尝试数) × 100%执行结果分类：
| 结果类别 | 定义 | 处理方式 |
|---|---|---|
| ✅ 完全成功 | 工具返回预期结果，无错误 | 计入成功 |
| ⚠️ 部分成功 | 工具返回数据但部分缺失/错误 | 可酌情计入 |
| ❌ 超时错误 | 工具响应超过设置的时间阈值 | 计入失败 |
| ❌ 授权错误 | 权限不足、API Key 无效 | 计入失败 |
| ❌ 系统错误 | 服务器错误、网络异常 | 计入失败 |
| ❌ 限流错误 | 触发了 API 速率限制 | 计入失败 |
基准参考值
| 工具类型 | 入门 | 良好 | 优秀 |
|---|---|---|---|
| 内部 API | 80% | 92% | 98%+ |
| 第三方 API | 75% | 88% | 95%+ |
| 代码执行 | 78% | 90% | 96%+ |
| 数据库查询 | 82% | 93% | 97%+ |
| 文件操作 | 85% | 94% | 98%+ |
评估工具/框架
- LangSmith Tracing：追踪每次工具调用的执行状态和错误详情
- Arize AI / Phoenix：可观测性监控工具调用失败模式
- Grafana + Prometheus：API 级别成功率监控和告警
- Custom Error Taxonomy：构建错误分类和自动分析流水线
实际应用案例
案例：电商 API Agent 的执行成功率提升
- 初始执行成功率 82%，失败分布：超时 40%、限流 30%、权限 15%、其他 15%
- 优化措施：
- 引入 3 次指数退避重试（超时率从 12% 降至 0.5%）
- 请求队列化+限流缓冲（限流错误从 8% 降至 0.3%）
- Token 刷新自动化（权限错误从 4% 降至 0.1%）
- 优化后：执行成功率 97.5%
4. 错误恢复率 (Error Recovery Rate)
定义
工具调用失败后，Agent 能够通过重试、换参、切换工具或降级策略成功恢复的比例。这是衡量 Agent 鲁棒性和自愈能力的关键指标。
计算方法
错误恢复率 = (成功从工具调用错误中恢复的次数 / 工具调用总失败次数) × 100%恢复策略分类：
| 恢复策略 | 定义 | 成功率期望 |
|---|---|---|
| 简单重试 | 相同参数重新调用（幂等场景） | 60-80% |
| 自适应重试 | 修改参数后重试（修正格式/值） | 70-85% |
| 工具切换 | 切换为功能等价的其他工具 | 50-70% |
| 参数纠错 | 自动检测并修正错误参数 | 65-80% |
| 降级响应 | 无法恢复时给出合理的替代回答 | 90-100% |
| 人工升级 | 转接人工处理 | 100%（但视为最终恢复） |
基准参考值
| Agent 成熟度 | 总体恢复率 | 自动恢复率（无需人工） |
|---|---|---|
| 初级 | < 40% | < 30% |
| 基础 | 40-60% | 30-50% |
| 成熟 | 60-80% | 50-70% |
| 先进 | > 80% | > 70% |
评估工具/框架
- LangSmith / LangFuse：追踪 Agent 的恢复链和决策路径
- Agentic Automation Tests：构造失败场景测试恢复策略
- Chaos Engineering for Agents：主动注入错误测试 Agent 鲁棒性
- 自定义恢复统计：基于日志分析恢复模式
实际应用案例
案例：物流查询 Agent 的错误恢复
- 初始恢复率 35%
- 主要失败模式：API 返回"运单号不存在"时直接报错
- 恢复策略优化：
- 重试前先验证运单号格式（格式错误→提示用户更正）
- 切换为"模糊查询"工具（根据用户手机号查询）
- 仍失败→转人工客服
- 优化后：错误恢复率 78%，其中 52% 实现自动恢复，仅 26% 需要转人工
5. 端到端成功率 (End-to-End Success Rate)
定义
一个任务或对话中涉及多次工具调用时，所有相关工具调用全部成功的比例。这是最综合的工具调用评估指标。
计算方法
简单端到端
端到端成功率 = (全部工具调用成功的任务数 / 总任务数) × 100%加权端到端
加权端到端成功率 = Σ (任务 i 的工具调用权重 × 任务 i 的工具调用成功率) / Σ 权重关键路径成功率
关键路径成功率 = (关键路径上的工具全部成功的任务数 / 总任务数) × 100%- 仅考虑任务完成所必需的关键工具调用，忽略非关键路径上的失败
基准参考值
| 任务复杂度 | 工具调用次数 | 入门 | 良好 | 优秀 |
|---|---|---|---|---|
| 简单任务 | 1-2 次调用 | 80% | 90% | 97%+ |
| 中等任务 | 3-5 次调用 | 65% | 80% | 92%+ |
| 复杂任务 | 6-10 次调用 | 50% | 68% | 85%+ |
| 超复杂任务 | 10+ 次调用 | 35% | 55% | 75%+ |
一个 10 次工具调用的任务，即使每次调用有 95% 的成功率，端到端成功率理论值也只有 0.95¹⁰ ≈ 60%。
评估工具/框架
- AgentBench：端到端 Agent 任务评测
- WebArena：网页 Agent 的端到端任务成功率
- SWE-bench：软件工程 Agent 端到端评估
- GAIA：通用 AI 助手端到端任务评测
- LangSmith Trace Tree：可视化工具调用链，识别瓶颈环节
实际应用案例
案例：旅行预订 Agent 的端到端成功率
- 场景：预订一次完整旅行（搜索航班 → 搜索酒店 → 检查签证 → 比较价格 → 预订支付 → 发送确认）
- 涉及 6 个工具调用，初始端到端成功率仅 32%
- 瓶颈分析（通过 Trace Tree 可视化）：
- 搜索航班成功率 96%
- 搜索酒店成功率 92%
- 检查签证成功率 78% ← 最大瓶颈
- 比较价格成功率 95%
- 预订支付成功率 85%
- 发送确认成功率 97%
- 针对性优化签证检查工具 → 端到端成功率提升至 55%
- 进一步优化：引入检查点 + 部分完成状态保存 → 端到端成功率 72%
工具调用评估综合框架
工具调用成功的递进关系
工具选择准确率
↓ (选对工具)
参数填充准确率
↓ (填对参数)
执行成功率
↓ (执行成功)
错误恢复率
↓ (失败后恢复)
端到端成功率
↓ (全局成功)
任务完成率每个环节的成功率相乘 ≈ 端到端成功率：
端到端成功率 ≈ 工具选择率 × 参数填充率 × 执行成功率 × (1 + 恢复率提升)关键工具调用 KPI 仪表盘
| 指标 | 计算周期 | 告警阈值 | 目标值 |
|---|---|---|---|
| 工具选择准确率 | 每小时 | < 80% | > 93% |
| 参数填充准确率 | 每小时 | < 75% | > 90% |
| 执行成功率 | 每分钟 | < 85% | > 95% |
| 错误恢复率 | 每小时 | < 50% | > 70% |
| 端到端成功率 | 每日 | < 60% | > 85% |
常见优化路径
1. 识别瓶颈环节（Trace + 日志分析）
2. 针对性优化（工具描述改进 / Schema 约束 / 重试策略）
3. A/B 测试验证改进效果
4. 回归测试确保未引入新问题
5. 持续监控并自动告警参考资源
- Berkeley Function Calling Leaderboard (BFCL) - 函数调用排行榜
- ToolBench - 大规模工具使用评测
- LangSmith Tool Tracing - LangChain 工具追踪
- Instructor - 结构化输出约束工具调用
- TypeChat - 类型安全工具调用
- Guardrails AI - 工具调用护栏