API调用准确率：Agent工具评测

可视化演示

展示Agent API选择准确率、参数填充正确率与多工具协同调用评测，切换模式理解Agent工具评测。

1. 评测框架总览

小杨是呼叫中心质检科的老手。给新来的 Agent 助理做上岗考核，她没有急着翻电话簿出题，而是先写了一份“考核方案”：考什么能力、分几个维度、最终怎么算总分。没有方案的考核，就像没有评分表的面试，全靠考官心情，谁都不服。评测 Agent 的 API 调用准确率也是一样，第一步动作是搭评测框架——明确评测目标、评测维度、评测流程三件事。

所谓目标，就是我们要衡量 Agent 调用工具的哪个能力，通常聚焦在“是否又准又稳”；维度则是把笼统的“准”拆成可量化的子项：工具选择准确率、参数填充正确率、调用成功率、错误恢复能力；流程则是定义工具集 → 构建测试集（含黄金答案）→ 运行评测 → 汇总指标 → 输出报告。为了让总分可复现，评测会把每个任务先单独打分，再取平均：

有了这张“考核方案”，小杨后续所有动作都有了依据——哪些算分、哪些不算，白纸黑字写清楚。评测框架就是 Agent 考核的宪法，后面的一切指标、数据集、报告都从它派生，框架不定，后面的分数就是一笔糊涂账。

2. 工具集构建

考核方案落笔后，小杨先整理“热线电话簿”。公司给 Agent 装了三部热线：天气热线（报城市名）、汇率热线（报币种对）、计算热线（报算式）。电话簿上每条热线都写清“负责什么、需要什么材料”——这套电话簿，在评测里就叫工具集。

工具集的核心是工具注册表，每个工具用三条信息描述：工具名称、用途说明、参数模式（参数名、类型、是否必填）。Agent 正是根据这些描述决定调哪个工具、填什么参数，所以描述写得越清楚，评测越公平——电话簿如果写着“汇率热线啥都能查”，Agent 把买菜钱也算进去就不奇怪了。工具集设计还讲究“模拟与真实”：生产环境的真实 API 不稳定、有费用、难控制出错，因此评测大多使用模拟工具，接口行为固定，可以随意注入超时和报错，每次评测都能复现。同时任务按难度分级：有的描述直白，一看就知道调哪个工具；有的要绕弯子，比如“帮我算算今天买菜花了多少钱”，需要 Agent 先判断哪个工具能用。

为了保证评测覆盖面，需要统计工具覆盖率——被测试到的工具占全部工具的比例：

电话簿越全，考核越有说服力。如果模拟工具连“占线”都不支持，就永远测不出 Agent 的临场反应。工具集构建决定了评测的天花板——热线都没铺好，后面的分数再高也是自欺欺人。

3. 核心指标设计

考核正式开始，小杨从抽屉里抽出三张不同颜色的计分卡。第一张卡记“有没有拨对号码”，第二张记“报的工单信息对不对”，第三张记“电话最后办成了没有”。三张卡各管一摊，拼出一幅完整画像——这正是 API 调用评测的三个核心指标：工具选择准确率、参数填充正确率、调用成功率。

不管 Agent 底层用的是什么大模型，评测只看它的“调用行为输出”：选了什么工具、填了什么参数、服务端是否返回成功。三个指标分别回答“去对地方了吗、材料带齐了吗、事情办成了吗”。

选择准确率（Selection Accuracy）：Agent 选出的工具是否与黄金答案标注的工具一致。选错热线，就像客户要查汇率却转到了计算台。

参数填充正确率（Parameter Correctness）：选对了工具还不够，工单上的每一项信息都得填对。查天气却把城市写成“北京朝阳区”，和写成“北京”就是两种结果。

调用成功率（Call Success Rate）：最后看结果——电话接通且服务端正常返回了可用结果。注意，这里的“成功”要求选对工具 + 参数合法 + 服务端正常响应，三者缺一不可。

综合评分（Weighted Score）：三张卡拼起来后，按业务重要性加权合成一个总分，便于横向比较与回归跟踪。

三张卡拼起来看才不会误判——只盯第一张，会漏掉“拨对号码却报错参数”的 Agent；只盯第三张，更会把“错打热线但对面居然接了”当成优秀员工。指标拆得越细，质检报告越有说服力，这正是评测区别于“凭感觉”的地方。

4. 数据集与黄金答案

有了计分卡，接下来得有“题”。小杨去机房翻出历史通话记录，挑出一批有代表性的客户请求，再让最资深的话务员给每题写下标准答案：这道题应该打哪条热线、报什么参数。这份标准答案，在评测里叫黄金答案（Golden Answer）。

数据集的构建分四步。第一，提示词构建：把真实场景整理成多样化的用户请求，覆盖不同工具、不同难度、不同表达方式，避免评测集“偏科”。第二，黄金答案标注：每条请求标注“正确工具名 + 完整参数”，作为判分基准；标注规范要精确到每个必填字段，多人标注后还要做一致性校验。第三，自动比对：运行时把 Agent 的预测与黄金答案按指标逐项比对，全程机器打分，速度一致，口径统一。第四，人工抽检：对自动比对结果中的异常样本抽检，防止标注错误或判分歧义。

黄金答案的质量直接决定评测可信度。若标注本身错了，Agent 答对了也会被扣分。判分时常用“完全匹配率”衡量整体达标情况，即工具和参数都必须与黄金答案完全一致才记对：

标准答案越严谨，机器判分越公平。小杨把录音答案归档成册，从此每次考核都用同一把尺子——不同版本、不同模型之间才真正可比。

5. 错误恢复评估

