Snabbstart: Optimera en värdbaserad agent (förhandsversion)

• azd CLI (Azure Developer CLI).

• Azure CLI för autentisering.

• Tillägget microsoft.foundry för azd (0.1.40-preview eller senare av beroendet azure.ai.agents ):

  azd ext install microsoft.foundry
  

  Om du redan har installerat uppgraderar du:

  azd ext upgrade microsoft.foundry
  

• Azure CLI för autentisering.

• Python 3.10 eller senare.

• De Python paket som används i den här sökvägen:

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

• Ett befintligt Foundry-projekt som redan innehåller den värdbaserade agenten, den registrerade datauppsättningen och utvärderaren som du vill använda för optimering.

• Visual Studio Code.

• Microsoft Foundry Toolkit för Visual Studio Code version 1.6.4 eller senare, inloggad på Azure. Foundry Toolkit installerar och uppdaterar Microsoft Foundry Skill som används av det här arbetsflödet.

• GitHub Copilot i Visual Studio Code med åtkomst till agentläge. Foundry Toolkit skickar agentoptimerarbegäran till GitHub Copilot när du har valt agentarbetsytan.

• Azure CLI och Azure Developer CLI (AZD) installerat och autentiserat:

  az login
  azd auth login
  

• En värd för en kodningsagent med den Microsoft Foundry Skill installerad.

• Azure CLI och Azure Developer CLI (AZD) installerat och autentiserat:

  az login
  azd auth login
  

• Tillägget microsoft.foundry för AZD. Installera det innan du startar arbetsflödet:

  azd ext install microsoft.foundry
  

  Om den redan är installerad uppgraderar du den:

  azd ext upgrade microsoft.foundry
  

Steg 1: Skapa projektet

Initiera ett nytt projekt från optimeringsexempelmallen:

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 .

Den här mallen importerar exemplet Customer Support för optimering, en optimeringsklar värdbaserad Python-agent som använder metoden bring-your-own och Responses-protokollet. Den representerar en supportagent för konsumentelektronik som hanterar orderförfrågningar, returer, garantianspråk, felsökning, klagomål, rekommendationer och eskalering. Den avsiktligt minimala baslinjeinstruktionen gör förbättringarna från instruktionsoptimering och kunskapsidentifiering lätta att jämföra.

Exemplet anropar load_config() för att läsa in baslinjen eller kandidatkonfigurationen och innehåller .agent_configs/baseline/, eval.yamlfullständiga och snabba utvärderingsdatauppsättningar, containerkonfiguration och Foundry-distributionsmanifestet. Det interaktiva flödet importerar dessa filer och frågar efter distributionsinställningarna för din Azure prenumeration, region och modell.

Steg 2: Etablera och distribuera

Autentisera och etablera Azure resurser:

az login
azd auth login
azd provision

Provisioneringen tar ungefär två minuter och skapar ett Foundry-konto, ett projekt, Azure Container Registry och modelldriftsättningar.

Distribuera agenten:

azd deploy

Testa driftsättningen:

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

Steg 3: Generera utvärderingssvit och optimera

Generera en utvärderingsdatauppsättning och utvärderare för din agent:

azd ai agent eval generate

Det här steget skapar eval.yaml, en testdatauppsättning och bedömningsutvärderingar baserat på agentens instruktioner. Optimeraren använder dessa filer för att mäta förbättringar.

Kör optimeraren:

azd ai agent optimize --max-candidates 2

CLI uppmanar dig att välja en optimeringsmodell. Om du vill hoppa över prompten skickar du den direkt:

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

CLI identifierar din agent från azure.yaml och använder den genererade eval.yaml automatiskt. Med två kandidater slutförs optimeringen vanligtvis på cirka 8 minuter. Realtidsförloppet visas:

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>

Använd portalens URL för att övervaka ditt jobb i Foundry-portalen.

Eval-modellen poängsätter varje svar (valfri modell för chattavslut fungerar). Optimeringsmodellen (--optimize-model) genererar förbättrade kandidater och måste vara från listan som stöds (gpt-5-familjen eller DeepSeek). Du kan också ange optimization_model under options: i eval.yaml för att undvika att skicka flaggan varje gång.

Steg 4: Distribuera vinnaren

