Eseguire valutazioni degli agenti con la CLI di azd (anteprima)

Usare la funzionalità di valutazione di Azure Developer CLI (azd) per aggiungere un ciclo di valutazione della qualità a un agente creato con Microsoft Foundry. Questo articolo è incentrato sul ciclo di vita dell'agente ospitato in azd, in cui si crea, si effettua il provisioning, si distribuisce, si inizializzano le risorse di valutazione, si esegue una prima valutazione, si esamina l'esecuzione e si riutilizza la ricetta di valutazione per esecuzioni successive.

Gli agenti basati su prompt possono essere valutati anche quando sono disponibili come obiettivi degli agenti nel progetto Foundry. I passaggi di distribuzione dell'agente ospitato si applicano solo agli agenti ospitati.

Questo articolo illustra come eseguire la prima valutazione dell'agente con azd ai agent eval generate e azd ai agent eval run.

Prerequisiti

• Una sottoscrizione di Azure con accesso a Microsoft Foundry.
• Azure Developer CLI (azd). Per istruzioni sull'installazione, vedere Installare l'interfaccia della riga di comando per sviluppatori Azure.
• Estensione azd ai agent , versione 0.1.40-preview o successiva, installata (azd ext install azure.ai.agents). Se l'estensione non è installata, quando si inizializza il modello di avvio o si esegue azd ai agent l'estensione viene installata automaticamente. Eseguire azd ext list per verificare la versione installata ed eseguire azd ext upgrade azure.ai.agents se è necessario eseguire l'aggiornamento. Per altre informazioni sull'azdestensione dell'agente di intelligenza artificiale, vedere estensione dell'agente Microsoft Foundry.
• Sessione autenticata azd . Per controllare lo stato di autenticazione, eseguire azd auth status. Se non si è connessi, eseguire azd auth login.
• Ruolo Foundry User nella risorsa Foundry (in precedenza denominata Azure AI User). Per altre informazioni, vedere Controllo degli accessi in base al ruolo per Microsoft Foundry.
• Per gli agenti ospitati: Non è necessario alcun progetto Foundry preesistente. azd ai agent init e azd provision creare le risorse necessarie.
• Per gli agenti basati su prompt: Progetto Foundry esistente con l'agente già distribuito e disponibile come destinazione di valutazione.
• Un'implementazione di modello che supporta il completamento automatico delle chat nello stesso progetto Foundry.
• Facoltativo: un set di dati di valutazione in formato JSONL con esempi rappresentativi, se non si desidera che eval generate generi un set di dati di prova.

Come funzionano le valutazioni di azd agent

L'esperienza principale di valutazione della CLI di azd è progettata per il ciclo di vita dell'hosted agent:

azd ai agent init
azd provision
azd deploy
azd ai agent eval generate
azd ai agent eval run
azd ai agent eval update
# Optional, after the agent and eval recipe meet optimization prerequisites:
azd ai agent optimize

Il flusso di valutazione include gli artefatti e i comandi seguenti.

azd provision non crea set di dati di valutazione, analizzatori, suite o processi di ottimizzazione. La configurazione della valutazione può comportare operazioni di generazione che possono richiedere diversi minuti, perciò resta un’operazione esplicita e ripetibile.

Per gli agenti in hosting, la prima valutazione richiede un agente di destinazione già distribuito e attivabile. Per gli agenti basati su prompt, il passaggio di distribuzione non si applica; L'agente deve esistere già nel progetto Foundry ed essere disponibile come destinazione di valutazione.

Creare e distribuire un agente ospitato

Se non è già disponibile un progetto di agente ospitato, inizializzarne uno con azd:

azd ai agent init

Effettuare il provisioning delle risorse di Foundry e distribuire l'agente:

azd provision
azd deploy

Al termine della distribuzione, verificare che l'agente sia richiamabile:

azd ai agent show

L'agente ospitato deve essere distribuito e richiamabile prima di inizializzare gli asset di valutazione.

Dopo una distribuzione corretta, l'interfaccia della riga di comando suggerisce la valutazione come passaggio successivo esplicito:

Set up an evaluation suite to measure quality and impact in one step with `azd ai agent eval generate`

Per valutare un agente basato su prompt, omettere i comandi di creazione e distribuzione dell'agente ospitato. Continuare con la sezione successiva dopo aver verificato che l'agente basato su prompt esista nel progetto Foundry ed è disponibile come destinazione di valutazione.

Inizializzare le risorse di valutazione

Esegui eval generate dalla cartella dell'area di lavoro di azd o del progetto agent:

azd ai agent eval generate

Senza flag, il comando avvia una procedura guidata interattiva. La procedura guidata rileva l'agente di destinazione dall'ambiente azd, quindi richiede un'istruzione di generazione affinché il servizio possa creare dati di valutazione iniziali utili e una griglia di valutazione.

