Automatice evaluaciones de agentes con la API de Power Platform

Copilot Studio proporciona a los desarrolladores herramientas para evaluar continuamente el rendimiento de los agentes ejecutando pruebas automatizadas sobre conjuntos de pruebas predefinidos utilizando la API de REST de Power Platform. Utilizando la API de REST, puede iniciar mediante programación evaluaciones de agentes como parte de sus flujos de trabajo de desarrollo, como durante actualizaciones de agentes, validación de versiones o pruebas de regresión.

Automatizar evaluaciones le ayuda a:

  • Valide la calidad del agente después de realizar cambios.
  • Ejecute comprobaciones recurrentes de rendimiento contra agentes de producción o de almacenamiento provisional.
  • Integración de pruebas de agente en canalizaciones de CI/CD.
  • Detecte regresiones en el comportamiento del agente durante las fases iniciales del ciclo de vida de desarrollo.

Requisitos previos

  • Tiene el id. de bot y el id. de entorno para el agente de destino.
  • Un conjunto de pruebas creado en Copilot Studio para el agente objetivo.
  • Un token de acceso de usuario emitido por Microsoft Entra ID (OAuth 2.0). Para obtener el token, consulte Autenticación.
    • Adquiera 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.

Información general para ejecutar evaluaciones utilizando la API de REST

Para realizar una evaluación utilizando la API de Power Platform, siga estos pasos generales:

  1. Complete los requisitos previos.
  2. Encuentre y recupere el id. del conjunto de pruebas que quiera usar.
  3. Ejecute la evaluación.
  4. Recupere los resultados utilizando el id. de la ejecución de evaluación.

Si la solicitud es correcta, la evaluación se ejecuta de manera asincrónica y produce resultados que puede revisar en Copilot Studio.

Operaciones de la API para automatizar evaluaciones

Copilot Studio admite operaciones de API de REST que le permiten desencadenar evaluaciones mediante programación para su agente utilizando un conjunto de pruebas existente.

Para obtener más información sobre cómo y cuándo utilizar la API de Power Platform, consulte:

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 id. de los conjuntos de prueba y otros detalles para un agente específico.
  • Respuesta: devuelve una lista llamada value de conjuntos de prueba con la siguiente información:
    • auditInfo: marcas de tiempo e identificadores de usuario para crear y modificar cada conjunto de pruebas
    • displayName: el nombre del conjunto de pruebas.
    • id: el id. del conjunto de pruebas. Se utiliza en Iniciar una evaluación de agente para elegir qué conjunto de pruebas utilizar.
    • description: la descripción del conjunto de pruebas.
    • state: el estado del conjunto de pruebas. Un conjunto de pruebas utilizable tiene el estado Active.
    • totalTestCases: el número de casos de prueba dentro del conjunto de pruebas.

Obtenga más información en Enumerar conjuntos de pruebas de evaluación de creador.

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/{TestSetId}?api-version=2024-10-01
  • Propósito: recupere detalles de un conjunto de pruebas específico, usando el id. del conjunto de pruebas.
  • Respuesta: devuelve la información de un elemento en la matriz de respuestas Obtener conjuntos de pruebas del agente.

Obtenga más información en Enumerar conjuntos de pruebas de evaluación de creador.

Iniciar una evaluación de un agente

  • Punto de conexión:: POST https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/makerevaluation/testsets/{TestSetId}/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 conexiones durante la ejecución de evaluación. Use mcsConnectionId para especificar el perfil de usuario. Si no agrega un mcsConnectionId a su llamada, la evaluación se ejecuta sin autenticación.
  • Respuesta: devuelve la siguiente información:
    • runId: identificador de la ejecución de la evaluación. Utilice este id. para recuperar detalles de la 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: el estado actual de la ejecución.
    • totalTestCases: número total de casos de prueba en el conjunto de casos de prueba utilizado para la evaluación.
    • testCasesProcessed: total de casos de prueba evaluados desde la última actualización.

Obtenga más información en Ejecutar conjunto de pruebas de evaluación de creador.

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 Obtener detalles de la ejecución de prueba del agente.

Obtenga más información en Enumerar ejecuciones de pruebas de evaluación de creador.

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/{TestRunId}?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. Utilice este id. para recuperar detalles de la evaluación.
    • environmentId: El Id. del entorno de su agente.
    • cdsBotId: el id. del agente objetivo.
    • ownerId: el id. del usuario que inició la ejecución de evaluación.
    • testSetId: el id. del conjunto de pruebas utilizado para la evaluación.
    • state: el estado del progreso de la evaluación.
    • startTime: cuando se inició la evaluación.
    • endTime: cuando finalice la evaluación, si finalizó.
    • name: nombre de la evaluación.
    • totalTestCases: total de casos de prueba en el conjunto de pruebas.
    • mcsConnectionId: el identificador de conexión de la 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 resultados para cada método de prueba utilizado para el caso de prueba. Incluye lo siguiente:
        • type: el método de prueba.
        • result: el resultado final de la prueba para este caso de prueba. Incluye lo siguiente:
          • data: los detalles del resultado. Los valores exactos dependen del método de prueba. Consulte la documentación de la API de Power Platform para obtener más información. Para una prueba general de calidad, la respuesta incluye lo siguiente:
            • abstention: si el agente respondió a la consulta.
            • relevance: si la respuesta es relevante.
            • completeness: si la respuesta está completa.
        • status: el estado del caso de prueba.
        • errorReason: si ocurre un error, la causa del error.
        • aiResultReason: la explicación de IA del resultado del caso de prueba.

Obtenga más información en Obtener la ejecución de prueba de evaluación de creador.

Utilizar un id. de Microsoft Studio Connector para las evaluaciones

Para iniciar una evaluación de agente, puede agregar opcionalmente un id. de Microsoft Studio Connector a la llamada 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 de Microsoft Copilot Studio.
  4. Copie el mcsConnectionId de la URL: .../connections/shared_microsoftcopilotstudio/{mcsConnectionId}/details
  • Last updated on