Stjärnan (*) i utdata anger den bästa kandidaten. Tillämpa den optimerade konfigurationen lokalt och distribuera sedan:

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

Kommandot apply laddar ned den optimerade konfigurationen till .agent_configs/<candidate_id>/ och uppdaterar din azure.yaml för att använda de nya anvisningarna. Kommandot deploy driftsätter den optimerade agenten via koddistribution.

Anropa din agent för att verifiera förbättringen:

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

Du kan också köra utvärderingen för att bekräfta poängförbättringen:

azd ai agent eval run

sökväg till Python SDK

Använd följande steg om du vill köra optimeraren från Python i stället för cli-arbetsflödet Azure Developer som beskrevs tidigare.

Den här sökvägen förutsätter att du redan har följande resurser i ett befintligt Foundry-projekt:

• En värdbaserad agent som ska optimeras.
• En registrerad träningsdatauppsättning.
• En registrerad utvärderare.

Till skillnad från Azure Developer CLI-flödet som beskrevs tidigare tillhandahåller Python SDK inte ett projekt, eval.yaml, en datauppsättning eller utvärderare åt dig. Om du vill att exemplet ska skapa dessa tillgångar automatiskt använder du azd ai agent eval generate först.

1. Skapa en .env fil

Skapa en arbetsmapp och lägg sedan till en .env fil med följande värden:

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>

Kör skriptet från samma arbetsmapp så att load_dotenv() kan läsa in filen .env automatiskt. Om du föredrar att köra den från en annan katalog anger du samma värden i shell-miljön först.

Använd den exakta projektslutpunkten från foundry-projektets översiktssida . Skriptet Python skickar sin första begäran omedelbart. Om FOUNDRY_PROJECT_ENDPOINT bara är en platshållare eller pekar på fel projekt misslyckas körningen med ResourceNotFound: The project does not exist.

Ange EVAL_MODEL och OPTIMIZATION_MODEL till distributionsnamn som redan finns i ditt Foundry-projekt, inte bara modellfamiljenamn. Om projektdistributionen till exempel heter gpt-4.1-mini eller DeepSeek-V3.2använder du det exakta distributionsnamnet i .env.

2. Kör optimeringsjobbet

Skapa en fil med namnet optimize_hosted_agent.py i samma mapp som .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}"
      )

Kör skriptet:

python optimize_hosted_agent.py

När jobbet lyckas skriver skriptet ut den vinnande kandidaten och sitt candidate_id.

Till skillnad från azd ai agent optimizeskapar inte Python SDK-flödet en lokal .agent_configs/baseline/metadata.yaml fil. Metadata för optimeringsjobbet finns kvar i det returnerade job objektet och i foundry-tjänstens svar, inklusive baslinjekandidat, bästa kandidat och poängsatt kandidatlista.

3. Använd den kandidat som valts

Om du också arbetar från det lokala azd-projektet som används i CLI-flödet ovan, använder du den vinnande kandidaten med hjälp av det candidate_id som Python-skriptet returnerade:

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

Om du bara behöver inspektera resultatet använder du kandidatpoängen och utvärderingsidentifierarna som skrivs ut av skriptet för att granska den vinnande konfigurationen i Foundry innan du marknadsför den.

Kör optimeringen i VS Code

Foundry Toolkit innehåller en intern agentoptimeringsupplevelse för distribuerade värdbaserade agenter. Från agentens testmiljö kan du starta en optimeringskörning, jämföra kandidater med baslinjen, inspektera konfigurationsändringar och driftsätta den bästa kandidaten.

Steg 1: Välj en distribuerad värdbaserad agent

1. Välj Foundry Toolkit i aktivitetsfältet.
2. Under Mina resurser väljer du Agenter.
3. Om du har en distribuerad värdbaserad agent väljer du den för att öppna den värdbaserade agentlekplatsen.
4. Om du inte har någon distribuerad värdbaserad agent slutför du VS Code-sökvägen i Snabbstart: Distribuera din första värdbaserade agent. När distributionen är klar går du tillbaka till Agenter och väljer den nya värdbaserade agenten.

Steg 2: Starta en optimeringskörning

1. Välj fliken Optimera , som är markerad som Förhandsversion.

1. Välj Ny optimering.

