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

Utilisez la fonctionnalité d’évaluation en ligne de commande d’Azure Developer CLI (azd) pour ajouter une boucle d’évaluation de la qualité fondée sur des mesures à un agent créé avec Microsoft Foundry. Cet article se concentre sur le cycle de vie de l’agent hébergé dans azdlequel vous créez, approvisionnez, déployez, initialisez des ressources d’évaluation, exécutez une première évaluation, inspectez l’exécution et réutilisez la recette d’évaluation pour les exécutions ultérieures.

Les agents basés sur des requêtes peuvent également être évalués lorsqu’ils sont disponibles en tant que cibles pour les agents dans le projet Foundry. Les étapes de déploiement de l’agent hébergé s’appliquent uniquement aux agents hébergés.

Cet article explique comment exécuter la première évaluation de l’agent avec azd ai agent eval generate et azd ai agent eval run.

Prerequisites

• Un abonnement Azure avec accès à Microsoft Foundry.
• L’interface de ligne de commande Azure Developer (azd). Pour obtenir des instructions d’installation, consultez Installer l’interface CLI Azure développeur.
• Extension azd ai agent , version 0.1.40 (version préliminaire) ou ultérieure, installée (azd ext install azure.ai.agents). Si l’extension n’est pas installée, lorsque vous initialisez le modèle de démarrage ou exécutez azd ai agent, l’extension est installée automatiquement. Exécutez pour vérifier la version installée et exécutez azd ext listazd ext upgrade azure.ai.agents si vous devez effectuer une mise à niveau. Pour en savoir plus sur l’extension azd d’agent d’IA, consultez extension d’agent Microsoft Foundry.
• 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.
• Pour connaître toutes les exigences de rôle d’évaluation, consultez Configurer les autorisations pour les flux de travail d’évaluation.
• Pour les agents hébergés : Aucun projet Foundry préexistant n’est requis. azd ai agent init et azd provision créent les ressources nécessaires.
• Pour les agents basés sur des prompts : Un projet Foundry existant avec l’agent déjà déployé et disponible en tant que cible d’évaluation.
• Déploiement de modèle qui prend en charge les achèvements de conversation dans le même projet Foundry.
• Facultatif : jeu de données d’évaluation JSONL avec des exemples représentatifs, si vous ne souhaitez pas que eval generate génère un jeu de données de test.

Fonctionnement des évaluations d’agent avec azd

L’expérience d’évaluation azd CLI principale est conçue pour le cycle de vie de l’agent hébergé :

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

Le flux d’évaluation inclut les artefacts et commandes suivants.

azd provision ne crée pas de jeux de données d’évaluation, d’évaluateurs, de suites ou de travaux d’optimisation. La configuration de l’évaluation peut impliquer un travail de génération qui prend des minutes, de sorte qu’elle reste explicite et retentable.

Pour les agents hébergés, la première évaluation nécessite une cible d’agent déployée et invocable. Pour les agents basés sur des requêtes, l’étape de déploiement ne s’applique pas ; l’agent doit déjà exister dans le projet Foundry et être disponible comme cible d’évaluation.

Créer et déployer un agent hébergé

Si vous n’avez pas encore de projet d’agent hébergé, initialisez-en un avec azd:

azd ai agent init

Provisionnez les ressources Foundry et déployez l’agent :

azd provision
azd deploy

Une fois le déploiement terminé, vérifiez que l’agent est invoquable :

azd ai agent show

L’agent hébergé doit être déployé et invoquable avant d’initialiser les ressources d’évaluation.

Après un déploiement réussi, l’interface CLI suggère l’évaluation en tant qu’étape suivante explicite :

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

Pour évaluer un agent piloté par prompt, ignorez les commandes de création et de déploiement de l’agent hébergé. Passez à la section suivante après avoir confirmé que l’agent basé sur les requêtes existe dans le projet Foundry et qu’il est disponible en tant que cible d’évaluation.

Initialiser des ressources d’évaluation

Exécutez eval generate depuis le dossier de projet de l’espace de travail ou de l’agent azd :

azd ai agent eval generate

Sans indicateur, la commande démarre un Assistant interactif. L’assistant détecte la cible de l’agent à partir de l’environnement azd, puis demande une instruction de génération afin que le service puisse créer des données de départ utiles pour l’évaluation ainsi qu’une grille d’évaluation.

Exemple de sortie interactive :

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

Pour une utilisation scriptée, transmettez directement les entrées de génération :

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 est facultatif et vaut par défaut eval.yaml à la racine du projet de l’agent. Utilisez --out-file <path> pour écrire la configuration à un autre emplacement.

Pour utiliser un jeu de données existant et des évaluateurs sélectionnés :

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

Remplacez ./tests/support-golden.jsonl par le chemin d’accès à votre propre jeu de données d’évaluation.

La --dataset valeur peut pointer vers un fichier local ou un nom de jeu de données inscrit. Répétez cette opération --evaluator pour inclure plusieurs évaluateurs personnalisés intégrés ou inscrits. Les références de l’évaluateur utilisent le format <source>.<name>:

