Analizzare gli agenti usando lo Strumento di revisione agente del kit agente Copilot

Lo Strumento di revisione agente è un sistema automatizzato di valutazione della qualità e di revisione della conformità per gli agenti Microsoft Copilot Studio e gli agenti dichiarativi Microsoft 365. Aiuta autori, amministratori e team di governance a individuare problemi, anti-criteri e lacune di conformità prima che raggiungano gli utenti finali.

Man mano che le organizzazioni ampliano le implementazioni di Copilot Studio, la revisione manuale della configurazione, delle istruzioni e della struttura degli argomenti di ogni agente diventa impossibile. Lo Strumento di revisione agente automatizza questa revisione tramite analisi basate sull'IA, facendo emergere tipicamente i risultati attuabili in meno di 60 secondi.

È per:

• Creatori: ricevono feedback concreti per migliorare la qualità degli agenti prima della distribuzione.
• Amministratori e team CoE: per applicare gli standard di governance a tutti gli agenti in un ambiente.
• Responsabili della sicurezza e della conformità: per verificare che gli agenti rispettino le linee guida su privacy, sicurezza e accuratezza.

Funzionalità chiave

Per iniziare: il dashboard

Quando apri lo Strumento di revisione agente, viene visualizzato il dashboard, l'hub centrale che mostra tutti gli agenti nel tuo ambiente e lo stato di revisione.

Layout dashboard

Il dashboard mostra tutto a colpo d'occhio: la barra delle schede che passa dagli agenti di Copilot Studio e Microsoft 365, quattro schede statistiche che riassumono lo stato del portfolio, una barra degli strumenti di ricerca, la griglia degli agenti impaginati e il pulsante Carica ZIP per le revisioni offline.

Schede statistiche

Le quattro schede statistiche offrono uno snapshot di panoramica dello stato del portafoglio di agenti:

Griglia di agenti

Selezione di un ambiente

Per impostazione predefinita, lo strumento mostra gli agenti dell'ambiente in cui sono stati installati. Se devi rivedere un agente da un ambiente diverso, usa il selettore di ambiente nella barra del dashboard. L'elenco a discesa elenca tutti gli ambienti Power Platform a cui hai accesso.

Dopo aver selezionato un ambiente diverso, la griglia degli agenti si aggiorna per mostrare gli agenti di quell'ambiente. Puoi quindi rivedere uno qualsiasi di tali agenti. Il risultato della revisione è memorizzato nell'ambiente attuale (home), non in quello selezionato da te.

Modalità di revisione

Lo strumento supporta due modalità di revisione distinte, accessibili dalla barra delle schede nella barra superiore del dashboard.

Revisione agenti di Copilot Studio

Questa modalità esamina gli agenti creati in Microsoft Copilot Studio. Legge direttamente da Dataverse, non è necessario il caricamento del file.

Cosa analizza:

• Configurazioni degli argomenti (nomi, descrizioni, variabili).
• Configurazioni di strumenti e azioni (conteggio, descrizioni, distribuzione).
• Tipi di fonti delle informazioni.
• Copertura dei test case.
• Istruzioni dell'agente (modalità generativa).
• Metadati dell'agente (lingua, autenticazione, impostazioni dell'IA).

Per avviare una revisione:

1. Trova il tuo agente nella griglia.
2. Selezionare Revisione. Il processo di analisi viene avviato automaticamente.
3. Un indicatore di avanzamento mostra cosa sta accadendo in tempo reale.
4. I risultati vengono visualizzati nel pannello di revisione una volta completati.

Puoi rivedere qualsiasi agente in qualsiasi momento. Ogni revisione crea un nuovo record in Dataverse. La griglia mostra sempre il risultato più recente della revisione.

Revisione di agenti dichiarativi (Microsoft 365 Copilot)

Questa modalità esamina gli agenti dichiarativi di Microsoft 365, definiti da un file JSON manifesto e distribuiti nell'ecosistema Microsoft 365 Copilot.

Puoi inviare un agente dichiarativo per la revisione in due modi:

Cosa analizza (5 criteri, non 15):

Cosa accade durante una revisione

Quando selezioni Rivedi, lo strumento esegue un'analisi automatica che di solito termina in meno di 60 secondi. Un pannello di avanzamento mostra le informazioni durante l'operazione.

L'analisi copre tre aspetti in sequenza:

1. Analisi della configurazione: lo strumento legge la configurazione completa dell'agente da Dataverse, ovvero ogni argomento, strumento, fonte di informazioni, test case e istruzione. Controlla la presenza di campi mancanti in tutti i componenti e misura elementi come il numero di strumenti e la copertura dei test rispetto alle procedure consigliate documentate da Microsoft.
2. Valutazione dei criteri basata sull'IA: un modello di IA esamina la stessa configurazione per valutare la qualità, non solo la completezza. Esamina se i nomi e le descrizioni degli argomenti siano abbastanza chiari perché l'orchestratore generativo possa instradare correttamente, se più argomenti si sovrappongono in modi che causano confusione nella distribuzione e se le descrizioni degli strumenti forniscono all'IA abbastanza indicazioni per invocare lo strumento giusto al momento giusto.
3. Controllo della conformità delle istruzioni: un secondo modello di IA legge le istruzioni di sistema dell'agente e le confronta con 15 criteri di procedure consigliate delle linee guida della modalità generativa di Microsoft, che coprono ambito, sicurezza, qualità della risposta ed esperienza utente. Per ogni criterio che le istruzioni non soddisfano, emergono un risultato specifico e una raccomandazione concreta.

Dopo aver completato tutti i tre passaggi, viene generato automaticamente un report PDF e i risultati si aprono nel pannello di revisione.

Criteri rilevati

I criteri identificano anti-criteri specifici o procedure consiglate mancanti nella configurazione di un agente. Lo strumento controlla 18 criteri in 7 categorie.

Tutti i 18 criteri

Per ogni criterio fallito, lo strumento mostra quali argomenti sono interessati, il valore attuale che ha attivato il risultato, un miglioramento suggerito e un collegamento alla documentazione pertinente di Microsoft Learn.

Categorie di criteri

La griglia dei risultati raggruppa i modelli in sette categorie, ordinate nel seguente ordine:

Logica di gravità

La combinazione tra corrispondenza delle parole chiave e conteggio degli argomenti determina la gravità del criterio:

La gravità determina sia la notifica visiva nella griglia dei risultati sia il livello di errore SARIF nel report esportato.

Criteri di conformità

Questa parte della revisione valuta la qualità delle istruzioni di sistema di un agente, ovvero il testo in linguaggio naturale che un creatore fornisce nelle impostazioni Generative di Copilot Studio. Queste istruzioni definiscono come l'agente si comporta in tutte le conversazioni.

I 15 criteri derivano dalle linee guida sulla modalità generativa di Microsoft e rappresentano le procedure consigliate più efficaci per la qualità delle istruzioni.

Tutti i 15 criteri

Suddivisione delle categorie

Come vengono calcolati i punteggi

Tutti i punteggi sono su una scala da 0 a 100 e sono deterministici. Gli stessi input producono sempre lo stesso punteggio.

Punteggio del criterio

Pattern Score = (Passed Patterns / Total Patterns) × 100

• Criteri totali = 10 deterministici + numero di criteri rilevati dall'IA restituiti (fino a 8).
• Criteri passati = numero di criteri per cui lo stato è pass.
• Il risultato viene arrotondato all'intero più vicino.

Esempio: 15 criteri in totale, 12 passaggi = punteggio criteri pari a 80.

Punteggio dell'istruzione

Il punteggio dell'istruzione utilizza un sistema a punti ponderato basato sulla gravità intrinseca di ciascun criterio:

Instruction Score = (Earned Points / 35) × 100

• Per ciascuno dei 15 criteri, se non viene riscontrato alcun problema per quel criterio, vengono aggiunti i relativi punti di gravità intrinseca.
• Se si rilevano "istruzioni mancanti", tutti i criteri falliscono e il punteggio è 0.
• Il risultato viene limitato a 100 e arrotondato all'intero più vicino.

Esempio: 3 criteri con valore Alto e 2 con punteggio Medio falliscono:

• Punti guadagnati: (4 × 3) + (4 × 2) + (2 × 1) = 12 + 8 + 2 = 22 punti.
• Punteggio = (22/35) × 100 = 63.

Punteggio complessivo

Overall Score = (Pattern Score × 0.5) + (Instruction Score × 0.5)

