Ottimizzare le istruzioni, le competenze, gli strumenti e i modelli dell'agente (anteprima)

L'utilità di ottimizzazione agente migliora quattro aspetti dell'agente ospitato: istruzioni, competenze, strumenti e selezione del modello. Rileva automaticamente quali di questi obiettivi ottimizzare dalla configurazione di riferimento del tuo agente.

Questo articolo illustra come eseguire un'ottimizzazione, configurare e monitorare l'esecuzione e distribuire i risultati. Per le operazioni eseguite da ogni destinazione e quando viene attivata, vedere Destinazioni di ottimizzazione. Per configurare gli input di riferimento, consulta Rendi il tuo agente pronto per l'ottimizzazione. Per una rapida panoramica delle modifiche apportate dall'ottimizzatore, consulta Che cosa cambia ciascun target.

Prerequisiti

• Un progetto Foundry con un agente ospitato già implementato
• L'estensione CLI azure.ai.agents installata (vedere Guida introduttiva: Ottimizzare un agente ospitato)
• Un modello distribuito per la valutazione (ad esempio, gpt-4.1-mini) e un modello di ottimizzazione dall'elenco supportato (ad esempio, gpt-5.1)
• Il tuo agente è compatibile con l'ottimizzatore (chiamate load_config())

Eseguire un'ottimizzazione

Avviare un'esecuzione di ottimizzazione con un singolo comando:

azd ai agent optimize

L'utilità di ottimizzazione valuta la baseline, genera candidati, li valuta e classifica i risultati. Per l'intero ciclo di valutazione e miglioramento, consulta Come funziona l'ottimizzatore dell'agente. Le destinazioni eseguite dipendono dalla configurazione di base, ovvero l'ottimizzazione delle istruzioni, il miglioramento delle competenze e l'ottimizzazione degli strumenti vengono attivati automaticamente quando sono presenti i file di base corrispondenti. Vedere Destinazioni di ottimizzazione.

Per controllare l'esecuzione con un file di configurazione, passare un oggetto eval.yaml che fa riferimento al set di dati, agli analizzatori e alle opzioni:

azd ai agent optimize --config eval.yaml

Per lo schema completo eval.yaml , vedere Configurare l'esecuzione dell'ottimizzazione.

Specificare come destinazione un agente specifico

Per impostazione predefinita, la CLI ottimizza l'agente rilevato nell'ambiente azd corrente e nel agent.yaml locale del progetto. Optimizer risolve il nome dell'agente in questo ordine di priorità:

Usare il --agent flag quando sono presenti più agenti nel progetto o si vuole eseguire l'override dell'impostazione predefinita. Il nome dell'agente deve corrispondere a un agente ospitato distribuito nel progetto Foundry.

Configurare l'esecuzione dell'ottimizzazione

Configurare l'ottimizzazione viene eseguita tramite un eval.yaml file che collega il set di dati, gli analizzatori e le opzioni di esecuzione. Il comando azd ai agent eval generate scrive automaticamente questo file oppure è possibile crearlo a mano. L'utilità di ottimizzazione rileva eval.yaml automaticamente nella radice del progetto oppure può essere passata in modo esplicito con --config eval.yaml.

# eval.yaml
name: my-optimization              # Optional label for the run
agent:
  name: my-agent                   # Deployed hosted agent name
  kind: hosted
  version: "1"                     # Agent version (optional)
  model: gpt-4.1-mini              # Baseline model deployment
  config: .agent_configs/baseline/metadata.yaml
dataset:
  local_uri: ./eval.jsonl          # A local JSONL file...
  # name: my-foundry-dataset       # ...OR a registered Foundry dataset
  # version: "1"
# validation_dataset:              # Optional held-out dataset
#   name: my-validation-dataset
#   version: "1"
evaluators:
  - builtin.task_adherence         # A built-in evaluator...
  # - name: my-custom-evaluator    # ...or a custom evaluator
  #   version: "1"
  #   local_uri: ./my_evaluator.json
options:
  eval_model: gpt-4.1-mini         # Scores responses
  optimization_model: gpt-5.1      # Generates candidates
  max_candidates: 4
  optimization_config:
    model_search_space:            # Optional: compare model deployments
      - gpt-4.1

Creare separatamente il set di dati e gli analizzatori; vedere Creare un set di dati di valutazione e analizzatori. Le sezioni seguenti descrivono le opzioni di esecuzione.

Scegliere i modelli di valutazione e ottimizzazione

L'utilità di ottimizzazione usa due modelli: un modello di valutazione che assegna punteggi alle risposte dell'agente rispetto ai criteri e un modello di ottimizzazione che genera configurazioni candidate. Impostarli in eval.yaml o usare i flag dell'interfaccia della riga di comando.

options:
  eval_model: gpt-4.1-mini
  optimization_model: gpt-5.1

azd ai agent optimize --eval-model gpt-4.1-mini --optimize-model gpt-5.1

Qualsiasi modello di completamento della chat distribuito nel progetto funziona come modello di valutazione. Il modello di ottimizzazione deve appartenere all'elenco supportato. Per i ruoli e i modelli supportati, vedere Modelli.

Impostare il numero di candidati

L'opzione max_candidates imposta il numero previsto di configurazioni candidate per l'esecuzione. L'ottimizzatore in genere termina una volta raggiunto quel conteggio, a meno che l'esecuzione non si interrompa prima a causa di un errore o di un'altra condizione di arresto.

