Schnellstart: Optimieren eines gehosteten Agents (Vorschau)

• azd CLI (Azure Developer CLI).

• Azure CLI für die Authentifizierung.

• Die microsoft.foundry-Erweiterung für azd (0.1.40-preview oder höher der azure.ai.agents-Abhängigkeit):

  azd ext install microsoft.foundry
  

  Wenn bereits installiert, führen Sie ein Upgrade durch:

  azd ext upgrade microsoft.foundry
  

• Azure CLI für die Authentifizierung.

• Python 3.10 oder höher.

• Die in diesem Pfad verwendeten Python Pakete:

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

• Ein vorhandenes Foundry-Projekt, das bereits den gehosteten Agent, das registrierte Dataset und den Auswertungsvorgang enthält, den Sie zur Optimierung verwenden möchten.

• Visual Studio Code.

• Microsoft Foundry Toolkit für Visual Studio Code Version 1.6.4 oder höher, angemeldet bei Azure. Foundry Toolkit installiert und aktualisiert die von diesem Workflow verwendete Microsoft Foundry Skill.

• GitHub Copilot in Visual Studio Code mit Zugriff auf den Agentmodus. Foundry Toolkit sendet die Agent-Optimiereranforderung an GitHub Copilot, nachdem Sie den Agent-Arbeitsbereich ausgewählt haben.

• Azure CLI und Azure Developer CLI (AZD) installiert und authentifiziert:

  az login
  azd auth login
  

• Ein Coding-Agent-Host mit installierter Microsoft Foundry Skill.

• Azure CLI und Azure Developer CLI (AZD) installiert und authentifiziert:

  az login
  azd auth login
  

• Die microsoft.foundry Erweiterung für AZD. Installieren Sie ihn, bevor Sie den Workflow starten:

  azd ext install microsoft.foundry
  

  Wenn sie bereits installiert ist, führen Sie ein Upgrade durch:

  azd ext upgrade microsoft.foundry
  

Schritt 1: Erstellen des Projekts

Initialisieren Sie ein neues Projekt aus der Optimierungsbeispielvorlage:

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 .

Diese Vorlage importiert das Beispiel „Optimization Customer Support“, einen optimierungsfähigen, in Python gehosteten Agenten, der den Bring-your-own-Ansatz und das Responses-Protokoll verwendet. Sie stellt einen Supportmitarbeiter für Unterhaltungselektronik dar, der Bestellanfragen, Rückgaben, Garantieansprüche, Problembehandlung, Beschwerden, Empfehlungen und Eskalation verarbeitet. Durch die bewusst minimale Grundanweisung lassen sich die Verbesserungen von der Optimierung von Anleitungen und der Fähigkeitserkennung leicht vergleichen.

Das Beispiel ruft load_config() auf, um die Basis- oder Kandidatenkonfiguration zu laden, und enthält .agent_configs/baseline/, eval.yaml, vollständige und schnelle Auswertungsdatensätze, Containerkonfiguration und das Foundry-Bereitstellungsmanifest. Der interaktive Ablauf importiert diese Dateien und fordert Sie zur Eingabe Ihres Azure-Abonnements, der Region und der Einstellungen für die Modellbereitstellung auf.

Schritt 2: Provisionieren und bereitstellen

Authentifizieren und Bereitstellen der Azure-Ressourcen:

az login
azd auth login
azd provision

Die Bereitstellung dauert etwa zwei Minuten und erstellt ein Foundry-Konto, ein Projekt, eine Azure Container Registry und Modellbereitstellungen.

Bereitstellen des Agents:

azd deploy

Testen Sie die Bereitstellung:

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

Schritt 3: Generieren einer Evaluierungssuite und Optimierung

Generieren Sie ein Auswertungs-Dataset und Evaluatoren für Ihren Agenten:

azd ai agent eval generate

In diesem Schritt werden eval.yaml, ein Testdataset und Bewertungsauswerter basierend auf den Anweisungen Ihres Agents erstellt. Der Optimierer verwendet diese Dateien, um die Verbesserung zu messen.

Führen Sie den Optimierer aus:

azd ai agent optimize --max-candidates 2

