Quickstart: Een gehoste agent optimaliseren (preview)

• azd CLI (Azure Developer CLI).

• Azure CLI voor verificatie.

• De microsoft.foundry extensie voor azd (0.1.40-preview of hoger van de azure.ai.agents afhankelijkheid):

  azd ext install microsoft.foundry
  

  Als deze al is geïnstalleerd, voert u een upgrade uit:

  azd ext upgrade microsoft.foundry
  

• Azure CLI voor verificatie.

• Python 3.10 of hoger.

• De Python pakketten die in dit pad worden gebruikt:

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

• Een bestaand Foundry-project dat al de gehoste agent, geregistreerde gegevensset en evaluator bevat die u wilt gebruiken voor optimalisatie.

• Visual Studio Code.

• Microsoft Foundry Toolkit voor Visual Studio Code versie 1.6.4 of hoger, aangemeld bij Azure. Foundry Toolkit installeert en werkt de Microsoft Foundry Skill bij die door deze werkstroom wordt gebruikt.

• GitHub Copilot in Visual Studio Code met toegang tot de agentmodus. Foundry Toolkit verzendt de aanvraag Agent Optimizer naar GitHub Copilot nadat u de agentwerkruimte hebt geselecteerd.

• Azure CLI en Azure Developer CLI (AZD) geïnstalleerd en geverifieerd:

  az login
  azd auth login
  

• Een codeeragenthost waarop de Microsoft Foundry Skill is geïnstalleerd.

• Azure CLI en Azure Developer CLI (AZD) geïnstalleerd en geverifieerd:

  az login
  azd auth login
  

• De microsoft.foundry extensie voor AZD. Installeer deze voordat u de werkstroom start:

  azd ext install microsoft.foundry
  

  Als deze al is geïnstalleerd, voert u een upgrade uit:

  azd ext upgrade microsoft.foundry
  

Stap 1: Het project maken

Initialiseer een nieuw project op basis van de voorbeeldsjabloon voor optimalisatie:

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 .

Met deze sjabloon importeert u het Optimization Customer Support sample, een voor optimalisatie geschikte, in Python gehoste agent die gebruikmaakt van de bring-your-own-aanpak en het Responses-protocol. Het vertegenwoordigt een ondersteuningsagent voor consumentenelektronica die ordervragen afhandelt, retourneert, garantieclaims, probleemoplossing, klachten, aanbevelingen en escalatie. De bewust minimale basislijninstructie maakt de verbeteringen van instructieoptimalisatie en vaardigheidsdetectie eenvoudig te vergelijken.

Het voorbeeld roept load_config() aan om de basislijn- of kandidaatconfiguratie te laden en omvat .agent_configs/baseline/, eval.yaml, gegevenssets voor volledige en snelle evaluatie, containerconfiguratie en het Foundry-implementatiemanifest. De interactieve stroom importeert deze bestanden en vraagt om uw Azure-abonnement, regio en modelimplementatie-instellingen.

Stap 2: Inrichten en implementeren

De Azure resources verifiëren en inrichten:

az login
azd auth login
azd provision

Het inrichten duurt ongeveer twee minuten en maakt een Foundry-account, project, Azure Container Registry en modelimplementaties.

Rol de agent uit:

azd deploy

De implementatie testen:

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

Stap 3: Evaluatiepakket genereren en optimaliseren

Genereer een evaluatiedataset en beoordelaars voor uw agent:

azd ai agent eval generate

Met deze stap worden eval.yaml, een testdataset en score-evaluatoren gemaakt op basis van de instructies van uw agent. De optimizer gebruikt deze bestanden om verbetering te meten.

Voer de optimizer uit:

azd ai agent optimize --max-candidates 2

De CLI vraagt u om een optimalisatiemodel te selecteren. Als u de prompt wilt overslaan, geeft u deze rechtstreeks door:

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

De CLI detecteert uw agent op basis van azure.yaml en gebruikt automatisch de gegenereerde eval.yaml. Met twee kandidaten wordt optimalisatie doorgaans in ongeveer 8 minuten voltooid. De voortgang wordt in real-time weergegeven:

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>

Gebruik de portal-URL om uw taak in de Foundry-portal te bewaken.

Het evaluatiemodel beoordeelt elk antwoord (elk chatvoltooiingsmodel werkt). Het optimalisatiemodel (--optimize-model) genereert verbeterde kandidaten en moet afkomstig zijn uit de ondersteunde lijst (gpt-5-familie of DeepSeek). U kunt optimization_model ook instellen onder options: in eval.yaml om te voorkomen dat u de vlag telkens moet meegeven.

Stap 4: Rol de winnaar uit

De ster (*) in de uitvoer geeft de beste kandidaat aan. Pas de geoptimaliseerde configuratie lokaal toe en implementeer vervolgens:

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

