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

  • Hai 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.
    • È necessario acquisire il token di accesso utilizzando l'ID client di una registrazione dell'app a cui è stato concesso l'ambito appropriato nell'API Power Platform.
  • Per Avvia una valutazione dell'agente, è possibile aggiungere facoltativamente un ID connettore Microsoft Studio alla chiamata da usare 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

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

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

  1. Soddisfare 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.

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: Lo stato del set di test. Un set di test utilizzabile è Active.
    • totalTestCases: il numero di casi di test all'interno dell'insieme di test.

Ottenere i dettagli del set di test dell'agente

  • Endpoint:GET https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/makerevaluation/testsets/{yourTestSetId}?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 saperne di più, consulta la documentazione di riferimento dell'API Dettagli del set di test.

Avviare una valutazione dell'agente

  • Endpoint:GET https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/makerevaluation/testsets/{yourTestSetId}/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'autenticazione delle 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. Per informazioni su come trovare l'ID connessione MCS, vedere Prerequisiti .
  • 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: Stato dell'esecuzione, durante la 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.

Ottenere i dettagli dell'esecuzione di test dell'agente

  • Endpoint:GET https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/makerevaluation/testruns/{yourTestRunId}?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: L'ID per l'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: al termine della valutazione (se completata).
    • name: nome della valutazione.
    • totalTestCases: Il totale dei test case nel set di test.
    • mcsConnectionId: ID di connessione per la connessione di 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:
        • type: metodo di test.
        • result: risultato finale del test per questo test case. Include:
          • 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:
            • 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 test case.
        • errorReason: se si è verificato un errore, la causa dell'errore.
        • aiResultReason: spiegazione del risultato del test case fornita dall'intelligenza artificiale.

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.
  • Last updated on