Guida introduttiva: Ottimizzare un agente ospitato (anteprima)

In questo argomento di avvio rapido, si distribuisce l'agente di esempio per l'ottimizzazione, si esegue l'ottimizzatore dell'agente per migliorarne le istruzioni e si distribuisce il candidato vincente.

Prerequisiti

Prima di iniziare, è necessario disporre di quanto segue:

• Sottoscrizione Azure-Crearne una gratuitamente.

• azd CLI (Azure Developer CLI).

• interfaccia della riga di comando di Azure per l'autenticazione.

• L'estensione microsoft.foundry per azd (0.1.40-preview o versione successiva della azure.ai.agents dipendenza):

  azd ext install microsoft.foundry
  

  Se è già installato, aggiornare:

  azd ext upgrade microsoft.foundry
  

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

Passaggio 1: Creare il progetto

Inizializzare un nuovo progetto dal modello di esempio di ottimizzazione:

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. Genera agent.yaml, .agent_configs/baseline/, il set di dati per la valutazione e i file di infrastruttura.

Passaggio 2: Eseguire il provisioning e distribuire

Eseguire l'autenticazione e il provisioning delle risorse Azure:

az login
azd auth login
azd provision

Il provisioning richiede circa due minuti e crea un account Foundry, un progetto, Registro Azure Container e distribuzioni di modelli.

Distribuire l'agente:

azd deploy

Verificare la distribuzione:

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

Passaggio 3: Generare una suite di valutazione e ottimizzare

Genera un dataset di valutazione e i valutatori per il tuo agente:

azd ai agent eval generate

Questo passaggio crea eval.yaml, un set di dati di test e valutatori di punteggio in base alle istruzioni dell'agente. L'utilità di ottimizzazione usa questi file per misurare il miglioramento.

Eseguire l'utilità di ottimizzazione:

azd ai agent optimize --max-candidates 2

L'interfaccia della riga di comando richiede di selezionare un modello di ottimizzazione. Per ignorare il prompt, passarlo direttamente:

azd ai agent optimize --max-candidates 2 --optimize-model gpt-5

L'interfaccia della riga di comando rileva l'agente in agent.yaml e usa automaticamente il eval.yaml generato. Con due candidati, l'ottimizzazione viene in genere completata in circa 8 minuti. Viene visualizzato lo stato di avanzamento in tempo reale:

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

Usare l'URL del portale per monitorare il processo nel portale Foundry.

Il modello di valutazione assegna punteggi a ogni risposta (qualsiasi modello di completamento della chat funziona). Il modello di ottimizzazione (--optimize-model) genera candidati migliorati e deve appartenere all'elenco supportato (famiglia gpt-5 o DeepSeek). Puoi anche impostare optimization_model sotto options: in eval.yaml per evitare di passare il flag ogni volta.

Passaggio 4: Distribuire il vincitore

Il simbolo ★ nell'output indica il candidato migliore. Applicare la configurazione ottimizzata in locale, quindi distribuire:

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

Il comando apply scarica la configurazione ottimizzata in .agent_configs/<candidate_id>/ e aggiorna agent.yaml per utilizzare le nuove istruzioni. Il comando deploy esegue il push dell'agente ottimizzato in tempo reale usando la distribuzione del codice.

Richiamare l'agente per verificare il miglioramento:

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

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

azd ai agent eval run

Pulire le risorse

Una volta terminata la sperimentazione, elimina le risorse create:

azd down --force --purge

Risoluzione dei problemi

Cosa si è appreso

Questo avvio rapido spiega come:

• Distribuito l'agente di esempio per l'ottimizzazione utilizzando il modello di assistenza clienti.
• È stato eseguita l'ottimizzatore dell'agente per migliorare automaticamente le istruzioni dell'agente.
• Ha distribuito il candidato vincente e verificato il miglioramento.

Passaggi successivi

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