Köra agentutvärderingar med azd CLI (förhandsversion)

Important

Objekt markerade (förhandsversion) i den här artikeln är för närvarande i offentlig förhandsversion. Den här förhandsversionen tillhandahålls utan ett serviceavtal och vi rekommenderar det inte för produktionsarbetsbelastningar. Vissa funktioner kanske inte stöds eller kan vara begränsade. Mer information finns i Kompletterande villkor för användning av Microsoft Azure-förhandsversioner.

Använd utvärderingsfunktionen i Azure Developer CLI (azd) för att lägga till en mätbar kvalitetsloop till en agent som har skapats med Microsoft Foundry. Den här artikeln fokuserar på livscykeln för värdbaserad agent i azd, där du skapar, etablerar, distribuerar, initierar utvärderingstillgångar, kör en första utvärdering, inspekterar körningen och återanvänder utvärderingsreceptet för senare körningar.

Prompt-baserade agenter kan också utvärderas när de är tillgängliga som agentmål i Foundry-projektet. Distributionsstegen för värdbaserad agent gäller endast för värdbaserade agenter.

Den här artikeln beskriver hur du kör den första agentutvärderingen med azd ai agent eval generate och azd ai agent eval run.

Förutsättningar

En Azure-prenumeration med åtkomst till Microsoft Foundry.
CLI för Azure Developer (azd). Installationsinstruktioner finns i Installera Azure Developer CLI.
Tillägget azd ai agent, version 0.1.40-preview eller senare, är installerat (azd ext install azure.ai.agents). Om du inte har installerat tillägget installeras det automatiskt när du initierar startmallen eller kör azd ai agent. Kör azd ext list för att verifiera den installerade versionen och kör azd ext upgrade azure.ai.agents om du behöver uppgradera. Mer information om AI-agenttillägget azd finns i Microsoft Foundry-agenttillägget.
En autentiserad azd-session. Om du vill kontrollera autentiseringsstatusen kör du azd auth status. Om du inte är inloggad kör du azd auth login.
Rollen Foundry User på Foundry-resursen (hette tidigare Azure AI User). Mer information finns i Rollbaserad åtkomstkontroll för Microsoft Foundry.
För värdbaserade agenter: Inget befintligt Foundry-projekt krävs. azd ai agent init och azd provision skapar nödvändiga resurser.
För promptbaserade agenter: Ett befintligt Foundry-projekt med agenten redan distribuerad och tillgänglig som utvärderingsmål.
En modelldistribution som stöder chattavslut i samma Foundry-projekt.
Valfritt: en JSONL-utvärderingsdatauppsättning med representativa exempel om du inte vill eval generate generera en rökdatauppsättning.

Så här fungerar utvärderingar av azd-agenter

Den primära utvärderingsmiljön för azd CLI är utformad för den värdbaserade agentens livscykel:

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

Utvärderingsflödet innehåller följande artefakter och kommandon.

Item	Description
`eval generate`	Skapar eller reparerar lokala utvärderingsresurser för en målagent.
`eval.yaml`	Recept för lokal utvärdering som kan köras. Den registrerar mål för agenten, datauppsättningsreferens, referenser till utvärderare och generationsalternativ
Genererade lokala artefakter	Redigerbara lokala kopior av genererade datauppsättningar och utvärderings rubriceringar. Artefakterna lagras under `datasets/` och `evaluators/` i agentmappen (till exempel `src/<agent-name>/datasets/` och `src/<agent-name>/evaluators/`).
Registrerade tjänstartefakter	Foundry-datasetet och versionerna av utvärderaren som används i utvärderingskörningar. Dessa utgör den auktoritativa källan för genererade resurser.
`eval run`	Kör utvärderingsreceptet mot det valda agentmålet.
`eval update`	Registrerar nya tjänstversioner från lokal datauppsättning eller ändringar från utvärderaren och uppdaterar `eval.yaml` efter bekräftelse.
`eval list` och `eval show`	Granska utvärderingskörningar och resultat från CLI.
`optimize --config eval.yaml`	Du kan också starta optimering från ett utvärderingsrecept efter att agenten och receptet uppfyller optimeringskraven.

