Guida introduttiva: Ottimizzare un agente ospitato

• 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.5.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.

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

• .NET 10 SDK o versione successiva.

• Pacchetti .NET usati in questo percorso.

  dotnet add package Azure.AI.Projects --prerelease
  dotnet add package Azure.Identity
  

• 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 for 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 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:

"""
DESCRIPTION:
    Create an optimization job for a hosted agent using the latest agent
    optimization API, poll the job to completion, and list its candidates.

USAGE:
    python optimize_hosted_agent_v3.py

    Before running the sample:

    pip install azure-ai-projects azure-ai-agentserver-optimization azure-identity python-dotenv

    Set these environment variables with your own values:
    1) FOUNDRY_PROJECT_ENDPOINT - Required. The Microsoft Foundry project endpoint.
    2) FOUNDRY_AGENT_NAME       - Required. The hosted agent name.
    3) DATASET_NAME             - Required. The registered training dataset name.
    4) EVALUATOR_NAME           - Required. The registered evaluator name.
    5) DATASET_VERSION          - Optional. The dataset version. Defaults to "1".
    6) EVAL_MODEL               - Optional. The evaluation model. Defaults to "gpt-4o".
    7) OPTIMIZATION_MODEL       - Optional. The optimization model. Defaults to "gpt-5".
    8) POLL_INTERVAL_SECONDS    - Optional. Seconds between status polls. Defaults to 10.
    9) OPTIMIZATION_JOB_ID      - Optional. An existing job ID to resume instead of creating a job.
   10) OPTIMIZATION_LOCAL_DIR   - Optional. Path to the local .agent_configs directory.
   11) CREDENTIAL_PROCESS_TIMEOUT_SECONDS
                                - Optional. Credential subprocess timeout. Defaults to 60.
"""

import os
import time
from pathlib import Path

from azure.ai.agentserver.optimization import load_config, load_skills_from_dir
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
    AgentOptimizationBaselineAgentConfiguration,
    AgentOptimizationCandidateExpand,
    AgentOptimizationCandidateSearchConfiguration,
    AgentOptimizationConfiguration,
    AgentOptimizationEvaluationConfiguration,
    AgentOptimizationEvaluator,
    AgentOptimizationFoundryAgentTargetConfiguration,
    AgentOptimizationJob,
    AgentOptimizationModelConfiguration,
    AgentOptimizationSkill,
    AgentOptimizationSpace,
    AgentOptimizationTargetCompletionDatasetReferenceDataSource,
    AgentOptimizationTargetCompletionEvaluationSet,
    EvaluationModelConfiguration,
    JobStatus,
    TargetAttribute,
)
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"))
existing_job_id = os.environ.get("OPTIMIZATION_JOB_ID")
credential_process_timeout_seconds = int(
    os.environ.get("CREDENTIAL_PROCESS_TIMEOUT_SECONDS", "60")
)

# Reads the hosted agent's baseline config from .agent_configs/baseline/metadata.yaml.
optimization_config = load_config()

target_attributes = [TargetAttribute.INSTRUCTIONS]
baseline_configuration = None
if optimization_config:
    loaded_skills = optimization_config.skills
    if not loaded_skills and optimization_config.skills_dir:
        loaded_skills = load_skills_from_dir(Path(optimization_config.skills_dir))

    skills = [
        AgentOptimizationSkill(
            name=skill.name,
            description=skill.description,
            body=skill.body or None,
        )
        for skill in loaded_skills
    ]

    if skills:
        target_attributes.append(TargetAttribute.SKILLS)
    if optimization_config.tool_definitions:
        target_attributes.append(TargetAttribute.TOOLS)

    baseline_configuration = AgentOptimizationBaselineAgentConfiguration(
        system_prompt=optimization_config.instructions,
        current_model=optimization_config.model,
        skills=skills or None,
        tools=optimization_config.tool_definitions or None,
    )

