Automatiser les évaluations d’agents avec l’API Power Platform

Copilot Studio fournit aux créateurs des outils permettant d’évaluer en permanence les performances de l’agent en exécutant des tests automatisés sur des jeux de tests prédéfinis à l’aide de l’API REST Power Platform. À l’aide de l’API REST, vous pouvez déclencher par programmation des évaluations d’agent dans le cadre de vos workflows de développement, tels que pendant les mises à jour de l’agent, la validation de mise en production ou les tests de régression.

L’automatisation des évaluations vous aide à :

  • Valider la qualité de l’agent après avoir apporté des modifications
  • Exécuter des vérifications périodiques des performances sur des agents de production ou de préproduction
  • Intégrer des tests d’agent dans les pipelines CI/CD
  • Détecter les régressions dans le comportement de l’agent au début du cycle de vie du développement

Prerequisites

  • Vous disposez de l’ID de bot et de l’ID d’environnement de l’agent cible.
  • Un test set créé dans Copilot Studio pour votre agent cible.
  • Jeton d’accès utilisateur émis par Microsoft Entra ID (OAuth 2.0). Pour obtenir le jeton, consultez Authentification.
    • Vous devez acquérir le jeton d'accès en utilisant l'ID client d'un enregistrement d'application qui dispose de la portée appropriée accordée par l'API Power Platform.
  • Pour Démarrer une évaluation d'agent, vous pouvez éventuellement ajouter un identifiant Microsoft Studio Connector à l'appel pour l'utiliser comme profil utilisateur pour l'évaluation. Pour trouver votre mcsConnectionId:
    1. Accédez à Power Automate.
    2. Ouvrez la page Connexions .
    3. Sélectionnez la connexion Microsoft Copilot Studio.
    4. Copiez l’URL mcsConnectionId à partir de l’URL : .../connections/shared_microsoftcopilotstudio/{mcsConnectionId}/details

Vue d’ensemble de l’exécution d’évaluations à l’aide de l’API REST

Pour exécuter une évaluation à l’aide de l’API Power Platform, procédez comme suit :

  1. Remplissez les conditions préalables.
  2. Recherchez et récupérez l'ID de l'ensemble de tests que vous désirez utiliser.
  3. Exécutez l’évaluation.
  4. Récupérez les résultats à l’aide de l’ID d’exécution d’évaluation.

Une fois la demande réussie, l’évaluation s’exécute de manière asynchrone et produit des résultats que vous pouvez examiner dans Copilot Studio.

Opérations d’API pour automatiser les évaluations

Copilot Studio prend en charge les opérations d’API REST que vous pouvez utiliser pour déclencher des évaluations par programmation sur votre agent à l’aide d’un jeu de tests existant.

Obtenir des jeux de test pour agents

  • Point de terminaison :GET https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/makerevaluation/testsets?api-version=2024-10-01
  • Objectif : récupérer un tableau des identifiants des jeux de tests et d’autres détails pour un agent spécifique.
  • Réponse : retourne une liste appelée value des jeux de tests avec les informations suivantes :
    • auditInfo: Horodatages et identifiants utilisateur pour la création et la modification de chaque ensemble de tests
    • displayName: nom du jeu de tests.
    • id: L'identifiant du jeu de tests. Utilisez-la dans Démarrer une évaluation de l’agent pour choisir le jeu de tests à utiliser.
    • description: description de l'ensemble de tests.
    • state: état de l'ensemble de tests. Un jeu de tests utilisable est Active.
    • totalTestCases: nombre de cas de test dans le jeu de tests.

Obtenir les détails du jeu de tests de l’assistant

  • Point de terminaison :GET https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/makerevaluation/testsets/{yourTestSetId}?api-version=2024-10-01
  • Objectif : récupérer les détails d’un jeu de tests spécifique, à l’aide de l’ID du jeu de tests.
  • Réponse : retourne les informations d’un élément dans le tableau de réponses des jeux de tests Get Agent .