azd provision skapar inte utvärderingsdatauppsättningar, utvärderare, sviter eller optimeringsjobb. Utvärderingskonfigurationen kan omfatta genereringsjobb som tar flera minuter, så den är explicit och går att köra om.

För värdbaserade agenter kräver den första utvärderingen ett distribuerat och anropat agentmål. Distributionssteget gäller inte för promptbaserade agenter. agenten måste redan finnas i Foundry-projektet och vara tillgänglig som ett utvärderingsmål.

Skapa och distribuera en värdbaserad agent

Om du inte redan har ett värdbaserat agentprojekt initierar du ett med azd:

azd ai agent init

Etablera Foundry-resurser och distribuera agenten:

azd provision
azd deploy

När distributionen är klar kontrollerar du att agenten kan anropas:

azd ai agent show

Den värdbaserade agenten måste distribueras och anropas innan du initierar utvärderingstillgångar.

Efter en lyckad distribution föreslår CLI utvärdering som ett explicit nästa steg:

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

Om du vill utvärdera en promptbaserad agent hoppar du över kommandona för att skapa och distribuera värdbaserade agenter. Fortsätt till nästa avsnitt när du har bekräftat att den promptbaserade agenten finns i Foundry-projektet och är tillgänglig som utvärderingsmål.

Note

Målbaserad utvärdering anropar din värdbaserade agent direkt. Det fungerar med agenter som använder svars- eller anropsprotokollet med synkron körning utan strömning. För att utvärdera agenter som använder A2A- eller Activity-protokollet, eller andra körningsmönster som långvariga eller strömmande, ska du i stället utvärdera de spår som agenten genererar. Se Spårningsutvärdering.

Initialisera resurser för utvärdering

Kör eval generate från azd-arbetsytan eller agentprojektmappen:

azd ai agent eval generate

Utan flaggor startar kommandot en interaktiv guide. Guiden identifierar agentmålet från azd-miljön och ber sedan om en instruktion för generering så att tjänsten kan skapa användbara startdata för utvärdering och en bedömningsmatris.

Exempel på interaktiva utdata:

? 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.

För skriptad användning skickar du generationsindata 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 är valfritt och standardvärdet är eval.yaml i agentprojektroten. Använd --out-file <path> för att skriva konfigurationen till en annan plats.

Så här använder du en befintlig datauppsättning och valda utvärderare:

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

Ersätt ./tests/support-golden.jsonl med sökvägen till din egen utvärderingsdatauppsättning.

Värdet --dataset kan peka på en lokal fil eller ett registrerat datauppsättningsnamn. Upprepa --evaluator för att inkludera flera inbyggda eller registrerade anpassade utvärderare. Utvärderarreferenser använder formatet <source>.<name>:

builtin.<name> – refererar till en inbyggd utvärderare som tillhandahålls av Foundry.
<name> – refererar till en anpassad utvärderare som är registrerad i Foundry-projektet. Använd utvärderarens registrerade namn utan versionssuffixet.

Skjut upp generering med `--no-wait`

Om datauppsättningen eller utvärderargenereringen tar för lång tid kan du använda --no-wait för att skicka generationsjobb och avsluta omedelbart:

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

De väntande åtgärds-ID:na skrivs till eval.yaml. När du senare kör azd ai agent eval runåterupptas dessa åtgärder automatiskt innan utvärderingskörningen startas.

Använd en promptbaserad målagent

Om du initierade utvärderingstillgångar för en prompt-baserad agent kan du använda samma utvärderingsreceptflöde. Distributionssteget för värdbaserad agent krävs inte för promptbaserade agenter.

Innan du kör en utvärdering kontrollerar du att:

Den promptbaserade agenten finns i Foundry-projektet.
Agenten är tillgänglig som ett utvärderingsmål.
Du har åtkomst till projektslutpunkten och agentmålet.
eval.yaml väljer den avsedda promptbaserade agenten.

Om du vill visa agenter som är tillgängliga i det aktuella Foundry-projektet kör du:

azd ai agent list

Använd sedan samma kommandon för att köra och inspektera utvärderingen:

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

Granska eval.yaml

