Remarque
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier des répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de modifier des répertoires.
Important
Agent Optimizer est actuellement en préversion. Cette version préliminaire est fournie sans contrat de niveau de service, et nous la déconseillons pour les charges de travail en production. Certaines fonctionnalités peuvent ne pas être prises en charge ou avoir des fonctionnalités contraintes. Pour plus d’informations, consultez Conditions d'utilisation supplémentaires pour les versions préliminaires de Microsoft Azure.
Dans ce guide de démarrage rapide, vous déployez l’exemple d’agent d’optimisation, exécutez l’optimiseur d’agent pour améliorer ses instructions et déployer le candidat gagnant.
Pour connaître les concepts derrière chaque étape et le chemin complet de bout en bout, consultez le flux de travail d’optimisation.
Prerequisites
Avant de commencer, vous avez besoin des éléments suivants :
- Un abonnement Azure --Create one gratuitement.
Azure CLI pour l’authentification.
Python 3.10 ou version ultérieure.
Packages Python utilisés dans ce chemin d’accès :
pip install "azure-ai-projects>=2.4.0" azure-ai-agentserver-optimization azure-identity python-dotenvProjet Foundry existant qui contient déjà l’agent hébergé, le jeu de données inscrit et l’évaluateur que vous souhaitez utiliser pour l’optimisation.
Microsoft Foundry Toolkit pour Visual Studio Code version 1.6.4 ou ultérieure, connecté à Azure. Foundry Toolkit installe et met à jour la compétence Microsoft Foundry utilisée dans ce flux de travail.
GitHub Copilot en Visual Studio Code avec accès au mode agent. Foundry Toolkit envoie la demande d’optimiseur d’agent à GitHub Copilot après avoir sélectionné l’espace de travail de l’agent.
Azure CLI et Azure Developer CLI (AZD) installés et authentifiés :
az login azd auth login
Conseil / Astuce
Si vous n'avez pas Foundry Toolkit, installez-le à partir de la Place de marché Visual Studio Code. Foundry Toolkit intègre vos ressources Foundry, le catalogue de modèles, le déploiement d’agents hébergés, les espaces de test et l’optimisation des agents dans Visual Studio Code. Rechargez Visual Studio Code si vous y êtes invité, puis connectez-vous à Azure. Pour une visite guidée de l’extension, consultez Utiliser Microsoft Foundry Toolkit pour Visual Studio Code extension.
Hôte pour agent de codage sur lequel la Microsoft Foundry Skill est installée.
Azure CLI et Azure Developer CLI (AZD) installés et authentifiés :
az login azd auth loginL’extension
microsoft.foundrypour AZD. Installez-le avant de démarrer le flux de travail :azd ext install microsoft.foundrySi elle est déjà installée, mettez-la à niveau :
azd ext upgrade microsoft.foundry
- Votre abonnement Azure doit figurer dans la liste d’autorisation de l’optimiseur d’agent. Contactez votre représentant Microsoft pour demander l’accès.
Note
L’optimiseur d’agents est actuellement en version préliminaire.
Étape 1 : Créer le projet
Initialisez un nouveau projet à partir de l’exemple de modèle d’optimisation :
mkdir my-agent && cd my-agent
azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/bring-your-own/responses/optimization-customer-support/azure.yaml .
Ce modèle importe l’exemple de support client d’optimisation, un assistant hébergé prêt à l’optimisation Python qui utilise l’approche bring-your-own et le protocole Réponses. Il représente un agent de support électronique grand public qui gère les demandes de commande, les retours, les réclamations de garantie, la résolution des problèmes, les plaintes, les recommandations et l’escalade. L’instruction de base minimale délibérément minimale facilite la comparaison des améliorations apportées à l’optimisation des instructions et à la découverte des compétences.
L’exemple appelle load_config() pour charger la configuration de base ou candidate et inclut .agent_configs/baseline/, eval.yaml, les jeux de données d’évaluation complète et rapide, la configuration du conteneur et le manifeste de déploiement Foundry. Le flux interactif importe ces fichiers et demande vos paramètres de déploiement de Azure abonnement, région et modèle.
Conseil / Astuce
Si vous avez déjà un projet d’agent, consultez Préparer votre agent pour l’optimiseur pour ajouter la prise en charge de l’optimisation.
Si vous disposez déjà d’un projet Foundry, ajoutez-y -p <project-resource-id> pour cibler des ressources existantes.
Pour optimiser un agent déjà déployé sans exécuter azd ai agent init ni créer de fichiers azure.yaml et .azure, ignorez cette étape de création du projet et suivez Optimiser un agent existant sans fichiers de projet AZD.
Étape 2 : Provisionner et déployer
Authentifiez et approvisionnez les ressources Azure :
az login
azd auth login
azd provision
L’approvisionnement prend environ deux minutes et crée un compte Foundry, un projet, un Azure Container Registry et des déploiements de modèles.
Déployez l’agent :
azd deploy
Testez le déploiement :
azd ai agent invoke "What is 2+2?"
Étape 3 : Générer une suite d’évaluation et optimiser
Générez un jeu de données d’évaluation et des évaluateurs pour votre agent :
azd ai agent eval generate
Cette étape crée eval.yaml, un jeu de données de test et des évaluateurs de notation en fonction des instructions de votre agent. L’optimiseur utilise ces fichiers pour mesurer l’amélioration.
Exécutez l’optimiseur :
azd ai agent optimize --max-candidates 2
L’interface CLI vous invite à sélectionner un modèle d’optimisation. Pour ignorer l’invite, transmettez-la directement :
azd ai agent optimize --max-candidates 2 --optimize-model gpt-5
L’interface en ligne de commande détecte votre agent à partir de azure.yaml et utilise automatiquement le eval.yaml généré. Avec deux candidats, l’optimisation se termine généralement en environ 8 minutes. La progression en temps réel s’affiche :
Optimizing agent "customer-support-py"...
Config: eval.yaml
Baseline saved to .agent_configs/baseline/metadata.yaml
Job ID: opt_162bd0f09....
Status: pending
Portal: <OPTIMIZATION-JOB-URL>
Utilisez l’URL du portail pour surveiller votre travail dans le portail Foundry.
Le modèle d’évaluation évalue chaque réponse (n’importe quel modèle de complétion de conversation convient). Le modèle d’optimisation (--optimize-model) génère des candidats améliorés et doit provenir de la liste prise en charge (famille gpt-5 ou DeepSeek). Vous pouvez également le définir optimization_model sous options:eval.yaml pour éviter de passer l’indicateur à chaque fois.
Étape 4 : Déployer le gagnant
L’étoile (*) dans le résultat indique le meilleur candidat. Appliquez la configuration optimisée localement, puis déployez :
azd ai agent optimize apply --candidate <candidate-id>
azd deploy
La apply commande télécharge la configuration optimisée dans .agent_configs/<candidate_id>/ et met à jour vos azure.yaml instructions pour utiliser les nouvelles instructions. La commande deploy déploie l’agent optimisé en production via CodeDeploy.
Appelez votre agent pour vérifier l’amélioration :
azd ai agent invoke "What is your return policy?"
Vous pouvez également exécuter l’évaluation pour confirmer l’amélioration du score :
azd ai agent eval run
chemin d’accès du KIT de développement logiciel (SDK) Python
Utilisez les étapes suivantes si vous souhaitez exécuter l’optimiseur à partir de Python au lieu du flux de travail CLI du développeur Azure décrit précédemment.
Ce chemin suppose que vous disposez déjà des ressources suivantes dans un projet Foundry existant :
- Optimisation d’un agent hébergé.
- Un jeu de données d’entraînement enregistré.
- Évaluateur inscrit.
Contrairement au flux de travail Azure Developer CLI décrit précédemment, l’approche avec le SDK Python ne crée pas la structure d’un projet et ne génère pas eval.yaml, de jeu de données ni d’évaluateurs pour vous. Si vous souhaitez que l’exemple crée automatiquement ces ressources, utilisez azd ai agent eval generate d’abord.
1. Créer un .env fichier
Créez un dossier de travail, puis ajoutez un .env fichier avec ces valeurs :
FOUNDRY_PROJECT_ENDPOINT=<your-project-endpoint>
FOUNDRY_AGENT_NAME=<your-hosted-agent-name>
DATASET_NAME=<your-registered-dataset-name>
EVALUATOR_NAME=<your-registered-evaluator-name>
DATASET_VERSION=1
POLL_INTERVAL_SECONDS=10
EVAL_MODEL=<your-eval-model-deployment-name>
OPTIMIZATION_MODEL=<your-optimization-model-deployment-name>
Exécutez le script à partir de ce même dossier de travail afin de load_dotenv() pouvoir charger le .env fichier automatiquement. Si vous préférez l’exécuter à partir d’un autre répertoire, définissez d’abord les mêmes valeurs dans votre environnement shell.
Utilisez le point de terminaison de projet exact à partir de la page Vue d’ensemble de votre projet Foundry.
Le script Python envoie immédiatement sa première requête. Si FOUNDRY_PROJECT_ENDPOINT est seulement un espace réservé ou pointe vers le mauvais projet, l’exécution échoue avec ResourceNotFound: The project does not exist.
Définissez EVAL_MODEL et OPTIMIZATION_MODEL sur des noms de déploiement qui existent déjà dans votre projet Foundry, et pas seulement sur des noms de famille de modèles. Par exemple, si votre déploiement de projet est nommé gpt-4.1-mini ou DeepSeek-V3.2, utilisez ce nom de déploiement exact dans .env.
2. Exécuter le travail d’optimisation
Créez un fichier nommé optimize_hosted_agent.py dans le même dossier que .env:
import os
import time
from azure.ai.agentserver.optimization import load_config
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
OptimizationAgentIdentifier,
OptimizationEvaluatorRef,
OptimizationJob,
OptimizationJobInputs,
OptimizationOptions,
OptimizationReferenceDatasetInput,
)
from azure.identity import DefaultAzureCredential
from dotenv import load_dotenv
load_dotenv()
endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
agent_name = os.environ["FOUNDRY_AGENT_NAME"]
dataset_name = os.environ["DATASET_NAME"]
evaluator_name = os.environ["EVALUATOR_NAME"]
dataset_version = os.environ.get("DATASET_VERSION", "1")
eval_model = os.environ.get("EVAL_MODEL", "gpt-4o")
optimization_model = os.environ.get("OPTIMIZATION_MODEL", "gpt-5")
poll_interval_seconds = int(os.environ.get("POLL_INTERVAL_SECONDS", "10"))
optimization_config = load_config() # Reads agent optimization config from .agent_configs/baseline/metadata.yaml
with (
DefaultAzureCredential() as credential,
AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
):
job = OptimizationJob(
inputs=OptimizationJobInputs(
agent=OptimizationAgentIdentifier(agent_name=agent_name),
train_dataset=OptimizationReferenceDatasetInput(
name=dataset_name,
version=dataset_version,
),
evaluators=[OptimizationEvaluatorRef(name=evaluator_name)],
options=OptimizationOptions(
max_candidates=2,
eval_model=eval_model,
optimization_model=optimization_model,
optimization_config={
"system_prompt": optimization_config.instructions,
**({"tools": optimization_config.tool_definitions} if optimization_config.tool_definitions else {}),
**({"skills": optimization_config.skills} if optimization_config.has_skills else {}),
}
),
)
)
poller = project_client.beta.agents.begin_create_optimization_job(job=job)
print(f"Optimization job started, waiting for completion...")
while not poller.done():
print(f"\tstatus=`{poller.status()}`")
time.sleep(poll_interval_seconds)
result = poller.result()
if result:
print(f"Baseline candidate: {result.baseline}")
print(f"Best candidate: {result.best}")
for candidate in result.candidates or []:
print(
f"{candidate.name}: candidate_id={candidate.candidate_id}, "
f"avg_score={candidate.avg_score:.4f}, "
f"avg_tokens={candidate.avg_tokens:.0f}"
)
Exécutez le script :
python optimize_hosted_agent.py
Lorsque la tâche réussit, le script affiche le candidat retenu et son candidate_id.
Contrairement à azd ai agent optimize, le processus du SDK Python ne crée pas de fichier local .agent_configs/baseline/metadata.yaml. Les métadonnées du travail d’optimisation restent dans l’objet retourné job et dans la réponse du service Foundry, y compris le candidat de référence, le meilleur candidat et la liste des candidats marqués.
3. Appliquer le candidat gagnant
Si vous travaillez également dans le projet local azd utilisé dans le flux CLI ci-dessus, appliquez le candidat retenu à l’aide de candidate_id, renvoyé par le script Python :
azd ai agent optimize apply --candidate <candidate-id>
azd deploy
Si vous devez uniquement inspecter le résultat, utilisez les scores et identificateurs d’évaluation des candidats imprimés par le script pour passer en revue la configuration gagnante dans Foundry avant de la promouvoir.
Exécuter l’optimisation dans VS Code
Foundry Toolkit inclut une expérience d’optimisation de l’agent native pour les agents hébergés déployés. À partir du terrain de jeu de l’agent, vous pouvez démarrer une exécution d’optimisation, comparer les candidats à la base de référence, inspecter les modifications de configuration et déployer le meilleur candidat.
Étape 1 : Sélectionner un agent hébergé déployé
- Sélectionnez Foundry Toolkit dans la barre d’activité.
- Sous Mes ressources, sélectionnez Agents.
- Si vous avez déployé un agent hébergé, sélectionnez-le pour ouvrir le terrain de jeu de l’agent hébergé.
- Si vous n’avez pas d’agent hébergé déployé, suivez le chemin d’accès VS Code dans le guide de démarrage rapide : Déployez votre premier agent hébergé. Une fois le déploiement terminé, revenez aux agents et sélectionnez le nouvel agent hébergé.
Étape 2 : Démarrer une exécution d’optimisation
- Sélectionnez l’onglet Optimiser , qui est marqué en préversion.
Sélectionnez Nouvelle optimisation.
Dans Sélectionner un espace de travail, choisissez l’espace de travail qui contient le code de l’agent hébergé sélectionné :
- Sélectionnez Espace de travail actif si l’espace de travail actuel contient le code de l’agent et son
azure.yamlfichier. - Sélectionnez Parcourir... pour ouvrir l’espace de travail qui contient le code de l’agent.
Foundry Toolkit utilise les fichiers d’espace de travail pour préparer l’optimisation et appliquer un candidat au service correspondant
azure.ai.agent.- Sélectionnez Espace de travail actif si l’espace de travail actuel contient le code de l’agent et son
Foundry Toolkit ouvre GitHub Copilot Chat et envoie une requête à l’Optimiseur d’agent contenant le type, le nom et le point de terminaison du projet Foundry de l’agent sélectionné.
Répondez aux quatre questions d’optimisation dans Copilot Chat :
Input Que fournir Mesures d’évaluation Entrez les métriques ou évaluateurs à utiliser. Si vous ne les avez pas, choisissez d’exécuter azd ai agent eval generateou d’utiliser les valeurs par défaut intégrées de l’optimiseur.Dataset Sélectionnez le jeu de données d’optimisation. Si vous n’en avez pas, choisissez d’exécuter azd ai agent eval generateou d’utiliser les valeurs par défaut intégrées de l’optimiseur.Nombre maximal de candidats Entrez le nombre maximal de candidats à générer, comme 2.Modèle d’optimisation Sélectionnez un déploiement existant à partir des modèles d’optimisation pris en charge.
GitHub Copilot attend ces entrées avant de commencer l’optimisation. La requête générée demande à Copilot d'utiliser exclusivement le flux de travail Agent Optimizer de Microsoft Foundry Skill et les commandes de l'interface Azure Developer CLI. Il n’utilise pas les outils Foundry MCP. Copilot :
- Inspecte le code de l’agent dans l’espace de travail sélectionné.
- Initialise un environnement AZD à partir des valeurs existantes
azure.yamlet.env, si le projet n’en a pas déjà un. - Configure l’assistant pour l’optimisation et déploie l’assistant hébergé mis à jour.
- Crée
eval.yamldans le dossier de service de l’agent. - Démarre l’optimisation après avoir examiné et approuvé les modifications et commandes de fichier proposées.
Une fois que Copilot a envoyé la tâche, revenez à l’onglet Optimiser. L’exécution apparaît sous Exécutions d’optimisation. Le tableau affiche son ID d’exécution, son état, son nombre de candidats, son score de référence, son meilleur score et son heure de création.
Étape 3 : Comparer et déployer le meilleur candidat
- Une fois l’exécution réussie, sélectionnez-la sous Optimisation.
- Comparez les scores de référence et les meilleurs scores. Passez en revue les détails du score pour chaque candidat, puis sélectionnez Afficher les modifications pour inspecter ses modifications de configuration.
- Si le meilleur candidat s’améliore sur la base de référence, sélectionnez Déployer le meilleur candidat pour mettre à jour l’agent actuel. Pour le déployer en tant que nouvel agent ou modifier les paramètres de déploiement, sélectionnez Déploiement personnalisé à la place.
Note
Si tous les candidats sont inférieurs à la ligne de base, ne déployez pas de candidat. Conservez l’agent actuel et révisez les paramètres de jeu de données ou d’optimisation avant d’exécuter à nouveau l’optimiseur.
Exécuter l’optimisation avec la compétence Microsoft Foundry
Utilisez ce chemin dans n’importe quel hôte d’agent de codage qui prend en charge la compétence Microsoft Foundry, telle que GitHub Copilot dans Visual Studio Code, Copilot CLI ou Claude Code. La compétence détermine le contexte de l’assistant à partir de azure.yaml, charge son workflow Agent Optimizer et maintient l’application candidate ainsi que son déploiement derrière des étapes de validation.
Étape 1 : Ouvrir l’espace de travail de l’agent
Ouvrez un dossier vide dans l’environnement hôte de votre agent de code. Vérifiez que la microsoft-foundry compétence est disponible. Si la compétence n'est pas disponible, suivez Utiliser la compétence Microsoft Foundry dans les agents de programmation.
Étape 2 : Demandez au skill d’exécuter Agent Optimizer
Envoyez cette invite à votre agent de codage :
Use the Microsoft Foundry Skill to run the Agent Optimizer workflow for a
Python hosted agent. If this workspace doesn't contain an agent, initialize the
customer support optimization sample from this template:
https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/bring-your-own/responses/optimization-customer-support/azure.yaml
Resolve the AZD environment and hosted-agent service, verify that the agent is
optimizer-ready, and deploy and invoke the baseline. Generate and show me the
evaluation dataset, evaluators, and eval.yaml before running optimization.
Verify that the project has a supported optimization model deployment, then run
Agent Optimizer with two candidates. Stop after reporting the operation ID,
portal URL, candidate IDs, and scores. Don't apply or deploy a candidate yet.
L’agent de codage peut vous demander de sélectionner un abonnement, une région, un projet Foundry, un service d’agent, un modèle d’évaluation ou un modèle d’optimisation lorsqu’il ne peut pas résoudre ces valeurs à partir de l’espace de travail. Passez en revue les fichiers générés et les ressources entraînant des coûts avant d’approuver toute modification ou commande.
Étape 3 : Appliquer et déployer un candidat approuvé
Après avoir examiné les résultats de l’optimisation, envoyez cette invite de suivi :
Recommend the best optimization candidate and explain the score improvement.
Summarize the candidate changes before applying anything. After I approve the
candidate, apply it locally, show the source diff, and stop again before
deployment. After I approve deployment, run azd deploy, invoke the agent with
"What is your return policy?", and rerun the evaluation to confirm the
improvement.
La compétence utilise azd ai agent optimize apply --candidate <candidate-id> pour pouvoir passer en revue la configuration optimisée localement. Il ne se déploie qu’après votre approbation, puis appelle et évalue l’agent hébergé mis à jour.
Nettoyer les ressources
Si votre flux de travail a créé des ressources via le projet AZD, supprimez les ressources approvisionnées lorsque vous terminez l’expérience :
azd down --force --purge
Conseil / Astuce
Pourquoi --purge? Les comptes Foundry utilisent, par défaut, la suppression réversible. Sans --purge, le nom de la ressource reste réservé pendant 48 heures et la reprovisionnement avec le même nom échoue.
Résolution des problèmes
| Problème | Cause | Réparer |
|---|---|---|
azd ai agent optimize commande introuvable |
Extension trop ancienne | Exécutez azd ext upgrade microsoft.foundry pour obtenir la version 0.1.40-preview ou ultérieure. |
optimization_model is required |
Exécution en mode non interactif sans modèle configuré | Ajoutez --optimize-model gpt-5 à la commande, ou définissez optimization_model: gpt-5 sous options: dans eval.yaml. En mode interactif, l’interface CLI invite à sélectionner le modèle. |
Python script échoue avec KeyError: 'DATASET_NAME' ou une autre variable manquante |
Le script n’a pas chargé votre .env fichier, ou la variable est manquante |
Exécutez le script à partir du même dossier que .env, ou exportez les valeurs requises dans votre interpréteur de commandes avant d’exécuter python optimize_hosted_agent.py. |
Le script Python échoue avec ResourceNotFound: The project does not exist |
FOUNDRY_PROJECT_ENDPOINT ne pointe pas vers un projet Foundry existant |
Copiez le point de terminaison de projet à partir de la page Vue d’ensemble du projet Foundry et mettez à jour FOUNDRY_PROJECT_ENDPOINT dans .env. |
Le script Python échoue avec Optimization model deployment '<name>' not found |
OPTIMIZATION_MODEL n’est pas le nom d’un modèle déployé dans votre projet Foundry |
Utilisez le nom exact du déploiement dans Build>Deployments, par exemple une famille gpt-5 existante ou un déploiement DeepSeek dans votre projet. |
| La section Optimiser n’apparaît pas pour un agent hébergé | Foundry Toolkit est antérieur à la version 1.6.4, ou l’agent sélectionné n’est pas un agent hébergé déployé | Mettez à jour Foundry Toolkit, rechargez Visual Studio Code et rouvrez l’agent déployé à partir de l’onglet Agents. |
| GitHub Copilot Chat ne s'ouvre pas après avoir sélectionné l'espace de travail | GitHub Copilot n'est pas installé, n'est pas disponible pour votre compte, ou le mode agent est désactivé | Configurez GitHub Copilot dans Visual Studio Code, activez le mode agent, puis sélectionnez Nouvelle optimisation. |
| Foundry Toolkit ne peut pas appliquer le meilleur candidat à l’espace de travail actuel | L’espace de travail ne contient pas de azure.yaml service dont le nom correspond à l’agent hébergé déployé |
Ouvrez l’espace de travail qui contient le code de l’agent sélectionné et le service correspondant azure.ai.agent , puis réessayez. |
| L’agent de codage ne peut pas trouver l’agent hébergé | Le dossier incorrect est ouvert ou azure.yaml ne définit pas de azure.ai.agent service |
Ouvrez le dossier de projet AZD qui contient azure.yaml, puis demandez à l’agent de codage de résoudre à nouveau le service d’agent hébergé. |
| L’agent de codage s’arrête avant d’appliquer ou de déployer un candidat | La compétence Agent Optimizer doit être examinée avant toute modification de la source et tout déploiement | Passez en revue les scores des candidats et les différences locales, puis approuvez explicitement l’étape d’application ou de déploiement. |
| Le score d’optimisation est de 0 ou très faible | L’évaluation comporte de nombreuses lignes erronées | Ouvrez le lien Eval dans les résultats. Corrigez les erreurs de génération de réponse ou d’évaluateur, puis réexécutez. |
azd provision échoue avec une erreur de quota |
L’abonnement ne dispose pas de capacité | Essayez une autre région ou demandez une augmentation de quota. |
Ce que vous avez appris
Dans ce guide de démarrage rapide, vous :
- Déployé l’exemple d’agent d’optimisation à l’aide du modèle de support client.
- Exécution de l’optimiseur d’agent à l’aide de l’interface CLI Azure développeur, du SDK Python, du Visual Studio Code ou de la compétence Microsoft Foundry.
- Déployé le candidat gagnant et vérifié l’amélioration.