Agentevaluaties uitvoeren met de azd CLI (preview)

Gebruik de CLI-evaluatie-ervaring Azure Developer CLI (azd) om een gemeten kwaliteitslus toe te voegen aan een agent die is gemaakt met Microsoft Foundry. Dit artikel richt zich op de levenscyclus van de gehoste agent in azd, waarin u evaluatieassets maakt, inricht, implementeert, initialiseert, een eerste evaluatie uitvoert, de uitvoering inspecteert en het evaluatierecept opnieuw gebruikt voor latere uitvoeringen.

Promptgebaseerde agents kunnen ook worden geëvalueerd wanneer ze beschikbaar zijn als doelen voor agents in het Foundry-project. De implementatiestappen voor gehoste agents zijn alleen van toepassing op gehoste agents.

In dit artikel wordt beschreven hoe u de eerste evaluatie van de agent uitvoert met azd ai agent eval generate en azd ai agent eval run.

Prerequisites

• Een Azure-abonnement met toegang tot Microsoft Foundry.
• De Azure Developer CLI (azd). Zie Install the Azure Developer CLI voor installatie-instructies.
• De azd ai agent extensie, versie 0.1.40 preview of hoger, geïnstalleerd (azd ext install azure.ai.agents). Als u de extensie niet hebt geïnstalleerd, wordt de extensie automatisch geïnstalleerd wanneer u de starterssjabloon initialiseert of de extensie uitvoert azd ai agent . Voer azd ext list deze opdracht uit om de geïnstalleerde versie te controleren en voer deze uit als u een upgrade wilt uitvoeren azd ext upgrade azure.ai.agents . Zie azd voor meer informatie over de AI-agentextensie.
• 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.
• Zie Machtigingen instellen voor evaluatiewerkstromen voor alle vereisten voor de evaluatierol.
• Voor gehoste agents: Er is geen vooraf bestaand Foundry-project vereist. azd ai agent init en azd provision maken de benodigde resources.
• Voor agents op basis van prompts: Een bestaand Foundry-project met de agent die al is geïmplementeerd en beschikbaar is als evaluatiedoel.
• Een modelimplementatie die ondersteuning biedt voor chatvoltooiingen in hetzelfde Foundry-project.
• Optioneel: een JSONL-evaluatiedataset met representatieve voorbeelden, als u niet wilt dat eval generate een smoke-dataset genereert.

Hoe evaluaties van azd-agents werken

De primaire azd CLI-evaluatie-ervaring is ontworpen voor de levenscyclus van de hosted-agent:

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

De evaluatiestroom bevat de volgende artefacten en opdrachten.

azd provision maakt geen evaluatiedatasets, evaluatoren, suites of optimalisatietaken. Het instellen van de evaluatie kan betrekking hebben op het genereren van werk dat minuten in beslag neemt, zodat het expliciet blijft en opnieuw kan worden geprobeerd.

Voor gehoste agents is voor de eerste evaluatie een geïmplementeerd en aanroepbaar agentdoel vereist. Voor agents op basis van prompts is de implementatiestap niet van toepassing; de agent moet al aanwezig zijn in het Foundry-project en beschikbaar zijn als evaluatiedoel.

Een gehoste agent maken en implementeren

Als u nog geen gehost agentproject hebt, initialiseert u er een met azd:

azd ai agent init

Richt de Foundry-resources in en rol de agent uit:

azd provision
azd deploy

Nadat de implementatie is voltooid, controleert u of de agent kan worden aanroepbaar:

azd ai agent show

De gehoste agent moet zijn uitgerold en kunnen worden aangeroepen voordat u evaluatiemiddelen initialiseert.

Na een geslaagde implementatie stelt de CLI evaluatie voor als een expliciete volgende stap:

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

Als u een op prompt gebaseerde agent wilt evalueren, slaat u de opdrachten voor het maken en implementeren van gehoste agents over. Ga door naar de volgende sectie nadat u hebt bevestigd dat de op prompts gebaseerde agent bestaat in het Foundry-project en beschikbaar is als evaluatiedoel.

