Power Platform API を使用してエージェントの評価を自動化する

Copilot Studioでは、Power Platform REST API を使用して、定義済みのテスト セットに対して自動テストを実行することで、エージェントのパフォーマンスを継続的に評価するツールを提供します。 REST API を使用すると、エージェントの更新、リリース検証、回帰テストなどの開発ワークフローの一部として、エージェントの評価をプログラムでトリガーできます。

評価の自動化は、次のことに役立ちます。

  • 変更後にエージェントの品質を検証する
  • 運用エージェントまたはステージング エージェントに対して定期的なパフォーマンス チェックを実行する
  • CI/CD パイプラインにエージェント テストを統合する
  • 開発ライフサイクルの早い段階でエージェントの動作の回帰を検出する

前提条件

  • ターゲット エージェントの「ボット ID」と「環境 ID」があります。
  • ターゲット エージェントのCopilot Studioで作成されたテスト セット。
  • Microsoft Entra ID (OAuth 2.0) によって発行されたユーザー アクセス トークン。 トークンを取得するには、「 認証」を参照してください。
    • Power Platform API で付与された適切なスコープを持つアプリ登録のクライアント ID を使用して、アクセス トークンを取得する必要があります。
  • エージェント評価の開始では、必要に応じて、評価のユーザー プロファイルとして使用する Microsoft Studio Connector ID を呼び出しに追加できます。 以下のようにしてmcsConnectionIdを見つけましょう。
    1. Power Automate に移動します。
    2. [接続] ページを開きます。
    3. Microsoft Copilot Studio接続を選択します。
    4. URL から mcsConnectionId をコピーします。 .../connections/shared_microsoftcopilotstudio/{mcsConnectionId}/details

REST API を使用した評価の実行の概要

Power Platform API を使用して評価を実行するには、次の一般的な手順に従います。

  1. 前提条件を満たす。
  2. 使用する テスト セットのテスト セット ID を 検索して取得します。
  3. 評価を実行します。
  4. 評価実行 ID を使用して結果を取得します。

要求が成功すると、評価は非同期的に実行され、Copilot Studioで確認できる結果が生成されます。

評価を自動化するための API 操作

Copilot Studioでは、既存のテスト セットを使用してエージェントに対する評価をプログラムでトリガーするために使用できる REST API 操作がサポートされています。

エージェント テスト セットを取得する

  • エンドポイント:GET https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/makerevaluation/testsets?api-version=2024-10-01
  • 目的: 特定のエージェントのテスト セット ID とその他の詳細の配列を取得します。
  • 応答: 次の情報を含むテスト セットの value と呼ばれる一覧を返します。
    • auditInfo: 各テスト セットを作成および変更するためのタイムスタンプとユーザー ID
    • displayName: テスト セットの名前。
    • id: テスト セットの ID。 エージェント評価を開始で、使用するテストセットを選択します。
    • description: テスト セットの説明。
    • state: テスト セットの状態。 使用可能なテスト セットが Active。
    • totalTestCases: テスト セット内のテスト ケースの数。

エージェント テスト セットの詳細を取得する

  • エンドポイント:GET https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/makerevaluation/testsets/{yourTestSetId}?api-version=2024-10-01
  • 目的: テスト セット ID を使用して、特定のテスト セットの詳細を取得します。
  • 応答: Get エージェント テスト セット 応答配列内の 1 つの項目の情報を返します。

詳細については、 Get Test Set Details API リファレンス ドキュメントを参照してください。

エージェントの評価を開始する

  • エンドポイント:GET https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/makerevaluation/testsets/{yourTestSetId}/run?api-version=2024-10-01
  • 目的: テスト セットの idを使用して、テスト セットの評価を実行します。 評価の実行中に接続を認証するためのユーザー プロファイルを含めることもできます。 mcsConnectionIdを使用して、ユーザー プロファイルを指定します。 呼び出しに mcsConnectionId を追加しない場合、評価は認証なしで実行されます。 MCS 接続 ID を検索する方法の 前提条件 を参照してください。
  • 応答: 次の情報を返します。
    • runId: 評価実行の ID。 この ID を使用して評価の詳細を取得します。
    • lastUpdatedAt: 実行の状態が最後に更新されたとき。
    • executionState: 評価を実行している間の実行状態。
    • state: 実行の現在の状態。
    • totalTestCases: 評価に使用されたテスト セット内のテスト ケースの合計数。
    • testCasesProcessed: 前回の更新時点で評価されたテスト ケースの合計数。

エージェント テストの実行の詳細を取得する

  • エンドポイント:GET https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/makerevaluation/testruns/{yourTestRunId}?api-version=2024-10-01
  • 目的: ターゲット評価実行の runId を使用して、評価の詳細を取得します。
  • 応答: 次の情報を返します。
    • id: 評価実行の ID。 この ID を使用して評価の詳細を取得します。
    • environmentId: エージェントの環境 ID です。
    • cdsBotId: ターゲット エージェントの ID。
    • ownerId: 評価実行を開始したユーザーの ID。
    • testSetId: 評価に使用されるテスト セットの ID。
    • state: 評価の進行状況。
    • startTime: 評価が開始されたとき。
    • endTime: 評価が完了したとき (完了した場合)。
    • name: 評価の名前。
    • totalTestCases: テスト セット内のテスト ケースの合計数。
    • mcsConnectionId: 評価実行に使用するユーザープロファイルのCopilot Studio接続ID。 null ユーザー プロファイルが接続されていない場合は 。
    • testCasesResults: 評価実行のテスト ケースの一覧。 含まれる内容:
      • testCaseId: テスト ケースの ID。
      • state: テスト ケースの完了状態。
      • metricsResults: テスト ケースに使用される各テスト メソッドの詳細と結果。 含まれる内容:
        • type: テスト メソッド。
        • result: このテスト ケースのテストの最終的な結果。 含まれる内容:
          • data: 結果の詳細。 正確な値は、テスト メソッドによって異なります。 詳細については、Power Platform API に関するドキュメントを参照してください。 一般的な品質 テストの場合、応答には次のものが含まれます。
            • abstention: エージェントがクエリに応答したかどうか。
            • relevance: 回答が関連していたかどうか。
            • completeness: 回答が完了したかどうか。
        • status: テスト ケースの 状態 。
        • errorReason: エラーが発生した場合、エラーの原因。
        • aiResultReason: テスト ケースの結果の AI の説明。

エージェントのテスト実行結果を取得する

  • エンドポイント:GET https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/makerevaluation/testruns?api-version=2024-10-01
  • 目的: 以前のすべての実行の配列を取得します。
  • 応答: 配列内の各項目には、「 エージェントのテスト実行の詳細を取得する」で見つかったのと同じ値が含まれます。
  • Last updated on