I valori più elevati esplorano più varianti, ma richiedono più tempo. L'ottimizzatore apprende dai candidati precedenti, quindi i candidati successivi tendono a assegnare punteggi più elevati.

Valutare più modelli

Per confrontare le distribuzioni dei modelli in un'unica esecuzione, elencarle sotto optimization_config.model_search_space. Optimizer valuta l'agente con ogni modello rispetto allo stesso set di dati e classifica i risultati in base al punteggio e al costo del token.

# eval.yaml
options:
  optimization_config:
    model_search_space:
      - gpt-4.1
      - gpt-4.1-mini
      - gpt-4o

Ogni modello elencato in model_search_space deve essere distribuito nel progetto Foundry.

La selezione del modello viene eseguita insieme alle destinazioni che vengono attivate automaticamente dalla baseline. Una singola esecuzione può produrre candidati che combinano istruzioni, competenze e descrizioni degli strumenti migliorate con diverse opzioni del modello: non si configura la combinazione manualmente.

Monitorare un processo in esecuzione

Un'esecuzione di ottimizzazione è asincrona. Usare questi comandi quando un processo è a esecuzione prolungata o si vuole controllarne lo stato di avanzamento:

# Check status and stream progress
azd ai agent optimize status <operation-id> --watch

# List recent optimization jobs
azd ai agent optimize list

# Cancel a running job
azd ai agent optimize cancel <operation-id>

Acquisisci l'ID dell'operazione, l'URL del portale, i punteggi e gli ID dei candidati dall'output dell'esecuzione. È anche possibile monitorare il processo nel portale Foundry usando l'URL visualizzato all'avvio dell'esecuzione.

Interpretare i risultati

Al termine dell'ottimizzazione, esaminare la tabella dei risultati. Un asterisco (*) contrassegna il candidato migliore. Per le colonne della tabella dei risultati, i dettagli di assegnazione dei punteggi, le soglie di miglioramento del punteggio e la visualizzazione del portale, vedere Informazioni sui risultati dell'ottimizzazione.

Implementa la variante vincente

Il flusso di lavoro consigliato consiste nell'applicare la configurazione ottimizzata in locale, quindi distribuire:

# Apply the winning candidate locally
azd ai agent optimize apply --candidate <candidate-id>

# Deploy with the optimized config
azd deploy

Consente di scaricare la configurazione ottimizzata in .agent_configs/<candidate_id>/ nel tuo progetto. Alla successiva distribuzione, l'agente usa le istruzioni e le descrizioni degli strumenti migliorate.

In alternativa, è possibile eseguire la distribuzione direttamente tramite l'API (utile per il test rapido A/B):

azd ai agent optimize deploy --candidate <candidate-id>

Se il punteggio di tutti i candidati è inferiore alla linea di base, non distribuire alcun candidato. La configurazione di base rimane attiva.

Modifiche apportate a ogni destinazione

L'ottimizzatore attiva automaticamente gli obiettivi pertinenti alla baseline. Questa sezione serve da riferimento per le modifiche che un’esecuzione apporta. Usare la tabella seguente per prevedere le operazioni di ottimizzazione per l'agente:

Il codice rimane invariato in tutte le destinazioni perché load_config() restituisce automaticamente i valori ottimizzati. Solo la configurazione visualizzata dal modello visualizza le modifiche.

Istruzioni

L'ottimizzatore riscrive il prompt di sistema. I miglioramenti comuni includono:

• Aggiungere vincoli espliciti che il prompt originale sottintendeva ma non specificava
• Istruzioni di ristrutturazione per maggiore chiarezza
• Aggiunta delle specifiche relative al formato di output
• Rafforzamento dei limiti di sicurezza e ambito

Ad esempio, un prompt di base minimo come You are a helpful assistant. potrebbe diventare:

You are a helpful coding assistant. Follow these guidelines:
1. Always include working code examples
2. Explain your reasoning step by step
3. If a question is outside your expertise, say so clearly
4. Use markdown formatting for code blocks
5. Handle edge cases in code examples

Competenze

L'ottimizzatore ottimizza la descrizione, il corpo e i criteri di attivazione di ogni competenza mantenendo intatto lo scopo della competenza. L'agente carica competenze migliorate tramite load_config(), che le aggiunge al set di istruzioni. Le skill utilizzano il formato aperto Agent Skills. Per informazioni su come l'agente carica le skill, vedi Rendi il tuo agente pronto per Optimizer.

Tools

Optimizer ottimizza le tools.json definizioni. I miglioramenti comuni includono:

• Descrizioni più chiare delle funzioni che consentono al modello di sapere quando chiamare uno strumento
• Descrizioni di parametri più specifiche che riducono argomenti imprecisi
• Aggiunti vincoli (enum, campi obbligatori) che impediscono input non validi

Il codice di implementazione dello strumento rimane invariato. Solo le definizioni visualizzate dal modello vedono la modifica.

Models

L'ottimizzatore classifica ogni modello candidato in base al punteggio composito e al costo del token, in modo da poter scegliere il compromesso migliore da qualità a costo. Per configurare i candidati, vedere Valutare più modelli.

Risoluzione dei problemi

Contenuti correlati

• Panoramica di Agent Optimizer
• Prepara il tuo agente per l'ottimizzazione
• Creare un set di dati di valutazione e analizzatori
• Guida introduttiva: Ottimizzare un agente ospitato