Optimieren von Agentanweisungen, Fähigkeiten, Tools und Modellen (Vorschau)

Der Agent-Optimierer verbessert vier Aspekte Ihres gehosteten Agents: Anweisungen, Fähigkeiten, Tools und Modellauswahl. Es erkennt automatisch, welche dieser Ziele aus der Basiskonfiguration Ihres Agents optimiert werden sollen.

In diesem Artikel wird gezeigt, wie Sie eine Optimierung ausführen, die Ausführung konfigurieren und überwachen und die Ergebnisse bereitstellen. Informationen dazu, was jedes Ziel bewirkt und wann es aktiviert wird, finden Sie unter Optimierungsziele. Informationen zum Einrichten der Basiseingaben finden Sie unter "Vorbereiten des Agent-Optimierers". Eine Kurzübersicht darüber, was der Optimierer ändert, finden Sie unter "Änderungen an den einzelnen Zielzielen".

Voraussetzungen

• Ein Foundry-Projekt mit einem bereitgestellten gehosteten Agent
• Die azure.ai.agents installierte CLI-Erweiterung (siehe Schnellstart: Optimieren eines gehosteten Agents)
• Ein für die Auswertung bereitgestelltes Modell (z. B gpt-4.1-mini. ) und ein Optimierungsmodell aus der unterstützten Liste (z. B gpt-5.1. )
• Ihr Agent ist bereit zur Optimierung (load_config() wird aufgerufen)

Ausführen einer Optimierung

Starten Sie eine Optimierung mit einem einzigen Befehl:

azd ai agent optimize

Der Optimierer wertet Ihre Basislinie aus, generiert Kandidaten, bewertet sie und bewertet die Ergebnisse. Den vollständigen Auswertungs- und Verbesserungszyklus finden Sie unter Funktionsweise des Agent-Optimierers. Welche Ziele ausgeführt werden, hängt von Ihrer Basiskonfiguration ab– Die Optimierung von Anleitungen, Qualifikationsverbesserungen und Tooloptimierung werden automatisch aktiviert, wenn die übereinstimmenden Basisplandateien vorhanden sind. Siehe Optimierungsziele.

Um den Durchlauf mit einer Konfigurationsdatei zu steuern, übergeben Sie ein eval.yaml, das auf Ihr Dataset, Ihre Evaluatoren und Optionen verweist:

azd ai agent optimize --config eval.yaml

Das vollständige eval.yaml Schema finden Sie unter Konfigurieren der Optimierungsausführung.

Ziel eines bestimmten Agents

Wie die CLI den Agent auflöst, hängt davon ab, ob Sie den Befehl aus einem azd-Projekt ausführen:

Der Name des bereitgestellten Agents muss mit einem gehosteten Agent im Ziel-Foundry-Projekt übereinstimmen.

Optimieren eines vorhandenen Agents ohne AZD-Projektdateien

Sie können einen vorhandenen gehosteten Agenten optimieren, ohne azd ai agent init auszuführen und ohne .azure oder ein azure.yaml-Umgebungsverzeichnis zu erstellen. Geben Sie in diesem eigenständigen Fluss den Foundry-Projektendpunkt und den Namen des bereitgestellten Agents explizit an.

1. Stellen Sie sicher, dass der bereitgestellte Agent für den Optimierer bereit ist. Erstellen Sie in einem lokalen Arbeitsverzeichnis die Anweisungsdatei, das Dataset, die Evaluatoren und eval.yaml, wie unter Optimierungslauf konfigurieren beschrieben.

   Führen Sie den Befehl aus diesem Arbeitsverzeichnis aus. Ohne ein azd-Projekt werden relative Pfade in eval.yaml vom aktuellen Arbeitsverzeichnis aus aufgelöst.

   Lassen Sie für diesen eigenständigen Ablauf agent.config weg. Die CLI fordert beim Ausführen des Befehls die Basisanweisung an:

   # eval.yaml
   agent:
     name: my-support-agent
     kind: hosted
     model: gpt-4.1-mini
   dataset:
     local_uri: ./eval.jsonl
   evaluators:
     - builtin.task_adherence
   options:
     eval_model: gpt-4.1-mini
     optimization_model: gpt-5.1
     max_candidates: 2
   