• builtin.<name> — fait référence à un évaluateur intégré fourni par Foundry.
• <name> — fait référence à un évaluateur personnalisé inscrit dans le projet Foundry. Utilisez le nom inscrit de l’évaluateur sans le suffixe de version.

Différer la génération avec --no-wait

Si la génération du jeu de données ou de l’évaluateur prend trop de temps, utilisez --no-wait pour envoyer des tâches de génération et quitter immédiatement :

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

Les identifiants des opérations en attente sont consignés dans eval.yaml. Lorsque vous exécutez azd ai agent eval runultérieurement, il reprend automatiquement ces opérations avant de commencer l’exécution de l’évaluation.

Utiliser une cible d’agent basé sur des requêtes

Si vous avez initialisé des ressources d’évaluation pour un agent basé sur des requêtes, vous pouvez utiliser le même processus d’évaluation. L’étape de déploiement de l’agent hébergé n’est pas nécessaire pour les agents basés sur des requêtes.

Avant d’exécuter une évaluation, vérifiez que :

• L’agent basé sur des requêtes existe dans le projet Foundry.
• L’agent est disponible en tant que cible d’évaluation.
• Vous avez accès au point de terminaison du projet et à la cible de l’agent.
• eval.yaml sélectionne l’agent basé sur des requêtes.

Pour répertorier les agents disponibles dans le projet Foundry actuel, exécutez :

azd ai agent list

Utilisez ensuite les mêmes commandes pour exécuter et inspecter l’évaluation :

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

Passer en revue eval.yaml

Une fois eval generate terminé, ouvrez eval.yaml dans le répertoire racine du projet de l’agent. Par exemple:

src/reservation-agent/eval.yaml

Exécutez eval run depuis ce répertoire, ou indiquez explicitement le chemin avec --config src/reservation-agent/eval.yaml. Le fichier identifie la cible de l’agent, la référence de jeu de données, les références de l’évaluateur et les options de génération. Une forme simplifiée est la suivante :

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 vit à la racine du projet de l’agent, par exemple src/<agent-name>/eval.yaml.
• Les jeux de données générés se trouvent sous datasets/ et les grilles d’évaluation générées se trouvent sous evaluators/ dans le dossier de l’agent.
• local_uri les chemins dans eval.yaml sont relatifs au répertoire du projet de l’agent.
• Les fichiers locaux référencés par local_uri sont modifiables. Exécutez azd ai agent eval update pour inscrire les modifications locales en tant que nouvelle version dans le service et faire passer la version dans eval.yaml.
• eval run utilise la version enregistrée épinglée dans eval.yaml. Pour appliquer des modifications locales, exécutez eval update avant eval run.
• Les évaluateurs peuvent être des références intégrées (par exemple, builtin.task_adherence) ou des évaluateurs personnalisés générés avec name, versionet local_uri.
• Traitez les champs de version comme des chaînes, même s’ils semblent numériques, de sorte que la recette reste stable dans les analyseurs YAML.

Exécuter l’évaluation

À partir du dossier du projet de l’agent, exécutez :

azd ai agent eval run

Par défaut, eval run sans argument résout eval.yaml dans la racine du projet de l’agent. Vous pouvez également passer le chemin de configuration explicitement :

azd ai agent eval run --config eval.yaml

Si eval generate --no-wait a créé des opérations de génération en suspens, eval run reprend ces opérations avant de démarrer l’exécution d’évaluation. Il ne lance pas de nouvelles tâches de génération de jeux de données ou d’évaluateurs à partir de zéro.

Inspecter les exécutions d’évaluation

Répertorier les exécutions d’évaluation récentes :

azd ai agent eval list

Affichez la dernière exécution :

azd ai agent eval show

En l’absence d’indicateurs, eval show utilise par défaut l’évaluation la plus récente et liste ses exécutions.

Pour afficher les détails d’une exécution spécifique, transmettez l’ID d’évaluation en tant qu’argument et l’ID d’exécution avec --eval-run-id. Copiez l’ID d’évaluation à partir de la azd ai agent eval list sortie et l’ID d’exécution de la azd ai agent eval show <eval-id> sortie :

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

Utilisez la sortie d’exécution pour répondre :

• Quelle version de l’agent a été évaluée.
• Quelle version du jeu de données et des évaluateurs a été résolue.
• Indique si l’exécution est terminée, a échoué ou s’est terminée partiellement.
• Quelles métriques ou quels scores d’évaluation ont été produits.
• Indique si l’utilisation des tokens ou les journaux de l’évaluateur nécessitent un examen.

Réexécuter après avoir modifié l’agent

Après avoir mis à jour et redéployé un agent hébergé, réexécutez la même recette d’évaluation :

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

Pour les agents basés sur des requêtes, mettez à jour l’agent dans Foundry, puis réexécutez le même processus.

Le fait de relancer le même eval.yaml permet de maintenir stables les références au jeu de données, à l’évaluateur et au seuil lors de changements d’agent.

Mettre à jour, réinitialiser ou réparer des ressources d’évaluation