Evaluatiemiddelen initialiseren

Voer eval generate uit vanuit de map van de azd-werkruimte of het agentproject:

azd ai agent eval generate

Zonder vlaggen wordt met de opdracht een interactieve wizard gestart. De wizard detecteert het doel van de agent in de azd-omgeving en vraagt vervolgens om een instructie voor het genereren, zodat de service nuttige initiële evaluatiegegevens en een beoordelingsrubriek kan maken.

Voorbeeld van interactieve uitvoer:

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

Voor gebruik met scripts geeft u de generatie-invoer rechtstreeks door:

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 is optioneel en heeft standaard de waarde eval.yaml in de hoofdmap van het agentproject. Gebruik --out-file <path> dit om de configuratie naar een andere locatie te schrijven.

Een bestaande gegevensset en geselecteerde evaluators gebruiken:

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

Vervang ./tests/support-golden.jsonl door het pad naar uw eigen evaluatiegegevensset.

De --dataset waarde kan verwijzen naar een lokaal bestand of een geregistreerde gegevenssetnaam. Herhaal --evaluator om meerdere ingebouwde of geregistreerde aangepaste evaluatoren op te nemen. Evaluatorverwijzingen gebruiken de notatie <source>.<name>:

• builtin.<name> — verwijst naar een ingebouwde evaluator geleverd door Foundry.
• <name> — verwijst naar een aangepaste evaluator die is geregistreerd in het Foundry-project. Gebruik de geregistreerde naam van de evaluator zonder het versieachtervoegsel.

Generatie uitstellen met --no-wait

Als het genereren van gegevenssets of evaluators te lang duurt, gebruik --no-wait om generatietaken in te dienen en direct af te sluiten:

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

De lopende operatie-ID's worden naar eval.yaml geschreven. Wanneer u later azd ai agent eval run uitvoert, worden deze bewerkingen automatisch hervat voordat de evaluatierun wordt gestart.

Een promptgebaseerde doelagent gebruiken

Als u evaluatiemiddelen hebt geïnitialiseerd voor een promptgestuurde agent, kunt u dezelfde evaluatiereceptworkflow gebruiken. De implementatiestap voor gehoste agents is niet vereist voor promptgestuurde agents.

Controleer voordat u een evaluatie uitvoert:

• De promptgestuurde agent bevindt zich in het Foundry-project.
• De agent is beschikbaar als evaluatiedoel.
• U hebt toegang tot het projecteindpunt en het agentdoel.
• eval.yaml selecteert de beoogde agent op basis van prompts.

Als u agents wilt weergeven die beschikbaar zijn in het huidige Foundry-project, voert u het volgende uit:

azd ai agent list

Gebruik vervolgens dezelfde opdrachten om de evaluatie uit te voeren en te inspecteren:

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

Eval.yaml controleren

Nadat eval generate is voltooid, opent u eval.yaml in de hoofdmap van het agentproject. Voorbeeld:

src/reservation-agent/eval.yaml

Voer eval run uit vanuit deze map of geef het pad expliciet door met --config src/reservation-agent/eval.yaml. Het bestand identificeert het agentdoel, gegevenssetverwijzing, evaluatorverwijzingen en generatieopties. Een vereenvoudigde vorm is:

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 bevindt zich in de hoofdmap van het agentproject, bijvoorbeeld src/<agent-name>/eval.yaml.
• Gegenereerde gegevenssets staan onder datasets/ en gegenereerde beoordelingsrubrieken staan onder evaluators/ in de agentmap.
• local_uri paden in eval.yaml zijn relatief ten opzichte van de projectmap van de agent.
• Lokale bestanden waarnaar local_uri wordt verwezen, kunnen worden bewerkt. Voer azd ai agent eval update uit om lokale wijzigingen als een nieuwe versie in de service te registreren en de versie in eval.yaml te verhogen.
• eval run maakt gebruik van de geregistreerde versie die is vastgemaakt in eval.yaml. Als u lokale bewerkingen wilt toepassen, voert u eval update uit vóór eval run.
• Evaluators kunnen ingebouwde referenties zijn (bijvoorbeeld builtin.task_adherence) of aangepaste evaluators die zijn gegenereerd met name, version en local_uri.
• Behandel versievelden als tekenreeksen, zelfs als ze numeriek lijken, zodat het recept stabiel blijft in YAML-parsers.

