Agentenbewertungen mit der azd CLI ausführen (Vorschau)

Important

Die in diesem Artikel markierten Elemente (Vorschau) sind aktuell als öffentliche Vorschau verfügbar. Diese Vorschauversion wird ohne Vereinbarung zum Servicelevel bereitgestellt und sollte nicht für Produktionsworkloads verwendet werden. Manche Features werden möglicherweise nicht unterstützt oder sind nur eingeschränkt verwendbar. Weitere Informationen finden Sie unter Supplementale Nutzungsbedingungen für Microsoft Azure Previews.

Verwenden Sie die Evaluierungsfunktion der Azure Developer CLI (azd), um einem mit Microsoft Foundry erstellten Agenten einen messbaren Qualitätsbewertungszyklus hinzuzufügen. Dieser Artikel konzentriert sich auf den Lebenszyklus des gehosteten Agents in azd, in dem Sie Auswertungsressourcen erstellen, provisionieren, bereitstellen, initialisieren, eine erste Auswertung ausführen, den Durchlauf überprüfen und das Auswertungsrezept für spätere Durchläufe wiederverwenden.

Promptbasierte Agenten können auch evaluiert werden, wenn sie im Foundry-Projekt als Agentziele verfügbar sind. Die Schritte zur Bereitstellung des gehosteten Agents gelten nur für gehostete Agents.

In diesem Artikel wird erläutert, wie Sie die erste Agent-Auswertung mit azd ai agent eval generate und azd ai agent eval run durchführen.

Voraussetzungen

Ein Azure-Abonnement mit Zugriff auf Microsoft Foundry.
Die Azure Developer CLI (azd). Installationsanweisungen finden Sie unter Install the Azure Developer CLI.
Die azd ai agent Erweiterung, Version 0.1.40-preview oder höher, ist installiert (azd ext install azure.ai.agents). Wenn die Erweiterung nicht installiert ist, wird die Erweiterung automatisch installiert, wenn Sie die Startvorlage initialisieren oder die Erweiterung ausführen azd ai agent . Führen Sie azd ext list aus, um die installierte Version zu überprüfen, und führen Sie azd ext upgrade azure.ai.agents aus, wenn Sie ein Upgrade durchführen müssen. Weitere Informationen zur azd AI-Agent-Erweiterung finden Sie unter Microsoft Foundry Agent Extension.
Eine authentifizierte azd Sitzung. Führen Sie azd auth status aus, um Ihren Authentifizierungsstatus zu überprüfen. Wenn Sie nicht angemeldet sind, führen Sie azd auth login aus.
Die Rolle Foundry User für die Foundry-Ressource (zuvor als Azure AI User bezeichnet). Weitere Informationen finden Sie unter Rollenbasierte Zugriffssteuerung für Microsoft Foundry.
Für gehostete Agents: Es ist kein bereits vorhandenes Foundry-Projekt erforderlich. azd ai agent init und azd provision erstellen die erforderlichen Ressourcen.
Für eingabeaufforderungsbasierte Agents: Ein vorhandenes Foundry-Projekt, bei dem der Agent bereits bereitgestellt und als Auswertungsziel verfügbar ist.
Eine Modellbereitstellung, die Chatabschlüsse im selben Foundry-Projekt unterstützt.
Optional: Ein JSONL-Dataset zur Evaluierung mit repräsentativen Beispielen, wenn Sie nicht möchten, dass eval generate ein Dataset für eine Feuerprobe generiert.

So funktionieren azd-Agent-Evaluierungen

Die primäre Azd CLI-Auswertungserfahrung wurde für den Lebenszyklus des gehosteten Agents entwickelt:

azd ai agent init
azd provision
azd deploy
azd ai agent eval generate
azd ai agent eval run
azd ai agent eval update
# Optional, after the agent and eval recipe meet optimization prerequisites:
azd ai agent optimize

Der Auswertungsfluss umfasst die folgenden Artefakte und Befehle.