with (
    DefaultAzureCredential(
        process_timeout=credential_process_timeout_seconds
    ) as credential,
    AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
):
    job_request = AgentOptimizationJob(
        target_configuration=AgentOptimizationFoundryAgentTargetConfiguration(
            name=agent_name
        ),
        optimization_model_configuration=AgentOptimizationModelConfiguration(
            model=optimization_model
        ),
        optimization_configuration=AgentOptimizationConfiguration(
            evaluation_configuration=AgentOptimizationEvaluationConfiguration(
                training_set=AgentOptimizationTargetCompletionEvaluationSet(
                    source=AgentOptimizationTargetCompletionDatasetReferenceDataSource(
                        name=dataset_name,
                        version=dataset_version,
                    )
                ),
                evaluators=[AgentOptimizationEvaluator(name=evaluator_name)],
                evaluation_model=EvaluationModelConfiguration(model=eval_model),
            ),
            candidate_search_configuration=AgentOptimizationCandidateSearchConfiguration(
                max_candidates=2
            ),
            baseline_agent_configuration=baseline_configuration,
            agent_optimization_space=AgentOptimizationSpace(
                target_attributes=target_attributes
            ),
        ),
    )

    if existing_job_id:
        job_id = existing_job_id
    else:
        poller = project_client.agents.begin_create_optimization_job(
            job=job_request,
            polling=False,
        )
        job_id = poller.details.get("job_id")
        if not isinstance(job_id, str):
            raise RuntimeError(
                "The create operation did not return an optimization job ID."
            )

    print(f"Optimization job ID: {job_id}")

    terminal_statuses = {
        JobStatus.SUCCEEDED,
        JobStatus.FAILED,
        JobStatus.CANCELLED,
    }
    job = project_client.agents.get_optimization_job(job_id=job_id)
    print("Optimization job started, waiting for completion...")
    while job.status not in terminal_statuses:
        print(f"\tstatus=`{job.status}`")
        time.sleep(poll_interval_seconds)
        job = project_client.agents.get_optimization_job(job_id=job_id)
    print(f"\tstatus=`{job.status}`")

    for warning in job.warnings or []:
        print(f"[WARNING] {warning}")

    if job.status == JobStatus.FAILED:
        message = job.error.message if job.error else "<no error message>"
        raise RuntimeError(f"Optimization job `{job.id}` failed: {message}")
    if job.status == JobStatus.CANCELLED:
        raise RuntimeError(f"Optimization job `{job.id}` was cancelled.")
    if job.result is None:
        raise RuntimeError(f"Optimization job `{job.id}` completed without a result.")

    result = job.result
    summary = result.candidate_summary
    if summary:
        print(f"Baseline candidate: {summary.baseline_id}")
        print(f"Best candidate: {summary.best_id}")
        print(f"Completed optimized candidates: {summary.completed_candidate_count}")
        if summary.baseline_score is not None:
            print(f"Baseline score: {summary.baseline_score:.4f}")
        if summary.best_score is not None:
            print(f"Best score: {summary.best_score:.4f}")
    if result.termination_reason:
        print(f"Termination reason: {result.termination_reason}")

    for candidate in project_client.agents.list_optimization_candidates(
        job_id=job_id,
        expand=[AgentOptimizationCandidateExpand.MUTATIONS],
    ):
        details = [
            f"{candidate.name}: candidate_id={candidate.candidate_id}",
            f"status={candidate.status}",
        ]
        if candidate.evaluation:
            if candidate.evaluation.score is not None:
                details.append(f"score={candidate.evaluation.score:.4f}")
            if candidate.evaluation.avg_tokens is not None:
                details.append(f"avg_tokens={candidate.evaluation.avg_tokens:.0f}")
        print(", ".join(details))

Eseguire lo script:

python optimize_hosted_agent.py

L'ID del processo di ottimizzazione viene visualizzato immediatamente dopo l'invio; utilizzarlo per monitorare lo stato di avanzamento nel portale Foundry.

Quando il processo ha esito positivo, lo script stampa il candidato vincente 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 si sta lavorando anche dal progetto locale azd usato nel flusso CLI sopra descritto, applicare 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.

Percorso SDK C#

Usare la procedura seguente se si vuole eseguire l'utilità di ottimizzazione da .NET anziché usare il 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.
• Un valutatore registrato, ad esempio il valutatore integrato builtin.task_adherence.

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

1. Impostare le variabili di ambiente

Creare un'app console e quindi impostare questi valori nella shell prima di eseguirlo:

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

Usa l'endpoint esatto del progetto dalla pagina Panoramica del progetto Foundry.

Impostare EVAL_MODEL e OPTIMIZATION_MODEL su nomi di distribuzione già esistenti nel progetto Foundry, non solo nomi di famiglia di modelli. Il modello di ottimizzazione deve essere un modello di ragionamento supportato da Optimizer. Se si seleziona una distribuzione non supportata, il servizio restituisce un errore che elenca i modelli consentiti.

2. Eseguire il processo di ottimizzazione

Sostituire Program.cs con il seguente codice.

L'ottimizzazione dell'agente richiede l'intestazione della funzionalità AgentsOptimization=V2Preview in ogni richiesta. La FoundryFeaturesPolicy classe in questo esempio aggiunge tale intestazione a ogni richiesta inviata dal client:

using System.ClientModel.Primitives;
using Azure.AI.Projects;
using Azure.AI.Projects.Agents;
using Azure.Identity;

#pragma warning disable AAIP001

// Adds the feature header that agent optimization requires.
public sealed class FoundryFeaturesPolicy(string features) : PipelinePolicy
{
    public override void Process(PipelineMessage message, IReadOnlyList<PipelinePolicy> pipeline, int index)
    {
        message.Request.Headers.Set("Foundry-Features", features);
        ProcessNext(message, pipeline, index);
    }