2. I Välj arbetsyta väljer du den arbetsyta som innehåller den valda värdbaserade agentens kod:

   • Välj Aktuell arbetsyta om den aktuella arbetsytan innehåller agentkoden och dess azure.yaml fil.
   • Välj Bläddra... för att öppna arbetsytan som innehåller agentkoden.

   Foundry Toolkit använder arbetsytefilerna för att förbereda optimeringen och tillämpa en kandidat på matchande azure.ai.agent tjänst.

1. Foundry Toolkit öppnar GitHub Copilot Chat och skickar en agentoptimerbegäran ifylld med den valda agentens typ, namn och Foundry-projektslutpunkt.

2. Besvara de fyra optimeringsfrågorna i Copilot Chat:

   Input	Vad du ska ange
   Utvärderingsmått	Ange de mått eller utvärderare som ska användas. Om du inte har dem väljer du om du vill köra azd ai agent eval generate eller använda optimerarens inbyggda standardvärden.
   Dataset	Välj datauppsättningen för optimering. Om du inte har någon väljer du om du vill köra azd ai agent eval generate eller använda optimerarens inbyggda standardvärden.
   Maximalt antal kandidater	Ange det maximala antalet kandidater som ska genereras, till exempel 2.
   Optimeringsmodell	Välj en befintlig distribution från de optimeringsmodeller som stöds.

GitHub Copilot väntar på dessa indata innan optimeringen påbörjas. Den genererade begäran uppmanar Copilot att enbart använda agentoptimeringsarbetsflödet för Microsoft Foundry Skill och Azure Developer CLI-kommandon. Den använder inte Foundry MCP-verktyg. Copilot:

• Inspekterar agentkoden på den valda arbetsytan.
• Initierar en AZD-miljö från befintliga värden för azure.yaml och .env om projektet inte redan har någon.
• Konfigurerar agenten för optimering och distribuerar den uppdaterade värdbaserade agenten.
• Skapar eval.yaml i agenttjänstmappen.
• Startar optimeringen när du har granskat och godkänt de föreslagna filändringarna och kommandona.

När Copilot har skickat jobbet går du tillbaka till fliken Optimera. Körningen visas under Optimeringskörningar. Tabellen visar dess körnings-ID, status, antal kandidater, baslinjepoäng, bästa poäng och skapandetid.

Steg 3: Jämför och distribuera den bästa kandidaten

1. När körningen har slutförts väljer du den under Optimeringskörningar.
2. Jämför poängen Baseline och Best. Granska Poänginformation för varje kandidat och välj Visa ändringar för att granska dess konfigurationsändringar.
3. Om den bästa kandidaten förbättras på baslinjen väljer du Distribuera bästa kandidat för att uppdatera den aktuella agenten. Om du vill distribuera den som en ny agent eller ändra distributionsinställningarna väljer du Anpassad distribution i stället.

Kör optimeringen med Microsoft Foundry Skill

Använd den här sökvägen i alla värdprogram för kodningsagenter med stöd för Microsoft Foundry Skill, till exempel GitHub Copilot i Visual Studio Code, Copilot CLI eller Claude Code. Kunskapen löser agentkontexten från azure.yaml, läser in arbetsflödet för agentoptimeraren och behåller kandidatprogram och distribution bakom granskningsgrindar.

Steg 1: Öppna agentarbetsytan

Öppna en tom mapp i kodningsagentens värd. Bekräfta att färdigheten microsoft-foundry är tillgänglig. Om kunskapen inte är tillgänglig följer du Använd Microsoft Foundry Skill i kodningsagenter.

Steg 2: Be kompetensen att köra Agent Optimizer

Skicka den här uppmaningen till kodningsagenten:

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.

Kodagenten kan be dig att välja en prenumeration, region, ett Foundry-projekt, en agenttjänst, en utvärderingsmodell eller en optimeringsmodell när den inte kan fastställa dessa värden utifrån arbetsytan. Granska genererade filer och kostnadsbärande resurser innan du godkänner ändringar eller kommandon.

Steg 3: Tillämpa och distribuera en godkänd kandidat

När du har granskat optimeringsresultatet skickar du följande uppföljningsprompt:

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.

Färdigheten använder azd ai agent optimize apply --candidate <candidate-id> så att du kan granska den optimerade konfigurationen lokalt. Den distribueras först efter ditt godkännande och anropar och utvärderar sedan den uppdaterade värdbaserade agenten.