エージェント評価CLI リファレンス

この記事では、@microsoft/m365-copilot-eval パッケージの一部である runevals コマンドの完全なコマンドライン リファレンスを提供します。

概要

runevals [options]
runevals cache-info
runevals cache-clear
runevals cache-dir

説明

runevals コマンドは、Microsoft Foundry クラウド評価と組み込みメトリックを使用して、テスト プロンプトを送信し、応答をスコアリングすることで、Microsoft 365 Copilot エージェントを評価します。 このツールでは、JSON ファイルからのバッチ評価、インライン プロンプト、対話型テストがサポートされています。

オプション

-V, --version

CLI ツールのバージョン番号を出力します。

例:

runevals --version

出力:

1.15.0

--log-level [level]

ログの詳細レベルを設定します。 使用可能なレベル: debug、 info、 warning、 error。

• 既定: 値なしでフラグを使用する場合、既定値は info になります。
• debug: API ペイロードを含む詳細なデバッグ情報。
• 情報: 評価の進行状況に関する一般的な情報。
• 警告: 警告メッセージのみ。
• エラー: エラー メッセージのみ。

例:

# Info level (default when flag is present)
runevals --log-level

# Debug level
runevals --log-level debug

# Error level only
runevals --log-level error

警告

debug レベルには、未加工の API ペイロードとコンソール出力の応答データが含まれる場合があります。 編集はパターン ベースであり、すべての PII または資格情報をキャッチしない場合があります。 手動で確認せずにデバッグ出力を一般公開しないでください。

--prompts <prompts...>

コマンド ラインで 1 つ以上のプロンプトを直接指定すると、ファイルを作成せずにすばやくテストできます。

例:

# Single prompt
runevals --prompts "What is Microsoft 365?"

# Multiple prompts
runevals --prompts "What is Teams?" "What is SharePoint?" "What is OneDrive?"

--expected <responses...>

--prompts で指定された付随するプロンプトに期待される応答を指定します。 応答の数は、プロンプトの数と一致する必要があります。

例:

runevals --prompts "What is Microsoft Graph?" \
  --expected "Microsoft Graph is the API gateway to Microsoft 365 data and intelligence."

複数のプロンプトと応答:

runevals --prompts "What is Teams?" "What is SharePoint?" \
  --expected "Teams is a collaboration platform" "SharePoint is a content management system"

--prompts-file <file>

テスト プロンプトを含むカスタム JSON ファイルを指定します。 このファイルは自動検出をオーバーライドします。

例:

runevals --prompts-file ./tests/my-custom-tests.json

ファイル形式:

[
  {
    "prompt": "Test question",
    "expected_response": "Expected answer"
  }
]

完全なデータセットスキーマについては、 データセットスキーマとテスト設計を参照してください。

-o, --output <file>

出力ファイルのパスと形式を指定します。 形式はファイル拡張子によって決まります。

サポートされる形式:

• .html - HTML レポート (デフォルト、ブラウザで自動オープン)
• .json - JSON 結果
• .csv - CSVスプレッドシート

例:

# HTML output
runevals --output ./reports/results.html

# JSON output
runevals --output ./results/eval-results.json

# CSV output
runevals --output ./data/scores.csv

既定の動作:

--outputがない場合、このコマンドは結果を ./.evals/YYYY-MM-DD_HH-MM-SS.html に保存します。

-i, --interactive

手動によるプロンプトの入力とテストのために、対話型モードに入ります。

例:

runevals --interactive

対話型モードでは、プロンプトを 1 つずつ入力するように求められるので、探索的テストを実行できます。

--m365-agent-id <id>

エージェント ID をオーバーライドして、特定のエージェントを評価します。 このパラメーターは、複数のエージェントをテストする場合や、エージェント ID を自動検出できない場合に便利です。

例:

runevals --m365-agent-id "U_0dc4a8a2-b95f-edac-91c8-d802023ec2d4"

エージェント ID の形式:

• ユーザー スコープ: U_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
• テナント スコープ: T_agent-name.declarativeAgent

--env <environment>

読み込む環境構成を指定します。 このパラメーターは env/.env.<environment> を読み込みます。

既定値: dev ( env/.env.dev を読み込みます)

例:

# Load env/.env.dev (default)
runevals --env dev

# Load env/.env.prod
runevals --env prod

# Load env/.env.staging
runevals --env staging

環境ファイルの優先順位:

1. .env.local (Agents Toolkit プロジェクトでは自動検出)
2. .env.local.user (シークレット、存在する場合は自動読み込み)
3. env/.env.<environment> ( --env で指定)
4. システム環境変数