Element	Description
`eval generate`	Erstellt oder repariert lokale Bewertungsobjekte für ein Agent-Ziel.
`eval.yaml`	Lokales ausführbares Rezept zur Auswertung. Es erfasst das Ziel des Agenten, den Verweis auf den Datensatz, die Evaluator-Verweise und die Generierungsoptionen.
Generierte lokale Artefakte	Bearbeitbare lokale Kopien generierter Datasets und Bewerter-Rubriken. Die Artefakte werden unter `datasets/` und `evaluators/` im Agentordner gespeichert (z. B `src/<agent-name>/datasets/` . und `src/<agent-name>/evaluators/`).
Registrierte Dienstartefakte	Der Foundry-Dataset und die Evaluator-Versionen, die von Auswertungsausführungen verwendet werden. Dies sind die Quelle der Wahrheit für generierte Vermögenswerte.
`eval run`	Führt das Evaluierungsrezept für das ausgewählte Agent-Ziel aus.
`eval update`	Registriert neue Dienstversionen aus lokalen Datasets oder Evaluator-Bearbeitungen und aktualisiert `eval.yaml` nach der Bestätigung.
`eval list` und `eval show`	Evaluierungsläufe und -ergebnisse in der CLI einsehen.
`optimize --config eval.yaml`	Startet optional eine Optimierung auf Grundlage eines Auswertungsrezepts, nachdem der Agent und das Rezept die Voraussetzungen für die Optimierung erfüllen.

azd provision erstellt keine Bewertungsdatensätze, Bewerter, Suiten oder Optimierungsaufträge. Das Evaluierungs-Setup kann Generierungsarbeit beinhalten, die mehrere Minuten dauern kann, daher bleibt es explizit und kann bei Bedarf erneut ausgeführt werden.

Für gehostete Agenten erfordert die erste Evaluierung ein bereitgestelltes und aufrufbares Agent-Ziel. Für promptbasierte Agenten entfällt der Bereitstellungsschritt; der Agent muss bereits im Foundry-Projekt vorhanden und als Evaluierungsziel verfügbar sein.

Erstellen und Bereitstellen eines gehosteten Agents

Wenn Sie noch nicht über ein Projekt mit gehostetem Agent verfügen, initialisieren Sie ein Projekt mit azd:

azd ai agent init

Stellen Sie die Foundry-Ressourcen bereit, und stellen Sie den Agent bereit:

azd provision
azd deploy

Überprüfen Sie nach Abschluss der Bereitstellung, ob der Agent aufrufbar ist:

azd ai agent show

Der gehostete Agent muss bereitgestellt und abgerufen werden, bevor Sie Auswertungsressourcen initialisieren.

Nach einer erfolgreichen Bereitstellung schlägt die CLI eine Bewertung als expliziten nächsten Schritt vor:

Set up an evaluation suite to measure quality and impact in one step with `azd ai agent eval generate`

Um einen eingabeaufforderungsbasierten Agent auszuwerten, überspringen Sie die Erstellungs- und Bereitstellungsbefehle des gehosteten Agents. Fahren Sie mit dem nächsten Abschnitt fort, nachdem Sie bestätigt haben, dass der promptbasierte Agent im Foundry-Projekt vorhanden ist und als Auswertungsziel verfügbar ist.

Note

Die zielbasierte Auswertung ruft Ihren gehosteten Agent direkt auf. Es funktioniert mit Agents, die das Antwort- oder Aufrufprotokoll mit synchroner, nicht streamingbasierter Ausführung verwenden. Um Agents auszuwerten, die das A2A- oder Activity-Protokoll oder andere Ausführungsmuster wie lange ausgeführt oder gestreamt verwenden, bewerten Sie stattdessen die Ablaufverfolgungen, die Ihr Agent ausgibt. Siehe Ablaufverfolgungsauswertung.

Evaluierungsressourcen initialisieren

Führen Sie eval generate im azd-Arbeitsbereich oder im Agent-Projektordner aus:

azd ai agent eval generate

Ohne Kennzeichnungen startet der Befehl einen interaktiven Assistenten. Der Assistent erkennt das Agent-Ziel aus der azd-Umgebung und fordert anschließend zur Eingabe einer Anweisung für die Generierung auf, damit der Dienst nützliche Seed-Daten für die Auswertung und eine Bewertungsrubrik erstellen kann.

Beispiel für eine interaktive Ausgabe:

? Eval suite name: reservation-agent
? How would you like to provide the agent instruction?: Type inline
? Describe what this agent does and what scenarios to test: This agent handles restaurant reservations. Test booking, modification, cancellation, and policy enforcement.
? Include agent traces for evaluator generation?: No
? Select the model for evaluation and generation: gpt-4o (deployed)
? Max samples (between 15 and 1000): 100
  (–) Running  Evaluator generation  (evaluatorgen-reservation-agent-v3-abc12345)
  (–) Running  Dataset generation  (datagen-abc123456)
  (✓) Done  Evaluator generation  (20 seconds)
  (✓) Done  Dataset generation  (2m 9s)

Eval suite created
  Config:     src/reservation-agent/eval.yaml
  Dataset:    reservation-agent-dev-eval-seed (1.0)
              src/reservation-agent/datasets/reservation-agent-dev-eval-seed
  Evaluator:  builtin.task_adherence
  Evaluator:  reservation-agent-quality (1)
              src/reservation-agent/evaluators/reservation-agent-quality/rubric_dimensions.json

  Evaluator dimensions (4):
    Weight  Dimension
    ──────  ─────────
        10  booking_accuracy
         5  policy_enforcement
         6  cancellation_handling
         5  general_quality

  Portal:
    Dataset:   https://ai.azure.com/.../build/data/datasets/reservation-agent-dev-eval-seed/1.0
    Evaluator: https://ai.azure.com/.../build/evaluations/catalog/reservation-agent-quality/1

  Next steps:
    azd ai agent eval run
      Run the eval suite against your agent.
    azd ai agent eval update
      Edit the generated dataset or evaluator locally, then upload changes.

Übergeben Sie für die Skriptverwendung die Generierungseingaben direkt:

azd ai agent eval generate \
  --gen-instruction "This agent handles restaurant reservations. Test booking, modification, cancellation, and policy enforcement." \
  --eval-model gpt-4o \
  --max-samples 100

--out-file ist optional und hat standardmäßig den Wert eval.yaml im Stammverzeichnis des Agent-Projekts. Verwenden Sie --out-file <path>, um die Konfiguration an einen anderen Speicherort zu schreiben.

So verwenden Sie einen vorhandenen Datensatz und ausgewählte Auswerter:

azd ai agent eval generate \
  --dataset ./tests/support-golden.jsonl \
  --gen-instruction "Support quality, policy adherence, and escalation behavior" \
  --max-samples 50 \
  --evaluator builtin.intent_resolution \
  --evaluator support-quality \
  --out-file eval.yaml

Ersetzen Sie ./tests/support-golden.jsonl durch den Pfad zu Ihrem eigenen Auswertungsdatensatz.

Der --dataset Wert kann auf eine lokale Datei oder einen registrierten Datasetnamen verweisen. Wiederholen Sie diesen Vorgang --evaluator , um mehrere integrierte oder registrierte benutzerdefinierte Bewerter einzuschließen. Evaluatorverweise verwenden das Format <source>.<name>:

builtin.<name> — verweist auf einen integrierten Evaluator , der von Foundry bereitgestellt wird.
<name> — verweist auf einen benutzerdefinierten Evaluator , der im Foundry-Projekt registriert ist. Verwenden Sie den registrierten Namen des Evaluators ohne das Versionssuffix.

Generierung zurückstellen mit `--no-wait`

Falls die Generierung eines Datasets oder Evaluators zu lange dauert, verwenden Sie --no-wait, um Generierungsaufträge zu übermitteln und den Vorgang sofort zu beenden:

azd ai agent eval generate \
  --gen-instruction "..." \
  --no-wait

Die ausstehenden Vorgangs-IDs werden in eval.yaml geschrieben. Wenn Sie später ausführen azd ai agent eval run, werden diese Vorgänge automatisch fortgesetzt, bevor Sie die Auswertung starten.

Ein promptbasiertes Agentenziel verwenden

Wenn Sie Auswertungsressourcen für einen eingabeaufforderungsbasierten Agent initialisiert haben, können Sie den gleichen Auswertungsrezeptfluss verwenden. Der Bereitstellungsschritt für gehostete Agenten ist für promptbasierte Agenten nicht erforderlich.

Bevor Sie eine Auswertung ausführen, vergewissern Sie sich, dass:

Der prompt-basierte Agent ist im Foundry-Projekt verfügbar.
Der Agent ist als Auswertungsziel verfügbar.
Sie haben Zugriff auf den Projektendpunkt und das Agentziel.
eval.yaml wählt den vorgesehenen eingabeaufforderungsbasierten Agent aus.

Führen Sie Folgendes aus, um Agents auflisten zu können, die im aktuellen Foundry-Projekt verfügbar sind:

azd ai agent list

Verwenden Sie dann die gleichen Befehle, um die Auswertung auszuführen und zu überprüfen:

azd ai agent eval run --config eval.yaml
azd ai agent eval show

Eval.yaml überprüfen

Nachdem eval generate erfolgreich abgeschlossen wurde, öffnen Sie eval.yaml im Stammverzeichnis des Agent-Projekts. Beispiel:

src/reservation-agent/eval.yaml

Führen Sie eval run in diesem Verzeichnis aus, oder übergeben Sie den Pfad explizit mit --config src/reservation-agent/eval.yaml. Die Datei identifiziert das Agentziel, den Datasetverweis, die Evaluatorverweise und die Generierungsoptionen. Eine vereinfachte Form lautet:

name: reservation-agent
agent:
  name: reservation-agent
  kind: hosted
  version: "3"
  config: .agent_configs\baseline\metadata.yaml
dataset_reference:
  name: reservation-agent-dev-eval-seed
  version: "1.0"
  local_uri: datasets\reservation-agent-dev-eval-seed
evaluators:
  - builtin.task_adherence
  - name: reservation-agent-quality
    version: "1"
    local_uri: evaluators\reservation-agent-quality\rubric_dimensions.json
options:
  eval_model: gpt-4o
max_samples: 100

eval.yaml befindet sich im Stammverzeichnis des Agent-Projekts, z. B. src/<agent-name>/eval.yaml.
Generierte Datensätze befinden sich unter datasets/ und generierte Bewertungsrichtlinien für Evaluatoren unter evaluators/ im Agent-Ordner.
local_uri Pfade in eval.yaml sind relativ zum Agent-Projektverzeichnis.
Lokale Dateien, auf die local_uri verwiesen wird, können bearbeitet werden. Führen Sie azd ai agent eval update aus, um lokale Änderungen als neue Version im Dienst zu registrieren und die Version in eval.yaml zu erhöhen.
eval run verwendet die in eval.yaml festgelegte registrierte Version. Führen Sie eval update vor eval run aus, um lokale Bearbeitungen anzuwenden.
Bewerter können integrierte Referenzen (zum Beispiel builtin.task_adherence) oder generierte benutzerdefinierte Bewerter mit name, version und local_uri sein.
Behandeln Sie Versionsfelder als Zeichenfolgen, auch wenn sie numerisch aussehen, sodass das Rezept für YAML-Parser stabil bleibt.

Führen Sie die Auswertung durch

Führen Sie im Agent-Projektordner Folgendes aus:

azd ai agent eval run

Standardmäßig löst das argumentlose eval runeval.yaml im Stammverzeichnis des Agent-Projekts auf. Sie können den Konfigurationspfad auch explizit übergeben:

azd ai agent eval run --config eval.yaml

Wenn eval generate --no-wait ausstehende Generierungsvorgänge angelegt hat, setzt eval run diese Vorgänge fort, bevor sie den Auswertungsdurchlauf startet. Neue Dataset- oder Evaluator-Generierungsaufträge werden nicht von Grund auf neu gestartet.

Auswertungsläufe prüfen

Neueste Evaluierungsläufe auflisten:

azd ai agent eval list

Neueste Ausführung anzeigen:

azd ai agent eval show

Ohne Kennzeichnungen eval show werden standardmäßig die neueste Auswertung verwendet, und die zugehörigen Läufe werden aufgelistet.

Um die Details einer bestimmten Ausführung anzuzeigen, übergeben Sie die eval-ID als Argument und die Ausführungs-ID mit --eval-run-id. Kopieren Sie die Eval-ID aus der azd ai agent eval list Ausgabe und die Ausführungs-ID aus der azd ai agent eval show <eval-id> Ausgabe:

azd ai agent eval show <eval-id> --eval-run-id <run-id>