真实工作哪有那么顺利。小杨在第一轮考核后加了一场“压力演习”：故意让汇率热线占线、让天气热线超时、让 Agent 提交的工单被系统退回。她要看的，是这位新人被拒绝之后怎么办——是反复重拨同一个号码，还是换个思路？

这对应评测中的错误注入与错误恢复评估。评测系统通过模拟工具主动制造错误，观察 Agent 的应对策略。第一是重试策略：是否重试同样的调用、是否调整参数后再调用、重试间隔是否合理。第二是降级处理：主工具不可用时，能否选择备选工具完成同一目标，比如汇率热线占线时改走备用汇率接口。第三是用户告知：最终无法完成时，是否向用户清晰说明失败原因，而不是假装成功——这一点常被忽视，却直接关系用户体验。衡量恢复能力的常规指标是恢复成功率：

演习中，那位 Agent 遇到占线先重试了一次，又改打备选热线，实在不行还跟用户道歉说明——小杨在“临场应变”一栏打了高分。错误恢复评估测的不是“会不会出错”，而是“出错之后有没有救回来”，这决定了 Agent 能不能真正上生产。

6. 结果分析与报告

考核结束，小杨没急着下结论，而是把所有红卡片摊在桌上。她发现 Agent 有接近一半的失败集中在“把汇率热线和计算热线搞混”——这不是粗心，而是电话簿描述有歧义；还有三成失败是参数漏填，集中在长对话场景。这些规律，就是质检报告的核心价值。

评测结果分析要依次回答“错在哪、为什么错、怎么改”。第一是错误聚类：把失败案例按错误类型分组，比如选错工具、参数缺失、参数类型错误、调用超时，找出高频模式。第二是失败归因：结合提示词和工具描述分析诱因——是工具描述太泛，是边界场景未覆盖，还是提示词本身有歧义。第三是改进建议：把归因翻译成可执行的动作，比如改写工具描述、补充示例、调整系统提示词。第四是回归对比：记录当前版本分数，下次评测用同一套数据再跑一遍，验证改进是否真的生效。为了让团队聚焦最关键问题，可以计算错误集中度：

报告最后一行写着：“选错工具类错误占 45%，建议优化汇率工具描述，下轮复测。”评测不是为了给 Agent 打差评，而是让每一次失败都变成可执行的改进路线——这才是 API 调用准确率评测的终局。

AI 应用场景

Python 演示

#-*- coding: utf-8 -*-"""演示: 用三指标评测一个模拟 Agent 的 API 调用准确率"""import json TOOLS = {    "weather": {"desc": "查询城市天气", "params": ["city"]},    "currency": {"desc": "查询货币汇率", "params": ["from", "to"]},    "calc": {"desc": "数学计算", "params": ["expr"]}} GOLD_CASES = [    {"prompt": "北京的天气怎么样", "tool": "weather", "params": {"city": "北京"}},    {"prompt": "100美元等于多少人民币", "tool": "currency", "params": {"from": "USD", "to": "CNY"}},    {"prompt": "计算 2 加 3 乘 4", "tool": "calc", "params": {"expr": "2+3*4"}},    {"prompt": "上海的天气如何", "tool": "weather", "params": {"city": "上海"}},    {"prompt": "10欧元等于多少日元", "tool": "currency", "params": {"from": "EUR", "to": "JPY"}}] def mocked_agent(prompt):    """模拟被测 Agent, 输入用户请求, 返回 (工具名, 参数字典)"""    if "天气" in prompt:        city = "北京" if "北京" in prompt else "上海"        return ("weather", {"city": city})    if "美元" in prompt:        return ("currency", {"from": "USD", "to": "CNY"})    if "欧元" in prompt:        return ("calc", {"expr": "10"})    return ("calc", {"expr": prompt.split("计算")[-1].strip()}) def match_params(pred, gold):    if set(pred.keys()) != set(gold.keys()):        return False    return all(pred[k] == gold[k] for k in gold) def evaluate():    n = len(GOLD_CASES)    sel_ok = param_ok = call_ok = 0    detail = []    for case in GOLD_CASES:        pred_tool, pred_params = mocked_agent(case["prompt"])        sel = pred_tool == case["tool"]        par = sel and match_params(pred_params, case["params"])        call = par        sel_ok += int(sel)        param_ok += int(par)        call_ok += int(call)        detail.append({"prompt": case["prompt"], "gold": case["tool"],                       "pred": pred_tool, "sel_ok": sel, "param_ok": par})    print(json.dumps(detail, ensure_ascii=False, indent=2))    print("选择准确率: %.0f%%" % (sel_ok * 100.0 / n))    print("参数正确率: %.0f%%" % (param_ok * 100.0 / n))    print("调用成功率: %.0f%%" % (call_ok * 100.0 / n)) if __name__ == "__main__":    evaluate()

1. def mocked_agent(prompt):模拟被测 Agent，输入用户请求后返回“预测工具 + 参数”，相当于考试中的考生。
2. sel = pred_tool == case["tool"]第一张计分卡：预测工具名与黄金工具名是否一致，对应选择准确率。
3. par = sel and match_params(pred_params, case["params"])第二张计分卡：先确认选对工具，再逐参数比对，避免“选对号码报错工单”被算对。
4. return set(pred.keys()) != set(gold.keys())先检查参数键集合是否一致，键都对不上就不用逐值比对了。
5. return all(pred[k] == gold[k] for k in gold)逐键比对参数值，全部相同才返回 True。
6. call = par第三张计分卡：模拟服务端只在参数合法时返回成功，现实中还可加入超时与重试逻辑。
7. print("选择准确率: %.0f%%" % (sel_ok * 100.0 / n))汇总输出三个指标，百分比统一保留整数，方便写进评测报告。

常见误区

面试题