Exécuter des évaluations d’agent avec l’interface CLI azd (préversion)

Utilisez l’extension azd ai eval pour ajouter une boucle de qualité mesurée à un agent créé avec Microsoft Foundry. Vous mettez en place une évaluation à côté de votre projet, générez éventuellement un jeu de données et un évaluateur basé sur une grille d’évaluation, exécutez l’évaluation sur votre agent et consultez les résultats sans quitter le terminal.

La même évaluation peut s’exécuter depuis un pipeline et --fail-on transformer ses résultats en une validation de build.

Cet article traite de la première évaluation avec azd ai eval init et azd ai eval run start.

Prerequisites

• Un abonnement Azure avec accès à Microsoft Foundry.
• L’interface CLI Azure Développeur (azd), version 1.27.1 ou ultérieure. Pour obtenir des instructions d’installation, consultez Installer l’interface CLI Azure développeur.
• L’extension azd ai eval : azd extension install azure.ai.evaluations. Exécutez azd extension list --installed pour vérifier la version installée.
• Une session authentifiée azd . Pour vérifier l’état de votre authentification, exécutez azd auth status. Si vous n’êtes pas connecté, exécutez azd auth login.
• Rôle Foundry User sur la ressource Foundry (précédemment nommé Azure AI User). Pour plus d’informations, consultez Contrôle d’accès en fonction du rôle pour Microsoft Foundry.
• Un projet Foundry et un agent à évaluer. Pour permettre à init de détecter la cible, l’agent doit être déclaré en tant que service dans le azure.yaml du projet, comme le fait azd ai agent init. Sinon, nommez-le avec --target. Pour les agents hébergés, consultez Agents hébergés.
• Déploiement de modèle qui prend en charge les achèvements de conversation dans le même projet. Les évaluateurs s’en servent pour juger.
• Facultatif : jeu de données JSONL d’exemples représentatifs, si vous ne souhaitez pas en synthétiser generate un.

Fonctionnement des évaluations azd

Une évaluation est décrite par un fichier, evals/azure.eval.yamlque vous pouvez lire, modifier et valider. Les commandes écrivent ce fichier ou agissent sur ce qu’il déclare.

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

Chaque commande prend en charge -o json pour les scripts et --debug pour les diagnostics. Toutes les commandes, sauf init, acceptent --project-endpoint.

Choisir d’où proviennent les lignes

Une évaluation note les lignes. Ils proviennent de l’un des deux endroits, et cette décision est la première décision :

• --source traces évalue ce que votre agent a déjà fait en lisant les traces qu’il a émises. Rien à rédiger.
• --source dataset évalue un ensemble fixe d’exemples, le vôtre ou généré. Reproductible et comparable entre les versions de l’agent.

Les évaluations basées sur des traces nécessitent un agent qui émet des traces. Les évaluations basées sur un jeu de données nécessitent un fichier .jsonl ou un jeu de données enregistré.

Mettre en place le cadre de l’évaluation

Exécutez init depuis la racine de votre projet :

azd ai eval init

Sans indicateurs, init détecte l’agent lorsque azure.yaml en déclare un, demande d’en choisir un lorsqu’il en déclare plusieurs, et demande avec quel modèle de déploiement les élèves évaluent et quels évaluateurs utiliser. Il écrit evals/azure.eval.yaml et ajoute un service d’évaluation à azure.yaml. Il n’effectue aucun appel à un service, on peut donc l’exécuter sans risque avant tout déploiement.

Dans un projet qui ne déclare aucun service d’agent, init s’arrête plutôt que de deviner :

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

Nommez l’agent vous-même dans ce cas, avec --target.

Pour une utilisation par script, passez les décisions directement :

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

Pour évaluer un jeu de données que vous avez déjà :

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 prend un chemin d’accès local .jsonl ou le nom d’un jeu de données inscrit. --evaluator est reproductible et séparé par des virgules ; builtin.<name> fait référence à un évaluateur intégré, et un nom nu fait référence à un évaluateur personnalisé inscrit dans le projet. Le passage de --evaluator remplace les valeurs par défaut, ce qui désactive également la génération de rubriques.

Pour découvrir les noms intégrés :

azd ai eval evaluator list --builtin

Générer un jeu de données et un évaluateur

Si vous ne disposez pas d’un jeu de données ou si vous souhaitez écrire une rubrique écrite pour cet agent plutôt qu’un jeu de données générique, générez-les :

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

Par défaut, cela génère à la fois un jeu de données et un évaluateur de rubrique, les télécharge sous evals/, et ajoute une entrée de catalogue pour chacun d’eux.evals/azure.eval.yaml Limitez-la avec --dataset ou --evaluator pour générer une seule ligne et limitez les lignes --max-samples avec (15 à 1000, par défaut 15).

generate soumet des tâches qui nécessitent des appels au modèle. L’instruction est importante : c’est ce que le service utilise pour déterminer ce dont traitent les lignes et la rubrique. Décrivez donc ce que fait l’agent et ce qui doit être testé.

Une entrée de catalogue déclare l’artefact ; elle ne décide pas de l’évaluation qui l’utilise. Après generate, ouvrez evals/azure.eval.yaml et vérifiez que l’eval que vous avez l’intention d’exécuter fait référence à ce qui a été produit — une eval basée sur les traces lit les traces, de sorte qu’un jeu de données généré n’est utilisé qu’une fois qu’une eval le mentionne :

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