Pour en savoir plus, consultez la documentation de référence de l’API Obtenir les détails du jeu de tests.

Démarrer une évaluation d’agent

  • Point de terminaison :GET https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/makerevaluation/testsets/{yourTestSetId}/run?api-version=2024-10-01
  • Objectif : Exécutez une évaluation pour un jeu de tests en utilisant le jeu de id. Vous pouvez également inclure un profil utilisateur pour l’authentification des connexions pendant l’exécution de l’évaluation. Permet mcsConnectionId de spécifier le profil utilisateur. Si vous n’ajoutez pas l’élément mcsConnectionId à votre appel, l’évaluation s’exécute sans authentification. Consultez les conditions préalables pour savoir comment trouver votre ID de connexion MCS.
  • Réponse : retourne les informations suivantes :
    • runId: L'ID de l'exécution de l’évaluation. Utilisez cet ID pour récupérer les détails de l’évaluation.
    • lastUpdatedAt: lorsque l’état de l’exécution a été mis à jour pour la dernière fois.
    • executionState: état de l’exécution, pendant le déroulement de l’évaluation.
    • state: état actuel de l’exécution.
    • totalTestCases: nombre total de cas de test dans le jeu de tests utilisé pour l’évaluation.
    • testCasesProcessed: nombre total de cas de test évalués à partir de la dernière mise à jour.

Obtenir les détails de l’exécution du test de l’agent

  • Point de terminaison :GET https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/makerevaluation/testruns/{yourTestRunId}?api-version=2024-10-01
  • Objectif : récupérer les détails d’une évaluation à l’aide de runId pour l’exécution d’évaluation cible.
  • Réponse : retourne les informations suivantes :
    • id: L'ID de l'exécution de l’évaluation. Utilisez cet ID pour récupérer les détails de l’évaluation.
    • environmentId: L'ID de l’environnement de votre agent.
    • cdsBotId: ID de l’agent cible.
    • ownerId: ID de l’utilisateur qui a démarré l’exécution de l’évaluation.
    • testSetId: ID du jeu de tests utilisé pour l’évaluation.
    • state: état de progression de l’évaluation.
    • startTime : Quand l'évaluation a commencé.
    • endTime: une fois l’évaluation terminée (si elle est terminée).
    • name: Nom de l’évaluation.
    • totalTestCases: nombre total de cas de test dans l'ensemble de tests.
    • mcsConnectionId : L'identifiant de connexion pour la connexion Copilot Studio du profil utilisateur utilisé pour l'exécution de l’évaluation. null si aucun profil utilisateur n’est connecté.
    • testCasesResults: liste des cas de test dans l’exécution de l’évaluation. Comprend :
      • testCaseId: ID du cas de test.
      • state: état d’achèvement du cas de test.
      • metricsResults: détails et résultats de chaque méthode de test utilisée pour le cas de test. Comprend :
        • type: méthode de test.
        • result: résultat final du test pour ce cas de test. Comprend :
          • data: détails du résultat. Les valeurs exactes dépendent de la méthode de test. Pour en savoir plus, consultez la documentation de l’API Power Platform. Pour un test de qualité général , la réponse inclut :
            • abstention: indique si l’agent a répondu à la requête.
            • relevance: indique si la réponse était pertinente.
            • completeness: indique si la réponse est terminée.
        • status: état du cas de test.
        • errorReason: en cas d’erreur, la cause de l’erreur.
        • aiResultReason: explication de l’IA du résultat du cas de test.

Obtenir les exécutions de test de l’assistant

  • Point de terminaison :GET https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/makerevaluation/testruns?api-version=2024-10-01
  • Objectif : récupérer un tableau de toutes les exécutions précédentes.
  • Réponse : chaque élément du tableau inclut les mêmes valeurs que celles trouvées dans les détails de l’exécution de test get agent.
  • Last updated on