Agentevaluaties automatiseren met Power Platform-API

Copilot Studio biedt makers hulpprogramma's voor het continu evalueren van agentprestaties door geautomatiseerde tests uit te voeren op vooraf gedefinieerde testsets met behulp van de Power Platform REST API. Met behulp van de REST API kunt u programmatisch agentevaluaties activeren als onderdeel van uw ontwikkelwerkstromen, zoals tijdens agentupdates, releasevalidatie of regressietests.

Het automatiseren van evaluaties helpt u bij het volgende:

  • De kwaliteit van de agent valideren nadat u wijzigingen hebt aangebracht
  • Terugkerende prestatiecontroles uitvoeren op productie- of faseringsagents
  • Agenttests integreren in CI/CD-pijplijnen
  • Regressies detecteren in agentgedrag vroeg in de ontwikkelingslevenscyclus

Vereiste voorwaarden

  • U hebt de bot- en omgevings-ID voor de doelagent.
  • Een testset gemaakt in Copilot Studio voor uw doelagent.
  • Een gebruikerstoegangstoken dat is uitgegeven door Microsoft Entra ID (OAuth 2.0). Zie Verificatie om het token te verkrijgen.
    • U moet het toegangstoken verkrijgen met behulp van de client-id van een app-registratie waarvoor het juiste bereik is verleend onder de Power Platform-API.
  • Voor Start een agentevaluatie kunt u eventueel een Microsoft Studio Connector-id toevoegen aan de aanroep die moet worden gebruikt als een gebruikersprofiel voor de evaluatie. Om uw mcsConnectionId te vinden:
    1. Ga naar Power Automate.
    2. Open de Verbindingen pagina.
    3. Selecteer de verbinding Microsoft Copilot Studio.
    4. Kopieer de mcsConnectionId uit de URL: .../connections/shared_microsoftcopilotstudio/{mcsConnectionId}/details

Overzicht voor het uitvoeren van evaluaties met behulp van REST API

Als u een evaluatie wilt uitvoeren met behulp van de Power Platform-API, voert u de volgende algemene stappen uit:

  1. Voldoen aan de vereisten.
  2. Zoek en haal de testset-id op van de testset die u wilt gebruiken.
  3. Voer de evaluatie uit.
  4. Haal de resultaten op met behulp van de evaluatieuitvoerings-id.

Wanneer de aanvraag is geslaagd, wordt de evaluatie asynchroon uitgevoerd en worden resultaten gegenereerd die u in Copilot Studio kunt bekijken.

API-bewerkingen voor het automatiseren van evaluaties

Copilot Studio ondersteunt REST API-bewerkingen die u kunt gebruiken om programmatisch evaluaties te activeren voor uw agent met behulp van een bestaande testset.

Agenttestsets ophalen

  • Eindpunt:GET https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/makerevaluation/testsets?api-version=2024-10-01
  • Doel: Haal een matrix op van de testset-id's en andere details voor een specifieke agent.
  • Antwoord: Retourneert een lijst value met testsets met de volgende informatie:
    • auditInfo: Tijdstempels en gebruikers-id's voor het maken en wijzigen van elke testset
    • displayName: De naam van de testset.
    • id: De id van de testset. Gebruik Een agentevaluatie starten om te bepalen welke testset moet worden gebruikt.
    • description: De beschrijving van de testset.
    • state: De status van de testset. Een bruikbare testset is Active.
    • totalTestCases: Het aantal testcases in de testset.

Gegevens van agenttestset ophalen

  • Eindpunt:GET https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/makerevaluation/testsets/{yourTestSetId}?api-version=2024-10-01
  • Doel: Haal details op voor een specifieke testset met behulp van de testset-id.
  • Antwoord: retourneert de informatie van één item in de get agent test sets response array.

Zie de API-referentiedocumentatie voor "Get Test Set Details" voor meer informatie.

Een agentevaluatie starten

  • Eindpunt:GET https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/makerevaluation/testsets/{yourTestSetId}/run?api-version=2024-10-01
  • Doel: Voer een evaluatie uit voor een testset met behulp van de testset id. U kunt ook een gebruikersprofiel opnemen voor het verifiëren van verbindingen tijdens de evaluatieuitvoering. Gebruik mcsConnectionId dit om het gebruikersprofiel op te geven. Als u geen mcsConnectionId aan uw aanroep toevoegt, wordt de evaluatie uitgevoerd zonder verificatie. Zie Vereisten voor het vinden van uw MCS-verbindings-id.
  • Antwoord: retourneert de volgende informatie:
    • runId: de ID voor de evaluatieronde. Gebruik deze id om evaluatiegegevens op te halen.
    • lastUpdatedAt: Wanneer de status van de run voor het laatst is bijgewerkt.
    • executionState: de status van de uitvoering, tijdens het uitvoeren van de evaluatie.
    • state: Huidige status van de uitvoering.
    • totalTestCases: Totaal aantal testcases in de testset die voor de evaluatie wordt gebruikt.
    • testCasesProcessed: Totaal aantal testcases geëvalueerd vanaf de laatste update.

Details van de testuitvoering van de agent ophalen

  • Eindpunt:GET https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/makerevaluation/testruns/{yourTestRunId}?api-version=2024-10-01
  • Doel: haal de details van een evaluatie op met behulp van de runId voor je doelevaluatierun.
  • Antwoord: retourneert de volgende informatie:
    • id: de ID voor de evaluatieronde. Gebruik deze id om evaluatiegegevens op te halen.
    • environmentId: de id voor de omgeving van uw agent.
    • cdsBotId: de ID van de doelagent.
    • ownerId: De id van de gebruiker die de evaluatie heeft gestart.
    • testSetId: de id van de testset die wordt gebruikt voor de evaluatie.
    • state: De voortgangsstatus van de evaluatie.
    • startTime: Wanneer de evaluatie is gestart.
    • endTime: Wanneer de evaluatie is voltooid (indien voltooid).
    • name: Naam van de evaluatie.
    • totalTestCases: Totaal aantal testcases in de testset.
    • mcsConnectionId: de verbindings-id voor de Copilot Studio-verbinding van het gebruikersprofiel dat wordt gebruikt voor de evaluatie-uitvoering. null als er geen gebruikersprofiel is verbonden.
    • testCasesResults: De lijst met testcases in de evaluatie-uitvoering. Omvat:
      • testCaseId: De ID van de test-case.
      • state: De voltooiingsstatus van de testcase.
      • metricsResults: De details en resultaten voor elke testmethode die wordt gebruikt voor de testcase. Omvat:
        • type: De testmethode.
        • result: Het uiteindelijke resultaat van de test voor deze testcase. Omvat:
          • data: De details van het resultaat. Exacte waarden zijn afhankelijk van de testmethode. Meer informatie vindt u in de Power Platform API-documenten. Voor een algemene kwaliteitstest omvat het antwoord:
            • abstention: Of de agent de query heeft beantwoord.
            • relevance: Of het antwoord relevant was.
            • completeness: Of het antwoord is voltooid.
        • status: De status van de testcase.
        • errorReason: de oorzaak van de fout, als er een fout is opgetreden.
        • aiResultReason: De AI-uitleg van het testcaseresultaat.

Testuitvoeringen van de agent ophalen

  • Eindpunt:GET https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/makerevaluation/testruns?api-version=2024-10-01
  • Doel: Haal een matrix op van alle vorige uitvoeringen.
  • Antwoord: elk item in de matrix bevat dezelfde waarden als gevonden in de uitvoeringsdetails van agenttest ophalen.
  • Last updated on