Guida introduttiva: Ottimizzare un agente ospitato (anteprima)

• azd CLI (CLI per sviluppatori di Azure).

• 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
  

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

• Python 3.10 o versione successiva.

• I pacchetti Python usati in questo percorso:

  pip install "azure-ai-projects>=2.4.0" azure-ai-agentserver-optimization azure-identity python-dotenv
  

• Progetto Foundry esistente che contiene già l'agente ospitato, il set di dati registrato e l'analizzatore da usare per l'ottimizzazione.

• Codice di Visual Studio.

• Microsoft Foundry Toolkit per Visual Studio Code versione 1.6.4 o successiva, con accesso ad Azure effettuato. Foundry Toolkit installa e aggiorna la Microsoft Foundry Skill utilizzata da questo flusso di lavoro.

• GitHub Copilot in Visual Studio Code con accesso alla modalità agente. Foundry Toolkit invia la richiesta di Agent Optimizer a GitHub Copilot dopo aver selezionato l'area di lavoro dell'agente.

• interfaccia della riga di comando di Azure e Azure Developer CLI (AZD) installati ed autenticati:

  az login
  azd auth login
  

• Host per agente di codifica con lo Skill Microsoft Foundry installato.

• interfaccia della riga di comando di Azure e Azure Developer CLI (AZD) installati ed autenticati:

  az login
  azd auth login
  

• L'estensione microsoft.foundry per AZD. Installarlo prima di avviare il flusso di lavoro:

  azd ext install microsoft.foundry
  

  Se è già installato, aggiornarlo:

  azd ext upgrade microsoft.foundry
  

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/azure.yaml .

Questo modello importa l'esempio di assistenza clienti Optimization, un agente Python ospitato predisposto per l'ottimizzazione che usa l'approccio Bring Your Own e il protocollo Responses. Rappresenta un agente di assistenza per l'elettronica di consumo che gestisce le richieste relative agli ordini, i resi, le richieste di garanzia, la risoluzione di problemi tecnici, i reclami, le raccomandazioni e le escalation. L'istruzione di base deliberatamente minima semplifica il confronto tra i miglioramenti apportati all'ottimizzazione delle istruzioni e all'individuazione delle competenze.

L'esempio invoca load_config() per caricare la configurazione di base o candidata e include .agent_configs/baseline/, eval.yaml, set di dati di valutazione completi e rapidi, la configurazione del contenitore e il manifest di distribuzione di Foundry. Il flusso interattivo importa questi file e richiede di specificare la sottoscrizione di Azure, l'area e le impostazioni di distribuzione del modello.

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 azure.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

La stella (*) 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 azure.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

Percorso dell'SDK di Python

Usare la procedura seguente se si vuole eseguire l'utilità di ottimizzazione da Python anziché dal flusso di lavoro dell'interfaccia della riga di comando per sviluppatori Azure descritto in precedenza.

Questo percorso presuppone che le risorse seguenti siano già disponibili in un progetto Foundry esistente:

• Un agente ospitato da ottimizzare.
• Un dataset di addestramento registrato.
• Analizzatore registrato.

A differenza del flusso di Azure Developer CLI descritto in precedenza, il percorso dell'SDK Python non crea la struttura di un progetto né genera eval.yaml, un set di dati o valutatori per te. Se si vuole che l'esempio crei automaticamente tali asset, usare azd ai agent eval generate prima di tutto.

1. Creare un .env file

Creare una cartella di lavoro e quindi aggiungere un .env file con questi valori:

FOUNDRY_PROJECT_ENDPOINT=<your-project-endpoint>
FOUNDRY_AGENT_NAME=<your-hosted-agent-name>
DATASET_NAME=<your-registered-dataset-name>
EVALUATOR_NAME=<your-registered-evaluator-name>
DATASET_VERSION=1
POLL_INTERVAL_SECONDS=10
EVAL_MODEL=<your-eval-model-deployment-name>
OPTIMIZATION_MODEL=<your-optimization-model-deployment-name>

Eseguire lo script da questa stessa cartella di lavoro in modo da load_dotenv() poter caricare automaticamente il .env file. Se si preferisce eseguirlo da un'altra directory, impostare prima gli stessi valori nell'ambiente della shell.

Usa l'endpoint esatto del progetto dalla pagina Panoramica del tuo progetto Foundry. Lo script Python invia immediatamente la prima richiesta. Se FOUNDRY_PROJECT_ENDPOINT è solo un segnaposto o punta al progetto errato, l'esecuzione ha esito negativo con ResourceNotFound: The project does not exist.

Impostare EVAL_MODEL e OPTIMIZATION_MODEL su nomi di distribuzione già esistenti nel progetto Foundry, non solo nomi di famiglia di modelli. Ad esempio, se la distribuzione del progetto è denominata gpt-4.1-mini o DeepSeek-V3.2, usare il nome esatto della distribuzione in .env.

2. Eseguire il processo di ottimizzazione

Creare un file denominato optimize_hosted_agent.py nella stessa cartella di .env:

import os
import time