Pour soumettre les travaux et revenir ultérieurement :

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 et --evaluator sur job permettent de choisir la collection sur laquelle effectuer l’action, et l’un des deux est requis.

Vérifier azure.eval.yaml

init écrit un fichier que vous voulez lire. Une évaluation basée sur des traces se présente ainsi :

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

Une évaluation basée sur un jeu de données nomme le jeu de données au lieu d’une source de trace et indique l’agent ciblé :

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

Les chemins d’accès sous source: sont relatifs au fichier de configuration. Les fichiers JSON générés et évaluateurs sont des fichiers ordinaires .jsonl : modifiez-les, puis réexécutez-les create pour inscrire une nouvelle version.

Validez ce fichier. C’est la partie reproductible de l’évaluation.

Créer l’évaluation puis l’exécuter

Permet create d’inscrire tout ce que la configuration déclare : jeux de données, évaluateurs et eval lui-même :

azd ai eval create

Exécutez-la ensuite :

azd ai eval run start

run start attend l’exécution par défaut et imprime une table par évaluateur avec un taux de réussite et un score moyen, ainsi qu’un lien vers l’exécution dans le portail. Permet --no-wait d’envoyer et de retourner et --max-samples de limiter les lignes envoyées.

Si la configuration déclare plus d’une évaluation, nommez celle que vous souhaitez désigner :

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

Inspecter les résultats

Le résumé vous indique si la qualité a évolué. Les lignes pour chaque échantillon vous expliquent pourquoi :

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

Pour afficher les exécutions au fil du temps et ce que le service conserve pour une évaluation :

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

show retourne l’identité de l’évaluation dans le projet : son ID, son nom et sa date de création. Ce que l’eval fait se trouve dans votre evals/azure.eval.yaml.

run list contient un taux de réussite pour chaque exécution. La décomposition par programme d’évaluation se trouve dans -o json, sous per_testing_criteria_results, car une colonne par programme d’évaluation cesse d’être lisible dès lors que les exécutions sont notées par différents programmes d’évaluation.

Pour exporter les résultats ailleurs :

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

Les deux sont différents, et la différence est importante : run output list --output-file écrit les lignes par échantillon, tandis que run output export écrit une ligne par exécution — les totaux sur lesquels repose le résumé.

Lancer une build

Passez --fail-on pour transformer l’exécution en vérification. Il renvoie un code de sortie non nul si l’exécution n’atteint pas le seuil, c’est ainsi qu’un pipeline rejette une modification qui a entraîné une régression de la qualité :

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

En l’absence de --fail-on, une exécution terminée avec des échantillons en échec se termine quand même avec le code 0. Les échantillons en échec sont le résultat attendu d’une évaluation qui fonctionne correctement, et non le signe d’une erreur de l’outil ; l’activation est donc facultative.

pass-rate prend un nombre compris entre 0 et 1. Un seuil qui n’en est pas un est rejeté avant la soumission de l’exécution ; ainsi, une porte mal saisie ne coûte rien.

--fail-on a besoin d’une exécution terminée. Sur run show, associez-le à --wait.

Déployer des évaluations avec le reste du projet

init ajoute un service d’évaluation à azure.yaml, de sorte que l’évaluation fait partie du projet plutôt qu’un artefact latéral :

azd up

Cela configure le projet et enregistre les jeux de données déclarés, les évaluateurs et les évaluations, soit le même travail que azd ai eval create effectue à lui seul.

Modifier l’agent et réévaluer

Après avoir modifié et redéployé l’agent, réexécutez la même évaluation :

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

La réutilisation de la même valeur d’évaluation conserve le jeu de données, les évaluateurs et les seuils fixes, de sorte que la comparaison concerne l’agent.

Pour modifier les mesures d’évaluation, modifier evals/azure.eval.yaml ou les artefacts générés sous evals/, puis réexécuter create . create inscrit une nouvelle version de tout ce qui a changé et laisse les exécutions antérieures épinglées aux versions utilisées.

Bonnes pratiques

• Commencez par --source traces si l’agent s’exécute déjà et émet des traces. Il mesure ce qui s’est passé, et il n’y a rien à rédiger.
• Passez à --source dataset une fois que vous souhaitez un ensemble fixe de cas que vous pouvez comparer entre les versions.
• Lisez le jeu de données généré et la rubrique avant de faire confiance aux scores. generate les génère à partir des instructions que vous lui donnez, donc des instructions vagues produisent des lignes imprécises.
• Utilisez plusieurs évaluateurs. Un seul critère déplace le nombre sans vous dire pourquoi.
• Validez evals/azure.eval.yaml et les artefacts générés, de sorte que l’évaluation peut être examinée.
• Utilisez --fail-on dans CI, et maintenez le seuil à partir duquel une véritable régression se déclenche.

Limitations

• L’extension est en préversion, et l’interface de commande peut changer.
• generate soumet des tâches facturées. Les jeux de données et les évaluateurs ne sont pas créés par azd provision.
• Une évaluation basée sur les traces ne peut lire que les traces que l’agent a déjà émises.
• azd réduit le code de sortie d’une extension, de sorte qu’une violation de porte et une défaillance opérationnelle s’affichent en tant que sortie non nulle. Lisez le message de porte pour les séparer.

Contenu connexe

• Évaluer vos agents
• Évaluateurs intégrés
• Évaluateurs personnalisés
• Évaluation des traces
• Configurer le suivi pour votre agent
• Surveiller les agents avec le tableau de bord de surveillance des agents