2. Authentifizieren:

   az login
   azd auth login
   

3. Kopieren Sie den Projektendpunkt von der Übersichtsseite des Foundry-Projekts. Verwenden Sie die Projektendpunkt-URL, nicht die Azure Ressourcen-ID.

4. Speichern Sie den Endpunkt in Ihrer Konfiguration auf Benutzerebene azd , damit nachfolgende Befehle dasselbe Projekt aus einem beliebigen Verzeichnis auflösen können:

   azd ai project set "<project-endpoint>"
   azd ai project show
   

   In diesem Schritt wird der Standard-Endpunkt nach ~/.azd/config.json geschrieben. Die vollständige Auflösungsreihenfolge sowie Befehle zum Überprüfen oder Löschen des gespeicherten Kontexts finden Sie unter Den Foundry-Projektkontext für azd-Befehle festlegen.

5. Führen Sie die Optimierung mit dem bereitgestellten Agentnamen aus:

   azd ai agent optimize --agent "<deployed-agent-name>" --config eval.yaml
   

   Wenn Sie zur Eingabe der Agent-Anweisung aufgefordert werden, geben Sie sie direkt ein oder wählen Sie eine Datei aus, z. B. .agent_configs/baseline/instructions.md.

   Note

   In der aktuellen Vorschauversion wird agent.config nicht durch eine eigenständige Ausführung auf eval.yaml erweitert. Führen Sie den Befehl interaktiv aus, damit Sie die Baseline-Anweisung angeben können. Verwenden Sie --no-prompt nicht für diesen Ablauf. Das Laden von dateibasierten Skills und Tool-Baselines erfordert ebenfalls ein Projekt vom Typ azd.

   Für einen einmaligen Befehl, der Ihre Konfiguration auf Benutzerebene nicht ändern soll, übergeben Sie --project-endpoint:

   azd ai agent optimize \
     --project-endpoint "<project-endpoint>" \
     --agent "<deployed-agent-name>" \
     --config eval.yaml
   

   Sie können den Endpunkt auch für die aktuelle Shell festlegen:

   export FOUNDRY_PROJECT_ENDPOINT="<project-endpoint>"
   azd ai agent optimize --agent "<deployed-agent-name>" --config eval.yaml
   

6. Speichern Sie die Vorgangs-ID aus der Befehlsausgabe. Da dieser Fluss keine azd Umgebung aufweist, behält die CLI die letzte Vorgangs-ID nicht lokal bei. Übergeben Sie die Vorgangs-ID, um Nachverfolgungsbefehle auszuführen:

   azd ai agent optimize status <operation-id> --watch
   
   azd ai agent optimize list
   
   azd ai agent optimize cancel <operation-id>
   

   Diese Befehle verwenden den von azd ai project set gespeicherten Endpunkt. Wenn Sie stattdessen das einmalige Formular --project-endpoint verwendet haben, übergeben Sie das Flag erneut an jeden nachfolgenden Befehl.

Konfigurieren der Optimierungsausführung

Konfigurieren Sie Optimierungsläufe über eine eval.yaml-Datei, die Ihren Datensatz, Ihre Auswertungen und Ihre Laufoptionen zusammenführt. Der Befehl azd ai agent eval generate schreibt diese Datei für Sie, oder Sie können sie manuell erstellen. Der Optimierer erkennt eval.yaml im Projektstamm automatisch, oder Sie können es explizit mit --config eval.yaml angeben.

# eval.yaml
name: my-optimization              # Optional label for the run
agent:
  name: my-agent                   # Deployed hosted agent name
  kind: hosted
  version: "1"                     # Agent version (optional)
  model: gpt-4.1-mini              # Baseline model deployment
  config: .agent_configs/baseline/metadata.yaml
dataset:
  local_uri: ./eval.jsonl          # A local JSONL file...
  # name: my-foundry-dataset       # ...OR a registered Foundry dataset
  # version: "1"
# validation_dataset:              # Optional held-out dataset
#   name: my-validation-dataset
#   version: "1"
evaluators:
  - builtin.task_adherence         # A built-in evaluator...
  # - name: my-custom-evaluator    # ...or a custom evaluator
  #   version: "1"
  #   local_uri: ./my_evaluator.json