Met de opdracht apply downloadt u de geoptimaliseerde configuratie naar .agent_configs/<candidate_id>/ en werkt u uw azure.yaml bij om de nieuwe instructies te gebruiken. Met de opdracht deploy wordt de geoptimaliseerde agent live gezet met CodeDeploy.

Roep uw agent aan om de verbetering te controleren:

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

U kunt ook een evaluatie uitvoeren om de scoreverbetering te bevestigen:

azd ai agent eval run

Python SDK-pad

Gebruik de volgende stappen als u de optimizer wilt uitvoeren vanuit Python in plaats van de Azure Developer CLI-werkstroom die eerder is beschreven.

In dit pad wordt ervan uitgegaan dat u al de volgende resources in een bestaand Foundry-project hebt:

• Een gehoste agent voor optimalisatie
• Een geregistreerde trainingsgegevensset.
• Een geregistreerde evaluator.

In tegenstelling tot de eerder beschreven Azure Developer CLI-workflow wordt er via de Python SDK-route niet automatisch een project opgezet en worden eval.yaml, een gegevensset of evaluatoren niet voor u gegenereerd. Als u wilt dat het voorbeeld deze onderdelen automatisch maakt, gebruikt u eerst azd ai agent eval generate.

1. Een bestand maken .env

Maak een werkmap en voeg vervolgens een .env bestand toe met deze waarden:

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>

Voer het script uit vanuit dezelfde werkmap, zodat load_dotenv() het .env bestand automatisch kan worden geladen. Als u deze liever vanuit een andere map uitvoert, stelt u eerst dezelfde waarden in uw shell-omgeving in.

Gebruik het exacte projecteindpunt op de overzichtspagina van uw Foundry-project. Het Python script verzendt de eerste aanvraag onmiddellijk. Als FOUNDRY_PROJECT_ENDPOINT dit slechts een tijdelijke aanduiding is of verwijst naar het verkeerde project, mislukt de uitvoering met ResourceNotFound: The project does not exist.

Stel EVAL_MODEL en OPTIMIZATION_MODEL in op deploymentnamen die al in je Foundry-project bestaan, en niet alleen op namen van modelfamilies. Als uw projectimplementatie bijvoorbeeld een naam gpt-4.1-mini heeft of DeepSeek-V3.2, gebruikt u die exacte implementatienaam in .env.

2. Voer de optimalisatietaak uit

Maak een bestand met de naam optimize_hosted_agent.py in dezelfde map als .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}"
      )

Voer het script uit:

python optimize_hosted_agent.py

Wanneer de taak succesvol wordt voltooid, toont het script de winnende kandidaat en diens candidate_id.

In tegenstelling tot azd ai agent optimize maakt de stroom van de Python-SDK geen lokaal .agent_configs/baseline/metadata.yaml-bestand aan. De metagegevens van de optimalisatietaak blijven in het geretourneerde job object en in het antwoord van de Foundry-service, inclusief de basislijnkandidaat, de beste kandidaat en de scorelijst.

3. De winnende kandidaat toepassen

Als u ook werkt met het lokale azd-project dat in het bovenstaande CLI-proces wordt gebruikt, past u de winnende kandidaat toe met de candidate_id die door het Python-script is geretourneerd:

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

Als u alleen het resultaat hoeft te inspecteren, gebruikt u de kandidaatscores en evaluatie-id’s die door het script worden weergegeven om de winnende configuratie in Foundry te beoordelen voordat u deze promoveert.

De optimalisatie uitvoeren in VS Code

Foundry Toolkit bevat een systeemeigen agentoptimalisatie-ervaring voor geïmplementeerde gehoste agents. Vanuit de agentspeelplaats kunt u een optimalisatieuitvoering starten, kandidaten vergelijken met de basislijn, configuratiewijzigingen inspecteren en de beste kandidaat implementeren.

Stap 1: Selecteer een uitgerolde gehoste agent

1. Selecteer Foundry Toolkit in de activiteitenbalk.
2. Selecteer onder Mijn resourcesde optie Agents.
3. Als u een geïmplementeerde gehoste agent hebt, selecteert u deze om de speeltuin van de gehoste agent te openen.
4. Als u geen geïmplementeerde gehoste agent hebt, voltooit u het VS Code-pad in quickstart: Uw eerste gehoste agent implementeren. Nadat de implementatie is voltooid, gaat u terug naar Agents en selecteert u de nieuwe gehoste agent.

Stap 2: Een optimalisatieuitvoering starten

1. Selecteer het tabblad Optimaliseren , dat is gemarkeerd als Voorbeeld.

1. Selecteer Nieuwe optimalisatie.