Entrambe le dimensioni hanno lo stesso peso. Se è disponibile una sola dimensione (ad esempio se non esistono istruzioni), il punteggio di quella dimensione viene utilizzato direttamente.

Guida ai colori e alle etichette dei punteggi

Analisi dei risultati

Dopo la conclusione della revisione, il pannello di revisione mostra i risultati. Il pannello ha tre schede.

Scheda Panoramica

La scheda Panoramica offre un riassunto generale:

• Punteggio complessivo: un indicatore circolare verde, ambra o rosso.
• Punteggio criteri e Punteggio istruzioni affiancati.
• Metadati agente: nome, ambiente, lingua, modalità di autenticazione, impostazioni IA.
• Riepilogo generato dall'IA: descrizione in linguaggio naturale dei risultati più significativi.
• Timestamp di revisione e origine dati (ambiente live o caricamento ZIP).

Scheda Criteri

La scheda Criteri mostra la griglia completa di tutti i 18 criteri valutati, con queste colonne:

Puoi ordinare la griglia in base a qualsiasi colonna. Per impostazione predefinita, i criteri con errore compaiono per primi, ordinati per gravità (Alta, poi Media, poi Bassa).

Scheda Conformità

La scheda Conformità mostra tutti i 15 criteri delle istruzioni:

Dettaglio del criterio

Quando selezioni Dettagli su qualsiasi criterio con errore, viene visualizzato il panello Dettagli criterio. Mostra:

• Nome e descrizione criterio: cosa controlla il criterio.
• Perché è importante: l'impatto di questo anti-criterio sulla qualità degli agenti.
• Tabella argomenti interessati: ogni argomento con il suo valore attuale e il sostituto suggerito dall'IA.
• Raccomandazione: un'azione concreta per risolvere il problema.
• Scopri di più: un collegamento diretto alla documentazione pertinente di Microsoft Learn.

Dettaglio della conformità

Quando selezioni Dettagli su qualsiasi criterio di conformità con errore, si apre il pannello Dettagli conformità. Mostra:

• Nome, categoria e gravità del criterio
• Cosa verifica il criterio: una spiegazione in linguaggio semplice
• Problema specifico riscontrato: l'analisi dell'IA su ciò che manca o non va
• Raccomandazione: linguaggio o criteri esatti da aggiungere alle istruzioni dell'agente
• Esempio: quando disponibile, un esempio di istruzione conforme
• Scopri di più: collegamento alle linee guida pertinenti di Microsoft Learn

Esportare i risultati

Puoi esportare i risultati in tre formati dall'intestazione del pannello di revisione.

Report PDF

Un report PDF accurato, leggibile, adatto alla condivisione con gli stakeholder oppure a essere allegato a un audit di governance.

Contenuto:

• Riepilogo esecutivo con punteggi e metriche chiave
• Risultati della valutazione dei criteri (stato, gravità, argomenti interessati)
• Risultati di conformità (tutti i 15 criteri)
• Raccomandazioni per ogni problema riscontrato
• Metadati dell'agente (nome, ambiente, data di revisione)

Criterio del nome file: {AgentName}_review_{YYYY-MM-DD}.pdf

Il file PDF viene generato automaticamente alla fine di ogni revisione e memorizzato in Dataverse insieme al record della revisione. I download successivi recuperano il file memorizzato senza rieseguire l'analisi.

Esportazione SARIF

SARIF (Static Analysis Results Interchange Format v2.1.0) è un formato JSON progettato per l'integrazione con strumenti per sviluppatori e pipeline CI/CD.

Casi d'uso:

• Carica su GitHub Advanced Security per annotazioni PR basate su SARIF
• Importa in controlli di qualità in Azure DevOps
• Elabora con strumenti di terze parti che usano SARIF (SonarQube, Visual Studio Code e così via)

Panoramica della struttura:

{
  "version": "2.1.0",
  "runs": [{
    "tool": {
      "driver": {
        "name": "Copilot Studio Agent Review Tool",
        "version": "1.0"
      }
    },
    "results": [
      {
        "ruleId": "pat-007",
        "level": "error",
        "message": { "text": "Excessive Tools Usage: 28 tools exceed the recommended limit of 25" },
        "properties": {
          "category": "Architecture",
          "recommendation": "Reduce tool count to 25 or fewer"
        }
      }
    ]
  }]
}

Mappatura tra gravità e livello SARIF:

