Automatizzare le valutazioni degli agenti con l'API Power Platform

Copilot Studio fornisce agli autori strumenti per valutare continuamente le prestazioni dell'agente eseguendo test automatizzati su set di test predefiniti usando l'API REST Power Platform. Usando l'API REST, è possibile attivare le valutazioni degli agenti a livello di codice come parte dei flussi di lavoro di sviluppo, ad esempio durante gli aggiornamenti dell'agente, la convalida del rilascio o i test di regressione.

L'automazione delle valutazioni consente di:

  • Convalidare la qualità dell'agente dopo aver apportato modifiche.
  • Eseguire controlli delle prestazioni ricorrenti rispetto agli agenti di produzione o di gestione temporanea.
  • Integrare i test dell'agente nelle pipeline CI/CD.
  • Rilevare le regressioni nel comportamento dell'agente nelle prime fasi del ciclo di vita dello sviluppo.

Prerequisiti

  • Avete l'ID bot e l'ID ambiente per l'agente di destinazione.
  • Un set test creato in Copilot Studio per l'agente di destinazione.
  • Token di accesso utente rilasciato da Microsoft Entra ID (OAuth 2.0). Per ottenere il token, vedere Autenticazione.
    • Acquisisci il token di accesso utilizzando l'ID client di una registrazione di un'app a cui è stata concessa l'autorizzazione appropriata nell'API Power Platform.

Panoramica per l'esecuzione di valutazioni tramite l'API REST

Per eseguire una valutazione usando l'API Power Platform, seguire questa procedura generale:

  1. Completare i prerequisiti.
  2. Trovare e recuperare l'ID del set di test da usare.
  3. Eseguire la valutazione.
  4. Recupera i risultati usando l'ID dell'esecuzione della valutazione.

Quando la richiesta ha esito positivo, la valutazione viene eseguita in modo asincrono e produce risultati che è possibile esaminare in Copilot Studio.

Operazioni API per l'automazione delle valutazioni

Copilot Studio supporta le operazioni DELL'API REST che è possibile usare per attivare le valutazioni a livello di codice sull'agente usando un set di test esistente.

Per altre informazioni su come e quando usare l'API Power Platform, vedere:

Ottenere set di test dell'agente

  • Endpoint:GET https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/makerevaluation/testsets?api-version=2024-10-01
  • Scopo: recuperare una matrice degli ID del set di test e altri dettagli per un agente specifico.
  • Risposta: restituisce un elenco denominato value set di test con le informazioni seguenti:
    • auditInfo: timestamp e ID utente per la creazione e la modifica di ogni set di test
    • displayName: nome del set di test.
    • id: ID dell'insieme di test. Usare in Avviare una valutazione dell'agente per scegliere il set di test da usare.
    • description: descrizione del set di test.
    • state: stato del set di test. Un set di test utilizzabile ha lo stato Active.
    • totalTestCases: il numero di casi di test all'interno dell'insieme di test.

Per altre informazioni, vedere Set di test di valutazione di List Maker.

Ottenere i dettagli del set di test dell'agente

  • Endpoint:GET https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/makerevaluation/testsets/{TestSetId}?api-version=2024-10-01
  • Scopo: recuperare i dettagli per un set di test specifico, usando l'ID del set di test.
  • Risposta: restituisce le informazioni di un elemento nella matrice di risposta Get agent test sets .

Per altre informazioni, vedere Set di test di valutazione di List Maker.