Le flux d’évaluation de l’agent utilise eval.yaml comme recette d’évaluation locale. Utilisez azd ai agent eval update lorsque vous modifiez des fichiers locaux de jeu de données ou des grilles d’évaluation et souhaitez enregistrer ces modifications comme nouvelles versions du service.

Pour mettre à jour ce qu’utilise une exécution d’évaluation, choisissez le chemin qui correspond au type de modification :

Par exemple, après avoir modifié une grille d’évaluation générée dans le dossier agent, sous evaluators/, exécutez :

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

La commande de mise à jour crée de nouvelles versions enregistrées de jeux de données ou d’évaluateurs. Les exécutions d’évaluation existantes restent liées aux versions utilisées à l’origine.

Lorsqu’il eval.yaml existe déjà, eval generate le détecte et imprime la configuration existante :

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

Pour remplacer la configuration locale et régénérer les ressources d’évaluation par défaut, exécutez :

azd ai agent eval generate --reset-defaults

--reset-defaults remplace le local eval.yaml et régénère les ressources d’évaluation par défaut. Les versions existantes du jeu de données et de l’évaluateur inscrits au service ne sont pas supprimées ; seule la recette locale est remplacée.

Ne vous fiez pas aux dernières versions distantes qui modifient silencieusement la recette locale. Le eval.yaml local enregistre les versions du jeu de données, de l’évaluateur ou de la suite utilisées par la recette afin d’assurer la reproductibilité.

Facultatif : démarrer l’optimisation à partir du signal d’évaluation

Une fois qu’au moins une exécution d’évaluation réussit, vous pouvez utiliser comme entrée pour l’optimisation eval.yaml de l’agent si l’agent et la recette répondent aux prérequis d’optimisation.

Avant de commencer l’optimisation, vérifiez que :

• La cible de l’agent est prête pour l’optimisation. Pour les agents hébergés, l’agent est déployé et invoquable.
• eval.yaml fait référence à l’agent, au jeu de données, aux versions de l’évaluateur et aux seuils prévus.
• Au moins une exécution d’évaluation s’est terminée avec succès.
• La préparation de l’agent requise par l’optimiseur est terminée. Pour connaître les prérequis de l’optimiseur et les exigences de préparation de l’agent, consultez Optimiser les prompts d’agent avec Prompt Optimizer.

Ensuite, exécutez :

azd ai agent optimize --config eval.yaml

La commande optimize lit la cible de l’agent, le jeu de données, les évaluateurs et les seuils à partir de eval.yaml. Il soumet un travail d’optimisation, mais il n’applique pas silencieusement les modifications sources ou redéploie l’agent candidat. Passez en revue toute sortie de l’optimiseur avant d’appliquer des modifications.

Bonnes pratiques

• Exécutez azd ai agent eval generate uniquement une fois l’agent disponible en tant que cible d’évaluation. Pour les agents hébergés, l’agent doit être déployé et invoquable.
• Commencez par un petit jeu de données générées ou un petit sous-ensemble de votre jeu de données de référence.
• Vérifiez le jeu de données généré ainsi que les artefacts de revue des évaluateurs avant de vous fier aux scores.
• Après avoir modifié des fichiers de jeu de données ou d’évaluateur générés, exécutez azd ai agent eval update pour inscrire les ressources modifiées avant d’exécuter à nouveau l’évaluation.
• Placez le fichier eval.yaml sous contrôle de version si votre équipe souhaite disposer d’un processus d’évaluation reproductible et pouvant être relu lors des revues.
• Envisagez de placer sous contrôle de version les jeux de données générés et les grilles d’évaluation dans datasets/ et evaluators/ au sein du dossier de l’agent, si votre équipe les révise et les modifie dans le cadre du processus d’évaluation.
• Réexécutez le même eval.yaml après les modifications de l’agent afin que les comparaisons utilisent la même recette de test.
• Utilisez azd ai agent optimize --config eval.yaml uniquement une fois que vous avez un résultat d’évaluation de base utile et que l’agent est préparé pour l’optimisation.

Limitations

• Le flux de commande principal est optimisé pour les agents hébergés et la boucle d’évaluation post-déploiement.
• azd provision ne crée pas de ressources d’évaluation.
• eval run ne génère pas de nouveaux jeux de données ou évaluateurs, à l’exception de la reprise des opérations en attente à partir de eval generate --no-wait.
• Le cycle de vie complet de la suite, l’évaluation planifiée, l’évaluation continue, les alertes et les flux de travail de comparaison ne sont pas nécessaires pour le premier chemin d’évaluation.

Contenu connexe

• Évaluer vos agents IA
• Évaluation humaine pour les agents Microsoft Foundry
• Analyse du cluster d’évaluation
• Optimiser les prompts des agents avec Prompt Optimizer
• Configurer le traçage des agents IA dans Microsoft Foundry
• Surveiller les agents avec le tableau de bord de surveillance des agents
• Agents hébergés dans le service Agent Foundry
• Cycle de vie du développement de l’agent