Esempio di output interattivo:

? Eval suite name: reservation-agent
? How would you like to provide the agent instruction?: Type inline
? Describe what this agent does and what scenarios to test: This agent handles restaurant reservations. Test booking, modification, cancellation, and policy enforcement.
? Include agent traces for evaluator generation?: No
? Select the model for evaluation and generation: gpt-4o (deployed)
? Max samples (between 15 and 1000): 100
  (–) Running  Evaluator generation  (evaluatorgen-reservation-agent-v3-abc12345)
  (–) Running  Dataset generation  (datagen-abc123456)
  (✓) Done  Evaluator generation  (20 seconds)
  (✓) Done  Dataset generation  (2m 9s)

Eval suite created
  Config:     src/reservation-agent/eval.yaml
  Dataset:    reservation-agent-dev-eval-seed (1.0)
              src/reservation-agent/datasets/reservation-agent-dev-eval-seed
  Evaluator:  builtin.task_adherence
  Evaluator:  reservation-agent-quality (1)
              src/reservation-agent/evaluators/reservation-agent-quality/rubric_dimensions.json

  Evaluator dimensions (4):
    Weight  Dimension
    ──────  ─────────
        10  booking_accuracy
         5  policy_enforcement
         6  cancellation_handling
         5  general_quality

  Portal:
    Dataset:   https://ai.azure.com/.../build/data/datasets/reservation-agent-dev-eval-seed/1.0
    Evaluator: https://ai.azure.com/.../build/evaluations/catalog/reservation-agent-quality/1

  Next steps:
    azd ai agent eval run
      Run the eval suite against your agent.
    azd ai agent eval update
      Edit the generated dataset or evaluator locally, then upload changes.

Per l'uso tramite script, passare direttamente gli input di generazione:

azd ai agent eval generate \
  --gen-instruction "This agent handles restaurant reservations. Test booking, modification, cancellation, and policy enforcement." \
  --eval-model gpt-4o \
  --max-samples 100

--out-file è facoltativo e il valore predefinito è eval.yaml nella radice del progetto dell'agente. Usare --out-file <path> per scrivere la configurazione in una posizione diversa.

Per usare un set di dati esistente e gli analizzatori selezionati:

azd ai agent eval generate \
  --dataset ./tests/support-golden.jsonl \
  --gen-instruction "Support quality, policy adherence, and escalation behavior" \
  --max-samples 50 \
  --evaluator builtin.intent_resolution \
  --evaluator support-quality \
  --out-file eval.yaml

Sostituisci ./tests/support-golden.jsonl con il percorso del tuo set di dati di valutazione.

Il --dataset valore può puntare a un file locale o a un nome di set di dati registrato. Ripetere --evaluator per includere più analizzatori personalizzati predefiniti o registrati. I riferimenti del valutatore usano il formato <source>.<name>:

• builtin.<name> — fa riferimento a un analizzatore predefinito fornito da Foundry.
• <name> — fa riferimento a un analizzatore personalizzato registrato nel progetto Foundry. Usare il nome registrato dell'analizzatore senza il suffisso della versione.

Posticipare la generazione con --no-wait

Se la generazione di set di dati o analizzatori richiede troppo tempo, usare --no-wait per inviare processi di generazione e uscire immediatamente:

azd ai agent eval generate \
  --gen-instruction "..." \
  --no-wait

Gli ID delle operazioni in sospeso vengono scritti in eval.yaml. Quando si esegue successivamente azd ai agent eval run, il sistema riprende automaticamente tali operazioni prima di avviare l'esecuzione di valutazione.

Utilizza un target agente basato su prompt

Se hai inizializzato le risorse di valutazione per un agente basato su prompt, puoi utilizzare lo stesso flusso della ricetta di valutazione. La fase di distribuzione dell'agente ospitato non è necessaria per gli agenti basati su prompt.

Prima di eseguire una valutazione, verificare che:

• L'agente basato su prompt esiste nel progetto Foundry.
• L'agente è disponibile come destinazione di valutazione.
• È possibile accedere all'endpoint del progetto e alla destinazione dell'agente.
• eval.yaml seleziona l'agente basato su prompt desiderato.

Per elencare gli agenti disponibili nel progetto Foundry corrente, eseguire:

azd ai agent list

Usare quindi gli stessi comandi per eseguire ed esaminare la valutazione:

azd ai agent eval run --config eval.yaml
azd ai agent eval show

Rivedi il file eval.yaml

Dopo che eval generate è andato a buon fine, aprire eval.yaml nella radice del progetto dell'agente. Per esempio:

src/reservation-agent/eval.yaml

