适用于智能 智能 Microsoft 365 Copilot 副驾驶® 副驾驶® 的工具调用评估程序 评估 CLI

工具调用评估程序检查运行时诊断 (开发人员信息) ,以验证工具选择和 HTTP 执行结果。 它们是确定性的,不使用 LLM 评委,也不评判回复文本或要求 expected_response.

注意

工具调用评估程序需要 智能 智能 Microsoft 365 Copilot 副驾驶® 副驾驶® 评估 CLI v2 (preview) 和架构 v2。 它们在 CLI v1 (latest) 中不可用。

评估器 检查 缩放 阈值 默认启用
ToolCallSelection 是否选择了预期的工具标识 通过/失败/错误 1.0,固定 否
ToolCallExecution 每个预期调用是否具有独特的成功 HTTP 执行 通过/失败/错误 1.0,固定 否

有关常规数据集设置,请参阅 配置赋值器。

设置预览 CLI

按照 快速入门中的租户访问和运行时先决条件进行操作。 如果仅运行确定性计算器,则不需要 Microsoft Foundry 评分配置。

安装预览版并接受许可条款:

npm install -g @microsoft/m365-copilot-eval@preview
runevals accept-eula

TENANT_ID在评估环境中设置 Microsoft 365 租户。 对于已部署的声明式代理,在运行数据集时通过 --m365-agent-id "<your-agent-id>" 。

对于独立插件评估,请先在智能 智能 Microsoft 365 Copilot 副驾驶® 副驾驶® 中预配和启用插件,然后在 Copilot 中完成任何必需的连接器登录。 如果没有配置代理 ID,v2 预览版将评估 Copilot 聊天。 保留 M365_AGENT_ID 和 AGENT_ID 旧版 of shell 并加载这些运行的环境文件。 这将评估使用可用插件而不是孤立插件终结点的 Copilot 响应。

安装任一 npm release 标记将替换全局 runevals 命令。 若要返回到 v1,请重新安装 @microsoft/m365-copilot-eval@latest。

允许工具调用

当工具需要确认时,配置审批和评估者的期望。 default_allowed_tools 在文档级别 allowed_tools ,按提示或轮次让 CLI 批准工具确认提示。 必须允许每个请求的同意标识符;否则,提示将停止并显示 toolCallNotAllowed 错误。

重要

允许通话即表示同意。 查看要批准的操作,并从只读方案开始。 期望不会授予同意;审批不会强制选择或证明执行。 不请求确认的工具不受此列表控制,因此它不是安全边界。

同意标识符不同 calls[].tool 于标识。 请勿拆分同意标识符来填充评估者标识字段。

查找工具调用名称

对于声明性代理,用于 runevals --list-tools 列出同意标识符和可复制的评估程序标识。 Microsoft 365 Agents Toolkit 还可以检查获取的代理的启动信息。 对于独立插件, --list-tools 不支持;请改为从应用清单构造同意标识符。

声明性代理

# List consent identifiers and evaluator identities for declarative agent actions.
npx -y --package @microsoft/m365-copilot-eval@preview runevals --list-tools "<your-agent-id>"

# Alternatively, inspect launch information with Agents Toolkit.
# Use the package Title ID without the .declarativeAgent suffix.
atk launchinfo --title-id "<your-title-id>"

可能未列出动态发现的工具。 工具调用评估后,在 JSON 报告的 diagnostics.tool_calls.

Agents Toolkit 需要访问应用,并且需要单独的 Microsoft 365 登录 (atk auth login m365) 。 其帐户可能与用于评估的帐户不同。

独立插件

根据插件的应用清单构造每个同意标识符 (agentConnectors[]) 如下所示:

<connector display name with only A-Z, a-z, and 0-9 retained>_<function name>

保留大小写。 仅从连接器显示名称中删除空格、连字符、下划线、标点符号和非 ASCII 字符。 保持函数名称不变。

连接器显示名称 函数名称 allowed_tools 条目
Contoso Catalog get_product ContosoCatalog_get_product
Contoso Catalog-Tools_1! get_product ContosoCatalogTools1_get_product

或者,运行一次评估:如果工具需要同意但不允许,则结果消息将包含其工具名称。

工具调用标识

所有三个标识字段都是必需的calls[].tool