• Alta = "error"
• Media = "warning"
• Bassa = "note"

Criterio del nome file: {AgentName}_review.sarif

Esportazione in Excel

Una cartella di lavoro Excel multi-foglio per analisi dei dati, report e archiviazione.

Le intestazioni sono in grassetto, con sfondo nel colore del brand. Le celle di punteggio e gravità sono codificate con colore verde, ambra o rosso. Le larghezze delle colonne si regolano automaticamente.

Criterio del nome file: {AgentName}_review_{YYYY-MM-DD}.xlsx

Analisi approfondita della revisione degli agenti dichiarativi

Gli agenti dichiarativi Microsoft 365 sono un tipo diverso di agente rispetto agli agenti di Copilot Studio. Sono definiti interamente da un file manifesto JSON e distribuiti nell'ecosistema Microsoft 365.

Cosa controlla la revisione dell'agente dichiarativo

La revisione controlla innanzitutto la struttura del file manifesto, verificando che tutti i campi richiesti siano presenti e che lo schema sia ben formato. Successivamente esegue una valutazione dell'IA secondo cinque criteri di qualità e genera un report PDF. Il controllo di conformità delle istruzioni per i 15 criteri (specifico per gli agenti di Copilot Studio) qui non si applica.

I 5 criteri di valutazione dell'agente dichiarativo

Controllo dello stato del manifesto (convalida locale)

Prima che l'IA venga eseguita, un controllo deterministico sullo stato verifica la struttura del manifesto:

• Campi richiesti presenti (name, description, instructions)
• Compatibilità tra versioni dello schema
• Riferimenti a plug-in di azione validi
• Numero di elementi di avvio della conversazione entro i limiti (3-12)
• Dichiarazioni di capacità con formato corretto

Eventuali errori nei controlli dello stato appaiono come problemi nei risultati della revisione dell'agente dichiarativo, indipendentemente dalla valutazione dell'IA.

Invia un agente dichiarativo per la revisione

Tramite il caricamento ZIP (il più comune):

1. Esporta l'agente dichiarativo dal tuo strumento di creazione come pacchetto ZIP.
2. Seleziona Carica ZIP nell'intestazione della pagina Strumento di revisione agente.
3. Se lo ZIP contiene più agenti, un pannello selettore ti permette di scegliere quale esaminare.
4. La revisione viene eseguita automaticamente.