Esegui eval run da questa directory o specifica esplicitamente il percorso con --config src/reservation-agent/eval.yaml. Il file identifica la destinazione dell'agente, il riferimento al set di dati, i riferimenti dell'analizzatore e le opzioni di generazione. Una forma semplificata è:

name: reservation-agent
agent:
  name: reservation-agent
  kind: hosted
  version: "3"
  config: .agent_configs\baseline\metadata.yaml
dataset_reference:
  name: reservation-agent-dev-eval-seed
  version: "1.0"
  local_uri: datasets\reservation-agent-dev-eval-seed
evaluators:
  - builtin.task_adherence
  - name: reservation-agent-quality
    version: "1"
    local_uri: evaluators\reservation-agent-quality\rubric_dimensions.json
options:
  eval_model: gpt-4o
max_samples: 100

• eval.yaml risiede nella radice del progetto dell'agente, ad esempio src/<agent-name>/eval.yaml.
• I dataset generati si trovano in datasets/ e le griglie di valutazione generate si trovano in evaluators/ nella cartella dell'agente.
• local_uri I percorsi in eval.yaml sono relativi alla directory del progetto dell'agente.
• I file locali a cui fa local_uri riferimento sono modificabili. Eseguire azd ai agent eval update per registrare le modifiche locali come nuova versione nel servizio e aggiornare la versione in eval.yaml.
• eval run utilizza la versione registrata inserita nel tag eval.yaml. Per applicare le modifiche locali, eseguire eval update prima di eval run.
• Gli analizzatori possono essere riferimenti predefiniti (ad esempio, builtin.task_adherence) o analizzatori personalizzati generati con name, versione local_uri.
• Considerare i campi della versione come stringhe, anche se sono numerici, quindi la ricetta rimane stabile tra i parser YAML.

Eseguire la valutazione

Dalla cartella del progetto agente eseguire:

azd ai agent eval run

Per impostazione predefinita, il tag eval run senza argomenti risolve il tag eval.yaml nella directory principale del progetto dell'agente. È anche possibile passare il percorso di configurazione in modo esplicito:

azd ai agent eval run --config eval.yaml

Se eval generate --no-wait sono state create operazioni di generazione in sospeso, eval run riprende tali operazioni prima di avviare l'esecuzione della valutazione. Non avvia nuovi processi di generazione di set di dati o analizzatori da zero.

Controllare le esecuzioni di valutazione

Elencare le esecuzioni di valutazione recenti:

azd ai agent eval list

Mostra l'ultima esecuzione:

azd ai agent eval show

Senza specificare flag, eval show usa per impostazione predefinita la valutazione più recente e ne elenca le esecuzioni.

Per visualizzare i dettagli di un'esecuzione specifica, fornire l'ID della valutazione come argomento e l'ID dell'esecuzione con --eval-run-id. Copia l'ID di valutazione dall'output azd ai agent eval list e l'ID di esecuzione dall'output azd ai agent eval show <eval-id>:

azd ai agent eval show <eval-id> --eval-run-id <run-id>

Rispondi utilizzando l'output dell'esecuzione:

• Quale versione dell'agente è stata valutata.
• Quali versioni del set di dati e dell'analizzatore sono state risolte.
• Se l'esecuzione è stata completata, è fallita o è stata completata solo in parte.
• Quali metriche o punteggi dell'analizzatore sono stati prodotti.
• Se sia necessario esaminare l'uso dei token o i log del valutatore.

Eseguire nuovamente dopo aver modificato l'agente

Dopo aver aggiornato e ridistribuire un agente ospitato, eseguire di nuovo la stessa ricetta di valutazione:

azd deploy
azd ai agent eval run --config eval.yaml

Per gli agenti basati su prompt, aggiornate l'agente in Foundry, quindi rieseguite la stessa ricetta di valutazione.

Rieseguire lo stesso eval.yaml aiuta a mantenere stabili i riferimenti a dataset, valutatori e soglie al variare dell'agente.

Aggiornare, reimpostare o ripristinare gli asset di valutazione

Il flusso di valutazione dell'agente usa eval.yaml come ricetta di valutazione locale. Usare azd ai agent eval update quando si modificano file di set di dati locali o rubriche dell'analizzatore e si vogliono registrare tali modifiche come nuove versioni del servizio.

Per aggiornare ciò che utilizza un'esecuzione di valutazione, scegli la procedura corrispondente al tipo di modifica:

Ad esempio, dopo aver modificato una griglia di valutazione generata nella cartella evaluators/ della cartella dell'agente, eseguire:

azd ai agent eval update
azd ai agent eval run --config eval.yaml

Il comando update crea nuovi set di dati registrati o versioni dell'analizzatore. Le esecuzioni di valutazione esistenti rimangono associate alle versioni utilizzate in origine.

Se eval.yaml esiste già, eval generate lo rileva e stampa la configurazione esistente:

