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
Les éléments indiqués comme (aperçu) dans cet article sont en aperçu public. 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.
L’interface CLI Azure développeur (azd) et son azd ai agent extension vous donnent un flux de travail de ligne de commande unique pour passer d’une idée à un agent hébergé prêt pour la production sur Microsoft Foundry. Cet article explique le parcours du développeur, les fichiers qui définissent un agent et les concepts fondamentaux que vous rencontrez le long de la route.
Cet article s’adresse aux développeurs qui préfèrent un flux de travail axé sur le terminal et scriptable, plutôt qu’au portail Foundry ou aux SDK de langage.
Parcours du développeur
Le azd ai flux de travail suit le même cycle de vie que vous construisiez un petit prototype ou un agent de production. Vous mettez en place la structure d’un projet une seule fois, puis combinez les commandes selon vos besoins à mesure que votre projet évolue.
| Étape | Ce que vous faites | Où en savoir plus |
|---|---|---|
| Install | Installez azd et les extensions Foundry. |
Configurer votre environnement de développement |
| Échafaudage | Initialisez un projet à partir d’un modèle ou de votre code existant. | Démarrage rapide : Déployer un agent hébergé |
| Définir | Configurez l’agent, les dépendances de déploiement de modèle, les protocoles, les outils et l’environnement dans azure.yaml. |
Créer un fichier azure.yaml pour les agents hébergés |
| Développer | Écrivez la logique de l’agent, ajoutez des outils et testez localement. | Vue d’ensemble des outils |
| Deploy | Configurez l’infrastructure et déployez sur Foundry. | Déployer un agent hébergé |
| Opérer | Surveillez les logs, gérez les versions et automatisez les lancements. | Gérer les agents hébergés |
| Evaluate | Mesurez la qualité de l’agent et améliorez le prompt. | Exécuter des évaluations d’agent avec l’interface CLI azd |
Types d’agents
L’extension azd ai agent se concentre sur les agents hébergés.
| Type | Description | Quand utiliser |
|---|---|---|
| Agent hébergé | Une application conteneurisée que vous développez par code, empaquetez sous forme d’image Docker et déployez sur Foundry. | Vous avez besoin d’une logique personnalisée, d’une intégration de framework ou d’un contrôle total sur le comportement. |
| Agent de prompt | Un agent défini entièrement par le biais d’instructions et de configurations d’outils, sans code personnalisé. | Vous souhaitez un agent rapide piloté par la configuration sans écrire de code d’application. |
Les agents hébergés vous donnent un contrôle total sur le runtime, l’infrastructure et les intégrations d’outils, tandis que Foundry gère l’infrastructure, la mise à l’échelle et la gestion des sessions.
Fichiers de configuration
Un projet d’agent hébergé utilise un azure.yaml fichier à la racine du projet pour déclarer l’agent et son modèle de provisionnement et de déploiement. Le fichier utilise un modèle de fractionnement de service, où chaque service nommé a une host valeur telle que azure.ai.project, , azure.ai.agent, azure.ai.connection, azure.ai.toolboxazure.ai.skillou azure.ai.routine.
| Fichier | Purpose | Qui le maintient |
|---|---|---|
azure.yaml |
Déclare le projet Foundry, les déploiements de modèles, le service d’agent hébergé, les dépendances, les protocoles, les outils, les variables d’environnement, les ressources de conteneur et les paramètres de déploiement. L’identité, le modèle, les protocoles, les outils et les valeurs d’environnement de l’agent vivent dans le azure.ai.agent service. |
L’initialisation le génère. Vous le personnalisez selon vos besoins. |
Le azure.ai.agent service définit votre agent hébergé inline et utilise uses: pour référencer d’autres services, tels que le projet, les connexions, les boîtes à outils, les compétences et les routines. Il n’existe pas de fichier agent.yaml ou agent.manifest.yaml autonome dans le modèle de projet actuel de l’agent hébergé azd.
Substitution de variable
Utilisez ${VAR_NAME} dans azure.yaml pour les valeurs qui diffèrent selon l’environnement azd. L'espace réservé est résolu à partir de .azure/<env>/.env lors du déploiement ou à l’exécution, de sorte que le même azure.yaml fonctionne dans différents environnements tels que dev, staging et production.
Où l’interface CLI s’exécute
Les commandes azd ai fonctionnent aussi bien à l’intérieur qu’à l’extérieur d’un répertoire azd de projet :
- À l’intérieur d’un projet
azd, les commandes déterminent le point de terminaison du projet dans Foundry à partir de l’environnementazdactif. - En dehors d’un projet
azd, définissez le contexte actif une seule fois avecazd ai project set <endpoint>, ou passez--project-endpointà une commande de ressource individuelle (connection,toolbox,skillouroutine). En guise de secours,azd ailit la variable d’environnementFOUNDRY_PROJECT_ENDPOINT. - Un environnement propre au projet prévaut toujours sur le contexte global ; ainsi, lorsqu’on se place dans le répertoire d’un projet, l’interface en ligne de commande pointe vers le point de terminaison de ce projet.
Protocoles
Un protocole définit le contrat HTTP entre Foundry et votre conteneur d’agent. Votre agent écoute sur le port 8088 et expose une sonde d'intégrité, quel que soit le protocole.
| Protocol | Style d’API | Quand utiliser |
|---|---|---|
responses |
API Réponses OpenAI (POST /responses) |
Le choix standard, compatible avec l’écosystème d’API OpenAI. |
invocations |
Contrat JSON personnalisé (POST /invocations) |
Lorsque vous avez besoin d’un contrôle total sur les charges utiles de demande et de réponse. |
Pour obtenir la spécification complète, consultez le contrat d’exécution de l’agent hébergé.
Sessions et conversations
| Concept | Description |
|---|---|
| Session | Environnement d’exécution isolé pour une interaction d’agent unique. Chaque session s’exécute dans son propre bac à sable avec des ressources dédiées. |
| Conversation | Séquence de messages au sein d’une session. Foundry gère l’historique des conversations et peut l’hydrater entre les requêtes. |
Les sessions sont identifiées par un session_id. Lorsque vous exécutez azd ai agent invoke, Foundry réutilise la session à partir de votre dernier appel par défaut. Permet --new-session de démarrer une nouvelle session ou --session-id <id> de cibler une session spécifique.
Ressources sur un projet Foundry
Un projet Foundry héberge plus que de simples agents. Il contient également des ressources partagées référencées par les agents au moment de l’exécution. L’interface CLI gère chacun d’eux via un groupe de commandes dédié.
| Resource | Qu’est-ce que c’est ? | Géré avec |
|---|---|---|
| Connection | Lie un projet Foundry à une ressource externe, telle qu’un serveur MCP, Recherche Azure AI ou Grounding avec Bing. | Commandes azd ai connection |
| Boîte à outils | Collection nommée d’outils que les agents utilisent au moment de l’exécution. | Commandes azd ai toolbox |
| Habileté | Recommandations comportementales réutilisables partagées entre les agents sur le projet. | Commandes azd ai skill |
| Routine | Un déclencheur associé à une action qui invoque un agent. | Commandes azd ai routine |
Ces ressources sont partagées entre les développeurs et les agents sur le même projet. Chaque groupe de commandes expose les verbes standard create, update, delete, show et list.
Évaluer et améliorer un agent
Une fois qu’un agent s’exécute, deux flux de travail connexes vous aident à mesurer et à améliorer sa qualité :
- L’évaluation exécute votre agent sur un ensemble de données, évalue les réponses à l’aide d’un ou de plusieurs évaluateurs et fournit un indicateur global de qualité. Vous le gérez avec
azd ai agent eval. - L’optimisation réécrit de manière itérative le prompt de votre agent afin d’améliorer un signal d’évaluation. Il utilise une évaluation comme fonction objective et produit un prompt candidat que vous examinez et acceptez. Vous le gérez avec
azd ai agent optimize.
Pour plus d’informations, consultez Exécuter les évaluations de l’agent avec l’interface CLI azd et optimiser les invites de l’agent.
Cycle de vie du déploiement
La boucle de développement complète se condense en une courte séquence de commandes. Mettez en place la structure initiale une seule fois, puis utilisez les commandes directes à mesure que votre projet se développe.
# Scaffold a project from a template or your existing code
azd ai agent init
# Run locally and invoke
azd ai agent run
azd ai agent invoke --local "Hello, world!"
# Provision infrastructure and deploy the agent
azd up
# Extend the project with shared resources at any time
azd ai connection create my-search --kind cognitive-search --target https://... --auth-type api-key --key "..."
azd ai routine create daily-digest --trigger recurring --cron "0 7 * * *" --agent-name my-agent
# Evaluate quality
azd ai agent eval generate
azd ai agent eval run
# Tear down all Azure resources
azd down