使用 Power Platform API 自动执行代理评估

Copilot Studio为制造商提供了使用 Power Platform REST API针对预定义测试集运行自动测试来持续评估代理性能的工具。 通过使用 REST API，可以编程方式触发代理评估，作为开发工作流的一部分，例如在代理更新、发布验证或回归测试期间。

自动评估可帮助你：

  • 在进行更改后验证代理质量。
  • 对生产或预发布环境中的代理程序执行定期性能检查。
  • 将代理测试集成到 CI/CD 流水线中。
  • 在开发生命周期早期发现代理行为退化问题。

Prerequisites

  • 您有目标智能体的机器人 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 的详细信息，请参阅：

获取代理测试集

  • 终结点：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：测试集中的测试用例数。

请参阅 List Maker 评估测试集 了解更多信息。

获取代理测试集详细信息

  • 终结点：GET https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/makerevaluation/testsets/{TestSetId}?api-version=2024-10-01
  • 目的：使用测试集 ID 检索特定测试集的详细信息。
  • 响应：返回 Get 代理测试集 响应数组中一项的信息。

在 List Maker 评估测试集 中了解更多信息。

启动智能体评估

  • 终结点：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：自上次更新起评估的测试用例总数。

在 Run Maker 评估测试集中了解详细信息。

获取智能体测试运行

  • 终结点：GET https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/makerevaluation/testruns?api-version=2024-10-01
  • 目的：检索所有以前运行的数组。
  • 响应：数组中的每个项都包含与 Get 代理测试运行详细信息中找到的值相同。

在 列表制作器评估测试运行中了解更多信息。

获取代理测试运行详细信息

  • 终结点：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 说明。

请参阅 Get Maker Evaluation Test Run 了解更多信息。

使用 Microsoft Studio 连接器 ID 进行评估

对于开始智能体评估，可以选择将 Microsoft Studio 连接器 ID 作为评估的用户配置文件添加到调用中。 查找您的 mcsConnectionId：

  1. 转到 Power Automate。
  2. 打开 “连接” 页。
  3. 选择 Microsoft Copilot Studio 连接。
  4. 从 URL 中复制 mcsConnectionId：.../connections/shared_microsoftcopilotstudio/{mcsConnectionId}/details
  • Last updated on