2. In Werkruimte selecteren kiest u de werkruimte die de code van de geselecteerde gehoste agent bevat:

   • Selecteer huidige werkruimte als de huidige werkruimte de agentcode en het azure.yaml bijbehorende bestand bevat.
   • Selecteer Bladeren... om de werkruimte met de agentcode te openen.

   Foundry Toolkit gebruikt de werkruimtebestanden om de optimalisatie voor te bereiden en een kandidaat toe te passen op de overeenkomende azure.ai.agent service.

1. Foundry Toolkit opent GitHub Copilot Chat en verzendt een Agent Optimizer-aanvraag die is gevuld met het type, de naam en het foundry-projecteindpunt van de geselecteerde agent.

2. Beantwoord de vier optimalisatievragen in Copilot Chat:

   Invoer	Wat u moet verstrekken
   Evaluatiemetrieken	Voer de metrieken of beoordelaars in die u wilt gebruiken. Als u deze niet hebt, kiest u of u de ingebouwde standaardinstellingen van de optimizer wilt uitvoeren azd ai agent eval generate of gebruiken.
   Dataset	Selecteer de optimalisatiegegevensset. Als u er geen hebt, kiest u of u de ingebouwde standaardinstellingen van de optimizer wilt uitvoeren azd ai agent eval generate of gebruiken.
   Maximum aantal kandidaten	Voer het maximum aantal kandidaten in dat moet worden gegenereerd, zoals 2.
   Optimalisatiemodel	Selecteer een bestaande implementatie in de ondersteunde optimalisatiemodellen.

GitHub Copilot wacht op deze invoer voordat de optimalisatie wordt gestart. De gegenereerde aanvraag instrueert Copilot om uitsluitend de Agent Optimizer-workflow van de Microsoft Foundry Skill en Azure Developer CLI-opdrachten te gebruiken. Er worden geen Foundry MCP-hulpprogramma's gebruikt. Copilot:

• Inspecteert de agentcode in de geselecteerde werkruimte.
• Initialiseert een AZD-omgeving op basis van bestaande azure.yaml- en .env-waarden, als het project er nog geen heeft.
• Configureert de agent voor optimalisatie en rolt de bijgewerkte gehoste agent uit.
• Maakt eval.yaml in de servicemap van de agent.
• Start de optimalisatie nadat u de voorgestelde bestandswijzigingen en -opdrachten hebt bekeken en goedgekeurd.

Nadat Copilot de taak heeft ingediend, gaat u terug naar het tabblad Optimaliseren. De uitvoering wordt weergegeven onder Optimalisatieuitvoeringen. De tabel toont de uitvoerings-id, status, aantal kandidaten, basislijnscore, beste score en aanmaaktijd.

Stap 3: de beste kandidaat vergelijken en implementeren

1. Wanneer de uitvoering is voltooid, selecteert u deze onder Optimalisatieuitvoeringen.
2. Vergelijk de Baseline- en Best-scores. Controleer de scoredetails voor elke kandidaat en selecteer Wijzigingen weergeven om de configuratiewijzigingen te controleren.
3. Als de beste kandidaat de basislijn verbetert, selecteert u De beste kandidaat implementeren om de huidige agent bij te werken. Als u deze wilt implementeren als een nieuwe agent of implementatie-instellingen wilt wijzigen, selecteert u in plaats daarvan Aangepaste implementatie .

De optimalisatie uitvoeren met de Microsoft Foundry Skill

Gebruik dit pad in elke host van een coderingsagent die ondersteuning biedt voor de Microsoft Foundry Skill, zoals GitHub Copilot in Visual Studio Code, Copilot CLI of Claude Code. De vaardigheid haalt de agentcontext op van azure.yaml, laadt de Agent Optimizer-workflow en houdt kandidaatapplicaties en implementatie achter beoordelingspoorten.

Stap 1: De werkruimte van de agent openen

Open een lege map in de host van de coderingsagent. Controleer of de microsoft-foundry vaardigheid beschikbaar is. Als de vaardigheid niet beschikbaar is, volg De Microsoft Foundry Skill gebruiken in codeeragents.

Stap 2: Vraag de vaardigheid om Agent Optimizer uit te voeren

Stuur deze prompt naar uw codeeragent:

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.

De coderingsagent kan u vragen om een abonnement, regio, Foundry-project, agentservice, evaluatiemodel of optimalisatiemodel te selecteren wanneer deze waarden niet kunnen worden omgezet in de werkruimte. Controleer de gegenereerde bestanden en kostenveroorzakende resources voordat u wijzigingen of opdrachten goedkeurt.

Stap 3: Een goedgekeurde kandidaat toepassen en implementeren

Nadat u de optimalisatieresultaten hebt bekeken, dient u deze vervolgprompt in:

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.

De vaardigheid gebruikt azd ai agent optimize apply --candidate <candidate-id> zodat u de geoptimaliseerde configuratie lokaal kunt bekijken. Deze wordt pas geïmplementeerd na uw goedkeuring en roept vervolgens de bijgewerkte gehoste agent aan en evalueert deze.