--init-only

Python 環境を初期化し、評価を実行せずに依存関係をダウンロードします。 このオプションは、次の場合に役立ちます。

• CI/CD パイプラインでのキャッシュの予熱
• インストールに関する問題のトラブルシューティング
• テストを実行する前のセットアップの検証

例:

runevals --init-only

トラブルシューティングのために、このオプションを --log-level debug と組み合わせます。

runevals --init-only --log-level debug

-h, --help

使用可能なコマンドとオプションに関するヘルプ情報を表示します。

例:

runevals --help

キャッシュ コマンド

評価ツールでは、Python ランタイムと依存関係にローカル キャッシュが使用されます。 これらのコマンドは、キャッシュの管理に役立ちます。

cache-info

サイズ、場所、インストールされているパッケージなど、キャッシュされた Python 環境に関する統計情報を表示します。

例:

runevals cache-info

出力:

Cache Information

Location: C:\Users\YourName\.m365-copilot-eval\cache
Size: 245 MB
Python Version: 3.11.5
Packages: 42 installed

Last updated: 2026-04-10 14:23:15

cache-clear

キャッシュされた Python 環境と、ダウンロードされたすべての依存関係を削除します。 インストールの問題のトラブルシューティングを行う場合やディスク領域を解放する場合に、このコマンドを使用します。

例:

runevals cache-clear

フォローアップ:

キャッシュをクリアしたら、次のように再初期化します。

runevals --init-only

cache-dir

キャッシュ ディレクトリの絶対パスを出力します。 この機能は、スクリプトや手動検査に役立ちます。

例:

runevals cache-dir

出力:

C:\Users\YourName\.m365-copilot-eval\cache

スクリプトでの使用法:

# Check cache directory permissions (Unix/macOS)
chmod -R u+w $(runevals cache-dir)

# View cache contents
ls -lah $(runevals cache-dir)

環境変数

このツールは、環境ファイルとシステム変数から構成を読み取ります。 これらの値を取得する詳細な手順については、「 必要な環境変数」を参照してください。

必須変数

変数	説明	例
TENANT_ID	Microsoft Entra テナント ID	xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
AZURE_AI_PROJECT_ENDPOINT	Microsoft Foundry プロジェクト エンドポイント	https://<account>.services.ai.azure.com/api/projects/<project>

オプション変数

変数	説明	既定値
M365_AGENT_ID	評価するエージェント ID	自動検出元 M365_TITLE_ID
M365_TITLE_ID	エージェント タイトル ID (Agents Toolkit)	なし
AZURE_AI_MODEL_NAME	評価のモデル	gpt-5-mini

例

基本的な使用方法

自動検出されたデータセット ファイルを使用して評価します。

cd /path/to/your-agent-project
runevals

環境の指定

実稼働環境構成を使用する:

runevals --env prod

カスタム データセット ファイル

特定のテスト ファイルを使用する:

runevals --prompts-file ./tests/regression-tests.json

インライン テスト

インライン プロンプトを使用したクイック テスト:

runevals --prompts "What is Microsoft 365?" \
  --expected "Microsoft 365 is a cloud-based productivity suite"

対話モード

プロンプトを手動で入力します。

runevals --interactive

カスタム出力形式

JSON 結果を生成する:

runevals --output ./results/eval-$(date +%Y%m%d).json

デバッグ モード

詳細なログで実行:

runevals --log-level debug --output ./debug-results.json

セットアップのみ

テストを実行せずに事前キャッシュする Python 環境:

runevals --init-only --log-level info

エージェント ID の上書き

特定のエージェントをテストする:

runevals --m365-agent-id "U_0dc4a8a2-b95f-edac-91c8-d802023ec2d4"

組み合わせオプション

カスタム設定による総合評価:

runevals \
  --env staging \
  --prompts-file ./evals/full-suite.json \
  --output ./reports/staging-eval-$(date +%Y%m%d).html \
  --log-level info \
  --m365-agent-id "T_my-agent.declarativeAgent"

終了コード

コード	意味
0	成功
1	一般的なエラー
2	無効な引数
3	環境構成エラー
4	エージェントが見つかりません
5	認証の失敗
10	Python 環境セットアップの失敗

トラブルシューティング

インストール、認証、実行時エラー、キャッシュの問題、プロキシのセットアップに関する一般的な問題については、 トラブルシューティング の記事を参照してください。

関連コンテンツ

• エージェント評価 CLI の概要
• クイック スタート: エージェント評価 CLI を使用する
• データセット スキーマとテスト設計