options:
  eval_model: gpt-4.1-mini         # Scores responses
  optimization_model: gpt-5.1      # Generates candidates
  max_candidates: 4
  optimization_config:
    model_search_space:            # Optional: compare model deployments
      - gpt-4.1

Erstellen Sie das Dataset und die Evaluatoren separat; siehe Erstellen Sie ein Auswertungs-Dataset und Evaluatoren. In den folgenden Abschnitten werden die Ausführungsoptionen beschrieben.

Auswählen der Auswertungs- und Optimierungsmodelle

Der Optimierer verwendet zwei Modelle: ein Eval-Modell , das Agentantworten anhand von Kriterien bewertet, und ein Optimierungsmodell , das Kandidatenkonfigurationen generiert. Legen Sie sie in eval.yaml oder verwenden Sie CLI-Flags.

options:
  eval_model: gpt-4.1-mini
  optimization_model: gpt-5.1

azd ai agent optimize --eval-model gpt-4.1-mini --optimize-model gpt-5.1

Jedes in Ihrem Projekt bereitgestellte Chatvervollständigungsmodell funktioniert als Auswertungsmodell. Das Optimierungsmodell muss aus der unterstützten Liste stammen. Rollen und unterstützte Modelle finden Sie unter "Modelle".

Festlegen der Anzahl der Kandidaten

Die max_candidates Option legt die erwartete Anzahl der Kandidatenkonfigurationen für die Ausführung fest. Der Optimierer wird in der Regel zurückgegeben, nachdem die Anzahl erreicht wurde, es sei denn, die Ausführung wird aufgrund eines Fehlers oder einer anderen Beendigungsbedingung frühzeitig beendet.

Höhere Werte untersuchen mehr Variationen, dauern aber länger. Der Optimierer lernt aus früheren Kandidaten, sodass spätere Kandidaten tendenziell höher bewertet werden.

Mehrere Modelle auswerten

Um Bereitstellungen von Modellen in einem einzelnen Durchlauf zu vergleichen, führen Sie sie unter optimization_config.model_search_space auf. Der Optimierer evaluiert Ihren Agenten für jedes Modell anhand desselben Datensatzes und ordnet die Ergebnisse nach Punktzahl und Tokenkosten.

# eval.yaml
options:
  optimization_config:
    model_search_space:
      - gpt-4.1
      - gpt-4.1-mini
      - gpt-4o

Jedes unter model_search_space aufgeführte Modell muss in Ihrem Foundry-Projekt bereitgestellt werden.

Die Modellauswahl läuft parallel zu den Zielen, die von Ihrer Baseline automatisch aktiviert werden. Eine einzelne Ausführung kann Kandidaten erstellen, die verbesserte Anweisungen, Fähigkeiten und Toolbeschreibungen mit verschiedenen Modelloptionen kombinieren – Sie konfigurieren die Kombination nicht selbst.

Laufenden Auftrag überwachen

Eine Optimierungsausführung ist asynchron. Verwenden Sie diese Befehle, wenn ein Auftrag lang ausgeführt wird oder Sie den Fortschritt überprüfen möchten:

# Check status and stream progress
azd ai agent optimize status <operation-id> --watch

# List recent optimization jobs
azd ai agent optimize list

# Cancel a running job
azd ai agent optimize cancel <operation-id>

Erfassen Sie die Vorgangs-ID, Portal-URL, Bewertungen und Kandidaten-IDs aus der Ausführungsausgabe. Sie können den Auftrag auch im Foundry-Portal überwachen, indem Sie die URL verwenden, die beim Starten der Ausführung angezeigt wird.

Wenn Sie den Auftrag ohne AZD-Projektdateien gestartet haben, übergeben Sie immer die Vorgangs-ID an status und cancel. Die Befehle verwenden den von azd ai project set gespeicherten Endpunkt auf Benutzerebene; andernfalls geben Sie --project-endpoint an.

Interpretieren von Ergebnissen

