通过

使用 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. mcsConnectionId从 URL 复制：.../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 代理测试集 响应数组中一项的信息。

在 获取测试集详细信息 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
  • 目的：检索所有以前运行的数组。
  • 响应：数组中的每个项都包含与 Get 代理测试运行详细信息中找到的值相同。
  • Last updated on