Die CLI fordert Sie auf, ein Optimierungsmodell auszuwählen. Um die Eingabeaufforderung zu überspringen, übergeben Sie sie direkt:

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

Die CLI erkennt Ihren Agenten aus azure.yaml und verwendet das generierte eval.yaml automatisch. Bei zwei Kandidaten wird die Optimierung in der Regel in etwa 8 Minuten abgeschlossen. Der Fortschritt in Echtzeit wird angezeigt:

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>

Verwenden Sie die Portal-URL, um Ihren Auftrag im Foundry-Portal zu verfolgen.

Das Eval-Modell bewertet jede Antwort (jedes Chat-Vervollständigungsmodell funktioniert). Das Optimierungsmodell (--optimize-model) generiert verbesserte Kandidaten und muss aus der unterstützten Liste (gpt-5 Family oder DeepSeek) stammen. Sie können auch optimization_model unter options: in eval.yaml festlegen, um zu vermeiden, dass das Flag jedes Mal übergeben wird.

Schritt 4: Stellen Sie den Gewinner bereit

Der Stern (*) in der Ausgabe gibt den besten Kandidaten an. Wenden Sie die optimierte Konfiguration lokal an, und stellen Sie folgendes bereit:

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

Der apply-Befehl lädt die optimierte Konfiguration in .agent_configs/<candidate_id>/ herunter und aktualisiert Ihr azure.yaml, um die neuen Anweisungen zu verwenden. Der deploy Befehl stellt den optimierten Agent mithilfe von Code Deploy live bereit.

Rufen Sie Ihren Agent auf, um die Verbesserung zu überprüfen:

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

Sie können auch eine Bewertung ausführen, um die Bewertungsverbesserung zu bestätigen:

azd ai agent eval run

Python SDK-Pfad

Führen Sie die folgenden Schritte aus, wenn Sie den Optimierer aus Python anstelle des zuvor beschriebenen Azure Developer CLI-Workflows ausführen möchten.

Bei diesem Pfad wird davon ausgegangen, dass Sie bereits über die folgenden Ressourcen in einem vorhandenen Foundry-Projekt verfügen:

• Ein gehosteter Agent, der optimiert werden soll.
• Ein registriertes Schulungsdatenset.
• Ein registrierter Evaluator.

Im Gegensatz zu dem zuvor beschriebenen Ablauf mit der Azure Developer CLI erstellt der Weg über das Python SDK kein Projektgerüst und generiert weder eval.yaml, noch ein Dataset oder Evaluatoren für Sie. Wenn das Beispiel diese Ressourcen automatisch erstellen soll, verwenden Sie azd ai agent eval generate zuerst.

1. Erstellen einer .env Datei

Erstellen Sie einen Arbeitsordner, und fügen Sie dann eine .env Datei mit den folgenden Werten hinzu:

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>

Führen Sie das Skript aus diesem Arbeitsordner aus, damit load_dotenv() die .env Datei automatisch geladen werden kann. Wenn Sie es lieber aus einem anderen Verzeichnis ausführen möchten, legen Sie zuerst die gleichen Werte in Ihrer Shellumgebung fest.

Verwenden Sie den exakten Projektendpunkt von der Übersicht-Seite Ihres Foundry-Projekts. Das skript Python sendet seine erste Anforderung sofort. Wenn FOUNDRY_PROJECT_ENDPOINT nur ein Platzhalter ist oder auf das falsche Projekt verweist, schlägt die Ausführung mit ResourceNotFound: The project does not exist fehl.

Setzen Sie EVAL_MODEL und OPTIMIZATION_MODEL auf Bereitstellungsnamen, die in Ihrem Foundry-Projekt bereits vorhanden sind, nicht nur auf Modellfamiliennamen. Wenn Ihre Projektbereitstellung z. B. den Namen gpt-4.1-mini oder DeepSeek-V3.2 trägt, verwenden Sie genau diesen Bereitstellungsnamen in .env.

2. Ausführen des Optimierungsauftrags

Erstellen Sie eine Datei optimize_hosted_agent.py namens im selben Ordner wie .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}"
      )

Führen Sie das Skript aus:

python optimize_hosted_agent.py

