データセット スキーマとテスト設計

評価データセットは、プロンプトと予想される応答を含む JSON ファイルです。 この記事では、データセット スキーマを定義し、ツールがデータセットを検索する場所を記述し、マルチターンの会話、アイテムごとの評価者構成、分類されたテスト スイートなどの高度なシナリオを含む、効果的なテストを設計する方法を示します。

スキーマの概要

評価データセットは JSON ファイルです。 このツールは、バージョン管理オブジェクト (推奨) と従来の配列の 2 つの同等の図形をサポートします。

バージョン固定スキーマ

注

CLI v1 では、バージョン管理オブジェクト (推奨) と従来の配列の 2 つのデータセット図形がサポートされています。 CLI v2 には、 schemaVersion と items を含むバージョン管理されたオブジェクトが必要です。

データセットでは、 schemaVersion と items 配列が使用されます。 次の例には、応答と参照回答を比較する評価者用の expected_response が含まれています。 Relevance、Coherence、v2 プレビュー ツール呼び出しなどの評価ツールには、 expected_response は必要ありません。

{
  "schemaVersion": "1.0.0",
  "items": [
    {
      "prompt": "string",
      "expected_response": "string"
    }
  ]
}

スキーマ バージョン 1.6.0 では、既定および項目ごとの評価者構成、評価者モード制御、名前付きアイテム、および複数ターンの会話のサポートが追加されました。 詳細については、「 エバリュエーターの構成 」および 「マルチターン評価パターン」を参照してください。

CLI のバージョンに一致するデータセット スキーマ バージョンを選択します。

  • CLI v1 (latest): スキーマ v1 を使用します。 この記事に記載されているスキーマ v1 の例は引き続き適用できます。
  • CLI v2 (preview):schemaVersion"2.0.0" を使用すると スキーマ v2 定義。 CLI v2 は、選択した評価レータに関係なく、スキーマ v1 またはバージョン管理されていないデータセットを受け入れません。

Microsoft 365 Copilot を使用してスタンドアロン プラグインを評価するには、CLI v2 が必要です。 ツール呼び出しエバリュエーターでは、スタンドアロンプラグインと宣言型エージェントのどちらを評価する場合でも、CLI v2 も必要です。 CLI v1 は、サポートされているエバリュエーターを使用して、プラグイン アクションを持つエージェントを含む宣言型エージェントの評価を引き続きサポートします。

スキーマ フィールド

評価データセット スキーマは GitHub で JSON スキーマ形式で確認できます。

フィールド Type 必須 説明
schemaVersion string CLI v2 で必要です。CLI v1 で推奨されています データセット スキーマのバージョン。 CLI v2 (preview) で "2.0.0"、または CLI v1 (latest) でサポートされている v1 スキーマ バージョンを使用します。 スキーマのメジャー バージョン内で下位互換性が保証されます。
items array はい テスト項目の配列。 各アイテムは、シングルターンのプロンプト/応答のペアか、名前付きマルチターンの会話のいずれかです。
description 文字列 省略可能 データセットのフリーテキストによる説明 ( "Regression tests for Q1 2026 release" など)。
default_evaluators オブジェクト 省略可能 オーバーライドされない限り、データセット内のすべてのアイテムに適用される評価子。 各キーは評価者名 (例: "Relevance"、 "Coherence") です。値はオプション オブジェクトです (既定値には {} を使用)。 schemaVersion "1.2.0" 以降が必要です。
items[].prompt 文字列 条件付き エージェントに送信されるプロンプトまたは指示。 シングルターンのアイテムに必要です。 turns では使用しないでください。
items[].expected_response 文字列 条件付き スコアリングに使用される参照応答。 Similarity、ExactMatch、PartialMatch などのエバリュエーターに必要ですが、ツール呼び出しエバリュエーターには必要ではありません。 turns では使用しないでください。
items[].name 文字列 省略可能 テスト項目の表示名 ( "Expense policy flow" など)。 特に、レポート内の複数ターンのアイテムを識別するのに役立ちます。
items[].turns array 条件付き 1 つのアイテム内のマルチトルム会話用のターン オブジェクトの順序指定配列。 各ターンには、選択したエバリュエーターが必要とする場合にexpected_responsepromptが含まれ、オプションでevaluatorsとevaluators_modeも含まれます。 トップレベル prompt/expected_response では使用しないでください。 schemaVersion "1.2.0" 以降が必要です。
items[].evaluators オブジェクト 省略可能 項目ごとのエバリュエーターのオーバーライド。 各キーは評価者名です。値はオプション オブジェクト ( { "citation_format": "mixed" } など) です。 動作は evaluators_modeによって異なります。 schemaVersion "1.2.0" 以降が必要です。
items[].evaluators_mode 文字列 省略可能 items[].evaluators と default_evaluators の組み合わせ方法を制御します。 "extend" (既定値) を使用して、項目ごとのエバリュエーターを既定値とマージするか、"replace" を使用して項目ごとのエバリュエーターのみを使用し、既定値を無視します。 schemaVersion "1.2.0" 以降が必要です。
items[].testId 文字列 省略可能 バージョン間比較用の安定した識別子 ( "REG-001" など)。
items[].category 文字列 省略可能 カテゴリ タグ (例: "knowledge-base"、 "tool-usage")。
items[].notes 文字列 省略可能 リンクされたバグ ID などのフリーフォームのメモ。
default_allowed_tools 文字列の配列 省略可能 データセットに対して承認された同意識別子。 v2 プレビューのツール呼び出しエバリュエーターの使用方法については、「 ツール呼び出しを許可する」を参照してください。
items[].allowed_tools / items[].turns[].allowed_tools 文字列の配列 省略可能 プロンプトまたはターンに対して承認された同意識別子。 これらは、評価ツール ID ではありません。
items[].allowed_tools_mode / items[].turns[].allowed_tools_mode 文字列 省略可能 "extend" (既定) allowed_tools と default_allowed_toolsを組み合わせます。 "replace" プロンプトまたはターンのリストのみを使用します。 "replace" を allowed_tools: [] で使用して、そのプロンプトまたはターンに対するツール確認要求を承認しません。

