Analizzare gli agenti con lo strumento Agent Review in Copilot Agent Kit

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à principali

Capacità Details
Copertura degli agenti Agenti di Copilot Studio e agenti dichiarativi di Microsoft 365
Tempo di revisione Tipicamente sotto i 60 secondi per agente
Modelli selezionati 18 criteri (10 deterministici + 8 basati sull'IA)
Criteri di conformità 15 criteri di qualità dell'istruzione
Sistema di punteggio Punteggio complessivo 0-100 (50% criterio, 50% conformità)
Formati di esportazione PDF, SARIF, Excel
Archiviazione dati Microsoft Dataverse (sicurezza applicata livello di riga in ambito utente)
Motore di intelligenza artificiale Prompt di intelligenza artificiale di Microsoft Copilot Studio tramite Dataverse PredictV2

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 del dashboard

Schermata del dashboard dello strumento di revisione degli agenti con schede statistiche, griglia degli agenti e pulsante Carica ZIP.

La dashboard mostra tutto a colpo d'occhio: la barra delle schede per passare da Copilot Studio agli agenti di Microsoft 365, quattro schede statistiche che riepilogano lo stato del portafoglio, una barra degli strumenti di ricerca, la griglia paginata degli agenti e il pulsante Carica ZIP per le revisioni offline.

Riquadri statistici

I quattro riquadri statistici offrono un'istantanea immediata dello stato di salute del portafoglio agenti:

Scheda Cosa mostra Come viene calcolato
Agenti totali Conteggio di tutti i bot attivi nell'ambiente. Eseguire una query sulla tabella bot in cui statecode = 0
Revisionato Numero e percentuale di agenti rivisti. Conteggio delle revisioni completate diviso per il totale degli agenti
Punteggio medio Punteggio medio complessivo su tutte le revisioni completate. Somma dei punteggi divisa per il numero di elementi revisionati
Numero totale di problemi Problemi cumulativi riscontrati in tutti gli agenti rivisti. Somma degli errori di criterio e di quelli di conformità

Griglia di agenti

Column Contenuto
Name Nome visualizzato dell'agente con icona.
Score Punteggio complessivo della revisione (0-100) o -- se non ancora rivisto. Codificato a colori.
Problemi Riepilogo dei risultati di gravità alta, media e bassa. -- se non esaminato.
Ultima revisione Tempo relativo (ad esempio "2 ore fa" o "1 settimana fa") oppure "Non rivisto".
Azioni Rivedi per agenti non rivisti; Visualizza per agenti con revisioni esistenti.

Seleziona 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 esaminare qualsiasi di questi agenti. Il risultato della revisione è memorizzato nell'ambiente attuale (home), non in quello selezionato da te.

Screenshot del menu a discesa del selettore di ambiente che elenca gli ambienti Power Platform accessibili.

Modalità di revisione

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

Revisione degli 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. Seleziona Esamina. 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.

Recensione dell'agente dichiarativo (Microsoft Copilot)

Questa modalità esamina i Microsoft 365 Declarative Agents, definiti da un file JSON manifest e distribuiti nell'ecosistema Microsoft Copilot.

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

metodo Come Quando utilizzare
Carica ZIP Seleziona Carica ZIP nell'intestazione della pagina, quindi seleziona il pacchetto esportato. L'agente è di un altro tenant o non è presente nel tuo catalogo.
Dal catalogo Microsoft 365 Connettiti a Microsoft 365 tramite l'Installazione guidata dell'API Graph, poi sfoglia gli agenti. L'agente è implementato nel tuo tenant Microsoft 365.

Cosa analizza (5 criteri, non 15):

Criterio Weight Cosa viene controllato
Istruzioni 30% Chiarezza, completezza e qualità delle istruzioni per l'agente
Conoscenza 20% Ancoraggio attraverso fonti di conoscenza connesse
Funzionalità 15% Uso di CodeInterpreter e OneDriveAndSharePoint
Azioni 15% Distribuzione degli strumenti e descrizioni delle azioni
Elementi per avviare la conversazione 10% Minimo 3, consigliato 6 (massimo 12)
Gestione corretta degli errori 10% Recupero da errori e comportamenti di riserva

Note

Il controllo di conformità delle istruzioni a 15 criteri è specifico per gli agenti di Copilot Studio e non si applica agli agenti dichiarativi.

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.

Schermata del pannello dei progressi della revisione che mostra le fasi eseguite durante una revisione dell'agente.

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.

Importante

Ogni recensione consuma crediti Copilot. I passaggi basati sull'IA (valutazione dei criteri, controllo della conformità delle istruzioni e generazione del file PDF) invocano ciascuno un modello di IA tramite Dataverse. Pianifica di conseguenza se stai valutando un gran numero di agenti.

Modelli rilevati

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

Tutti i 18 pattern

ID Schema del nome Categoria Impatto
pat-001 Nome del modello mancante Denominazione dei modelli L'orchestratore generativo non può indirizzare in modo affidabile a questo argomento.
pat-002 Descrizione del modello mancante Descrizione modello L'argomento potrebbe essere saltato o attivato erroneamente durante la distribuzione.
pat-003 Nome della variabile di input mancante Variabili di input Gli utenti vedono variabili senza nome, causando confusione nella conversazione.
pat-004 Descrizione della variabile di input mancante Variabili di input L'IA non riesce a estrarre correttamente il valore giusto dagli input dell'utente.
pat-005 Nome della variabile di output mancante Variabili di output I valori di output non sono etichettati e sono difficili da interpretare per gli utenti.
pat-006 Descrizione della variabile di output mancante Variabili di output L'IA non ha il contesto per popolare correttamente la variabile.
pat-007 Uso eccessivo degli strumenti Architecture Troppi strumenti degradano la precisione della distribuzione e aumentano la latenza.
pat-008 Casi di test inadeguati Evaluation Le regressioni nel comportamento dell'argomento passano inosservate prima della distribuzione.
pat-009 Descrizione dell'agente figlio mancante Architecture L'orchestratore non riesce a decidere quando delegare all'agente figlio.
pat-010 Espansione dell'architettura dell'agente figlio Architecture Una delega eccessiva crea complessità e latenza nell'orchestrazione.
pat-011 Nome del modello non chiaro Denominazione dei modelli Nomi vaghi inducono l'orchestratore a instradare verso l'argomento sbagliato.
pat-012 Descrizione del modello poco chiara Descrizione modello Descrizioni inadeguate causano attivazioni di argomenti mancate o errate.
pat-013 Nome della variabile di input non chiaro Variabili di input I nomi ambigui rendono più difficile la compilazione corretta della variabile da parte dell'IA.
pat-014 Descrizione della variabile di input poco chiara Variabili di input L'IA estrae il valore sbagliato o pone domande di chiarimento inutili.
pat-015 Nome della variabile di output poco chiaro Variabili di output Argomenti a valle o flussi che consumano questa variabile potrebbero fraintenderla.
pat-016 Descrizione della variabile di output poco chiara Variabili di output L'IA non può produrre in modo affidabile il formato o il valore di output atteso.
pat-017 Descrizioni di argomenti sovrapposte Descrizione modello Più argomenti competono per le stesse espressioni dell'utente, causando una distribuzione imprevedibile.
pat-018 Lacuna di distribuzione degli strumenti Architecture L'IA non riesce a decidere quale strumento chiamare, il che porta a invocazioni sbagliate oppure a nessuna azione.

Per ogni modello non conforme, lo strumento mostra quali argomenti sono interessati, il valore corrente che ha generato la segnalazione, un miglioramento suggerito e un collegamento alla documentazione pertinente di Microsoft Learn.

Screenshot della scheda Criteri che elenca tutti i 18 criteri con stato, gravità, categoria e conteggi degli argomenti interessati.

Categorie di modelli

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

# Categoria Modelli inclusi
1 Denominazione dei modelli pat-001, pat-011
2 Descrizione modello pat-002, pat-012, pat-017
3 Variabili di input pat-003, pat-004, pat-013pat-014
4 Variabili di output pat-005, pat-006, pat-015pat-016
5 Architecture pat-007, pat-009, pat-010pat-018
6 Orchestrazione Riservato per futuri modelli rilevati dall'IA
7 Evaluation pat-008

Logica di gravità

La combinazione della corrispondenza delle parole chiave e del numero di argomenti determina la gravità del pattern:

Condition Gravità assegnata
Il nome del modello contiene "nome del modello" o "descrizione del modello" Alto
Il nome del modello contiene "variable" Media (a meno che il numero di argomenti non sia 5 o più)
Il numero di argomenti è 5 o più Alto
Il numero di argomenti è 2 o più Medium
Il numero degli argomenti è 1 Basso

La gravità influisce sia sul badge visivo nella griglia dei risultati sia sul 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

# ID Nome del criterio Categoria Severity Cosa controlla
1 scope-definition Definizione dell'ambito Scope Alto Le istruzioni dell'agente definiscono esplicitamente a quali argomenti l'agente deve rispondere e a quali no.
2 out-of-scope-handling Gestione del fuori ambito Scope Medio Le istruzioni specificano cosa dire quando un utente chiede qualcosa al di fuori dell'ambito dell'agente.
3 persona-and-tone Persona e tono Esperienza utente Basso Le istruzioni definiscono il tono per scenari non predefiniti. (Professionale/educato è già l’opzione predefinita; omettere se non necessario.)
4 privacy-and-sensitive-data Privacy e dati sensibili Safety Alto Le istruzioni contengono indicazioni esplicite in relazione al non memorizzare, mostrare o ripetere dati personali.
5 fallback-when-uncertain Opzione di riserva in caso di incertezza Quality Alto Le istruzioni specificano cosa fare quando l'agente non ha le informazioni necessarie per rispondere.
6 citations-and-sources Citazioni e fonti Quality Medio Le istruzioni richiedono all'agente di citare nomi e sezioni di documenti quando si riferisce alle fonti delle informazioni.
7 formatting-guidelines Linee guida di formattazione Esperienza utente Basso Le istruzioni specificano il formato della risposta (elenco, tabelle, passaggi numerati) per un output strutturato.
8 clarifying-questions Domande di chiarimento Esperienza utente Medio Le istruzioni spiegano come gestire le domande ambigue ponendo domande di approfondimento per chiarire.
9 prompt-injection-resilience Protezione dall’iniezione di prompt Safety Alto Le istruzioni includono salvaguardie esplicite contro i tentativi di jailbreak o di prompt injection.
10 link-safety Sicurezza dei collegamenti Safety Medio Le istruzioni garantiscono che solo collegamenti verificati e sicuri vengano condivisi con gli utenti.
11 advice-disclaimers Esclusioni di responsabilità sulla consulenza Safety Alto Le istruzioni includono dichiarazioni di non responsabilità per ambiti di consulenza sensibili (finanza, sanitario, legale).
12 accuracy-quality Accuratezza e qualità Quality Alto Le istruzioni ancorano esplicitamente l'agente alle sue fonti di informazioni e vietano la creazione di informazioni inventate o basate su congetture.
13 tool-routing-hints Suggerimenti per l'instradamento degli strumenti Quality Medio Le istruzioni forniscono indicazioni su quali strumenti o fonti di informazioni utilizzare quando la distribuzione è ambigua.
14 escalation-guidance Linee guida sull'escalation Esperienza utente Alto Le istruzioni definiscono cosa fare quando l'agente non è in grado di aiutare: passare a un operatore umano, suggerire un'alternativa o terminare in modo appropriato.
15 deterministic-language Linguaggio deterministico Quality Medio Le istruzioni usano direttive assolute (sempre, mai, solo, devono) invece di vari modificatori vaghi (potrei, di solito, provare, a volte).

Screenshot della scheda Conformità che mostra i 15 criteri di qualità delle istruzioni con stato e gravità.

Suddivisione delle categorie

Categoria Conteggio dei criteri Stato attivo
Scope 2 Definisce a quali domande l'agente risponde e a quali no
Safety 4 Protegge gli utenti da disinformazione, perdita di dati e manipolazione
Quality 5 Garantisce risposte accurate, fondate e ben strutturate
Esperienza utente 4 Modella l'esperienza conversazionale e i percorsi di escalation

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 modello

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 delle istruzioni

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

Gravità intrinseca Punti in caso di superamento Conteggio dei criteri Numero massimo di punti
Alto 3 7 21
Medio 2 6 12
Basso 1 2 2
Totale 15 35
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 del punteggio

Intervallo di punteggi Label Colore
80 e oltre Eccellente Verde
60-79 Bene Ambra
Da 40 a 59 Sufficiente Rosso
Meno di 40 Necessario miglioramento Rosso

Analisi dei risultati

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

Tab Panoramica

La scheda Panoramica offre un riassunto generale:

  • Punteggio complessivo: un indicatore circolare verde, ambra o rosso.
  • Punteggio del modello e Punteggio delle istruzioni uno accanto all’altro.
  • Metadati agente: nome, ambiente, lingua, modalità di autenticazione, impostazioni IA.
  • Riepilogo generato dall'IA: descrizione in linguaggio naturale dei risultati più significativi.
  • Data e ora della revisione e origine dei dati (ambiente attivo o caricamento ZIP).

Screenshot della scheda panoramica del pannello di revisione che mostra l'indicatore di punteggio complessivo, i punteggi dei criteri e delle istruzioni e il riepilogo dell'IA.

Scheda Criteri

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

Column Descrzione
Condizione Superamento o fallimento
Severity Notifica con valori Alta, Media o Bassa
Categoria Categoria di modelli (denominazione del modello, architettura e così via)
Nome del pattern Nome completo del modello
Argomenti interessati Conteggio degli argomenti interessati da questo modello
Azioni Pulsante Dettagli per aprire il pannello Dettagli del modello

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

Scheda Conformità

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

Column Descrzione
Condizione Superamento o fallimento
Severity Notifica con valori Alta, Media o Bassa
Categoria Ambito, sicurezza, qualità o esperienza utente
Nome criterio Nome completo del criterio
Problemi rilevati Conteggio dei problemi specifici secondo questo criterio
Azioni Pulsante Dettagli per aprire il pannello Dettagli conformità

Approfondimento dei dettagli del modello

Quando selezioni Dettagli in un modello con esito negativo, si apre il pannello Dettagli del modello. Mostra:

  • Nome e descrizione del modello: che cosa verifica questo modello.
  • 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.

Schermata del pannello Dettagli del pattern che mostra la descrizione del pattern, gli argomenti interessati, la raccomandazione e il collegamento Scopri di più.

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.

Contenuti:

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

Schema 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"
  • Medio = "warning"
  • Basso = "note"

Schema del nome file: {AgentName}_review.sarif

Esportazione in Excel

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

Foglio Contenuto
Sommario Una riga per ogni agente rivisto, ovvero nome, punteggi, conteggio dei problemi, data della revisione
Modelli Tutti i 18 criteri, ovvero ID, nome, categoria, gravità, stato, argomenti interessati, raccomandazione
Conformità Tutti i 15 criteri, ovvero ID, nome, categoria, gravità, stato, numero di problemi, raccomandazione

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.

Schema 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 verifica 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

Criterio Weight Cosa viene valutato
Istruzioni 30% Chiarezza, specificità e completezza del prompt di sistema dell'agente
Conoscenza 20% Uso di fonti di informazioni connesse per il grounding
Funzionalità 15% Uso delle funzionalità CodeInterpreter e OneDriveAndSharePoint
Azioni 15% Presenza e qualità delle descrizioni delle azioni degli strumenti
Elementi per avviare la conversazione 10% Numero e qualità (minimo 3, consigliato 6)
Gestione corretta degli errori 10% Gestione di input e stati di errore sconosciuti

Verifica dello stato del manifest (convalida locale)

Prima che l'IA entri in esecuzione, un controllo deterministico di integrità verifica la struttura del file manifest:

  • Campi richiesti presenti (name, description, instructions)
  • Compatibilità tra versioni dello schema
  • Riferimenti a plug-in di azione validi
  • Numero di spunti di conversazione compreso tra 3 e 12
  • Dichiarazioni di capacità con formato corretto

Eventuali errori dei controlli di integrità compaiono come problemi nei risultati della revisione del Declarative Agent, 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 file ZIP nell'intestazione della pagina dello strumento di revisione degli agenti.
  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.

Schermata del pannello di revisione dell'agente dichiarativo che mostra i risultati della verifica dello stato del manifest e della valutazione dell'IA.

Sicurezza e accesso ai dati

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

Archiviazione dati

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

Campo Contenuto
cat_agentreviewsid ID unico del record di revisione
cat_botid Riferimento all'agente esaminato
cat_overallscore Punteggio complessivo 0-100
cat_patternscore Punteggio di valutazione del modello
cat_instructionscore Punteggio di conformità delle istruzioni
cat_totalissues Numero totale di problemi
cat_reviewresultjson Risultato completo della revisione in formato JSON
cat_reviewpdfreport_name Report in PDF (colonna file di Dataverse)
cat_sourceenvironment URL dell'ambiente di origine o zip
cat_agenttype 1 = Copilot Studio, 2 = agente dichiarativo

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 dell'agente, un tour introduttivo lo guida attraverso gli elementi principali 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

L'avanzamento del tour viene mantenuto in Dataverse, quindi il tour non viene ripetuto una volta completato. 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?

No. Lo strumento è interamente di sola lettura per quanto riguarda i dati degli agenti. Legge solo la configurazione dell'agente. Tutte le operazioni di scrittura vengono eseguite nella tabella cat_agentreviews.

Posso riesaminare un agente dopo aver apportato modifiche?

Yes. 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?

Yes. Puoi esaminare qualsiasi agente per cui disponi dell'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?

Yes. 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 è di bassa priorità perché il suo mancato rispetto raramente causa problemi visibili all’utente.

Fare una recensione consuma crediti Copilot?

Yes. 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 utilizza Crediti Copilot del tuo tenant. Rivedere di nuovo lo stesso agente consuma crediti, quindi apporta prima le modifiche e poi riesaminalo.

Posso esportare tutte le revisioni contemporaneamente?

Yes. 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.