Optimiser les instructions de l’agent, les compétences, les outils et les modèles (version préliminaire)

L’optimiseur d’agent améliore quatre aspects de votre agent hébergé : instructions, compétences, outils et sélection de modèle. Il détecte automatiquement les cibles à optimiser à partir de la configuration de base de votre agent.

Cet article explique comment exécuter une optimisation, configurer et surveiller l’exécution et déployer les résultats. Pour ce que fait chaque cible et quand elle s’active, consultez les cibles d’optimisation. Pour configurer les entrées de base, consultez Rendre votre optimiseur d’agent prêt. Pour obtenir une référence rapide sur ce que l’optimiseur change, consultez Ce que chaque cible change.

Prerequisites

• Un projet Foundry avec un agent hébergé déployé
• L’extension azure.ai.agents CLI installée (voir Démarrage rapide : Optimiser un agent hébergé)
• Un modèle déployé pour l’évaluation (par exemple) gpt-4.1-miniet un modèle d’optimisation à partir de la liste prise en charge (par exemple, gpt-5.1)
• Votre agent est prêt pour l’optimisation (appelle load_config())

Exécuter une optimisation

Démarrez une exécution d’optimisation avec une seule commande :

azd ai agent optimize

L’optimiseur évalue votre base de référence, génère des candidats, les évalue et classe les résultats. Pour obtenir le cycle d’évaluation et d’amélioration complet, consultez le fonctionnement de l’optimiseur d’agent. Les cibles exécutées dépendent de votre configuration de base de référence : l’optimisation des instructions, l’amélioration des compétences et l’optimisation des outils s’activent automatiquement lorsque les fichiers de base correspondants sont présents. Consultez les cibles d’optimisation.

Pour contrôler l’exécution avec un fichier de configuration, transmettez un eval.yaml faisant référence à votre jeu de données, à des évaluateurs et à des options :

azd ai agent optimize --config eval.yaml

Pour obtenir le schéma complet eval.yaml , consultez Configurer l’exécution de l’optimisation.

Cibler un agent spécifique

La façon dont l’interface CLI résout l’agent dépend de l’exécution de la commande à partir d’un azd projet :

Le nom de l’agent déployé doit correspondre à un agent hébergé dans le projet Foundry cible.

Optimiser un agent existant sans fichiers projet AZD

Vous pouvez optimiser un agent hébergé existant sans exécuter azd ai agent init et sans créer azure.yaml ou créer un répertoire d’environnement .azure . Dans ce flux autonome, fournissez explicitement le point de terminaison du projet Foundry et le nom de l’agent déployé.

1. Assurez-vous que l’agent déployé est compatible avec l’optimiseur. Dans un répertoire de travail local, créez le fichier d’instructions, le jeu de données, les évaluateurs et eval.yaml décrits dans Configurer l’exécution de l’optimisation.

   Exécutez la commande à partir de ce répertoire de travail. Sans projet azd, les chemins relatifs dans eval.yaml sont résolus à partir du répertoire de travail actuel.

   Pour ce flux autonome, omettez agent.config. L’interface CLI demande l’instruction de base lorsque vous exécutez la commande :

   # eval.yaml
   agent:
     name: my-support-agent
     kind: hosted
     model: gpt-4.1-mini
   dataset:
     local_uri: ./eval.jsonl
   evaluators:
     - builtin.task_adherence
   options:
     eval_model: gpt-4.1-mini
     optimization_model: gpt-5.1
     max_candidates: 2
   

2. Authentifier:

   az login
   azd auth login
   

3. Copiez le point de terminaison du projet à partir de la page Vue d’ensemble du projet Foundry. Utilisez l’URL du point de terminaison du projet, et non l’ID de ressource Azure.

4. Enregistrez le point de terminaison dans votre configuration au niveau azd de l’utilisateur afin que les commandes suivantes puissent résoudre le même projet à partir de n’importe quel répertoire :

   azd ai project set "<project-endpoint>"
   azd ai project show
   

   Cette étape écrit le point de terminaison par défaut dans ~/.azd/config.json. Pour obtenir l’ordre de résolution complet et les commandes pour inspecter ou effacer le contexte enregistré, consultez Définir le contexte du projet Foundry pour les commandes azd.