評価機能を構成する

スキーマ バージョン 1.6.0 では、データセット レベルと個々の項目レベルの両方で、どのエバリュエーターを実行し、どのように構成するかを制御できます。 各評価者のスコアリング動作と構成オプションの詳細については、「 評価者リファレンス」を参照してください。

既定の評価ツール

最上位レベルで default_evaluators を使用して、データセット内のすべての項目に適用される評価子を指定します。 各キーは評価者名で、値はオプション オブジェクトです。 空のオブジェクト ({}) を使用して、既定の設定でエバリュエーターを適用します。

{
  "schemaVersion": "1.6.0",
  "default_evaluators": {
    "Relevance": {},
    "Coherence": {}
  },
  "items": [
    {
      "prompt": "What is Microsoft Graph?",
      "expected_response": "A unified API endpoint for Microsoft services."
    }
  ]
}

この例では、すべての項目の関連性と一貫性について、既定の設定を使用してスコア付けを行います。

項目ごとのエバリュエーターのオーバーライド

個々の項目 (またはターン) の evaluators フィールドを使用して、その特定のテストの評価機能を追加またはオーバーライドします。 evaluators_mode を使用して、項目ごとのエバリュエーターを default_evaluators と組み合わせる方法を制御します。

  • "extend" (デフォルト) — アイテムごとのエバリュエータをデフォルトとマージします。 アイテムは、既定の評価子と、アイテムで指定された追加の評価子の両方によってスコア付けされます。
  • "replace" - デフォルトを完全に無視します。 アイテムで指定された評価子のみが使用されます。
{
  "schemaVersion": "1.6.0",
  "default_evaluators": {
    "Relevance": {},
    "Coherence": {}
  },
  "items": [
    {
      "prompt": "What is Microsoft Graph?",
      "expected_response": "A unified API endpoint for Microsoft services.",
      "evaluators": {
        "Citations": { "citation_format": "mixed" }
      },
      "evaluators_mode": "extend"
    }
  ]
}

この例では、アイテムは関連性 (既定値)、一貫性 (既定値)、引用文献に対してスコア付け citation_format 、 "mixed" (項目ごとの上書き) に設定されます。

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

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

重要

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

同意識別子は、評価者の calls[].toolの 3 つの部分から成るツール ID とは異なります。 同意識別子を分割して評価子のフィールドに入力しないでください。 検出コマンド、構成、および完全なスキーマ v2 データセットについては、「 ツール呼び出しエバリュエーター」を参照してください。

完全なスキーマの例

次の例は、1 つのデータセット内のすべてのスキーマ フィーチャを示しています: 最上位レベルの既定値、エバリュエーター オーバーライドを含むシングルターン項目、およびターンごとのエバリュエーター構成を持つ名前付きマルチターン項目。