Verwenden Sie die Run-Ausgabe, um zu antworten:

Die Agent-Version, die ausgewertet wurde.
Welche Dataset- und Auswertungsversionen aufgelöst wurden.
Gibt an, ob die Ausführung abgeschlossen, fehlgeschlagen oder teilweise abgeschlossen ist.
Welche Metriken oder Bewertungsergebnisse erstellt wurden.
Ob Tokenverwendungs- oder Auswertungsprotokolle Untersuchung benötigen.

Erneute Ausführung nach dem Ändern des Agents

Nachdem Sie einen gehosteten Agent aktualisiert und erneut bereitgestellt haben, führen Sie das gleiche Auswertungsrezept erneut aus:

azd deploy
azd ai agent eval run --config eval.yaml

Bei promptbasierten Agenten aktualisieren Sie den Agent in Foundry und führen dann dasselbe Auswertungsrezept erneut aus.

Das erneute Ausführen desselben eval.yaml hilft dabei, Verweise auf Datensatz, Auswerter und Schwellenwert über Agentenänderungen hinweg stabil zu halten.

Aktualisieren, Zurücksetzen oder Reparieren von Auswertungsressourcen

Der Ablauf zur Agentenbewertung verwendet eval.yaml als lokales Auswertungsrezept. Verwenden Sie azd ai agent eval update, wenn Sie Dateien lokaler Datensätze oder Bewertungsrubriken bearbeiten und diese Änderungen als neue Dienstversionen registrieren möchten.

Um zu aktualisieren, welche Auswertungsausführung verwendet wird, wählen Sie den Pfad aus, der dem Änderungstyp entspricht:

Veränderung	So aktualisieren Sie
Ändern von Schwellenwerten, Evaluatorverweise, Ausgabeeinstellungen oder anderen Rezeptfeldern	Bearbeiten Sie `eval.yaml`, und führen Sie dann `azd ai agent eval run --config eval.yaml` aus.
Verwenden eines anderen lokalen oder registrierten Datasets	Bearbeiten Sie den Datensatzverweis in `eval.yaml`, oder führen Sie `azd ai agent eval generate --dataset <path-or-name> --out-file eval.yaml` erneut aus.
Hinzufügen oder Ändern von Bewertungsreferenzen	Bearbeiten Sie `eval.yaml`, oder führen Sie `azd ai agent eval generate` mit reproduzierbaren `--evaluator`-Werten erneut aus.
Lokale Bearbeitungen an einem generierten Datensatz oder einer Bewertungsrubrik registrieren	Führen Sie `azd ai agent eval update`aus, überprüfen Sie die erkannten Änderungen, und bestätigen Sie das Versionsreferenzupdate in `eval.yaml`.
Beginnen Sie erneut mit der standardmäßig generierten Konfiguration	Führen Sie `azd ai agent eval generate --reset-defaults` aus.

Führen Sie z. B. nach dem Bearbeiten einer generierten Evaluator-Rubrik im evaluators/ Agentordner Folgendes aus:

azd ai agent eval update
azd ai agent eval run --config eval.yaml

Mit dem Befehl "Aktualisieren" werden neue registrierte Dataset- oder Auswertungsversionen erstellt. Vorhandene Auswertungsläufe bleiben an die ursprünglich verwendeten Versionen gebunden.

Wenn eval.yaml bereits vorhanden ist, erkennt eval generate dies und gibt die vorhandene Konfiguration aus:

Eval config already exists: src/reservation-agent/eval.yaml
  Dataset:    reservation-agent-dev-eval-seed (1.0)
              src/reservation-agent/datasets/reservation-agent-dev-eval-seed
  Evaluator:  builtin.task_adherence
  Evaluator:  reservation-agent-quality (1)
              src/reservation-agent/evaluators/reservation-agent-quality/rubric_dimensions.json

  To run the evaluation:
    azd ai agent eval run

  To update local edits as new versions:
    azd ai agent eval update

  To overwrite and regenerate:
    azd ai agent eval generate --reset-defaults

Führen Sie Folgendes aus, um die lokale Konfiguration zu überschreiben und die Standardauswertungsressourcen neu zu generieren:

azd ai agent eval generate --reset-defaults

