Power Platform REST 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 を使用して、ユーザー アクセス トークンを取得します。

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

Power Platform APIを使って評価を実行するには、以下の一般的な手順に従ってください。

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

リクエストが成功すると、評価は非同期で実行され、結果が生成され、それらはCopilot Studioで確認できます。

評価の自動化のためのAPI操作

Copilot Studio は、既存のテストセットを使用してエージェントの評価をプログラムで実行できる REST API 操作をサポートしています。

Power Platform API の使用方法と使用タイミングの詳細については、以下を参照してください:

• Power Platform API と SDK: UX 優先から API 優先まで (Power Platform 開発者ブログ)
• プログラム可能性と拡張性の概要
• Power Platform API の使用を開始する
• Copilot Studio エージェント向け Power Platform 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/{TestSetId}?api-version=2024-10-01
• 目的: テストセットIDを使って特定のテストセットの詳細を取得する。
• 応答: エージェント テスト セットを取得する応答配列内の1つのアイテムの情報を返します。

「リスト メーカー評価テスト セット」で詳細をご覧ください。

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

• エンドポイント: POST https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/makerevaluation/testsets/{TestSetId}/run?api-version=2024-10-01
• 目的: テスト セットの id を使用して、テスト セットの評価を実行する。 評価実行中に接続を認証するためのユーザー プロファイルを含めることもできます。 mcsConnectionId を使用してユーザープロファイルを指定します。 リクエストにmcsConnectionIdを追加しない場合、評価は認証なしで行われます。
• 応答: 以下の情報を返します。
  • runId: 評価実行の ID。 このIDを使用して評価の詳細を取得してください。
  • lastUpdatedAt：ランのステータスが最後に更新された時点
  • executionState: 評価中の実行状況。
  • state: 実行の現在の状態。
  • totalTestCases: 評価用テストセット内のテストケース総数。
  • testCasesProcessed：最終更新時点で評価済みのテストケース総数。

「作成者評価テスト セット」で詳細をご覧ください。

エージェント テストランの取得

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

詳細は、「作成者評価テスト実行を一覧表示する」をご覧ください。

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

• エンドポイント: GET https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/makerevaluation/testruns/{TestRunId}?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 によるテスト ケース結果の説明。

詳細については、「作成者評価テストを実行する」を参照してください。

評価には Microsoft Studio コネクタ ID を使用する

エージェント評価を開始する際、評価用のユーザープロファイルとしてMicrosoft Studio Connector IDをリクエストに任意で追加できます。 mcsConnectionId を見つける方法は次のとおりです。

1. Power Automate に移動します。
2. 接続ページを開きます。
3. Microsoft Copilot Studio 接続を開きます。
4. URL .../connections/shared_microsoftcopilotstudio/{mcsConnectionId}/details から mcsConnectionId をコピーします。

関連記事

• エージェントの評価について
• コネクタを使用してエージェントの評価をトリガーする