工具调用评估程序检查运行时诊断 (开发人员信息) ,以验证工具选择和 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省略保留的诊断。
它不会编辑提示、响应、评估程序选项或本机验证消息。 在共享之前审查项目。 隐藏的证据不可重播。