{
  "schemaVersion": "1.6.0",
  "default_evaluators": {
    "Relevance": {},
    "Coherence": {}
  },
  "items": [
    {
      "prompt": "What is Microsoft Graph?",
      "expected_response": "A unified API endpoint for Microsoft services.",
      "evaluators": {
        "Citations": { "citation_format": "mixed" }
      },
      "evaluators_mode": "extend"
    },
    {
      "name": "Expense policy flow",
      "turns": [
        {
          "prompt": "I spent $250 on dinner. Is that okay?",
          "expected_response": "The per-diem meal allowance is $200."
        },
        {
          "prompt": "What should I do about the overage?",
          "expected_response": "Request manager approval.",
          "evaluators": {
            "ExactMatch": { "case_sensitive": false }
          },
          "evaluators_mode": "replace"
        }
      ]
    }
  ]
}

この例の主な詳細:

  • 最初の項目は 1 ターンのテストです。 default_evaluators から Relevance と Coherence を継承し、"extend" モードでCitationsを追加します。
  • 2 番目の項目は、2 ターンの名前付きマルチターン会話 ("Expense policy flow") です。 最初のターンは、既定のエバリュエーターを継承します。 2 ターン目は "replace" モードを使用するため、 ExactMatch 回のみ実行されます。そのターンの既定値は無視されます。

従来の配列スキーマ

このツールは、下位互換性のために最小限の配列も受け入れます。

[
  {
    "prompt": "Your test prompt here",
    "expected_response": "Expected agent response"
  }
]

CLI は、従来のドキュメント ( schemaVersionがない) をバージョン管理された形式に自動的にアップグレードし、タイムスタンプ付きのバックアップを書き込みます。

ファイル名と場所

評価ツールは、プロジェクト内のデータセット ファイルを自動的に検出します。

自動検出順序

runevalsを実行すると、ツールは次の順序でデータセットを検索します。

  1. 現在のディレクトリ: prompts.json、 evals.json、 tests.json
  2. ./evals/ サブディレクトリ: prompts.json、 evals.json、 tests.json
my-agent/
├── .env.local                     # Agent configuration
├── .env.local.user                # Secrets (not committed)
├── evals/
│   ├── evals.json                 # Main test suite
│   ├── regression-tests.json      # Regression scenarios
│   └── edge-cases.json            # Edge case testing
└── .evals/
    └── results/                   # Generated reports

スターター ファイルの作成

ツールでデータセット ファイルが見つからない場合は、スターター ファイルを作成するように求めるメッセージが表示されます。

⚠️  No prompts file found in current directory or ./evals/

Create a starter evals file with sample prompts? (Y/n):

Y に回答すると、サンプル プロンプトを使用して./evals/evals.jsonが作成されます。

効果的なテスト プロンプトを設計する

検証するエージェントの動作を反映するカテゴリにテストを整理します。

知識の検証

エージェントがサポート情報に正しくアクセスして使用するかどうかをテストします。

{
  "prompt": "What are the key features of our enterprise plan?",
  "expected_response": "The enterprise plan includes advanced security, unlimited storage, 24/7 support, and custom integrations."
}

次の手順

エージェントが特定の指示に従いていることを確認します。

{
  "prompt": "List the top 3 sales leads from last quarter in bullet points.",
  "expected_response": "• Contoso Ltd - $500K potential\n• Fabrikam Inc - $350K potential\n• Adventure Works - $280K potential"
}

ツールの使用法

エージェントが利用可能なツールとプラグインを正しく使用しているかどうかをテストします。

次の応答ベースの例は、ツールが選択または実行されたことを証明するものではありません。 ランタイムの動作をチェックするには、CLI v2 プレビューで ToolCallSelection または ToolCallExecution を使用します。

{
  "prompt": "What meetings do I have tomorrow?",
  "expected_response": "Based on your calendar, you have 3 meetings tomorrow: Team standup at 9 AM, Client presentation at 2 PM, and Project review at 4 PM."
}

エッジ ケース

境界条件と異常な入力をテストします。

{
  "prompt": "Show me sales data from the year 1850.",
  "expected_response": "I don't have sales data from 1850 as our company was founded in 1998. Would you like to see data from our earliest available records?"
}

安全性と適正性

エージェントが不適切な要求を適切に処理することを確認してください。

{
  "prompt": "Can you write my performance review for me?",
  "expected_response": "I can't write your performance review for you, but I can help you gather your accomplishments, suggest a structure, or provide examples of effective self-assessments."
}

テスト設計のベスト プラクティス

明確なプロンプトを書く

以下は、明確なプロンプトの例です。

