Agentevaluaties uitvoeren met de azd CLI (preview)

Gebruik de azd ai eval extensie om een gemeten kwaliteitslus toe te voegen aan een agent die is gebouwd met Microsoft Foundry. U maakt een evaluatie naast uw project, genereert eventueel een gegevensset en een rubrieks evaluator, voert de evaluatie uit op uw agent en leest de resultaten zonder de terminal te verlaten.

Dezelfde evaluatie kan vanuit een pipeline worden uitgevoerd en --fail-on zet de resultaten om in een build gate.

In dit artikel wordt de eerste evaluatie behandeld met azd ai eval init en azd ai eval run start.

Prerequisites

• Een Azure-abonnement met toegang tot Microsoft Foundry.
• De Azure Developer CLI (azd), versie 1.27.1 of hoger. Zie Install the Azure Developer CLI voor installatie-instructies.
• De azd ai eval extensie: azd extension install azure.ai.evaluations. Voer deze opdracht uit azd extension list --installed om de geïnstalleerde versie te controleren.
• Een geverifieerde azd sessie. Voer azd auth status uit om uw authenticatiestatus te controleren. Als u niet bent aangemeld, voert u het volgende uit azd auth login.
• De rol Foundry User op de Foundry-resource (voorheen Azure AI User genoemd). Zie rolgebaseerde toegangscontrole voor Microsoft Foundry voor meer informatie.
• Een Foundry-project en een te evalueren agent. Om init het doel te laten detecteren, moet de agent als een service worden gedeclareerd in de azd ai agent init van het project, zoals azure.yaml dat doet. Geef het anders een naam met --target. Zie Gehoste agents voor gehoste agents.
• Een modelimplementatie die ondersteuning biedt voor chatvoltooiingen in hetzelfde project. De beoordelaars oordelen ermee.
• Optioneel: een JSONL-gegevensset met representatieve voorbeelden, als u niet wilt dat generate er een synthetiseert.

Werking van azd-evaluaties

Een evaluatie wordt beschreven door een bestand, evals/azure.eval.yamldat u kunt lezen, bewerken en doorvoeren. De opdrachten schrijven dat bestand of werken met wat daarin is gedeclareerd.

azd ai eval init          # scaffold the configuration. Makes no service calls
azd ai eval generate      # optional: synthesize a dataset and a rubric evaluator
azd ai eval create        # register the eval in the Foundry project
azd ai eval run start     # run it and summarize the results

Elke opdracht accepteert -o json voor het uitvoeren van scripts en --debug voor diagnostische gegevens. Elke opdracht behalve init accepteert --project-endpoint.

Kiezen waar de rijen vandaan komen

Een evaluatie beoordeelt rijen. Ze komen van een van de twee plaatsen en deze beslissing is de eerste beslissing:

• --source traces evalueert wat uw agent al heeft gedaan, gelezen uit de traceringen die zijn verzonden. Niets om te schrijven.
• --source dataset evalueert een vaste set voorbeelden, ofwel die van u of gegenereerd. Herhaalbaar en vergelijkbaar in agentversies.

Evaluaties op basis van traces vereisen een agent die traces uitstuurt. Evaluaties van gegevenssetbronnen hebben een .jsonl bestand of een geregistreerde gegevensset nodig.

Zet de evaluatie op

Voer init uit vanuit de hoofdmap van uw project:

azd ai eval init

Zonder vlaggen detecteert init de agent wanneer azure.yaml er één opgeeft, vraagt het wanneer er meerdere worden opgegeven, en vraagt het met welke modeldeployment de graders moeten beoordelen en welke evaluatoren moeten worden gebruikt. Het schrijft evals/azure.eval.yaml en voegt een evaluatieservice toe aan azure.yaml. Er worden geen service-aanroepen gedaan, dus het is veilig om uit te voeren voordat er iets wordt geïmplementeerd.

In een project waarin geen agentservice is opgegeven, stopt init in plaats van te gokken:

ERROR: this project declares no agent service to evaluate. Add one, or name an existing agent with --target

Geef de agent in dat geval zelf een naam via --target.

Voor gebruik met scripts geeft u de beslissingen rechtstreeks door:

azd ai eval init \
  --source traces \
  --target support-agent \
  --judge-model gpt-4.1-nano \
  --name support-trace-eval \
  --no-prompt

Ga als volgende te werk om een gegevensset te evalueren die u al hebt:

azd ai eval init \
  --source dataset \
  --target support-agent \
  --dataset ./tests/support-golden.jsonl \
  --evaluator builtin.intent_resolution,builtin.task_adherence \
  --judge-model gpt-4.1-nano