Eval config already exists: src/reservation-agent/eval.yaml
  Dataset:    reservation-agent-dev-eval-seed (1.0)
              src/reservation-agent/datasets/reservation-agent-dev-eval-seed
  Evaluator:  builtin.task_adherence
  Evaluator:  reservation-agent-quality (1)
              src/reservation-agent/evaluators/reservation-agent-quality/rubric_dimensions.json

  To run the evaluation:
    azd ai agent eval run

  To update local edits as new versions:
    azd ai agent eval update

  To overwrite and regenerate:
    azd ai agent eval generate --reset-defaults

Per sovrascrivere la configurazione locale e rigenerare gli asset di valutazione predefiniti, eseguire:

azd ai agent eval generate --reset-defaults

--reset-defaults sovrascrive gli asset di valutazione locali eval.yaml e rigenera gli asset di valutazione predefiniti. I set di dati e le versioni dell'analizzatore registrati dal servizio esistenti non vengono eliminati; solo la ricetta locale viene sostituita.

Non fare affidamento sulle versioni più recenti remote che modificano automaticamente la ricetta locale. Il record locale eval.yaml registra le versioni del set di dati, dell'analizzatore o della suite usate dalla ricetta per la riproducibilità.

Facoltativo: avviare l'ottimizzazione dal segnale di valutazione

Dopo che almeno un'esecuzione di valutazione ha esito positivo, è possibile usare eval.yaml come input per l'ottimizzazione dell'agente se l'agente e la ricetta soddisfano i prerequisiti di ottimizzazione.

Prima di avviare l'ottimizzazione, verificare che:

• L'agente di destinazione è pronto per l'ottimizzazione. Per gli agenti ospitati, l'agente viene distribuito e può essere richiamato.
• eval.yaml fa riferimento all'agente, al set di dati, alle versioni dell'analizzatore e alle soglie previste.
• È stata completata con successo almeno una sessione di valutazione.
• La preparazione dell'agente richiesta da Optimizer è completata. Per i prerequisiti di Optimizer e i requisiti di preparazione dell'agente, vedere Ottimizzare i prompt degli agenti con Prompt Optimizer.

Poi eseguire:

azd ai agent optimize --config eval.yaml

Il comando optimize legge la destinazione dell'agente, il set di dati, gli analizzatori e le soglie da eval.yaml. Invia un job di ottimizzazione, ma non applica in modo invisibile le modifiche al codice sorgente né redistribuisce l'agente candidato. Esaminare qualsiasi output di Optimizer prima di applicare le modifiche.

Procedure consigliate

• Esegui azd ai agent eval generate solo dopo che l'agente è disponibile come target di valutazione. Per gli agenti ospitati, l'agente deve essere distribuito e richiamabile.
• Inizia con un set di dati generato di dimensioni ridotte o con un piccolo sottoinsieme del tuo set di dati di riferimento.
• Prima di considerare attendibili i punteggi, controlla il set di dati generato e i documenti di revisione dei valutatori.
• Dopo aver modificato i file del set di dati o dell'analizzatore generati, eseguire azd ai agent eval update per registrare gli asset modificati prima di eseguire di nuovo la valutazione.
• Controllo del codice sorgente eval.yaml se il tuo team desidera una procedura di valutazione verificabile e riproducibile.
• Se il vostro team esamina e modifica i set di dati generati e le griglie di valutazione nell'ambito della procedura di valutazione, vi invitiamo a inserirli nei file datasets/ e evaluators/ all'interno della cartella "agent".
• Rieseguire la stessa operazione eval.yaml dopo che l'agente cambia in modo che i confronti usino la stessa ricetta di test.
• Usare azd ai agent optimize --config eval.yaml solo dopo avere ottenuto un risultato di valutazione di base utile e l'agente viene preparato per l'ottimizzazione.

Limitations

• Il flusso di comando primario è ottimizzato per gli agenti ospitati e il ciclo di valutazione post-distribuzione.
• azd provision non crea asset di valutazione.
• eval run non genera nuovi set di dati o analizzatori, ad eccezione della ripresa delle operazioni in sospeso da eval generate --no-wait.
• Il ciclo di vita completo della suite, la valutazione pianificata, la valutazione continua, gli avvisi e i flussi di lavoro di confronto non sono necessari per il primo percorso di valutazione.

Contenuti correlati

• Valutare gli agenti di intelligenza artificiale
• Valutazione umana per gli agenti Microsoft Foundry
• Analisi dei cluster di valutazione
• Ottimizzare le richieste degli agenti con Prompt Optimizer
• Configurare il tracciamento per gli agenti IA in Microsoft Foundry
• Monitorare gli agenti con il dashboard di monitoraggio dell'agente
• Agenti ospitati nel servizio Foundry Agent
• Ciclo di vita di sviluppo dell'agente