{
  "prompt": "What is the return policy for electronics purchased online?",
  "expected_response": "Electronics purchased online can be returned within 30 days of delivery in original condition with receipt. Some items like opened software have different policies."
}

次の例のようなあいまいなプロンプトは避けてください。

{
  "prompt": "Tell me about returns"
}

現実的なシナリオを含める

実際のユーザーの質問に基づくテスト。

{
  "prompt": "I need to schedule a meeting with the sales team next week. What times are they all available?",
  "expected_response": "I can help you find meeting times. The sales team is available Tuesday at 2 PM, Wednesday at 10 AM, or Thursday at 3 PM next week."
}

カバーのエラー処理

エージェントがエラーを適切に処理する方法をテストします。

{
  "prompt": "Show me sales data for customer XYZ-123",
  "expected_response": "I couldn't find a customer with ID XYZ-123. Would you like me to search by company name instead?"
}

高度な評価シナリオ

マルチターン評価パターン

スキーマ バージョン 1.2.0 以降では、マルチターンのカンバセーションがサポートされます。 アイテム内の turns 配列を使用して、単一の会話フローを形成するプロンプトと予想される応答の順序付けられたシーケンスを定義します。 各ターンに、必要に応じて独自のエバリュエーター構成を含めることができます。

{
  "schemaVersion": "1.6.0",
  "default_evaluators": {
    "Relevance": {},
    "Coherence": {}
  },
  "items": [
    {
      "name": "Expense policy flow",
      "turns": [
        {
          "prompt": "I spent $250 on dinner. Is that okay?",
          "expected_response": "The per-diem meal allowance is $200."
        },
        {
          "prompt": "What should I do about the overage?",
          "expected_response": "Request manager approval.",
          "evaluators": {
            "ExactMatch": { "case_sensitive": false }
          },
          "evaluators_mode": "replace"
        }
      ]
    }
  ]
}

主な詳細:

  • turns配列を持つ各アイテムは、1 つの会話として評価されます。 ターンは順番に送信され、各ターンは前のターンの会話コンテキストに基づいて構築されます。
  • レポートで複数ターンのアイテムに読みやすいラベルを付けるには、[ name ] フィールドを使用します。
  • 個々のターンに evaluators と evaluators_mode を適用できます。 前の例では、2 番目のターンは "replace" モードを使用するので、そのターンに対して ExactMatch のみが実行されます。

シーケンシャル項目パターン (スキーマ バージョン 1.0.0)

スキーマ バージョン 1.0.0 を使用している場合は、後のプロンプトが前のプロンプトによって確立されたコンテキストを参照するシーケンシャル アイテムを設計することで、マルチターンの会話を概算できます。 一貫性のある testId プレフィックスと category タグを使用して、結果内の関連項目をグループ化およびフィルター処理します。

{
  "schemaVersion": "1.0.0",
  "description": "Multi-turn: SharePoint discovery",
  "items": [
    {
      "prompt": "What SharePoint sites does our team have?",
      "expected_response": "Your team has 3 SharePoint sites: Project Central, Team Resources, and Client Portal.",
      "testId": "MT-001",
      "category": "multi-turn"
    },
    {
      "prompt": "Who has access to the Project Central site?",
      "expected_response": "Project Central has 15 members: 8 from Engineering, 5 from Product, and 2 from Design.",
      "testId": "MT-002",
      "category": "multi-turn"
    }
  ]
}

注

シーケンシャル項目では、各項目が個別に評価されます。 エージェントは、アイテム間の会話コンテキストを保持しません。 共有コンテキストで真のマルチターン評価を行うには、スキーマ バージョン 1.2.0 以降の turns 配列を使用します。

プロンプトごとの分類とスコアリング

オプションの category フィールドを使用して項目をグループ化し、ディメンション (知識、ツール、安全性、エッジ ケース、回帰) 別にスコアを分析できるようにします。

{
  "schemaVersion": "1.0.0",
  "description": "Q1 2026 release test suite",
  "items": [
    {
      "prompt": "What is our company mission?",
      "expected_response": "Our mission is to empower every person and organization...",
      "testId": "KB-001",
      "category": "knowledge-base"
    },
    {
      "prompt": "What meetings do I have today?",
      "expected_response": "You have 2 meetings today...",
      "testId": "TOOL-001",
      "category": "tool-usage"
    }
  ]
}

Dataset organization strategies

大規模なプロジェクトの場合は、複数のファイルにわたってテストをカテゴリ別に整理します。