De evaluatie uitvoeren

Voer vanuit de projectmap van de agent het volgende uit:

azd ai agent eval run

Standaard verwijst eval run zonder argumenten naar eval.yaml in de hoofdmap van het agentproject. U kunt ook het configuratiepad expliciet doorgeven:

azd ai agent eval run --config eval.yaml

Als eval generate --no-wait generatiebewerkingen in behandeling heeft gemaakt, hervat eval run die bewerkingen voordat het de evaluatieronde start. Er worden geen nieuwe jobs voor het genereren van datasets of evaluators vanaf nul gestart.

Evaluatieuitvoeringen controleren

Recente evaluatieuitvoeringen weergeven:

azd ai agent eval list

De meest recente uitvoering weergeven:

azd ai agent eval show

Zonder vlaggen gebruikt eval show standaard de meest recente evaluatie en worden de uitvoeringen daarvan weergegeven.

Als u de details van een specifieke run wilt weergeven, geeft u de eval-ID door als argument en de run-ID bij --eval-run-id. Kopieer de evaluatie-id uit de azd ai agent eval list uitvoer en de uitvoerings-id uit de azd ai agent eval show <eval-id> uitvoer:

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

Gebruik de uitvoer van de uitvoering om het volgende te beantwoorden:

• Welke agentversie is geëvalueerd.
• Welke gegevensset- en evaluatorversies zijn opgelost.
• Of de uitvoering is voltooid, mislukt of gedeeltelijk is voltooid.
• Welke metrische gegevens of evaluatorscores zijn geproduceerd.
• Of tokengebruik of evaluatorlogboeken onderzoek nodig hebben.

Opnieuw uitvoeren na het wijzigen van de agent

Nadat u een gehoste agent hebt bijgewerkt en opnieuw hebt geïmplementeerd, voert u hetzelfde evaluatierecept opnieuw uit:

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

Voor promptgebaseerde agents werkt u de agent bij in Foundry en voert u hetzelfde evaluatierecept opnieuw uit.

Door dezelfde eval.yaml opnieuw uit te voeren, blijven verwijzingen naar datasets, beoordelaars en drempelwaarden stabiel wanneer agents veranderen.

Evaluatieassets bijwerken, opnieuw instellen of herstellen

De stroom voor agentevaluatie gebruikt eval.yaml als het lokale evaluatierecept. Gebruik azd ai agent eval update wanneer u lokale datasetbestanden of beoordelingsrubrieken bewerkt en die bewerkingen als nieuwe serviceversies wilt registreren.

Als u wilt bijwerken wat een evaluatieuitvoering gebruikt, kiest u het pad dat overeenkomt met het type wijziging:

Voer bijvoorbeeld na het bewerken van een gegenereerde evaluatorrubriek in evaluators/ de agentmap het volgende uit:

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

Met de updateopdracht worden nieuwe geregistreerde gegevensset- of evaluatorversies gemaakt. Bestaande evaluatieuitvoeringen blijven gekoppeld aan de versies die ze oorspronkelijk hebben gebruikt.

Als eval.yaml al bestaat, detecteert eval generate dit en toont het de bestaande configuratie:

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

Als u de lokale configuratie wilt overschrijven en de standaardevaluatieassets opnieuw wilt genereren, voert u het volgende uit:

azd ai agent eval generate --reset-defaults

--reset-defaults Overschrijft de lokale eval.yaml en genereert de standaard evaluatie-assets opnieuw. Bestaande service-geregistreerde gegevensset- en evaluatorversies worden niet verwijderd; alleen het lokale recept wordt vervangen.

