Développement d’agents avec Azure Developer CLI

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 en ligne de commande unique pour passer d’une idée à un agent prêt pour la production sur Microsoft Foundry. Vous pouvez développer des agents hébergés basés sur le code et des agents vocaux déclaratifs reposant sur des invites textuelles. 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 agent hébergé à partir d’un modèle ou de votre code existant, ou créez un agent vocal basé sur des invites. Démarrage rapide : Déployer un agent hébergé ou démarrage rapide : Créer un agent vocal d’invite
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 à l’aide d’une boîte à outils et testez localement. Vue d’ensemble de la boîte à 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 prend en charge les types d’agents basés sur le code et déclaratifs.

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.
Agent vocal basé sur des prompts Agent vocal déclaratif qui utilise un modèle managé ou auto-déployé sans code d’exécution personnalisé. Vous souhaitez une expérience vocale conversationnelle en temps réel sans créer et héberger un pipeline audio.
Agent vocal hébergé avec une encapsulation gérée Une cible hébergée gère la logique conversationnelle, tandis qu’un service vocal distinct s’en remet à elle via conversationEngine. Voice Live gère l’expérience audio. Vous avez besoin d’une logique d’agent personnalisée sans implémenter la reconnaissance vocale et la synthèse vocale dans la cible hébergée.

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.

Les agents vocaux basés sur des instructions ne nécessitent pas de conteneur personnalisé. Si vous devez exécuter un pipeline audio en cascade ou de reconnaissance vocale personnalisé dans votre propre conteneur, créez un agent vocal avec un agent hébergé et utilisez le invocations_ws protocole.

Pour conserver la logique de conversation dans un agent textuel hébergé tandis que Voice Live gère l’audio, utilisez le workflow d’encapsulation vocale hébergée. Le wrapper et la cible sont des services distincts dans le même azure.yaml projet. Ce flux ne remplace pas le flux de pipeline audio personnalisé invocations_ws existant.

Avant d’utiliser les options cli vocale en préversion publique, vérifiez votre extension installée comme décrit dans les prérequis de démarrage rapide de l’agent vocal.

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.

Pour un agent vocal piloté par prompt, azure.yaml stocke la définition déclarative de l’agent, y compris kind: prompt-voice, le modèle, le type de modèle et le nom de l’agent. Il n’inclut pas de runtime de conteneur d’agent hébergé. Pour personnaliser les instructions, l’audio, la détection de tour, la transcription, la sortie vocale, les outils et les messages d’accueil, consultez Configurer un agent vocal.

Pour un wrapper vocal hébergé, conversationEngine.name fait référence au nom du service de la cible hébergée. La dépendance uses de l’encapsuleur détermine l’ordre de déploiement, et conversationEngine.version utilise par défaut la version déployée par l’environnement actuel. Consultez la référence du service vocal pour les champs de configuration.

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’environnement azd actif.
  • En dehors d’un projet azd, définissez le contexte actif une seule fois avec azd ai project set <endpoint>, ou passez --project-endpoint à une commande de ressource individuelle (connection, toolbox, skill ou routine). En guise de secours, azd ai lit la variable d’environnement FOUNDRY_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é.

Ces paramètres de protocole s’appliquent aux conteneurs d’agent hébergé. Les agents vocaux basés sur des prompts ne configurent pas de protocole pour agent hébergé.

azd ai agent invoke ne prend pas en charge les conversations vocales pour les agents vocaux basés sur des prompts ou les wrappers vocaux hébergés. Pour obtenir des conseils sur le comportement et les tests de l’interface CLI, consultez les limitations de l’agent vocal.

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.

Pour la procédure relative à l’agent vocal géré, consultez Démarrage rapide : Créer un agent vocal basé sur des prompts.

# 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

Contenu connexe

  • Last updated on