Microsoft 365 Copilot 評価 CLI 用のツール呼び出しエバリュエーター

ツール呼び出しエバリュエーターは、ランタイム診断 (開発者情報) を検査して、ツールの選択と HTTP 実行の結果を確認します。 これらは決定論的であり、LLM ジャッジを使用せず、応答テキストを判断したり、 expected_responseを要求したりしません。

注

ツール呼び出しエバリュエーターには、Microsoft 365 Copilot Evaluations CLI v2 (preview) と Schema v2 が必要です。 CLI v1 (latest) では使用できません。

Evaluator 小切手 [倍率] 限度額 既定で有効
ToolCallSelection 期待するツール ID が選択されたかどうか 成功/不合格/エラー 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 で必要なコネクタ サインインを完了します。 エージェント ID が構成されていない場合、v2 プレビューは Copilot チャットを評価します。 これらの実行のために、シェルおよびロードされた環境ファイルから M365_AGENT_ID と従来の AGENT_ID を保持します。 これにより、プラグイン エンドポイントを単独で評価するのではなく、使用可能なプラグインを使用する Copilot 応答が評価されます。

いずれかの npm リリース タグをインストールすると、グローバル runevals コマンドに置き換えられます。 v1 に戻すには、 @microsoft/m365-copilot-eval@latest を再インストールします。

ツール呼び出しを許可する

ツールで確認が必要な場合は、承認と評価者の期待の両方を構成します。 default_allowed_tools ドキュメント レベルでプロンプトごとに allowed_tools またはターンごとに、CLI にツール確認プロンプトを承認させます。 要求されたすべての同意識別子を許可する必要があります。それ以外の場合、プロンプトは toolCallNotAllowed エラーで停止します。

重要

呼び出しを許可すると、同意が付与されます。 承認している操作を確認し、読み取り専用のシナリオから開始します。 期待は同意を与えるものではありません。承認によって、選択が強制されたり、実行が証明されたりすることはありません。 確認を要求しないツールは、この一覧によって制御されないため、セキュリティ境界ではありません。

同意識別子は、 calls[].tool ID とは異なります。 同意識別子を分割して評価者 ID フィールドに入力しないでください。

ツール呼び出し名を検索する

宣言型エージェントの場合は、 runevals --list-tools を使用して同意識別子とコピー可能な評価者 ID を一覧表示します。 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で ID を確認します。

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 entry
Contoso Catalog get_product ContosoCatalog_get_product
Contoso Catalog-Tools_1! get_product ContosoCatalogTools1_get_product

または、評価を 1 回実行します。ツールに同意が必要で許可されていない場合は、結果メッセージにそのツール名が含まれます。

ツール呼び出し ID

3 つの ID フィールドはすべて、 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 として報告されます。

タプル (plugin_id, toolset_id, function_name) はツールを一意に識別します。 一致では大文字と小文字が区別されます。 表示名ではなく、アクション ID またはコネクタ ID を使用します。 次に例を示します。

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

エバリュエーターの構成

default_evaluatorsの [ToolCallSelection] または [ToolCallExecution]、またはアイテムまたはターンの evaluators オブジェクトで、次のオプションを構成します。

オプション Type 必須 説明
calls array ○ 予期される選択または実行の空でないリスト。
calls[].id 文字列 × 空ではない、評価者のローカル診断ラベル。ランタイム呼び出し ID ではありません。 期待値ごとに一意のラベルを使用します。
calls[].tool オブジェクト ○ [ツール呼び出し ID] の 3 つのフィールドすべて。
allow_additional_calls ブール値 × ToolCallSelection のみ。 既定値は true です。 [ false ] に設定すると、余分に選択された ID (未識別の選択を含む) を拒否します。

ToolCallSelection

ToolCallSelection は、順序と重複を無視して、予想されるツール ID のセットをチェックします。 実行の成功や呼び出し回数は検証されません。

ToolCallSelection サンプル データセット

このデータセットを evals\tool-selection.json として保存します。 サンプルの ID と同意識別子を独自のものに置き換えます。

{
  "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

スタンドアロンプラグインシナリオの場合は、「プレビューCLIの設定」で説明されているように、--m365-agent-idを省略し、エージェントIDが構成されていないことを確認します。

次の結果は、 plugin_id と toolset_id が例と一致することを前提としています。

確認された選択範囲 このサンプルの結果
get_product(重複するエントリを含む) 合格
get_product と別の関数 失敗: 追加選択
選択した関数がありません ([]) 失敗: 必要な選択がありません
利用できないテレメトリ (null) エラー

ToolCallExecution

ToolCallExecution では、calls 内のエントリごとに HTTP ステータス 200 から 299 の整数で個別の一致実行が必要です。 ID を繰り返して、複数の正常な実行を要求します。

再試行の失敗を含む追加の試行は許可されます。 HTTP の成功だけでは、ビジネスの正確性や回答の質が確立されるわけではありません。

ToolCallExecution サンプル データセット

このデータセットを evals\tool-execution.json として保存し、サンプルの ID と同意識別子を独自のものに置き換えます。

{
  "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 合格: 失敗したものの 2 回の成功
200 失敗: 成功 1 回のみ
200、不明 エラー: 2 番目の呼び出しは不明な結果で満たされる可能性があります

このサンプルでは、どの製品 ID が使用されたかではなく、成功した 2 つの呼び出しを確認します。 それぞれの期待には、個別の実行が必要です。1 回の実行では、両方を満たすことはできません。

結果の解釈

次のルールを使用して、エラーとエバリュエーター エラーを区別します。

オブザベーション 結果
想定されるすべての選択が存在し、追加選択のルールが満たされます 選択パス
必要な選択が信頼できるリストにありません 選択に失敗しました
十分な数の個別の HTTP 2xx 実行が、すべての予想される ID と一致します 実行パス
予期される実行 ID が見つからないか、確認された結果によって必要な成功数を実行できない 実行に失敗する
確認された呼び出しの ID が不完全な 想定される呼び出しにクレジットされない
必要なテレメトリが利用できない、複数の開発者情報アーティファクトが原因で信頼できるスナップショットが生成できない、または解析不能な 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"
    }
  }
}

診断と Saved-Response の評価

出力 ツール呼び出しの証拠
JSON diagnostics.tool_calls
CSV 完全なシリアル化された診断オブジェクト
HTML / コンソール 選択項目と HTTP 結果を含むツール呼び出し診断

選択表示により ID が重複排除されます。実行診断は、すべての試行を保持します。 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保持された診断を省略します。

プロンプト、応答、評価機能オプション、ネイティブ検証メッセージは編集されません。 共有する前に成果物を確認します。 抑制された証拠を再生することはできません。