Guida introduttiva: Ottimizzare un agente ospitato (anteprima)

In questa guida rapida installerai l'estensione CLI per l'ottimizzazione, distribuirai un agente ospitato, eseguirai l'ottimizzatore dell'agente e distribuirai il candidato vincitore.

Prerequisiti

Il tuo abbonamento Azure deve figurare nell'elenco delle autorizzazioni per l'ottimizzatore dell'agente. Contattare il rappresentante Microsoft per richiedere l'accesso.

Installare l'estensione CLI

Installare la versione 0.1.40-preview o successiva dell'estensione azure.ai.agents per la CLI di azd:

azd ext install azure.ai.agents

Verificare la versione dell'estensione installata:

azd ext list

Se la versione installata è precedente alla versione 0.1.40-preview, aggiornare l'estensione:

azd ext upgrade azure.ai.agents

Verificare che il comando optimizer sia disponibile:

azd ai agent optimize --help

Creare il progetto

Inizializzare un nuovo progetto dall'esempio di Agent Optimizer. Creare una cartella, quindi usare azd ai agent init con il manifesto di esempio:

mkdir my-agent && cd my-agent
azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/bring-your-own/responses/optimization-customer-support/agent.manifest.yaml .

Il flusso interattivo chiede la tua sottoscrizione di Azure, l'area geografica e le impostazioni di distribuzione del modello. Scarica il campione e genera i file agent.yaml, .agent_configs/baseline/, il set di dati di valutazione e i file "infrastructure-as-code" necessari per il provisioning.

azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/bring-your-own/responses/optimization-customer-support/agent.manifest.yaml -p "/subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.CognitiveServices/accounts/<account>/projects/<project> ."

Authenticate

az login
azd auth login

Se si hanno più sottoscrizioni, selezionare quella desiderata:

az account set --subscription "<subscription-name-or-id>"

Configurare e provisionare

Scegliere una delle opzioni seguenti in base alla necessità di creare nuove risorse Azure o di avere già un progetto Foundry esistente.

Opzione A: Creare nuove risorse

Effettuare il provisioning delle risorse di Azure. Questo passaggio richiede circa due minuti:

azd provision

Questo passaggio crea:

• Un account e un progetto Foundry
• Un registro contenitori di Azure
• Implementazioni dei modelli (gpt-4.1-mini per la valutazione, gpt-5.4 per l'ottimizzazione)

Opzione B: Usare un progetto Foundry esistente

Se è già disponibile un progetto Foundry con modelli distribuiti, usare agent init per configurare l'ambiente:

azd ai agent init --project-id "/subscriptions/<sub-id>/resourceGroups/<rg>/providers/Microsoft.CognitiveServices/accounts/<account>/projects/<project>"

Imposta il nome della distribuzione del modello:

azd env set AZURE_AI_MODEL_DEPLOYMENT_NAME "gpt-4.1-mini"

Distribuire l'agente

azd deploy

Questo comando compila l'immagine del contenitore, lo inserisce in Registro Azure Container e registra l'agente ospitato. Il processo richiede circa 1,5 minuti. Il risultato include un link al portale di chat che puoi utilizzare per chattare con l'operatore.

Verificare la distribuzione:

azd ai agent invoke "What is 2+2?"

Generare set di dati e valutazioni personalizzati

Per un'ottimizzazione significativa con scenari personalizzati, generare un set di dati con eval generate. Se si dispone già di una configurazione di base in .agent_configs/baseline/, eseguire:

azd ai agent eval generate

Se non si dispone di una configurazione di base, includere --gen-instruction in modo che l'interfaccia della riga di comando possa generare un set di dati per il dominio dell'agente:

azd ai agent eval generate --gen-instruction "You are a helpful customer support agent."

Il comando crea un eval.yaml oggetto con un set di dati e analizzatori ottimizzati per il dominio dell'agente.

Per informazioni dettagliate, vedere Creare un set di dati di valutazione.

Esegui l'ottimizzazione

Eseguire quindi l'ottimizzazione con la configurazione generata:

azd ai agent optimize

La CLI usa l'ambiente corrente azd e il campo name nel file agent.yaml locale per determinare quale agente distribuito ottimizzare. Rileva e usa automaticamente anche il file generato eval.yaml per eseguire l'ottimizzazione. Se si dispone di più agenti o configurazioni o si vuole specificarne uno diverso, usare i --agent flag e --config :

azd ai agent optimize --agent <your-agent-name> --config <your-config-file>.yaml

Per maggiori dettagli sulla selezione dell'agente, consulta Quale agente viene ottimizzato. Per le fasi dell'optimizer e i requisiti del modello, consulta Panoramica dell'Agent Optimizer.

Questo processo richiede alcuni minuti. Viene visualizzato lo stato di avanzamento in tempo reale:

Optimizing agent "customer-support-py"...
  Config: C:\Dev\my-agent\eval.yaml
  Baseline saved to .agent_configs\baseline\metadata.yaml
  Job ID: opt_162bd0f09....
  Status: pending
  Portal: <OPTIMIZATION-JOB-URL>

Usa l'URL fornito nella CLI per visualizzare e monitorare la tua attività nel portale Foundry.

Il modello di valutazione assegna punteggi a ogni risposta (qualsiasi modello di completamento della chat funziona). Il modello di ottimizzazione genera candidati migliorati e deve appartenere all'elenco supportato (famiglia gpt-5 o DeepSeek).

Implementa la variante vincente

Indica ★ il candidato migliore. 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, per i test rapidi è possibile distribuire direttamente:

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

La azure-ai-agentserver-optimization funzione del load_config() pacchetto preleva automaticamente la nuova configurazione all'avvio.

Richiamare di nuovo l'agente per verificare il miglioramento:

azd ai agent invoke "What is your return policy?"

È anche possibile eseguire la valutazione separatamente per confermare il miglioramento del punteggio:

azd ai agent eval run

Monitorare e gestire

Usare l'ID del processo, formattato come opt_<hex> e riportato nell'output di ottimizzazione, per tenere traccia e gestire le esecuzioni:

# Watch a running job
azd ai agent optimize status <job-id> --watch

# List all optimization runs
azd ai agent optimize list

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

Pulire le risorse

Una volta terminata la sperimentazione, elimina le risorse create:

azd down --force --purge

Risoluzione dei problemi

Contenuti correlati

• Panoramica di Agent Optimizer
• Creare una suite di valutazione
• Esegui valutazioni degli agenti con l'interfaccia della riga di comando (CLI) di azd
• Ottimizzare le istruzioni, le competenze, gli strumenti e i modelli dell'agente
• Prepara il tuo agente per l'ottimizzazione