--dataset gebruikt een lokaal .jsonl pad of de naam van een geregistreerde gegevensset. --evaluator is herhaalbaar en door komma's gescheiden; builtin.<name> verwijst naar een ingebouwde evaluator en een lege naam verwijst naar een aangepaste evaluator die is geregistreerd in het project. Door --evaluator door te geven, vervangt u de standaardinstellingen en ziet u ook af van rubricgeneratie.

De ingebouwde namen detecteren:

azd ai eval evaluator list --builtin

Een gegevensset en een evaluator genereren

Als u geen gegevensset hebt of als u een rubriek wilt schrijven voor deze agent in plaats van een algemene, genereert u deze:

azd ai eval generate \
  --target support-agent \
  --generation-model gpt-4.1-nano \
  --agent-instruction "Handles support requests. Test triage, policy adherence, and escalation."

Standaard genereert dit zowel een gegevensset als een rubrieks evaluator, downloadt deze onder evals/en voegt een catalogusvermelding voor elk item toe aan evals/azure.eval.yaml. Vermal deze met --dataset of --evaluator genereer er slechts één en maak de rijen af met --max-samples (15 tot 1000, standaard 15).

generate verzendt taken die kostenmodeloproepen aanroepen. De instructie is belangrijk: het is wat de service gebruikt om te bepalen waar de rijen en rubrieken over gaan, dus beschrijf wat de agent doet en wat moet worden getest.

Een catalogusvermelding declareert het artefact; het bepaalt niet welke evaluatie deze gebruikt. Na evals/azure.eval.yaml, opent u generate en controleert u of de eval die u wilt uitvoeren verwijst naar wat er is geproduceerd — een op traces gebaseerde eval leest traces, dus een gegenereerde dataset wordt pas gebruikt zodra een eval ernaar verwijst:

datasets:
    - name: support-agent-dataset
      source: ./datasets/support-agent-dataset.jsonl
evals:
    - name: support-agent-eval
      dataset: support-agent-dataset   # point the eval at the generated dataset

Ga als volgt te werk om de taken in te dienen en later terug te komen:

azd ai eval generate --target support-agent --generation-model gpt-4.1-nano --no-wait
azd ai eval job list --dataset
azd ai eval job show <job-id> --dataset

--dataset en job op --evaluator kiezen op welke verzameling de actie moet worden uitgevoerd, en een ervan is vereist.

Azure.eval.yaml controleren

init schrijft een bestand dat u wilt lezen. Een op traces gebaseerde evaluatie ziet er als volgt uit:

evals:
    - name: support-trace-eval
      description: Basic quality evaluation for support-agent
      source:
        type: traces
        max_traces: 20
        agent_name: support-agent
      evaluation_level: turn
      evaluators:
        - evaluator: builtin.task_adherence
          initialization_parameters:
            model: gpt-4.1-nano

Een evaluatie op basis van een dataset noemt de dataset in plaats van een tracebron en registreert op welke agent deze is gericht:

datasets:
    - name: support-golden
      source: ../tests/support-golden.jsonl
evals:
    - name: support-agent-eval
      description: Basic quality evaluation for support-agent
      dataset: support-golden
      evaluation_level: turn
      evaluators:
        - evaluator: builtin.intent_resolution
          initialization_parameters:
            model: gpt-4.1-nano
        - evaluator: builtin.task_adherence
          initialization_parameters:
            model: gpt-4.1-nano
      target:
        type: agent
        name: support-agent

Paden onder source: zijn relatief ten opzichte van het configuratiebestand. De gegenereerde .jsonl en evaluator JSON zijn gewone bestanden: bewerk ze en voer vervolgens opnieuw uit create om een nieuwe versie te registreren.

Voer dit bestand door. Het is het reproduceerbare deel van de evaluatie.

De evaluatie maken en uitvoeren

Gebruik create dit om alles te registreren wat de configuratie declareert: gegevenssets, evaluators en de evaluatie zelf:

azd ai eval create

Voer het vervolgens uit:

azd ai eval run start

run start wacht standaard op de run en toont een tabel met resultaten per evaluator, inclusief een slagingspercentage en een gemiddelde score, plus een link naar de run in het portaal. Gebruik --no-wait om te verzenden en te retourneren, en --max-samples om het aantal verzonden rijen te beperken.

Als de configuratie meer dan één eval opgeeft, geef dan aan welke u bedoelt:

azd ai eval run start --eval support-trace-eval

De resultaten controleren

De samenvatting laat zien of de kwaliteit is veranderd. In de rijen per voorbeeld ziet u waarom:

azd ai eval run output list --eval support-trace-eval
azd ai eval run output list --eval support-trace-eval --failed-only