Tramite il catalogo Microsoft 365 (richiede la configurazione dell'API Graph):

1. Seleziona Collegati a Microsoft 365 nella scheda Agenti Microsoft 365.
2. Completa la procedura di autorizzazione guidata per l'API Graph.
3. I tuoi agenti dichiarativi distribuiti vengono visualizzati nella griglia degli agenti dichiarativi.
4. Seleziona Rivedi per qualsiasi agente dichiarativo.

Sicurezza e accesso ai dati

Questa sezione descrive come lo Strumento di revisione agente gestisce la sicurezza e l'accesso ai dati.

Archiviazione dei dati

Tutti i risultati delle revisioni sono memorizzati nella tabella cat_agentreviews di Dataverse. Ogni record include:

Sicurezza a livello di riga

La tabella cat_agentreviews utilizza l'ambito di lettura a livello utente (di base) in Dataverse. Gli utenti possono vedere solo le revisioni che hanno creato. Le revisioni di un altro utente non sono mai visibili, nemmeno nello stesso ambiente. Dataverse applica in modo nativo questa sicurezza, non il codice dell'applicazione.

Ambienti di origine

Gli utenti possono esaminare gli agenti dagli ambienti a cui hanno accesso, non solo dall'ambiente attuale. Il dashboard supporta revisioni tra ambienti tramite il selettore di ambiente. Le revisioni di altri ambienti sono etichettate con l'URL dell'ambiente di origine in modo da apparire correttamente quando lo strumento viene caricato.

Le revisioni originate da un file ZIP caricato sono sempre mostrate indipendentemente dall'ambiente a cui lo strumento è collegato.

Quali dati escono dall'ambiente

• La configurazione dell'agente (argomenti, strumenti, istruzioni) viene inviata ai modelli IA tramite Dataverse PredictV2. La configurazione segue il percorso standard di invocazione del modello IA di Dataverse ed è soggetta agli stessi criteri di residenza dati di qualsiasi operazione IA di Dataverse.
• Non vengono inviati dati ad alcun servizio di terze parti o endpoint esterno.
• I risultati della revisione (incluso il file PDF) sono archiviati esclusivamente in Dataverse.

Prima esecuzione e tour di introduzione

La prima volta che un utente apre lo Strumento di revisione agente, un tour di introduzione lo guida tra le parti chiave dell'interfaccia:

1. Schede statistiche del dashboard e cosa rappresentano
2. Come leggere la griglia degli agenti
3. Come avviare una revisione
4. Come interpretare i risultati
5. Opzioni di esportazione

Il tour procede in Dataverse, ma non si ripete dopo il completamento. Gli utenti possono riaprire il tour in qualsiasi momento dalla sezione Guida/Collegamenti rapidi nell'intestazione della pagina.

Domande frequenti

Questa sezione risponde alle domande più comuni sullo Strumento di revisione degli agenti.

Quanto tempo richiede una revisione?

Per un agente tipico con meno di 20 argomenti termina in meno di 60 secondi. Lo strumento ha un timeout fisso di 2 minuti. Agenti molto grandi (più di 50 argomenti, molti strumenti) potrebbero avvicinarsi al limite.

Lo strumento modifica il mio agente?

Nr. Lo strumento è interamente di sola lettura per quanto riguarda i dati degli agenti. Legge solo la configurazione dell'agente. Tutte le scritture sono inviate nella tabella cat_agentreviews.

Posso riesaminare un agente dopo aver apportato modifiche?

Sì. Ogni revisione crea un nuovo record. La griglia mostra sempre la revisione più recente. Le vecchie revisioni rimangono in Dataverse e possono essere consultate in modo programmatico se necessario.

Cosa accade se il mio agente si trova in un ambiente diverso?

Usa il selettore di ambiente nel dashboard per indirizzare lo strumento verso un altro ambiente a cui hai accesso. La revisione viene eseguita in quell'ambiente e il risultato viene memorizzato nell'ambiente attuale.

Posso rivedere agenti che non ho creato?

Sì. Puoi rivedere qualsiasi agente a cui hai accesso in lettura in Dataverse. Tuttavia, puoi solo vedere le revisioni che hai creato (sicurezza a livello di riga). Le revisioni di altri utenti non sono visibili.

Cos'è SARIF e ne ho bisogno?

SARIF è un formato standard per i risultati dell'analisi statica. Ti serve solo se integri i controlli qualità degli agenti in una pipeline CI/CD (GitHub Actions o Azure DevOps). Per la maggior parte degli utenti, le esportazioni in formato PDF ed Excel sono sufficienti.

Lo strumento dice che il mio agente non ha istruzioni. È un problema?

Sì. Lo strumento mostra solo gli agenti che hanno l'IA generativa attivata, quindi ogni agente nella griglia dovrebbe avere istruzioni. Se il controllo di conformità non segnala istruzioni, l'orchestrazione generativa dell'agente è attiva ma non sono ancora state scritte istruzioni di sistema. Aggiungere istruzioni è fortemente consigliato.

Perché l'opzione "Utente tipo e tono" è di bassa severità?

Le linee guida di Microsoft sottolineano che un tono professionale ed educato è già il comportamento predefinito per gli agenti di Copilot Studio. Le istruzioni per il tono sono necessarie solo se vuoi un tono non predefinito. Questo criterio è basso perché fallirlo raramente causa problemi a contatto con l'utente.

Eseguire una revisione consuma crediti Copilot?

Sì. Ogni revisione utilizza i modelli di IA tre volte: per la valutazione dei criteri, per la conformità alle istruzioni e per la generazione di file PDF. Ogni invocazione consuma crediti Copilot dal tuo tenant. Anche il riesame dello stesso agente consuma crediti, quindi prima apporta le modifiche e poi rivedi una seconda volta.

Posso esportare tutte le revisioni contemporaneamente?

Sì. Usa il pulsante Esporta Tutto nella barra degli strumenti della griglia degli agenti per generare una cartella di lavoro Excel che copra tutti gli agenti revisionati nella vista corrente.

Informazioni correlate

• Panoramica sul Kit Agente Copilot
• Installa il Kit Agente Copilot
• Indicazioni sulla modalità generativa
• Configurare gli agenti nel kit agente Copilot
• Inventario degli agenti nel kit agente Copilot