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.3.0" 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.

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 .

Der interaktive Ablauf fragt nach Ihrem Azure-Abonnement, der Region und den Einstellungen für die Modellbereitstellung. Es verwendet azure.yaml für die Konfiguration des gehosteten Agents und generiert .agent_configs/baseline/, den Evaluierungsdatensatz, und Infrastrukturdateien.

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.projects import AIProjectClient
from azure.ai.projects.models import (
  JobStatus,
  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")
poll_interval = int(os.environ.get("POLL_INTERVAL_SECONDS", "10"))
eval_model = os.environ.get("EVAL_MODEL", "gpt-4o")
optimization_model = os.environ.get("OPTIMIZATION_MODEL", "gpt-5")

terminal_statuses = {JobStatus.SUCCEEDED, JobStatus.FAILED, JobStatus.CANCELLED}

with (
  DefaultAzureCredential() as credential,
  AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
):
  job = project_client.beta.agents.create_optimization_job(
    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,
        ),
      )
    )
  )

  print(f"Created optimization job: {job.id}")
  print(f"Initial status: {job.status}")

  while job.status not in terminal_statuses:
    time.sleep(poll_interval)
    job = project_client.beta.agents.get_optimization_job(job_id=job.id)
    print(f"Status: {job.status}")

  if job.status == JobStatus.FAILED:
    message = job.error.message if job.error else "<no error message>"
    raise RuntimeError(f"Optimization job failed: {message}")

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

    for candidate in job.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.