from azure.ai.agentserver.optimization import load_config
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
  OptimizationAgentIdentifier,
  OptimizationEvaluatorRef,
  OptimizationJob,
  OptimizationJobInputs,
  OptimizationOptions,
  OptimizationReferenceDatasetInput,
)
from azure.identity import DefaultAzureCredential
from dotenv import load_dotenv

load_dotenv()

endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
agent_name = os.environ["FOUNDRY_AGENT_NAME"]
dataset_name = os.environ["DATASET_NAME"]
evaluator_name = os.environ["EVALUATOR_NAME"]
dataset_version = os.environ.get("DATASET_VERSION", "1")
eval_model = os.environ.get("EVAL_MODEL", "gpt-4o")
optimization_model = os.environ.get("OPTIMIZATION_MODEL", "gpt-5")
poll_interval_seconds = int(os.environ.get("POLL_INTERVAL_SECONDS", "10"))

optimization_config = load_config() # Reads agent optimization config from .agent_configs/baseline/metadata.yaml

with (
  DefaultAzureCredential() as credential,
  AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
):
  job = OptimizationJob(
    inputs=OptimizationJobInputs(
      agent=OptimizationAgentIdentifier(agent_name=agent_name),
      train_dataset=OptimizationReferenceDatasetInput(
        name=dataset_name,
        version=dataset_version,
      ),
      evaluators=[OptimizationEvaluatorRef(name=evaluator_name)],
      options=OptimizationOptions(
        max_candidates=2,
        eval_model=eval_model,
        optimization_model=optimization_model,
        optimization_config={
          "system_prompt": optimization_config.instructions,
          **({"tools": optimization_config.tool_definitions} if optimization_config.tool_definitions else {}),
          **({"skills": optimization_config.skills} if optimization_config.has_skills else {}),
        }
      ),
    )
  )
  poller = project_client.beta.agents.begin_create_optimization_job(job=job)

  print(f"Optimization job started, waiting for completion...")
  while not poller.done():
    print(f"\tstatus=`{poller.status()}`")
    time.sleep(poll_interval_seconds)

  result = poller.result()

  if result:
    print(f"Baseline candidate: {result.baseline}")
    print(f"Best candidate: {result.best}")

    for candidate in result.candidates or []:
      print(
        f"{candidate.name}: candidate_id={candidate.candidate_id}, "
        f"avg_score={candidate.avg_score:.4f}, "
        f"avg_tokens={candidate.avg_tokens:.0f}"
      )

Eseguire lo script:

python optimize_hosted_agent.py

Quando il processo ha esito positivo, lo script stampa il candidato vincitore e il relativo candidate_id.

A differenza di azd ai agent optimize, il flusso Python SDK non crea un file locale.agent_configs/baseline/metadata.yaml. I metadati del processo di ottimizzazione rimangono nell'oggetto restituito job e nella risposta del servizio Foundry, inclusi il candidato di base, il candidato migliore e l'elenco dei candidati con punteggio.

3. Applica il candidato vincente

Se stai lavorando anche dal progetto locale azd usato nel flusso CLI sopra descritto, applica il candidato vincente usando il candidate_id restituito dallo script Python:

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

Se devi solo controllare il risultato, usa i punteggi delle configurazioni candidate e gli identificatori di valutazione stampati dallo script per rivedere la configurazione vincente in Foundry prima di promuoverla.

Eseguire l'ottimizzazione in VS Code

Foundry Toolkit include un'esperienza di ottimizzazione dell'agente nativa per gli agenti ospitati distribuiti. Dal playground dell'agente è possibile avviare un'esecuzione di ottimizzazione, confrontare i candidati con la linea di base, esaminare le modifiche di configurazione e distribuire il candidato migliore.

Passaggio 1: Selezionare un agente ospitato già distribuito

1. Selezionare Foundry Toolkit nella barra delle attività.
2. In Risorse personali selezionare Agenti.
3. Se hai un agente ospitato già distribuito, selezionalo per aprire l'ambiente di prova dell'agente ospitato.
4. Se non si dispone di un agente ospitato distribuito, completare il percorso di VS Code in Avvio rapido: Distribuire il primo agente ospitato. Al termine della distribuzione, tornare agli agenti e selezionare il nuovo agente ospitato.

Passaggio 2: Avviare un'esecuzione di ottimizzazione

1. Selezionare la scheda Ottimizza , contrassegnata come Anteprima.

1. Selezionare Nuova ottimizzazione.

2. In Seleziona area di lavoro scegliere l'area di lavoro che contiene il codice dell'agente ospitato selezionato:

   • Selezionare Area di lavoro corrente se l'area di lavoro corrente contiene il codice dell'agente e il relativo azure.yaml file.
   • Selezionare Sfoglia... per aprire l'area di lavoro che contiene il codice dell'agente.

   Foundry Toolkit usa i file dell'area di lavoro per preparare l'ottimizzazione e applicare un candidato al servizio corrispondente azure.ai.agent.

1. Foundry Toolkit apre GitHub Copilot Chat e invia una richiesta di Agent Optimizer popolata con il tipo, il nome e l'endpoint del progetto Foundry dell'agente selezionato.

