Automatización de las evaluaciones del agente mediante Power Platform API

Copilot Studio proporciona a los creadores herramientas para evaluar continuamente el rendimiento del agente mediante la ejecución de pruebas automatizadas en conjuntos de pruebas predefinidos mediante la API REST de Power Platform. Mediante el uso de la API REST, puede desencadenar evaluaciones de agente mediante programación como parte de los flujos de trabajo de desarrollo, como durante las actualizaciones del agente, la validación de versiones o las pruebas de regresión.

La automatización de evaluaciones le ayuda a:

  • Validación de la calidad del agente después de realizar cambios
  • Ejecución de comprobaciones periódicas de rendimiento en agentes de producción o almacenamiento provisional
  • Integración de pruebas de agente en canalizaciones de CI/CD
  • Detección de regresiones en el comportamiento del agente al principio del ciclo de vida de desarrollo

Prerrequisitos

  • Tiene el id. de bot y el id. de entorno para el agente de destino.
  • Conjunto de pruebas creado en Copilot Studio para el agente de destino.
  • Token de acceso de usuario emitido por Microsoft Entra ID (OAuth 2.0). Para obtener el token, consulte Autenticación.
    • Debe adquirir el token de acceso con el id. de cliente de un registro de aplicación que tenga el ámbito apropiado concedido bajo la API de Power Platform.
  • Para Iniciar una evaluación del agente, puede agregar opcionalmente un identificador de conector de Microsoft Studio a la llamada que se usará como perfil de usuario para la evaluación. Para encontrar su mcsConnectionId:
    1. Vaya a Power Automate.
    2. Abra la página Conexiones .
    3. Seleccione la conexión Microsoft Copilot Studio.
    4. Copie el mcsConnectionId de la URL: .../connections/shared_microsoftcopilotstudio/{mcsConnectionId}/details

Información general sobre la ejecución de evaluaciones mediante la API REST

Para ejecutar una evaluación mediante Power Platform API, siga estos pasos generales:

  1. Cumplir los requisitos previos.
  2. Busque y recupere el identificador del conjunto de pruebas del conjunto de pruebas que desea usar.
  3. Ejecute la evaluación.
  4. Obtenga los resultados usando el identificador de ejecución de evaluación.

Cuando la solicitud se realiza correctamente, la evaluación se ejecuta de forma asincrónica y genera resultados que puede revisar en Copilot Studio.

Operaciones de API para automatizar las evaluaciones

Copilot Studio admite operaciones de API REST que puede usar para desencadenar programáticamente evaluaciones contra su agente utilizando un conjunto de pruebas existente.

Obtener conjuntos de pruebas del agente

  • Punto de conexión:GET https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/makerevaluation/testsets?api-version=2024-10-01
  • Propósito: recupere una matriz de los identificadores del conjunto de pruebas y otros detalles para un agente específico.
  • Respuesta: devuelve una lista denominada value conjuntos de pruebas con la siguiente información:
    • auditInfo: marcas de tiempo e identificadores de usuario para crear y modificar cada conjunto de pruebas
    • displayName: nombre del conjunto de pruebas.
    • id: el identificador del conjunto de pruebas. Usa Iniciar una evaluación del agente para elegir qué conjunto de pruebas usar.
    • description: descripción del conjunto de pruebas.
    • state: el estado del conjunto de pruebas. Un conjunto de pruebas utilizable es Active.
    • totalTestCases: número de casos de prueba dentro del conjunto de pruebas.

Obtención de los detalles del conjunto de pruebas del agente

  • Punto de conexión:GET https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/makerevaluation/testsets/{yourTestSetId}?api-version=2024-10-01
  • Propósito: recupere los detalles de un conjunto de pruebas específico mediante el identificador del conjunto de pruebas.
  • Respuesta: Devuelve la información de un elemento del array de respuestas Get agent test sets.

Obtenga más información en la documentación de referencia de Get Test Set Details API.

Iniciar una evaluación del agente

  • Punto de conexión:GET https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/makerevaluation/testsets/{yourTestSetId}/run?api-version=2024-10-01
  • Propósito: ejecute una evaluación para un conjunto de pruebas mediante el uso del conjunto de pruebas id. También puede incluir un perfil de usuario para autenticar las conexiones durante la ejecución de evaluación. Use mcsConnectionId para especificar el perfil de usuario. Si no agregas un mcsConnectionId a tu llamada, la evaluación se ejecuta sin autenticación. Consulte Requisitos previos para encontrar el identificador de conexión de MCS.
  • Respuesta: devuelve la siguiente información:
    • runId: identificador de la ejecución de la evaluación. Use este identificador para recuperar los detalles de evaluación.
    • lastUpdatedAt: cuando se actualizó por última vez el estado de la ejecución.
    • executionState: estado de la ejecución, mientras se ejecuta la evaluación.
    • state: estado de la ejecución actual.
    • totalTestCases: número total de casos de prueba en el conjunto de pruebas usado para la evaluación.
    • testCasesProcessed: total de casos de prueba evaluados a partir de la última actualización.

Obtención de los detalles de la ejecución de pruebas del agente

  • Punto de conexión:GET https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/makerevaluation/testruns/{yourTestRunId}?api-version=2024-10-01
  • Propósito: recupere los detalles de una evaluación mediante el runId de ejecución de evaluación objetivo.
  • Respuesta: devuelve la siguiente información:
    • id: identificador de la ejecución de la evaluación. Use este identificador para recuperar los detalles de evaluación.
    • environmentId: El Id. del entorno de su agente.
    • cdsBotId: el identificador del agente de destino.
    • ownerId: el identificador del usuario que inició la ejecución de evaluación.
    • testSetId: el identificador del conjunto de pruebas usado para la evaluación.
    • state: el estado de progreso de la evaluación.
    • startTime: cuando se inició la evaluación.
    • endTime: cuando se complete la evaluación (si se completó).
    • name: nombre de la evaluación.
    • totalTestCases: Total de casos de prueba en el conjunto de pruebas.
    • mcsConnectionId: el identificador de conexión de Copilot Studio del perfil de usuario utilizado para la ejecución de la evaluación. null si no hay ningún perfil de usuario conectado.
    • testCasesResults: La lista de casos de prueba en la ejecución de una evaluación. Incluye:
      • testCaseId: el identificador del caso de prueba.
      • state: estado de finalización del caso de prueba.
      • metricsResults: los detalles y los resultados de cada método de prueba que se usa para el caso de prueba. Incluye:
        • type: método de prueba.
        • result: resultado final de la prueba para este caso de prueba. Incluye:
          • data: los detalles del resultado. Los valores exactos dependen del método de prueba. Obtenga más información en los documentos de Power Platform API. Para una prueba de calidad general , la respuesta incluye:
            • abstention: indica si el agente respondió a la consulta.
            • relevance: indica si la respuesta era relevante.
            • completeness: indica si la respuesta está completa.
        • status: el estado del caso de prueba.
        • errorReason: si se produjo un error, la causa del error.
        • aiResultReason: la explicación de IA del resultado del caso de prueba.

Obtener ejecuciones de prueba del agente

  • Punto de conexión:GET https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/makerevaluation/testruns?api-version=2024-10-01
  • Propósito: recupere una matriz de todas las ejecuciones anteriores.
  • Respuesta: cada elemento de la matriz incluye los mismos valores que se encuentran en Obtención de los detalles de la ejecución de la prueba del agente.
  • Last updated on