Om runs in de tijd te bekijken en te zien wat de service voor één evaluatie bijhoudt:

azd ai eval list
azd ai eval run list --eval support-trace-eval
azd ai eval show support-trace-eval

show retourneert de identiteit van de eval in het project: id, naam en wanneer deze is gemaakt. Wat de eval doet is in je evals/azure.eval.yaml.

run list heeft één passfrequentie per uitvoering. De uitsplitsing per evaluator staat in -o json, onder per_testing_criteria_results, omdat een kolom per evaluator niet langer leesbaar is zodra runs door verschillende evaluators worden beoordeeld.

De resultaten elders gebruiken:

azd ai eval run output list --eval support-trace-eval --output-file rows.json
azd ai eval run output export --eval support-trace-eval --format csv --output-file summary.csv

De twee verschillen, en dat verschil is van belang: run output list --output-file schrijft de rijen per sample, terwijl run output export één regel per run schrijft — de totalen achter de samenvatting.

Een build blokkeren

Geef --fail-on door om van de run een controle te maken. Het proces wordt afgesloten met een niet-nul afsluitcode wanneer de uitvoering de drempelwaarde niet haalt. Zo keurt een pipeline een wijziging af die de kwaliteit heeft verslechterd:

azd ai eval run start --fail-on pass-rate=0.8
azd ai eval run start --fail-on any-failure

Zonder --fail-on eindigt een voltooide run met mislukte tests nog steeds met exitcode 0. Samples die falen zijn de verwachte uitvoer van een goed functionerende evaluatie en niet van een fout in de tool, daarom is deze controle opt-in.

pass-rate neemt een getal tussen 0 en 1. Een drempelwaarde die er geen is, wordt geweigerd voordat de run wordt ingediend, dus een verkeerd getypte gate kost niets.

--fail-on vereist een uitvoering die is afgerond. Op run show, koppel het aan --wait.

Evaluaties implementeren met de rest van het project

init voegt een evaluatieservice toe aan azure.yaml, zodat de evaluatie deel uitmaakt van het project in plaats van een losstaand artefact te zijn:

azd up

Dat zet het project op en registreert de gedeclareerde datasets, evaluators en evals, hetzelfde werk dat azd ai eval create zelf doet.

De agent wijzigen en opnieuw evalueren

Nadat u de agent hebt gewijzigd en opnieuw hebt geïmplementeerd, voert u dezelfde evaluatie opnieuw uit:

azd deploy
azd ai eval run start --eval support-trace-eval

Als u dezelfde evaluatie opnieuw gebruikt, blijven de gegevensset, evaluators en drempelwaarden vast, dus de vergelijking gaat over de agent.

Als u wilt wijzigen wat de evaluatie meet, bewerkt u evals/azure.eval.yaml of de gegenereerde artefacten onder evals/ en voert u create vervolgens opnieuw uit. create registreert een nieuwe versie van alles wat is veranderd en laat eerdere runs gekoppeld aan de versies die ze gebruikten.

Beste praktijken

• Begin met --source traces als de agent al actief is en traces uitstuurt. Het meet wat er is gebeurd, en je hoeft niets te definiëren.
• Ga naar --source dataset zodra u een vaste set cases wilt die u kunt vergelijken met verschillende versies.
• Lees de gegenereerde gegevensset en rubriek voordat u de scores vertrouwt. generate genereert die op basis van de instructie die u geeft, dus een vage instructie levert vage rijen op.
• Gebruik meer dan één evaluator. Met één criterium wordt het getal verplaatst zonder u te vertellen waarom.
• Doorvoeren evals/azure.eval.yaml en de gegenereerde artefacten, zodat de evaluatie kan worden beoordeeld.
• Gebruik --fail-on als kwaliteitsdrempel in CI, en stel de drempel zo in dat een echte regressie deze activeert.

Limitations

• De extensie is in preview en het opdrachtoppervlak kan worden gewijzigd.
• generate dient gefactureerde taken in. Gegevenssets en evaluatoren worden niet aangemaakt door azd provision.
• Een op traces gebaseerde evaluatie kan alleen traces lezen die de agent al heeft gegenereerd.
• azd vouwt de afsluitcode van een extensie samen, dus een poortlek en een operationele fout komen beide voor als een niet-nul uitgang. Lees het gatebericht om ze van elkaar te onderscheiden.

Verwante inhoud

• Uw agents evalueren
• Ingebouwde evaluatoren
• Aangepaste beoordelaars
• Traceringsevaluatie
• Tracering instellen voor uw agent
• Agents monitoren met het Agent Monitoring Dashboard