    public override ValueTask ProcessAsync(PipelineMessage message, IReadOnlyList<PipelinePolicy> pipeline, int index)
    {
        message.Request.Headers.Set("Foundry-Features", features);
        return ProcessNextAsync(message, pipeline, index);
    }
}

public static class Program
{
    public static void Main()
    {
        var endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")!;
        var agentName = Environment.GetEnvironmentVariable("FOUNDRY_AGENT_NAME")!;
        var datasetName = Environment.GetEnvironmentVariable("DATASET_NAME")!;
        var datasetVersion = Environment.GetEnvironmentVariable("DATASET_VERSION") ?? "1";
        var evaluatorName = Environment.GetEnvironmentVariable("EVALUATOR_NAME") ?? "builtin.task_adherence";
        var evalModel = Environment.GetEnvironmentVariable("EVAL_MODEL")!;
        var optimizationModel = Environment.GetEnvironmentVariable("OPTIMIZATION_MODEL")!;

        var options = new AIProjectClientOptions();
        options.AddPolicy(new FoundryFeaturesPolicy("AgentsOptimization=V2Preview"), PipelinePosition.PerCall);

        AIProjectClient projectClient = new(new Uri(endpoint), new DefaultAzureCredential(), options);
        AgentOptimizationJobs optimizationJobs = projectClient.AgentAdministrationClient.GetAgentOptimizationJobs();

        OptimizationJob job = new()
        {
            Inputs = new OptimizationJobInputs(
                new OptimizationAgentIdentifier(agentName),
                new OptimizationReferenceDatasetInput(datasetName) { Version = datasetVersion },
                new[] { new OptimizationEvaluatorRef(evaluatorName) })
            {
                Options = new OptimizationOptions
                {
                    MaxCandidates = 2,
                    EvalModel = evalModel,
                    OptimizationModel = optimizationModel,
                    // The optimizer needs at least one optimizable target, such as the
                    // baseline system prompt, the tool definitions, or skills.
                    OptimizationConfig =
                    {
                        ["system_prompt"] = BinaryData.FromObjectAsJson(
                            "You are a helpful assistant that answers user requests accurately and concisely."),
                    },
                },
            },
        };

        OptimizationJob created = optimizationJobs.Create(job);
        Console.WriteLine($"Optimization job started: {created.Id}");

        OptimizationJob current = created;
        while (current.Status != AgentsJobStatus.Succeeded
            && current.Status != AgentsJobStatus.Failed
            && current.Status != AgentsJobStatus.Cancelled)
        {
            Thread.Sleep(TimeSpan.FromSeconds(20));
            current = optimizationJobs.Get(created.Id);
            Console.WriteLine($"\tstatus=`{current.Status}`");
        }

        Console.WriteLine($"Final status: {current.Status}");

        if (current.Result is not null)
        {
            Console.WriteLine($"Baseline candidate: {current.Result.Baseline}");
            Console.WriteLine($"Best candidate: {current.Result.Best}");

            foreach (OptimizationCandidate candidate in current.Result.Candidates)
            {
                Console.WriteLine(
                    $"{candidate.Name}: candidate_id={candidate.CandidateId}, " +
                    $"avg_score={candidate.AvgScore:F4}, " +
                    $"avg_tokens={candidate.AvgTokens:F0}");
            }
        }
    }
}

Eseguire l'app:

dotnet run

Quando il processo ha esito positivo, l'app stampa il candidato vincente e il relativo candidate_id:

Optimization job started: opt_<job-id>
        status=`in_progress`
        status=`succeeded`
Final status: succeeded
Baseline candidate: cand_opt_<job-id>_0000
Best candidate: cand_opt_<job-id>_0000
baseline: candidate_id=cand_opt_<job-id>_0000, avg_score=1.0000, avg_tokens=0

A differenza di azd ai agent optimize, il flusso .NET SDK non crea un file locale.agent_configs/baseline/metadata.yaml. I metadati del processo di ottimizzazione restano nell'oggetto processo restituito e nella risposta del servizio Foundry, tra cui il candidato di riferimento, il candidato migliore e l'elenco dei candidati valutati.

3. Applica il candidato vincente

Se si sta lavorando anche dal progetto locale azd usato nel flusso CLI, applicare il candidato vincente utilizzando il candidate_id restituito dall'app:

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

Se devi solo esaminare il risultato, usa i punteggi dei candidati e gli identificatori di valutazione stampati dall'app per esaminare 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 .

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 competenza ricava il contesto dell'agente da azure.yaml, carica il relativo flusso di lavoro di ottimizzazione dell'agente 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. Esegue la distribuzione solo dopo l'approvazione, quindi richiama e valuta l'agente ospitato aggiornato.