5. Exécutez l’optimisation avec le nom de l’agent déployé :

   azd ai agent optimize --agent "<deployed-agent-name>" --config eval.yaml
   

   Lorsque vous êtes invité à saisir l’instruction de l’agent, fournissez-la directement dans le champ ou sélectionnez un fichier, par exemple .agent_configs/baseline/instructions.md.

   Note

   Dans la préversion actuelle, une exécution autonome ne se développe agent.config pas à partir de eval.yaml. Exécutez la commande de manière interactive afin de pouvoir fournir l’instruction de base. N’utilisez pas --no-prompt pour ce flux. Le chargement des bases de référence de compétences et d’outils fondées sur des fichiers nécessite également un projet azd.

   Pour une commande ponctuelle qui ne doit pas modifier votre configuration au niveau de l’utilisateur, passez --project-endpoint:

   azd ai agent optimize \
     --project-endpoint "<project-endpoint>" \
     --agent "<deployed-agent-name>" \
     --config eval.yaml
   

   Vous pouvez également définir le point de terminaison pour la session shell en cours :

   export FOUNDRY_PROJECT_ENDPOINT="<project-endpoint>"
   azd ai agent optimize --agent "<deployed-agent-name>" --config eval.yaml
   

6. Enregistrez l’ID d’opération à partir de la sortie de la commande. Étant donné que ce flux n’a pas d’environnement azd , l’interface CLI ne conserve pas le dernier ID d’opération localement. Transmettez l’ID d’opération aux commandes de suivi :

   azd ai agent optimize status <operation-id> --watch
   
   azd ai agent optimize list
   
   azd ai agent optimize cancel <operation-id>
   

   Ces commandes utilisent le point de terminaison enregistré par azd ai project set. Si vous avez utilisé à la place la forme ponctuelle --project-endpoint, spécifiez de nouveau l’option pour chaque commande ultérieure.

Configurer l’exécution de l’optimisation

Configurer l’optimisation s’exécute via un eval.yaml fichier qui lie votre jeu de données, évaluateurs et options d’exécution. La commande azd ai agent eval generate écrit ce fichier pour vous, ou vous pouvez le créer manuellement. L’optimiseur détecte eval.yaml automatiquement dans la racine de votre projet, ou vous pouvez le transmettre explicitement avec --config eval.yaml.

# eval.yaml
name: my-optimization              # Optional label for the run
agent:
  name: my-agent                   # Deployed hosted agent name
  kind: hosted
  version: "1"                     # Agent version (optional)
  model: gpt-4.1-mini              # Baseline model deployment
  config: .agent_configs/baseline/metadata.yaml
dataset:
  local_uri: ./eval.jsonl          # A local JSONL file...
  # name: my-foundry-dataset       # ...OR a registered Foundry dataset
  # version: "1"
# validation_dataset:              # Optional held-out dataset
#   name: my-validation-dataset
#   version: "1"
evaluators:
  - builtin.task_adherence         # A built-in evaluator...
  # - name: my-custom-evaluator    # ...or a custom evaluator
  #   version: "1"
  #   local_uri: ./my_evaluator.json
options:
  eval_model: gpt-4.1-mini         # Scores responses
  optimization_model: gpt-5.1      # Generates candidates
  max_candidates: 4
  optimization_config:
    model_search_space:            # Optional: compare model deployments
      - gpt-4.1

Créer le jeu de données et les évaluateurs séparément ; consultez Créer un jeu de données d’évaluation et des évaluateurs. Les sections suivantes décrivent les options d’exécution.

Choisir les modèles d’optimisation et d’évaluation

L’optimiseur utilise deux modèles : un modèle d’évaluation qui note les réponses de l’agent par rapport aux critères et un modèle d’optimisation qui génère des configurations candidates. Définissez-les dans eval.yaml ou utilisez des indicateurs CLI.

options:
  eval_model: gpt-4.1-mini
  optimization_model: gpt-5.1

azd ai agent optimize --eval-model gpt-4.1-mini --optimize-model gpt-5.1

Tout modèle de complétion de conversation déployé dans votre projet peut être utilisé comme modèle d'évaluation. Le modèle d’optimisation doit provenir de la liste prise en charge. Pour connaître les rôles et les modèles pris en charge, consultez Modèles.

Définir le nombre de candidats

L’option max_candidates définit le nombre attendu de configurations candidates pour l’exécution. L’optimiseur s’arrête généralement lorsqu’il atteint ce nombre, sauf si l’exécution s’interrompt plus tôt en raison d’une erreur ou d’une autre condition d’arrêt.

Les valeurs plus élevées explorent davantage de variations, mais prennent plus de temps. L’optimiseur apprend des candidats antérieurs, donc les candidats ultérieurs ont tendance à noter plus haut.

Évaluer plusieurs modèles

Pour comparer des déploiements de modèles au cours d’une même exécution, listez-les sous optimization_config.model_search_space. L’optimiseur évalue votre agent avec chaque modèle sur le même jeu de données et classe les résultats par score et coût de jeton.

# eval.yaml
options:
  optimization_config:
    model_search_space:
      - gpt-4.1
      - gpt-4.1-mini
      - gpt-4o