När eval generate har slutförts öppnar du eval.yaml i agentprojektets rotkatalog. Ett exempel:

src/reservation-agent/eval.yaml

Kör eval run från den här katalogen eller skicka sökvägen explicit med --config src/reservation-agent/eval.yaml. Filen identifierar agentmålet, datamängdsreferensen, utvärderarreferenser och alternativ för generering. En förenklad form är:

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 bor på agentprojektroten, till exempel src/<agent-name>/eval.yaml.
Genererade datauppsättningar finns under datasets/ och genererade utvärderingskriteriet finns under evaluators/ i agentmappen.
local_uri sökvägar i eval.yaml är relativa till agentens projektkatalog.
Lokala filer som refereras av local_uri kan redigeras. Kör azd ai agent eval update för att registrera lokala ändringar som en ny version i tjänsten och uppdatera versionsnumret i eval.yaml.
eval run använder den registrerade versionen som är fäst i eval.yaml. Om du vill tillämpa lokala redigeringar kör du eval update före eval run.
Utvärderare kan vara inbyggda referenser (till exempel builtin.task_adherence) eller genererade anpassade utvärderare med name, versionoch local_uri.
Behandla versionsfält som strängar, även om de ser numeriska ut, så receptet förblir stabilt mellan YAML-parsare.

Kör utvärderingen

Från agentprojektmappen kör du:

azd ai agent eval run

Som standard löses eval run nollargument eval.yaml i agentprojektroten. Du kan också uttryckligen ange sökvägen till konfigurationen:

azd ai agent eval run --config eval.yaml

Om eval generate --no-wait skapade väntande genereringsoperationer återupptar eval run dessa operationer innan den startar utvärderingskörningen. Den startar inte nya datauppsättnings- eller utvärderargenereringsjobb från grunden.

Inspektera utvärderingskörningar

Lista de senaste utvärderingskörningarna:

azd ai agent eval list

Visa den senaste körningen:

azd ai agent eval show

Utan några flaggor används eval show som standard för den senaste utvärderingen och listar dess körningar.

Om du vill visa detaljerna för en specifik körning anger du eval-ID:t som ett argument och körnings-ID:t med --eval-run-id. Kopiera eval-ID:t från azd ai agent eval list utdata och körnings-ID:t från azd ai agent eval show <eval-id> utdata:

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

Använd utdata från körningen för att svara:

Vilken agentversion utvärderades.
Vilka datauppsättnings- och utvärderarversioner fastställdes?
Om körningen slutfördes, misslyckades eller slutfördes delvis.
Vilka mätvärden eller utvärderingspoäng som genererades.
Om tokenanvändning eller utvärderingsloggar behöver undersökas.

Kör igen när agenten har ändrats

När du har uppdaterat och distribuerat om en värdbaserad agent kör du samma utvärderingsrecept igen:

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

För promptbaserade agenter uppdaterar du agenten i Foundry och kör sedan samma utvärderingsrecept igen.

Att köra om samma eval.yaml hjälper till att hålla referenser till datamängd, evaluator och tröskelvärde stabila vid ändringar av agenten.

Uppdatera, återställa eller reparera utvärderingstillgångar

Agentutvärderingsflödet använder eval.yaml som recept för lokal utvärdering. Använd azd ai agent eval update när du redigerar lokala datamängdsfiler eller utvärderingskriteriet och vill registrera dessa ändringar som nya tjänstversioner.

Om du vill uppdatera vad en utvärderingskörning använder väljer du den sökväg som matchar typen av ändring:

Change	Så här uppdaterar du
Ändra tröskelvärden, utvärderarreferenser, utdatainställningar eller andra receptfält	Redigera `eval.yaml` och kör sedan `azd ai agent eval run --config eval.yaml`.
Använda en annan lokal eller registrerad datauppsättning	Redigera referensen till datauppsättningen i `eval.yaml`, eller kör `azd ai agent eval generate --dataset <path-or-name> --out-file eval.yaml` igen.
Lägga till eller ändra utvärderarreferenser	Redigera `eval.yaml`eller kör `azd ai agent eval generate` igen med repeterbara `--evaluator` värden.
Registrera lokala redigeringar till en genererad datauppsättning eller utvärderings rubricering	Kör `azd ai agent eval update`, granska de identifierade ändringarna och bekräfta versionsreferensuppdateringen i `eval.yaml`.
Börja om från den standardgenererade konfigurationen	Kör `azd ai agent eval generate --reset-defaults`.