2. Rispondere alle quattro domande di ottimizzazione in Copilot Chat:

   Inserimento	Cosa fornire
   Metriche di valutazione	Immettere le metriche o gli analizzatori da usare. Se non li hai, scegli se eseguire azd ai agent eval generate o usare le impostazioni predefinite integrate dell'optimizer.
   Dataset	Selezionare il set di dati di ottimizzazione. Se non se ne ha uno, scegliere se eseguire azd ai agent eval generate o usare le impostazioni predefinite integrate dell'optimizer.
   Numero massimo di candidati	Immettere il numero massimo di candidati da generare, ad esempio 2.
   Modello di ottimizzazione	Selezionare una distribuzione esistente dai modelli di ottimizzazione supportati.

GitHub Copilot attende questi input prima di avviare l'ottimizzazione. La richiesta generata indica a Copilot di utilizzare esclusivamente il flusso di lavoro Agent Optimizer di Microsoft Foundry Skill e i comandi di Azure Developer CLI. Non usa gli strumenti MCP di Foundry. Copilot:

• Controlla il codice dell'agente nell'area di lavoro selezionata.
• Inizializza un ambiente AZD utilizzando i valori azure.yaml e .env esistenti, se il progetto non ne ha già uno.
• Collega l'agente per l'ottimizzazione e distribuisce l'agente ospitato aggiornato.
• Crea eval.yaml nella cartella del servizio agent.
• Avvia l'ottimizzazione dopo aver esaminato e approvato le modifiche e i comandi del file proposti.

Dopo Copilot invia il processo, tornare alla scheda Ottimizza. L'esecuzione viene visualizzata in Esecuzioni di ottimizzazione. La tabella mostra l'ID di esecuzione, lo stato, il conteggio dei candidati, il punteggio di base, il punteggio migliore e il tempo di creazione.

Passaggio 3: Confrontare e distribuire il candidato migliore

1. Quando l'esecuzione ha esito positivo, selezionarla in Esecuzioni di ottimizzazione.
2. Confrontare i punteggi Baseline e Best . Esaminare i dettagli del punteggio per ogni candidato e selezionare Visualizza modifiche per esaminare le modifiche alla configurazione.
3. Se il candidato migliore migliora nella linea di base, selezionare Distribuisci candidato migliore per aggiornare l'agente corrente. Per distribuirlo come nuovo agente o modificare le impostazioni di distribuzione, selezionare Distribuzione personalizzata .

Esegui l'ottimizzazione con la skill Microsoft Foundry

Usa questo percorso in qualsiasi host per agenti di codifica che supporti la Skill Microsoft Foundry, ad esempio GitHub Copilot in Visual Studio Code, Copilot CLI o Claude Code. La skill ricava il contesto dell'agente da azure.yaml, carica il relativo flusso di lavoro di Agent Optimizer e mantiene l'applicazione candidata e la distribuzione subordinate ai controlli di revisione.

Passaggio 1: Aprire l'area di lavoro dell'agente

Aprire una cartella vuota nell'host dell'agente di codifica. Verifica che l'microsoft-foundry abilità sia disponibile. Se l'abilità non è disponibile, consulta Usare l'abilità Microsoft Foundry negli agenti di codifica.

Passaggio 2: Chiedi alla skill di eseguire Agent Optimizer

Inviare questa richiesta all'agente di codifica:

Use the Microsoft Foundry Skill to run the Agent Optimizer workflow for a
Python hosted agent. If this workspace doesn't contain an agent, initialize the
customer support optimization sample from this template:
https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/bring-your-own/responses/optimization-customer-support/azure.yaml
Resolve the AZD environment and hosted-agent service, verify that the agent is
optimizer-ready, and deploy and invoke the baseline. Generate and show me the
evaluation dataset, evaluators, and eval.yaml before running optimization.
Verify that the project has a supported optimization model deployment, then run
Agent Optimizer with two candidates. Stop after reporting the operation ID,
portal URL, candidate IDs, and scores. Don't apply or deploy a candidate yet.

L'agente di codifica potrebbe chiedere di selezionare una sottoscrizione, un'area, un progetto Foundry, un servizio agente, un modello di valutazione o un modello di ottimizzazione quando non riesce a risolvere tali valori dall'area di lavoro. Esaminare i file generati e le risorse con costi prima di approvare eventuali modifiche o comandi.

Passaggio 3: Applicare e distribuire un candidato approvato

Dopo aver esaminato i risultati dell'ottimizzazione, inviare questo prompt di completamento:

Recommend the best optimization candidate and explain the score improvement.
Summarize the candidate changes before applying anything. After I approve the
candidate, apply it locally, show the source diff, and stop again before
deployment. After I approve deployment, run azd deploy, invoke the agent with
"What is your return policy?", and rerun the evaluation to confirm the
improvement.

La funzionalità utilizza azd ai agent optimize apply --candidate <candidate-id> così da poter esaminare in locale la configurazione ottimizzata. Viene distribuito solo dopo la tua approvazione, quindi richiama e valuta l'agente ospitato aggiornato.