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

Il modo in cui la CLI determina l'agente dipende dal fatto che il comando venga eseguito da un progetto azd:

Il nome dell'agente distribuito deve corrispondere a un agente ospitato nel progetto Foundry di destinazione.

Ottimizzare un agente esistente senza file di progetto AZD

È possibile ottimizzare un agente ospitato esistente senza eseguire azd ai agent init e senza creare azure.yaml o una .azure directory di ambiente. In questo flusso autonomo specificare in modo esplicito l'endpoint del progetto Foundry e il nome dell'agente distribuito.

1. Assicurarsi che l'agente distribuito sia pronto per l'ottimizzazione. In una directory di lavoro locale creare il file di istruzioni, il set di dati, gli analizzatori e eval.yaml descritto in Configurare l'esecuzione dell'ottimizzazione.

   Eseguire questo comando dalla directory di lavoro. Senza un progetto azd, i percorsi relativi in eval.yaml vengono risolti a partire dalla directory di lavoro corrente.

   Per questo flusso autonomo, omettere agent.config. La CLI richiede l'istruzione di riferimento quando esegui il comando:

   # eval.yaml
   agent:
     name: my-support-agent
     kind: hosted
     model: gpt-4.1-mini
   dataset:
     local_uri: ./eval.jsonl
   evaluators:
     - builtin.task_adherence
   options:
     eval_model: gpt-4.1-mini
     optimization_model: gpt-5.1
     max_candidates: 2
   

2. Autenticare:

   az login
   azd auth login
   

3. Copia l'endpoint del progetto dalla pagina Panoramica del progetto di Foundry. Usare l'URL dell'endpoint del progetto, non l'ID risorsa Azure.

4. Salvare l'endpoint nella configurazione azd a livello di utente in modo che i comandi successivi possano risolvere lo stesso progetto da qualsiasi directory:

   azd ai project set "<project-endpoint>"
   azd ai project show
   

   Questo passaggio scrive l'endpoint predefinito in ~/.azd/config.json. Per l'ordine di risoluzione completa e i comandi per controllare o cancellare il contesto salvato, vedere Impostare il contesto del progetto Foundry per i comandi azd.

5. Eseguire l'ottimizzazione con il nome dell'agente distribuito:

   azd ai agent optimize --agent "<deployed-agent-name>" --config eval.yaml
   

   Quando vengono richieste le istruzioni per l'agente, fornirle direttamente nel testo oppure selezionare un file come .agent_configs/baseline/instructions.md.

   Annotazioni

   Nell'anteprima attuale, un'esecuzione standalone non espande agent.config da eval.yaml. Eseguire il comando in modo interattivo in modo da poter fornire l'istruzione di base. Non usare --no-prompt per questo flusso. Anche il caricamento di linee di base di competenze e strumenti basati su file richiede un progetto azd.

   Per un comando una tantum che non deve modificare la configurazione a livello utente, passare --project-endpoint:

   azd ai agent optimize \
     --project-endpoint "<project-endpoint>" \
     --agent "<deployed-agent-name>" \
     --config eval.yaml
   

   È anche possibile impostare l'endpoint per la shell corrente:

   export FOUNDRY_PROJECT_ENDPOINT="<project-endpoint>"
   azd ai agent optimize --agent "<deployed-agent-name>" --config eval.yaml
   

6. Salva l'ID dell'operazione dall'output del comando. Poiché questo flusso non ha alcun ambiente azd, la CLI non salva localmente l’ID dell’ultima operazione. Passare l'ID dell'operazione ai comandi successivi:

   azd ai agent optimize status <operation-id> --watch
   
   azd ai agent optimize list
   
   azd ai agent optimize cancel <operation-id>
   

   Questi comandi usano l'endpoint salvato da azd ai project set. Se invece hai usato la forma una tantum --project-endpoint, passa di nuovo il flag a ogni comando successivo.

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 di CLI.

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.

Se hai avviato il processo senza file di progetto AZD, passa sempre l'ID dell'operazione a status e cancel. I comandi usano l'endpoint a livello di utente salvato da azd ai project set; in caso contrario, includere --project-endpoint.

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