Автоматизация оценки агентов с помощью API Power Platform

Примечание.

В этой статье описываются особенности, используемые в агентах или потоках агентов, питаемых стандартным жгутом.

Copilot Studio предоставляет создателям инструменты для непрерывной оценки производительности агентов, позволяя запускать автоматизированные тесты по заранее определенным тестовым наборам с использованием Power Platform REST API. Используя REST API, вы можете программно запускать оценки агентов в рамках рабочих процессов разработки, например во время обновлений агентов, валидации выпусков или регрессионного тестирования.

Автоматизация оценок позволяет:

  • Проверять качество агента после внесения изменений.
  • Проводить повторяющиеся проверки работы для агентов, используемых в рабочих или промежуточных средах.
  • Интегрировать тестирование агентов в конвейеры CI/CD.
  • Обнаруживать регрессии в поведении агентов на ранних этапах жизненного цикла разработки.

Необходимые условия

  • У вас есть идентификатор бота и среды для целевого агента.
  • Тестовый набор, созданный в Copilot Studio для вашего целевого агента.
  • Токен доступа пользователя, выпущенный Microsoft Entra ID (OAuth 2.0). О том, как получить токен, см. в разделе Аутентификация.
    • Получите токен доступа, используя идентификатор клиента регистрации приложения, которому предоставлены соответствующие разрешения в API Power Platform.

Обзор проведения оценок с использованием REST API

Чтобы провести оценку с помощью API Power Platform, выполните следующие основные шаги:

  1. Выполните предварительные условия.
  2. Найдите и получите идентификатор тестового набора, который вы хотите использовать.
  3. Запустите оценку.
  4. Получите результаты с помощью идентификатора запуска оценки.

Если запрос выполнен успешно, оценка выполняется асинхронно и предоставляет результаты, которые можно просмотреть в 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
  • Цель: получить массив идентификаторов тестовых наборов и дополнительные сведения для конкретного агента.
  • Ответ: возвращается список value тестовых наборов со следующей информацией:
    • auditInfo: метки времени и идентификаторы пользователей для создания и изменения каждого тестового набора
    • displayName: название тестового набора.
    • id: идентификатор тестового набора. Используйте его при выполнении действий разделе Запуск оценки агента, чтобы выбрать, какой тестовый набор использовать.
    • description: описание тестового набора.
    • state: состояние тестового набора. Пригодный к использованию тестовый набор находится в состоянии Active.
    • totalTestCases: количество тестовых случаев внутри тестового набора:

Подробнее см. в разделе Вывод списка оценочных тестовых наборов создателя.

Получение сведений о тестовом наборе агента

  • Конечная точка:GET https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/makerevaluation/testsets/{TestSetId}?api-version=2024-10-01
  • Цель: получить сведения о конкретном тестовом наборе по его идентификатору.
  • Ответ: возвращает сведения об одном элементе в массиве ответов на запрос, описанный в разделе Получение тестовых наборов агента.

Подробнее см. в разделе Вывод списка оценочных тестовых наборов создателя.

Запуск оценки агента

  • Конечная точка:POST https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/makerevaluation/testsets/{TestSetId}/run?api-version=2024-10-01
  • Цель: выполнить оценку для тестового набора с использованием id тестового набора. Вы также можете включить профиль пользователя для аутентификации подключений во время выполнения оценки. Используйте mcsConnectionId для указания профиля пользователя. Если вы не добавите в вызов mcsConnectionId, оценка будет выполняться без аутентификации.
  • Ответ: возвращает следующую информацию:
    • runId: идентификатор запуска оценки. Используйте этот идентификатор для получения сведений об оценке.
    • 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: идентификатор запуска оценки. Используйте этот идентификатор для получения сведений об оценке.
    • environmentId: идентификатор среды вашего агента.
    • cdsBotId: идентификатор целевого агента.
    • ownerId: идентификатор пользователя, который запустил оценку.
    • testSetId: идентификатор тестового набора, используемого для оценки.
    • state: ход выполнения оценки.
    • startTime: когда началась оценка.
    • endTime: когда закончилась оценка, если она закончилась.
    • name: имя оценки.
    • totalTestCases: общее количество тестовых случаев в тестовом наборе.
    • mcsConnectionId: идентификатор подключения Copilot Studio, связанный с профилем пользователя, используемым для запуска оценки. null, если связанного профиля пользователя нет.
    • testCasesResults: список тестовых случаев в запуске оценки. Включает:
      • testCaseId: идентификатор тестового случая.
      • state: состояние завершения тестового случая.
      • metricsResults: сведения и результаты для каждого метода тестирования, используемого в тестовом случае. Включено следующее:
        • type: метод тестирования.
        • result: итоговый результат теста для этого тестового случая. Включено следующее:
          • data: сведения о результате. Точные значения зависят от метода тестирования. Узнайте больше в документации API Power Platform. Для теста общего качества ответ включает следующее:
            • abstention: ответил ли агент на запрос.
            • relevance: был ли ответ релевантным.
            • completeness: был ли ответ полным.
        • status: состояние тестового случая.
        • errorReason: если произошла ошибка, причина ошибки.
        • aiResultReason: сгенерированное ИИ объяснение результата тестового случая.

Подробнее см. в разделе Получение оценочного тестового запуска создателя.

Использование ИД Microsoft Studio Connector для оценивания

Чтобы запустить оценку агента, вы можете при необходимости добавить идентификатор Майкрософт Studio Connector в вызов в качестве профиля пользователя для оценки. Чтобы найти mcsConnectionId:

  1. Перейдите в Power Automate.
  2. Откройте страницу Подключения.
  3. Выберите подключение Microsoft Copilot Studio.
  4. Скопируйте mcsConnectionId из URL-адреса: .../connections/shared_microsoftcopilotstudio/{mcsConnectionId}/details
  • Last updated on