Wenn die Aufgabe erfolgreich abgeschlossen wird, gibt das Skript den erfolgreichen Kandidaten und dessen candidate_id aus.

Im Gegensatz dazu azd ai agent optimizeerstellt der Python SDK-Fluss keine lokale .agent_configs/baseline/metadata.yaml Datei. Die Metadaten des Optimierungsauftrags verbleiben im zurückgegebenen job Objekt und in der Antwort des Foundry-Diensts, einschließlich der Basiskandidaten, der besten Kandidatenliste und der bewerteten Kandidatenliste.

3. Wenden Sie den Gewinnerkandidaten an.

Wenn Sie auch mit dem lokalen azd-Projekt arbeiten, das im obigen CLI-Ablauf verwendet wird, wenden Sie den ausgewählten Kandidaten an, indem Sie das vom Python-Skript zurückgegebene candidate_id verwenden:

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

Wenn Sie nur das Ergebnis prüfen müssen, verwenden Sie die vom Skript ausgegebenen Kandidatenbewertungen und Auswertungs-IDs, um die ausgewählte Konfiguration in Foundry zu prüfen, bevor Sie sie hochstufen.

Ausführen der Optimierung in VS Code

Das Foundry Toolkit enthält eine native Agent-Optimierungserfahrung für bereitgestellte gehostete Agents. Im Agent-Playground können Sie einen Optimierungslauf starten, Kandidaten mit dem Basisplan vergleichen, Konfigurationsänderungen überprüfen und den besten Kandidaten bereitstellen.

Schritt 1: Auswählen eines bereitgestellten gehosteten Agents

1. Wählen Sie das Foundry Toolkit in der Aktivitätsleiste aus.
2. Wählen Sie unter "Meine Ressourcen""Agents" aus.
3. Wenn Sie über einen bereitgestellten gehosteten Agent verfügen, wählen Sie ihn aus, um den gehosteten Agent-Playground zu öffnen.
4. Wenn Sie keinen bereitgestellten gehosteten Agent haben, führen Sie den VS-Codepfad in der Schnellstartanleitung aus: Bereitstellen Ihres ersten gehosteten Agents. Kehren Sie nach Abschluss der Bereitstellung zu Agents zurück, und wählen Sie den neuen gehosteten Agent aus.

Schritt 2: Starten einer Optimierungsausführung

1. Wählen Sie die Registerkarte "Optimieren " aus, die als Vorschau gekennzeichnet ist.

1. Wählen Sie "Neue Optimierung" aus.

2. Wählen Sie in "Arbeitsbereich auswählen" den Arbeitsbereich aus, der den Code des ausgewählten gehosteten Agents enthält:

   • Wählen Sie "Aktueller Arbeitsbereich " aus, wenn der aktuelle Arbeitsbereich den Agentcode und seine azure.yaml Datei enthält.
   • Wählen Sie "Durchsuchen" aus , um den Arbeitsbereich zu öffnen, der den Agentcode enthält.

   Das Foundry Toolkit verwendet die Arbeitsbereichsdateien, um die Optimierung vorzubereiten und einen Kandidaten auf den passenden azure.ai.agent Dienst anzuwenden.

1. Das Foundry Toolkit öffnet GitHub Copilot Chat und sendet eine Agent-Optimiereranforderung, die mit der Art, dem Namen und dem Foundry-Projektendpunkt des ausgewählten Agents gefüllt ist.

2. Beantworten Sie die vier Optimierungsfragen in Copilot Chat:

   Eingabe	Was zu bieten ist
   Auswertungsmetriken	Geben Sie die zu verwendenden Metriken oder Bewerter ein. Wenn Sie nicht darüber verfügen, wählen Sie, ob azd ai agent eval generate ausgeführt oder die integrierten Standardeinstellungen des Optimierers verwendet werden sollen.
   Dataset	Wählen Sie das Optimierungsdatenset aus. Wenn Sie keine haben, wählen Sie, ob Sie azd ai agent eval generate ausführen oder die integrierten Standardwerte des Optimierers verwenden möchten.
   Maximale Kandidatenzahl	Geben Sie die maximale Anzahl an Kandidaten ein, die generiert werden sollen, z. B. 2.
   Optimierungsmodell	Wählen Sie eine vorhandene Bereitstellung aus den unterstützten Optimierungsmodellen aus.