Überprüfen Sie nach Abschluss der Optimierung die Ergebnistabelle. Ein Sternchen (*) markiert den besten Kandidaten. Informationen zu den Ergebnistabellenspalten, Bewertungsdetails, Schwellenwerten zur Bewertung und der Portalansicht finden Sie unter "Grundlegendes zu Optimierungsergebnissen".

Bereitstellen des Siegers

Der empfohlene Workflow besteht darin, die optimierte Konfiguration lokal anzuwenden und dann Folgendes bereitzustellen:

# Apply the winning candidate locally
azd ai agent optimize apply --candidate <candidate-id>

# Deploy with the optimized config
azd deploy

Dadurch wird die optimierte Konfiguration in .agent_configs/<candidate_id>/ in Ihrem Projekt heruntergeladen. Bei der nächsten Bereitstellung verwendet Ihr Agent die verbesserten Anweisungen und Toolbeschreibungen.

Alternativ können Sie direkt über die API bereitstellen (nützlich für schnelle A/B-Tests):

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

Wenn alle Kandidaten schlechter als die Baseline abschneiden, setzen Sie keinen Kandidaten ein. Die Basiskonfiguration bleibt aktiv.

Was jedes Ziel ändert

Der Optimierer aktiviert automatisch die Ziele, die für Ihren Basisplan gelten. Dieser Abschnitt dient als Referenz dafür, was ein Durchlauf ändert. Verwenden Sie die folgende Tabelle, um zu antizipieren, welche Optimierung für Ihren Agent bewirkt:

Ihr Code bleibt für alle Ziele gleich, da load_config() die optimierten Werte automatisch zurückgibt. Nur die Konfiguration, die das Modell sieht, ändert sich.

Instructions

Der Optimierer schreibt die Systemaufforderung neu. Zu den allgemeinen Verbesserungen gehören:

• Hinzufügen expliziter Einschränkungen, die die ursprüngliche Eingabeaufforderung impliziert, aber nicht angezeigt wurde
• Anweisungen zur Umstrukturierung für bessere Verständlichkeit
• Hinzufügen von Ausgabeformatspezifikationen
• Stärkung der Sicherheits- und Umfangsgrenzen

So könnte beispielsweise eine minimale Basisaufforderung You are a helpful assistant. wie folgt aussehen:

You are a helpful coding assistant. Follow these guidelines:
1. Always include working code examples
2. Explain your reasoning step by step
3. If a question is outside your expertise, say so clearly
4. Use markdown formatting for code blocks
5. Handle edge cases in code examples

Fähigkeiten

Der Optimierer verfeinert die Beschreibung, den Hauptteil und die Aktivierungskriterien jeder Fähigkeit, wobei der Zweck der Fähigkeit erhalten bleibt. Der Agent lädt verbesserte Fähigkeiten über load_config(), das diese dem Anweisungssatz hinzufügt. Fähigkeiten verwenden das offene Agent Skills-Format . Informationen dazu, wie Ihr Agent Fähigkeiten lädt, finden Sie unter Make your agent optimizer-ready.

Tools

Der Optimierer optimiert Ihre tools.json Definitionen. Zu den allgemeinen Verbesserungen gehören:

• Übersichtlichere Funktionsbeschreibungen, die dem Modell helfen, zu wissen, wann ein Tool aufgerufen werden soll
• Spezifischere Parameterbeschreibungen, die ungenaue Argumente reduzieren
• Hinzugefügte Einschränkungen (Enumerationen, erforderliche Felder), die ungültige Eingaben verhindern

Ihr Toolimplementierungscode bleibt gleich. Nur die Definitionen, die das Modell sieht, ändert sich.

Models

Der Optimierer ordnet jedes Kandidatenmodell nach zusammengesetzter Punktzahl und Token-Kosten ein, sodass Sie den besten Kompromiss zwischen Qualität und Kosten wählen können. Informationen zum Konfigurieren der Kandidaten finden Sie unter Auswerten mehrerer Modelle.

Problembehandlung

Verwandte Inhalte

• Übersicht über den Agent-Optimierer
• Machen Sie Ihren Agent-Optimierer bereit
• Erstellen eines Evaluierungsdatensatzes und von Evaluatoren
• Schnellstart: Optimieren eines gehosteten Agents