域 类型 说明
plugin_id 字符串 M365_TITLE_ID例如,从已部署的代理或插件项目的环境文件复制。env\.env.local 这是开发者信息) 中 (plugin.titleId 的包标题 ID, 而不是plugin.id。 即使 CLI 已面向该声明性代理,也是必需的。
toolset_id 字符串 对于声明性代理操作,请在声明性代理清单中使用其 actions[].id 。 对于独立插件,请在应用清单中使用它 agentConnectors[].id 。
function_name 字符串 插件定义的函数名,例如 get_product。 保留外壳;这将在开发人员信息中报告 functionDisplayName 。

元组 (plugin_id, toolset_id, function_name) 唯一标识工具。 匹配区分大小写。 使用操作或连接器 ID,而不是显示名称。 例如:

{
  "plugin_id": "T_1234",
  "toolset_id": "catalog",
  "function_name": "get_product"
}

评估程序配置

在项或轮evaluators对象下ToolCallSelectionToolCallExecutiondefault_evaluators或中配置这些选项:

选项 类型 必需 描述
calls array 是 预期选择或执行的非空列表。
calls[].id 字符串 否 非空,评估者-局部诊断标签;不是运行时调用 ID。 为每个预期使用唯一的标签。
calls[].tool 对象 是 工具调用标识中的所有三个字段。
allow_additional_calls boolean 否 仅限 ToolCallSelection。 默认为 true. 设置为 以 false 拒绝任何额外的选定标识,包括无法识别的选择。

ToolCallSelection

ToolCallSelection 检查一组预期的工具标识,忽略顺序和重复项。 它不会验证执行成功或调用计数。

ToolCallSelection 示例数据集

将此数据集另存为 evals\tool-selection.json. 将示例标识和同意标识符替换为自己的标识符和同意标识符:

{
  "schemaVersion": "2.0.0",
  "default_allowed_tools": ["ContosoCatalog_get_product"],
  "default_evaluators": {
    "ToolCallSelection": {
      "calls": [
        {
          "tool": {
            "plugin_id": "T_1234",
            "toolset_id": "catalog",
            "function_name": "get_product"
          }
        }
      ],
      "allow_additional_calls": false
    }
  },
  "items": [
    {
      "prompt": "Find product SKU-123 in the Contoso Catalog."
    }
  ]
}

针对已部署的声明性代理运行:

runevals --m365-agent-id "<your-agent-id>" --prompts-file evals\tool-selection.json --output results\tool-selection.json

对于独立插件方案,请 --m365-agent-id 省略并确保未配置代理 ID,如 “设置预览 CLI”中所述。

以下结果假定 plugin_id 并 toolset_id 匹配该示例。

已观察到的选择 此示例的结果
get_product,包括重复条目 通行证
get_product 和另一个函数 失败:附加选择
未选定函数 ([]) 失败:缺少必需的选择
遥测 (null) 不可用 错误

ToolCallExecution

ToolCallExecution 需要一个不同的匹配执行,对于 中的每个条目calls,HTTP 状态为整数 200-299。 重复标识以要求多次成功执行。

允许其他尝试,包括失败的重试。 仅靠 HTTP 的成功并不能确定业务正确性或答案质量。

ToolCallExecution 示例数据集

将此数据集另存为 evals\tool-execution.json ,并将示例标识和同意标识符替换为您自己的标识符和同意标识符:

{
  "schemaVersion": "2.0.0",
  "default_evaluators": {
    "ToolCallExecution": {
      "calls": [
        {
          "id": "first-lookup",
          "tool": {
            "plugin_id": "T_1234",
            "toolset_id": "catalog",
            "function_name": "get_product"
          }
        },
        {
          "id": "second-lookup",
          "tool": {
            "plugin_id": "T_1234",
            "toolset_id": "catalog",
            "function_name": "get_product"
          }
        }
      ]
    }
  },
  "items": [
    {
      "prompt": "Look up products SKU-123 and SKU-456 individually in the Contoso Catalog.",
      "allowed_tools": ["ContosoCatalog_get_product"]
    }
  ]
}

使用与选择示例相同的目标配置运行数据集:

runevals --m365-agent-id "<your-agent-id>" --prompts-file evals\tool-execution.json --output results\tool-execution.json
观察到匹配的 HTTP 结果 此示例的结果
200, 200 通行证
500, 200, 200 通过:尽管尝试失败,但仍成功两次
200 失败:只有一次成功
200, 未知 错误:未知结果可能满足第二次调用

此示例检查两个成功的调用,而不是使用了哪些产品 ID。 每个期望都需要不同的执行;一次执行无法同时满足两者。

解释结果

使用这些规则将故障与评估程序错误区分开来:

观察 结果
每个预期的选择都存在,并且满足其他选择的规则 选择阶段
权威列表中没有所需的选择 选择失败
足够多的不同 HTTP 2xx 执行与每个预期标识匹配 执行阶段
缺少预期的执行标识,或确认的结果无法执行所需的成功计数 执行失败
观察到的调用具有不完整的标识 未记入任何预期调用
所需的遥测不可用,多个开发人员信息项目阻止权威快照,或者无法分析的 HTTP 结果可能会改变判定 评估程序错误: toolCallEvidenceIndeterminate

如果未知的证据无法完成所有期望,则确定的失败优先。 不可读的额外尝试不会使足够多的已确认成功无效。

通过 = 1.0;失败 = 0.0。 错误省 score 略 ; threshold它们不一定是传递或不一定是代理缺陷。 JSON 分数键为 toolCallSelection 和 toolCallExecution:

{
  "scores": {
    "toolCallSelection": {
      "score": 1.0,
      "result": "pass",
      "threshold": 1.0,
      "reason": "All expected tool functions were selected."
    },
    "toolCallExecution": {
      "result": "error",
      "error": "Developer Info execution telemetry is unavailable.",
      "code": "toolCallEvidenceIndeterminate"
    }
  }
}

诊断和保存的响应评估

输出 工具调用证据
JSON diagnostics.tool_calls
CSV 完整的序列化诊断对象
HTML/控制台 包含选择和 HTTP 结果的工具调用诊断

选择显示删除重复身份;执行诊断将保留每次尝试。 null 表示无法获得的证据; [] 表示对无呼叫的权威观察。

在不执行提示的情况下对保存的选择和执行结果重新评分。 每个已保存的物品或回合都必须包含一个 response:

npx -y --package @microsoft/m365-copilot-eval@preview runevals --evaluate-only results\captured-tool-calls.json --output results\rescored.html

警告

诊断可能包含敏感工具和执行详细信息。 EVALS_SUPPRESS_DIAGNOSTICS=true省略保留的诊断。

它不会编辑提示、响应、评估程序选项或本机验证消息。 在共享之前审查项目。 隐藏的证据不可重播。