--reset-defaults überschreibt das lokale eval.yaml und generiert die Standard-Evaluierungsressourcen erneut. Vorhandene beim Dienst registrierte Datensätze und Evaluator-Versionen werden nicht gelöscht; nur das lokale Rezept wird ersetzt.

Verlassen Sie sich nicht darauf, dass entfernte neueste Versionen das lokale Rezept stillschweigend ändern. Der lokale eval.yaml zeichnet die vom Rezept verwendeten Versionen des Datasets, des Evaluators oder der Suite auf, um die Reproduzierbarkeit zu gewährleisten.

Optional: Optimierung vom Auswertungssignal starten

Nachdem mindestens ein Bewertungslauf erfolgreich abgeschlossen wurde, können Sie eval.yaml als Eingabe für die Agentoptimierung verwenden, wenn der Agent und das Rezept die Voraussetzungen für die Optimierung erfüllen.

Bevor Sie mit der Optimierung beginnen, vergewissern Sie sich, dass:

Das Agent-Ziel ist zur Optimierung bereit. Für gehostete Agenten wird der Agent bereitgestellt und kann aufgerufen werden.
eval.yaml verweist auf die beabsichtigten Agent-, Dataset-, Evaluator-Versionen und Schwellenwerte.
Mindestens eine Auswertung wurde erfolgreich ausgeführt.
Die vom Optimierer erforderliche Agentvorbereitung ist abgeschlossen. Informationen zu Optimierervoraussetzungen und Agentvorbereitungsanforderungen finden Sie unter Optimieren von Agent-Eingabeaufforderungen mit Prompt Optimizer.

Führen Sie dann Folgendes aus:

azd ai agent optimize --config eval.yaml

Der Befehl "Optimieren" liest das Agentziel, das Dataset, die Auswertungen und Schwellenwerte aus eval.yaml. Es übermittelt einen Optimierungsauftrag, wendet jedoch weder stillschweigend Änderungen am Quellcode an noch stellt es den Kandidaten-Agenten erneut bereit. Überprüfen Sie alle Ausgaben des Optimierers, bevor Sie Änderungen übernehmen.

Bewährte Methoden

Führen Sie azd ai agent eval generate erst aus, nachdem der Agent als Evaluierungsziel verfügbar ist. Für gehostete Agents muss der Agent bereitgestellt und abgerufen werden können.
Beginnen Sie mit einem kleinen generierten Dataset oder einer kleinen Teilmenge Ihres goldenen Datasets.
Überprüfen Sie den generierten Datensatz und die Artefakte der Evaluator-Überprüfung, bevor Sie den Bewertungen vertrauen.
Nach der Bearbeitung generierter Datensätze oder Evaluator-Dateien führen Sie azd ai agent eval update aus, um die bearbeiteten Ressourcen zu registrieren, bevor Sie die Auswertung erneut ausführen.
Verwenden Sie eine Quellcodeverwaltung für eval.yaml, wenn Ihr Team ein bewertbares, reproduzierbares Auswertungsrezept wünscht.
Ziehen Sie die Quellenkontrolle generierter Datasets und Bewertungsrubriken unter datasets/ und evaluators/ im Agentordner in Betracht, wenn Ihr Team sie im Rahmen des Auswertungsrezepts überprüft und bearbeitet.
Führen Sie nach Änderungen am Agenten denselben eval.yaml erneut aus, damit für Vergleiche dasselbe Testrezept verwendet wird.
Verwenden Sie azd ai agent optimize --config eval.yaml nur, nachdem Sie ein nützliches Baseline-Bewertungsergebnis haben und der Agent für eine Optimierung bereit ist.

Einschränkungen

Der primäre Befehlsfluss ist für gehostete Agents und die Auswertungsschleife nach der Bereitstellung optimiert.
azd provision erstellt keine Auswertungsressourcen.
eval run generiert keine neuen Datasets oder Auswertungen, mit Ausnahme der Fortsetzung ausstehender Vorgänge aus eval generate --no-wait.
Der vollständige Lebenszyklus der Suite, geplante Evaluierung, kontinuierliche Evaluierung, Warnungen und Vergleichs-Workflows sind für den ersten Evaluierungspfad nicht erforderlich.

Feedback

War diese Seite hilfreich?

Last updated on 2026-06-19