Chaque modèle répertorié sous model_search_space doit être déployé dans votre projet Foundry.

La sélection du modèle s’exécute parallèlement aux cibles qui sont automatiquement activées à partir de votre base de référence. Une seule exécution peut produire des candidats qui combinent des instructions, des compétences et des descriptions d’outils améliorées avec différentes options de modèle . Vous ne configurez pas la combinaison vous-même.

Surveiller un travail en cours d’exécution

Une exécution d’optimisation est asynchrone. Utilisez ces commandes lorsqu’un travail est long ou que vous souhaitez vérifier sa progression :

# Check status and stream progress
azd ai agent optimize status <operation-id> --watch

# List recent optimization jobs
azd ai agent optimize list

# Cancel a running job
azd ai agent optimize cancel <operation-id>

Relevez l’ID de l’opération, l’URL du portail, les scores et les ID des candidats dans la sortie d’exécution. Vous pouvez également surveiller le travail dans le portail Foundry à l’aide de l’URL affichée au démarrage de l’exécution.

Si vous avez démarré le travail sans fichiers projet AZD, transmettez toujours l’ID d’opération à status et cancel. Les commandes utilisent le point de terminaison de niveau utilisateur enregistré via azd ai project set ; sinon, incluez --project-endpoint.

Interpréter les résultats

Une fois l’optimisation terminée, passez en revue la table des résultats. Un astérisque (*) marque le meilleur candidat. Pour connaître les colonnes de la table des résultats, les détails du scoring, les seuils d’amélioration du score et l’affichage du portail, consultez Comprendre les résultats de l’optimisation.

Déployer le gagnant

Le flux de travail recommandé consiste à appliquer la configuration optimisée localement, puis à déployer :

# Apply the winning candidate locally
azd ai agent optimize apply --candidate <candidate-id>

# Deploy with the optimized config
azd deploy

Cela télécharge la configuration optimisée dans le fichier .agent_configs/<candidate_id>/ de votre projet. Lors du déploiement suivant, votre agent utilise les instructions améliorées et les descriptions des outils.

Vous pouvez également déployer directement via l’API (utile pour les tests A/B rapides) :

azd ai agent optimize deploy --candidate <candidate-id>

Si tous les candidats ont un score inférieur à la ligne de base, ne déployez aucun candidat. La configuration de la base de référence reste active.

Ce que chaque cible change

L’optimiseur active automatiquement les cibles qui s’appliquent à votre base de référence. Cette section est une référence pour ce qu’une exécution change. Utilisez le tableau suivant pour anticiper ce que fait l’optimisation pour votre agent :

Votre code reste le même sur toutes les cibles, car load_config() retourne automatiquement les valeurs optimisées. Seule la configuration que le modèle voit change.

Instructions

L’optimiseur réécrit l’invite système. Les améliorations courantes sont les suivantes :

• Ajout de contraintes explicites que le prompt d’origine impliquait sans les énoncer
• Instructions de restructuration pour plus de clarté
• Ajout de spécifications de format de sortie
• Renforcement des limites de sécurité et d’étendue

Par exemple, un prompt de base minimal comme You are a helpful assistant. peut devenir :

You are a helpful coding assistant. Follow these guidelines:
1. Always include working code examples
2. Explain your reasoning step by step
3. If a question is outside your expertise, say so clearly
4. Use markdown formatting for code blocks
5. Handle edge cases in code examples

Compétences

L’optimiseur affine la description, le corps et les critères d’activation de chaque compétence tout en conservant l’objectif de la compétence. L’agent charge des compétences améliorées via load_config(), qui les ajoute à l’ensemble d’instructions. Les compétences utilisent le format ouvert Agent Skills. Pour savoir comment votre agent charge les compétences, veuillez consulter la section Préparer votre agent pour l'optimiseur.

Tools

L’optimiseur affine vos tools.json définitions. Les améliorations courantes sont les suivantes :

• Descriptions de fonctions plus claires qui aident le modèle à savoir quand appeler un outil
• Descriptions de paramètres plus spécifiques qui réduisent les arguments incorrects
• Ajout de contraintes (énumérations, champs obligatoires) qui empêchent les entrées non valides

Votre code d’implémentation d’outil reste le même. Seules les définitions que le modèle voit changent.

Models

L’optimiseur classe chaque modèle candidat par score composite et coût de jeton. Vous pouvez donc choisir le meilleur compromis qualité-coût. Pour configurer les candidats, consultez Évaluer plusieurs modèles.

Résolution des problèmes

Contenu connexe

• Vue d’ensemble de l’optimiseur d’agent
• Préparer votre agent pour l’optimisation
• Créer un jeu de données d’évaluation et des évaluateurs
• Démarrage rapide : Optimiser un agent hébergé