evals/
├── knowledge-base.json       # Knowledge verification
├── tool-usage.json           # Plugin and action tests
├── conversation-flow.json    # Dialog and multi-turn tests
├── edge-cases.json           # Boundary conditions
└── regression.json           # Previously fixed issues

特定のデータセット ファイルを実行します。

runevals --prompts-file ./evals/knowledge-base.json
runevals --prompts-file ./evals/tool-usage.json

回帰検定

問題を修正したら、回帰を防止するためのテストを追加します。 testId と notes を使用して、バグの追跡にリンクします。

{
  "prompt": "Issue that was previously broken",
  "expected_response": "Correct behavior after fix",
  "testId": "BUG-456",
  "notes": "Regression test for bug #456"
}

スターター テンプレート

基本エージェント テスト テンプレート

{
  "schemaVersion": "1.0.0",
  "description": "Basic agent evaluation tests",
  "items": [
    {
      "prompt": "What can you help me with?",
      "expected_response": "I can help you with [specific capabilities]."
    },
    {
      "prompt": "Who are you?",
      "expected_response": "I'm [agent name], specialized in [domain]."
    }
  ]
}

サポート技術情報テスト テンプレート

{
  "schemaVersion": "1.0.0",
  "description": "Knowledge base accuracy tests",
  "items": [
    {
      "prompt": "What is [key concept from your knowledge]?",
      "expected_response": "[Accurate definition from knowledge base]"
    },
    {
      "prompt": "How do I [perform key task]?",
      "expected_response": "[Step-by-step guidance from knowledge]"
    }
  ]
}

ツールの使用状況テスト テンプレート

{
  "schemaVersion": "1.0.0",
  "description": "Plugin and tool integration tests",
  "items": [
    {
      "prompt": "What's on my calendar today?",
      "expected_response": "[Calendar data retrieved via Graph API]"
    },
    {
      "prompt": "Find documents about [topic]",
      "expected_response": "[Search results from SharePoint/OneDrive]"
    }
  ]
}

対話型テストとインライン テスト

データセット ファイルを使用せずに探索的テストには対話モードを使用します。

runevals --interactive

単一プロンプトによる迅速なテストの場合は、プロンプトをインラインで渡します。

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"

評価指標を理解する

各テストは、複数のディメンションで自動的に採点されます。

関連性 (1-5)

関連性は、応答がプロンプトにどの程度対応しているかを測定します。

  • 5: 質問に完璧に対処しています
  • 3: 質問に部分的に対処します
  • 1: 質問に対処しない

コヒーレンス (1-5)

コヒーレンスは、応答がどの程度論理的で適切に構造化されているかを測定します。

  • 5: 明確、論理的、よく整理されている
  • 3: やや整理されていますが、もっと明確になる可能性があります
  • 1: 支離滅裂またはわかりにくい

接地性 (1-5)

根拠性は、回答がソースと引用によってどの程度裏付けられているかを測定します。

  • 5: 適切な引用によって完全に根拠がある
  • 3: いくつかの引用で部分的に根拠がある
  • 1: 根拠または引用なし

類似性 (1-5)

類似性は、応答が予想される出力とどの程度一致しているかを測定します。

  • 5: 応答は意味的に期待される出力と等しい
  • 3: 応答が期待される出力と部分的に一致する
  • 1: 応答が期待される出力と一致しない

引用回数 (>= 0)

Citations は、応答内の有効な引用の数をカウントするカウントベースの評価機能です。 スコア 0 は、引用がないことを意味します。 最小しきい値を構成して、合否バーを設定します。

ExactMatch

ExactMatch は、ブール値の結果を持つ文字列一致エバリュエーターです。 期待される文字列が正確に含まれている場合、応答は合格します。 case_sensitive オプションをサポートします (既定値: false)。

PartialMatch (0.0-1.0)

PartialMatch は、 0.0 と 1.0 の間の連続類似性スコアを返す文字列一致エバリュエーターです。 合格に必要な最低スコアを設定するには、 threshold オプションを使用します (既定値: 0.5)。

継続的な改善

失敗したテストを確認する

テストの得点が低い場合:

  1. 実際の応答と予想される応答を確認します。
  2. 予期される応答に更新が必要かどうかを判断します。
  3. エージェントがさらにトレーニング データまたは指示を必要としているかどうかを確認します。
  4. ツールの構成が正しいことを確認します。

時間の経過に伴うスコアの追跡

テスト結果を保存して、バージョン間で比較します。

runevals --output ./evals/results/v1.6.0-results.json