Vertrouw niet op externe nieuwste versies om het lokale recept op de achtergrond te wijzigen. De lokale eval.yaml registreert de versies van de gegevensset, evaluator of suite die door het recept worden gebruikt om reproduceerbaarheid te waarborgen.

Optioneel: optimalisatie starten vanaf evaluatiesignaal

Nadat ten minste één evaluatie is uitgevoerd, kunt u als invoer voor agentoptimalisatie gebruiken eval.yaml als de agent en het recept voldoen aan de optimalisatievereisten.

Voordat u begint met optimalisatie, moet u controleren of:

• Het agentdoel is gereed voor optimalisatie. Voor gehoste agents wordt de agent uitgerold en kan deze worden aangeroepen.
• eval.yaml verwijst naar de beoogde agent, gegevensset, evaluatorversies en drempelwaarden.
• Ten minste één evaluatietaak is succesvol voltooid.
• De agentvoorbereiding die door de optimizer is vereist, is voltooid. Zie Agentprompts optimaliseren met Prompt Optimizer voor vereisten en agentvoorbereidingsvereisten voor optimizer.

Voer vervolgens het volgende uit:

azd ai agent optimize --config eval.yaml

De opdracht optimaliseren leest het agentdoel, de gegevensset, evaluators en drempelwaarden van eval.yaml. Het dient een optimalisatietaak in, maar past bronwijzigingen niet stilzwijgend toe en rolt de kandidaat-agent ook niet opnieuw uit. Controleer eventuele optimizer-uitvoer voordat u wijzigingen toepast.

Beste praktijken

• Alleen azd ai agent eval generate uitvoeren nadat de agent beschikbaar is als evaluatiedoel. Voor gehoste agenten moet de agent zijn uitgerold en aanroepbaar zijn.
• Begin met een kleine gegenereerde gegevensset of een kleine subset van uw gouden gegevensset.
• Controleer de gegenereerde dataset en de reviewartefacten van de evaluator voordat u op scores vertrouwt.
• Nadat u gegenereerde dataset- of evaluatorbestanden hebt bewerkt, voert u azd ai agent eval update uit om de bewerkte onderdelen te registreren voordat u de evaluatie opnieuw uitvoert.
• Broncodebeheer eval.yaml als uw team een controleerbaar, reproduceerbaar evaluatierecept wil.
• Overweeg bronbeheer gegenereerde gegevenssets en evaluatorrubrieken onder datasets/ en evaluators/ in de agentmap als uw team deze beoordeelt en bewerkt als onderdeel van het evaluatierecept.
• Voer hetzelfde eval.yaml opnieuw uit nadat de agent is gewijzigd, zodat vergelijkingen hetzelfde testrecept gebruiken.
• Pas gebruiken azd ai agent optimize --config eval.yaml nadat u een nuttig evaluatieresultaat voor de basislijn hebt en de agent is voorbereid op optimalisatie.

Limitations

• De primaire opdrachtstroom is geoptimaliseerd voor gehoste agents en de evaluatielus na de implementatie.
• azd provision maakt geen evalueringsassets aan.
• eval run genereert geen nieuwe datasets of evaluatoren, behalve voor het hervatten van in behandeling zijnde bewerkingen van eval generate --no-wait.
• Volledige suitelevenscyclus, geplande evaluatie, continue evaluatie, waarschuwingen en vergelijkingswerkstromen zijn niet vereist voor het eerste evaluatietraject.

Verwante inhoud

• Uw AI-agents evalueren
• Menselijke evaluatie voor Microsoft Foundry-agents
• Evaluatieclusteranalyse
• Agentprompts optimaliseren met Prompt Optimizer
• Opsporing instellen voor AI-agents in Microsoft Foundry
• Agents monitoren met het Agent Monitoring Dashboard
• Gehoste agenten van de Foundry Agent Service
• Levenscyclus van agentontwikkeling