Avviare una valutazione dell'agente

  • Endpoint:POST https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/makerevaluation/testsets/{TestSetId}/run?api-version=2024-10-01
  • Scopo: eseguire una valutazione per un set di test utilizzando il set di test id. È anche possibile includere un profilo utente per l'autenticazionedelle connessioni durante l'esecuzione della valutazione. Usare mcsConnectionId per specificare il profilo utente. Se non si aggiunge un oggetto mcsConnectionId alla chiamata, la valutazione viene eseguita senza autenticazione.
  • Risposta: restituisce le informazioni seguenti:
    • runId: ID per l'esecuzione della valutazione. Usare questo ID per recuperare i dettagli della valutazione.
    • lastUpdatedAt: Quando lo stato dell'esecuzione è stato aggiornato l'ultima volta.
    • executionState: Lo stato dell'esecuzione durante l'esecuzione della valutazione.
    • state: Stato dell'esecuzione corrente.
    • totalTestCases: numero totale di test case nel set di test usato per la valutazione.
    • testCasesProcessed: Casi di test totali valutati dall'ultimo aggiornamento.

Per altre informazioni, vedere Set di test di valutazione di Run Maker.

Ottenere esecuzioni di test dell'agente

  • Endpoint:GET https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/makerevaluation/testruns?api-version=2024-10-01
  • Scopo: recuperare una matrice di tutte le esecuzioni precedenti.
  • Risposta: ogni elemento nella matrice include gli stessi valori trovati in Ottenere i dettagli dell'esecuzione del test dell'agente.

Per altre informazioni, vedere Esecuzioni di test di valutazione di List Maker.

Ottenere i dettagli dell'esecuzione dei test dell'agente

  • Endpoint:GET https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/makerevaluation/testruns/{TestRunId}?api-version=2024-10-01
  • Scopo: recuperare i dettagli di una valutazione usando runId per l'esecuzione della valutazione di destinazione.
  • Risposta: restituisce le informazioni seguenti:
    • id: ID per l'esecuzione della valutazione. Usare questo ID per recuperare i dettagli della valutazione.
    • environmentId: L'ID per l'ambiente dell'agente.
    • cdsBotId: ID dell'agente di destinazione.
    • ownerId: ID dell'utente che ha avviato l'esecuzione della valutazione.
    • testSetId: ID del set di test usato per la valutazione.
    • state: stato di avanzamento della valutazione.
    • startTime: all'avvio della valutazione.
    • endTime: Quando la valutazione è terminata, se è terminata.
    • name: nome della valutazione.
    • totalTestCases: Il totale dei test case nel set di test.
    • mcsConnectionId: ID della connessione a Copilot Studio del profilo utente utilizzato per l'esecuzione della valutazione. null se non è connesso alcun profilo utente.
    • testCasesResults: l'elenco dei casi di test nell'esecuzione della valutazione. Include:
      • testCaseId: L'ID del caso di prova.
      • state: stato di completamento del test case.
      • metricsResults: dettagli e risultati per ogni metodo di test usato per il test case. Include quanto segue:
        • type: metodo di test.
        • result: risultato finale del test per questo test case. Include quanto segue:
          • data: dettagli del risultato. I valori esatti dipendono dal metodo di test. Per altre informazioni, vedere la documentazione dell'API Power Platform. Per un test di qualità generale , la risposta include quanto segue:
            • abstention: indica se l'agente ha risposto alla query.
            • relevance: indica se la risposta è rilevante.
            • completeness: indica se la risposta è stata completata.
        • status: Lo stato del caso di test.
        • errorReason: se si è verificato un errore, la causa dell'errore.
        • aiResultReason: spiegazione del risultato del test case fornita dall'intelligenza artificiale.

Per altre informazioni, vedere Get Maker Evaluation Test Run (Esegui test di valutazione di Get Maker).

Usare un ID connettore di Microsoft Studio per le valutazioni

Per Avvia una valutazione dell'agente, è possibile aggiungere facoltativamente un ID connettore Microsoft Studio alla chiamata come profilo utente per la valutazione. Per trovare il tuo mcsConnectionId:

  1. Passare a Power Automate.
  2. Aprire la pagina Connessioni .
  3. Selezionare la connessione Microsoft Copilot Studio.
  4. Copiare l'oggetto mcsConnectionId dall'URL: .../connections/shared_microsoftcopilotstudio/{mcsConnectionId}/details
  • Last updated on