GitHub Copilot wartet auf diese Eingaben, bevor die Optimierung gestartet wird. Die generierte Anforderung leitet Copilot an, ausschließlich den Agent-Optimierer-Workflow Microsoft Foundry Skill und Azure Developer CLI-Befehle zu verwenden. Es verwendet keine Foundry MCP-Tools. Copilot:

• Überprüft den Agentcode im ausgewählten Arbeitsbereich.
• Initialisiert eine AZD-Umgebung aus vorhandenen Werten für azure.yaml und .env, wenn das Projekt noch keine hat.
• Verkabelt den Agent zur Optimierung und stellt den aktualisierten gehosteten Agent bereit.
• Erstellt eval.yaml im Ordner des Agent-Diensts.
• Startet die Optimierung, nachdem Sie die vorgeschlagenen Dateiänderungen und -befehle überprüft und genehmigt haben.

Nachdem Copilot den Auftrag übermittelt hat, kehren Sie zur Registerkarte "Optimieren" zurück. Die Ausführung wird unter "Optimierung" ausgeführt. Die Tabelle zeigt die Ausführungs-ID, den Status, die Kandidatenanzahl, die Baselinebewertung, die beste Bewertung und die Erstellungszeit.

Schritt 3: Vergleichen und Bereitstellen des besten Kandidaten

1. Wenn die Ausführung erfolgreich ausgeführt wird, wählen Sie sie unter "Optimierung" aus.
2. Vergleichen Sie die Baseline- und Best-Werte. Überprüfen Sie die Bewertungsdetails für jeden Kandidaten, und wählen Sie "Änderungen anzeigen " aus, um die Konfigurationsänderungen zu überprüfen.
3. Wenn der beste Kandidat die Baseline übertrifft, wählen Sie Besten Kandidaten bereitstellen aus, um den aktuellen Agenten zu aktualisieren. Um sie als neuer Agent bereitzustellen oder Bereitstellungseinstellungen zu ändern, wählen Sie stattdessen "Benutzerdefinierte Bereitstellung" aus.

Ausführen der Optimierung mit dem Microsoft Foundry Skill

Verwenden Sie diesen Pfad in jedem Codierungs-Agent-Host, der die Microsoft Foundry Skill unterstützt, z. B. GitHub Copilot in Visual Studio Code, Copilot CLI oder Claude Code. Die Fähigkeit ermittelt den Agentenkontext aus azure.yaml, lädt den Workflow des Agent Optimizer und hält die Kandidatenanwendung und die Bereitstellung bis zu den Prüffreigaben zurück.

Schritt 1: Öffnen des Agent-Arbeitsbereichs

Öffnen Sie einen leeren Ordner in Ihrem Codierungs-Agent-Host. Vergewissern Sie sich, dass die microsoft-foundry Fähigkeit verfügbar ist. Wenn der Skill nicht verfügbar ist, befolgen Sie Verwenden des Microsoft Foundry Skill in Programmier-Agents.

Schritt 2: Fordern Sie den Skill auf, Agent Optimizer auszuführen

Übermitteln Sie diese Aufforderung an Ihren Codierungs-Agent:

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.

Der Programmier-Agent fordert Sie möglicherweise auf, ein Abonnement, eine Region, ein Foundry-Projekt, einen Agent-Dienst, ein Auswertungsmodell oder ein Optimierungsmodell auszuwählen, wenn er diese Werte nicht im Arbeitsbereich ermitteln kann. Überprüfen Sie generierte Dateien und ressourcenaufwendige Ressourcen, bevor Sie Änderungen oder Befehle genehmigen.

Schritt 3: Anwenden und Bereitstellen eines genehmigten Kandidaten

Nachdem Sie die Optimierungsergebnisse überprüft haben, übermitteln Sie diese Nachverfolgungsaufforderung:

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.

Die Fähigkeit verwendet azd ai agent optimize apply --candidate <candidate-id> , um die optimierte Konfiguration lokal zu überprüfen. Die Bereitstellung erfolgt erst nach Ihrer Genehmigung; anschließend wird der aktualisierte gehostete Agent aufgerufen und ausgewertet.