När du till exempel har redigerat ett genererat utvärderingsämne under evaluators/ i agentmappen kör du:

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

Uppdateringskommandot skapar nya registrerade datauppsättnings- eller utvärderarversioner. Befintliga utvärderingskörningar är fortfarande knutna till de versioner som de ursprungligen använde.

När eval.yaml redan finns upptäcker eval generate den och skriver ut den befintliga konfigurationen:

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

Om du vill skriva över den lokala konfigurationen och återskapa standardutvärderingstillgångarna kör du:

azd ai agent eval generate --reset-defaults

--reset-defaults skriver över den lokala eval.yaml och återskapar standardutvärderingstillgångarna. Befintliga tjänstregistrerade datauppsättningar och utvärderingsversioner tas inte bort. endast det lokala receptet ersätts.

Lita inte på att de senaste fjärrversionerna ändrar det lokala receptet tyst. Den lokala eval.yaml dokumenterar versionerna av datauppsättningen, utvärderaren eller sviten som används i receptet för att säkerställa reproducerbarhet.

Valfritt: Starta optimering från utvärderingssignal

När minst en utvärderingskörning har slutförts kan du använda eval.yaml som indata till agentoptimering om agenten och receptet uppfyller optimeringskraven.

Innan du påbörjar optimeringen kontrollerar du att:

Agentmålet är redo för optimering. För värdbaserade agenter är agenten distribuerad och kan anropas.
eval.yaml refererar till den avsedda agenten, datauppsättningen, utvärderingsversionerna och tröskelvärdena.
Minst en utvärderingskörning har slutförts.
De agentförberedelser som krävs av optimeraren är slutförda. För krav för optimerare och krav på agentförberedelse, se Optimera agentprompter med Prompt Optimizer.

Kör sedan:

azd ai agent optimize --config eval.yaml

Kommandot optimize läser agentmålet, datamängden, utvärderarna och tröskelvärdena från eval.yaml. Den skickar in ett optimeringsjobb, men tillämpar inte källändringar i bakgrunden eller driftsätter om kandidatagenten. Granska eventuella utdata från optimeraren innan du tillämpar ändringar.

Metodtips

Kör azd ai agent eval generate endast när agenten är tillgänglig som mål för utvärdering. För värdbaserade agenter måste agenten distribueras och anropas.
Börja med en liten genererad datamängd eller en liten delmängd av din gyllene datauppsättning.
Kontrollera den genererade datamängden och utvärderarens granskningsartefakter innan du litar på resultaten.
När du har redigerat genererade datamängder eller utvärderarfiler kör du azd ai agent eval update för att registrera de redigerade tillgångarna innan du kör utvärderingen igen.
Källkontroll eval.yaml om ditt team vill ha ett granskningsbart, reproducerbart utvärderingsrecept.
Överväg att versionshantera genererade datauppsättningar och bedömningsmatriser för utvärderare under datasets/ och evaluators/ i agentmappen om ditt team granskar och redigerar dem som en del av utvärderingsprocessen.
Kör samma eval.yaml sak igen efter att agenten har ändrats så att jämförelser använder samma testrecept.
Använd azd ai agent optimize --config eval.yaml endast när du har ett användbart baslinjeutvärderingsresultat och agenten är förberedd för optimering.

Limitations

Det primära kommandoflödet är optimerat för värdbaserade agenter och utvärderingsloopen efter distributionen.
azd provision skapar inte utvärderingstillgångar.
eval run genererar inte nya datauppsättningar eller utvärderare, förutom för att återuppta väntande åtgärder från eval generate --no-wait.
Fullständig livscykel för sviter, schemalagd utvärdering, kontinuerlig utvärdering, aviseringar och jämförelsearbetsflöden krävs inte för den första utvärderingsvägen.

Feedback

Var den här sidan till hjälp?

Last updated on 2026-06-19