適用於 Microsoft 365 Copilot 評估 CLI 的工具呼叫評估工具

工具呼叫評估程式會檢查執行階段診斷 (開發人員資訊) ,以驗證工具選擇和 HTTP 執行結果。 它們是確定性的,不使用 LLM 判斷,也不判斷回應文字或要求 expected_response。

注意

工具呼叫評估工具需要 Microsoft 365 Copilot 評估 CLI v2 (preview) 和結構描述 v2。 它們不適用於 CLI v1 (latest) 。

評估工具 支票 Scale 信用額度 預設為啟用
ToolCallSelection 是否已選取預期的工具識別 通過/失敗/錯誤 1.0,已修正 否
ToolCallExecution 每個預期的呼叫是否有不同的成功 HTTP 執行 通過/失敗/錯誤 1.0,已修正 否

如需一般資料集設定,請參閱 設定評估工具。

設定預覽 CLI

請遵循 快速入門中的租用戶存取權和執行階段必要條件。 如果您只執行判斷性評估工具,則不需要 Microsoft Foundry 評分設定。

安裝預覽版本並接受授權條款:

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

在您的評估環境中為您的 Microsoft 365 租用戶設定 TENANT_ID 。 對於已部署的宣告式代理程式,請在執行資料集時傳遞 --m365-agent-id "<your-agent-id>" 。

如需獨立外掛程式評估,請先在 Microsoft 365 Copilot 中佈建和啟用外掛程式,然後在 Copilot 中完成任何必要的連接器登入。 在沒有設定代理程式識別碼的情況下,v2 預覽會評估 Copilot 聊天。 保留 M365_AGENT_ID 和舊版 AGENT_ID from your shell and loaded environment files for these runs. 這會評估使用可用外掛程式的 Copilot 回應,而不是單獨的外掛程式端點。

安裝任一 npm 發行標籤會取代全域 runevals 命令。 若要回到 v1,請重新安裝 @microsoft/m365-copilot-eval@latest。

允許工具呼叫

當工具需要確認時,請設定核准和評估者期望。 default_allowed_tools 在文件層級並 allowed_tools 按每個提示或回合,讓 CLI 核准工具確認提示。 必須允許每個要求的同意識別碼;否則,提示會停止並出現 toolCallNotAllowed 錯誤。

重要

允許通話會授與同意。 檢閱您要核准的作業,並從唯讀案例開始。 期望不會給予同意;核准不會強制選取項目或證明執行。 未要求確認的工具不受此清單控制,因此它不是安全性界限。

同意識別碼與 calls[].tool 身分識別碼不同。 請勿分割同意識別碼來填入評估者身分欄位。

尋找工具呼叫名稱

對於宣告式代理程式,用 runevals --list-tools 來列出同意識別碼和可複製的評估者身分識別。 Microsoft 365 代理程式工具組也可以檢查取得代理程式的啟動資訊。 如果是獨立外掛程式, --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 需要應用程式的存取權,以及) (atk auth login m365 單獨的 Microsoft 365 登入。 其帳戶可能與用於評估的帳戶不同。

獨立外掛程式

從外掛程式的應用程式資訊清單建構每個同意識別碼 () 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 string M365_TITLE_ID例如env\.env.local,從已部署的代理程式或外掛程式專案的環境檔案複製。 這是套件標題 ID (plugin.titleId 在開發人員資訊) , 而不是plugin.id。 即使 CLI 已以該宣告式代理程式為目標,仍為必要。
toolset_id 字串 針對宣告式代理程式動作,請在宣告式代理程式資訊清單中使用其 actions[].id 。 若為獨立的外掛程式,請在 agentConnectors[].id 應用程式資訊清單中使用其外掛程式。
function_name 字串 例如,由您的外掛程式定義的函數名稱。get_product 保存外殼;這會報告為 functionDisplayName 開發人員資訊。

Tuple (plugin_id, toolset_id, function_name) 唯一識別工具。 比對會區分大小寫。 使用動作或連接器識別碼,而非顯示名稱。 例如:

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

評估工具設定

在 下或ToolCallExecution中default_evaluators,或在項目或車削evaluators物件中設定這些選項ToolCallSelection:

選項 Type (類型) 必要 描述
calls array 是 預期選取項目或執行的非空清單。
calls[].id 字串 否 非空,評估者本機診斷標籤;不是執行階段通話識別碼。 針對每個期望使用唯一標籤。
calls[].tool 物件 是 來自 工具呼叫身分識別的所有三個欄位。
allow_additional_calls 布林值 否 僅限 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 省略保留的診斷。

它不會修訂提示、回應、評估工具選項或原生驗證訊息。 共用前先檢閱成品。 隱藏的證據無法重播。