Démarrage rapide : Déployer votre premier agent hébergé

Dans ce guide de démarrage rapide, vous déployez un agent IA conteneurisé avec les outils Foundry dans le Service des agents Foundry. L’exemple d’agent utilise des outils de recherche web et éventuellement des outils MCP (Model Context Protocol) pour répondre aux questions. À la fin, vous disposez d’un agent hébergé en cours d’exécution avec lequel vous pouvez interagir via le terrain de jeu Foundry. Choisissez votre méthode de déploiement préférée pour commencer.

Dans ce guide de démarrage rapide, vous allez :

  • Configurer un exemple d’agent project avec les outils Foundry
  • Tester l’agent localement
  • Déployer sur le service de l’agent Foundry
  • Interagir avec votre agent dans le terrain de jeu
  • Nettoyer les ressources

Prerequisites

Avant de commencer, vous avez besoin des éléments suivants :

Note

Les agents hébergés sont actuellement en préversion.

Autorisation requise

Vous avez besoin d’Azure AI Project Manager au niveau de l’étendue du projet pour créer et déployer des agents hébergés. Ce rôle inclut les autorisations de plan de données pour créer des agents et la possibilité d’attribuer le rôle d’utilisateur Azure AI à l’identité de l’agent créé par la plateforme. L’identité de l’agent a besoin d’Un utilisateur Azure AI sur le projet pour accéder aux modèles et artefacts au moment de l’exécution.

Si vous utilisez azd ou l’extension de VS Code, l’outil gère automatiquement la plupart des attributions de rôles RBAC, notamment :

Vérifiez que l’identité managée du projet Foundry a un rôle de lecture ACR sur l'Azure Container Registry que vous utilisez. Si vous préférez et que vous disposez d’un accès Propriétaire ou « Administrateur de l’accès utilisateur », l’outil azd/vscode peut également effectuer cette affectation pour vous. Utilisateur Azure AI pour l’identité de l’agent créé par la plateforme (modèle d’exécution et accès aux outils)

Étape 1 : Configurer l’exemple de project

Avertissement

Ce document concerne les agents hébergés sur le nouveau serveur principal et nécessite azd ai agent version 0.1.27-preview ou ultérieure. Pour l’expérience héritée qui utilise Azure Container Apps, continuez à utiliser la version 0.1.25-preview.

Installez l’extension de l’agent CLI développeur Azure et initialisez un nouveau projet d’agent hébergé.

  1. Installez l’extension ai agent pour l’interface CLI développeur Azure :

    azd ext install azure.ai.agents

    Pour vérifier que l’extension est installée, exécutez :

    azd ext list

  2. Initialisez un nouveau projet d’agent hébergé dans un répertoire vide :

    azd ai agent init

    Le flux interactif vous guide tout au long de la configuration suivante :

    • Langage : sélectionnez le langage de programmation pour lequel vous souhaitez obtenir un exemple de code, C# ou Python.
    • Modèle d’agent : sélectionnez un exemple pour commencer.
    • Configuration du modèle : sélectionnez le déploiement d’un nouveau modèle dans Foundry ou utilisez un modèle existant à partir d’un projet Foundry existant.
    • Azure abonnement, sélectionnez l’abonnement dans lequel vous souhaitez que les ressources Foundry soient créées.
    • Emplacement : sélectionnez une région pour les ressources.
    • Référence SKU de modèle : sélectionnez la référence SKU disponible pour votre région et votre abonnement.
    • Nom du déploiement : entrez un nom pour le déploiement du modèle.
    • Taille du conteneur : sélectionnez l’allocation de processeur et de mémoire ou acceptez les valeurs par défaut.

    Important

    Si vous avez sélectionné un exemple avec des outils et que vous n’utilisez pas de serveur MCP, commentez ou supprimez les lignes suivantes dans le agent.yaml fichier :

    - name: AZURE_AI_PROJECT_TOOL_CONNECTION_ID
  value: <CONNECTION_ID_PLACEHOLDER>

    Conseil / Astuce

    Si vous exécutez dans un environnement non interactif tel qu’un pipeline CI/CD ou une session SSH, utilisez l’indicateur --no-prompt avec azd ai agent init. Vous devez également fournir toutes les valeurs requises en tant qu’indicateurs de ligne de commande plutôt que de répondre aux invites interactives.

  3. Provisionnez les ressources Azure requises :

    Note

    Vous avez besoin d’un accès Contributor sur votre abonnement Azure pour l’approvisionnement des ressources.

    azd provision

    Cette commande prend quelques minutes et crée les ressources suivantes :

    Resource Objectif Coûts
    groupe de ressources Organise toutes les ressources associées dans la même zone Aucun coût
    Déploiement de modèle Modèle utilisé par l’agent Découvrez les tarifs Foundry
    Projet de fonderie Héberge votre agent et fournit des fonctionnalités d’IA Basé sur la consommation ; consultez Tarification de Foundry
    Azure Container Registry Stocke les images de conteneur de votre agent Niveau de base ; consultez la tarification ACR
    espace de travail Log Analytics Gérer toutes les données de journal en un seul endroit Aucun coût direct. Consultez le coût de Log Analytics
    Application Insights Surveille les performances de l’agent et les journaux de bord Paiement à l’utilisation ; consultez Azure Monitor tarification
    Identité managée Authentifie votre agent pour Azure services Aucun coût

    Conseil / Astuce

    Exécutez azd down lorsque vous avez terminé ce guide de démarrage pour supprimer des ressources et éviter des frais supplémentaires.

Étape 2 : Tester l’agent localement

Avant de déployer, vérifiez que l’agent fonctionne localement.

  1. Démarrez l’agent localement :

    azd ai agent run

    Cette commande configure automatiquement l’environnement, installe les dépendances et démarre l’agent. Il utilise l'élément startupCommand défini dans azure.yaml pour lancer votre agent.

    Note

    Les packages en préversion peuvent générer des avertissements de conflit de version de dépendance pip pendant l’installation. Ces avertissements ne sont pas bloquants : l’agent démarre et répond correctement malgré eux.

    Si l’agent ne parvient pas à démarrer, vérifiez les problèmes courants suivants :

    Erreur Solution
    AuthenticationError ou DefaultAzureCredential échec Exécutez azd auth logout puis azd auth login pour actualiser votre session.
    ResourceNotFound Vérifiez que vos URL de point de terminaison correspondent aux valeurs du portail Foundry.
    DeploymentNotFound Vérifiez le nom du déploiement dans Build>Deployments.
    Connection refused Vérifiez qu’aucun autre processus n’utilise le port 8088.

  2. Dans un terminal distinct, envoyez un message de test à l’agent local.

    Pour les agents utilisant l’API Réponses, vous pouvez envoyer une chaîne en tant que charge utile :

    azd ai agent invoke --local "What is Microsoft Foundry?"

    Pour les agents utilisant l’API Invocations, vérifiez la README.md charge utile attendue. Les exemples nécessitent généralement une charge utile JSON, mais passez en revue ce qui se trouve dans cet README.md exemple pour un exemple spécifique :

    Vous devez voir une réponse de l’agent.

Étape 3 : Déployer sur le service de l’agent Foundry

Étant donné que vous avez déjà approvisionné l’infrastructure à l’étape 1, déployez votre code d’agent sur Azure :

azd deploy

Le conteneur de l’agent est généré à distance. Docker Desktop n’est donc pas requis sur votre ordinateur.

Note

La azd deploy commande affecte des rôles RBAC Azure à l’identité de l’agent. Cette attribution de rôle nécessite des autorisations d’administrateur d’accèsutilisateur ou propriétaire sur votre abonnement, en plus du rôle Contributeur requis pour l’approvisionnement.

Avertissement

Votre agent hébergé entraîne des frais lors du déploiement. Une fois les tests terminés, effectuez le nettoyage des ressources pour supprimer les ressources et arrêter les frais.

Une fois terminé, le résultat affiche un lien vers l'Agent Playground et le point de terminaison pour appeler l'agent par programmation :

Deploying services (azd deploy)

  (✓) Done: Deploying service af-agent-with-foundry-tools
  - Agent playground (portal): https://ai.azure.com/nextgen/.../build/agents/af-agent-with-foundry-tools/build?version=1 
  - Agent endpoint: https://ai-account-<name>.services.ai.azure.com/api/projects/<project>/agents/af-agent-with-foundry-tools/versions/1

Important

Veillez à utiliser la version préliminaire de l’extension Microsoft Foundry Toolkit et l’extension Foundry dans VS Code.

Dans votre page extensions VS Code, choisissez l’extension Foundry Toolkit et l’extension Foundry et basculez vers la version préliminaire.

Étape 1 : Créer un projet Foundry

Utilisez l’extension Microsoft Foundry Toolkit dans VS Code pour créer une ressource Microsoft Foundry Project.

  1. Ouvrez la palette de commandes (Ctrl+Maj+P), puis sélectionnez Microsoft Foundry : Create Project.

  2. Sélectionnez votre abonnement Azure.

  3. Créez un groupe de ressources ou sélectionnez-en un existant.

  4. Entrez un nom pour la ressource Project Foundry.

Une fois la création du projet terminée, passez à l’étape suivante et déployez un modèle.

Étape 2 : Déployer un modèle

Utilisez l’extension Microsoft Foundry Toolkit dans VS Code pour déployer un modèle sur Foundry.

  1. Ouvrez la palette de commandes (Ctrl+Maj+P) et sélectionnez Microsoft Foundry : Open Model Catalog.

  2. Parcourez le catalogue de modèles ou recherchez gpt-4.1 et sélectionnez le bouton Déployer .

  3. Dans la page Déploiement du modèle, sélectionnez le bouton Deploy to Microsoft Foundry.

Une fois le modèle déployé, passez à l’étape suivante et créez un projet d’agent hébergé.

Étape 3 : Créer un projet d’agent hébergé

Utilisez l’extension Microsoft Foundry Toolkit dans VS Code pour générer une structure d’un nouveau projet d’agent hébergé.

  1. Ouvrez la palette de commandes (Ctrl+Maj+P), puis sélectionnez Microsoft Foundry : Create new Hosted Agent.

  2. Sélectionnez l’infrastructure que vous souhaitez utiliser.

  3. Sélectionnez un langage de programmation, Python ou C#.

  4. Sélectionnez l’API Réponses ou l’API d'appel.

  5. Sélectionnez l’exemple de code que vous souhaitez utiliser.

  6. Choisissez le dossier dans lequel vous souhaitez enregistrer vos fichiers projet.

  7. Entrez un nom pour l’agent hébergé.

Une nouvelle fenêtre VS Code s’ouvre avec le nouveau dossier de projet agent en tant qu’espace de travail actif.

Étape 4 : Installer les dépendances

Il est recommandé d’utiliser un environnement virtuel pour isoler les dépendances de projet :

macOS/Linux :

python -m venv .venv
source .venv/bin/activate

Windows (PowerShell) : 

python -m venv .venv
.\.venv\Scripts\Activate.ps1

Installation des dépendances

Installez les dépendances de Python requises à l’aide de pip :

pip install -r requirements.txt

Consultez la requirement.txt pour obtenir la liste des packages requis.

Étape 5 : Tester l’agent localement

Procédez à l’exécution et aux tests de votre agent avant son déploiement.

Appuyez sur F5 dans VS Code pour démarrer le débogage. Vous pouvez également utiliser le menu de débogage VS Code :

  1. Ouvrez la vue Exécuter et Déboguer (Ctrl+Maj+D / Cmd+Maj+D)
  2. Sélectionnez « Déboguer le serveur HTTP du flux de travail local » dans la liste déroulante
  3. Cliquez sur le bouton Démarrer le débogage vert (ou appuyez sur F5)

Cela va :

  1. Démarrer le serveur HTTP avec débogage activé
  2. Ouvrez l’inspecteur de l’agent Foundry Toolkit pour les tests interactifs
  3. Vous permet de définir des points d’arrêt et d’inspecter le flux de travail

Option 2 : Exécuter dans le terminal

Exécutez en tant que serveur HTTP (par défaut) :

python main.py

Cela démarre l’agent hébergé localement sur http://localhost:8088/.

PowerShell (Windows) : 

$body = @{
   input = "I need a hotel in Seattle from 2025-03-15 to 2025-03-18, budget under `$200 per night"
    stream = $false
} | ConvertTo-Json

Invoke-RestMethod -Uri http://localhost:8088/responses -Method Post -Body $body -ContentType "application/json"

Bash/curl (Linux/macOS) :

curl -sS -H "Content-Type: application/json" -X POST http://localhost:8088/responses \
   -d '{"input": "Find me hotels in Seattle for March 20-23, 2025 under $200 per night","stream":false}'

L’agent utilisera l’outil get_available_hotels pour rechercher des hôtels disponibles correspondant à vos critères.

Étape 6 : Déployer sur le service de l’agent Foundry

Déployez votre agent directement à partir de VS Code.

  1. Ouvrez la palette de commandes (Ctrl+Maj+P), puis sélectionnez Microsoft Foundry : Deploy Hosted Agent.

  2. Sélectionnez « ACR par défaut »

  3. Sélectionnez la configuration du processeur et de la mémoire pour le conteneur De l’Agent hébergé.

Basculez vers l’Explorateur Microsoft Foundry Toolkit en sélectionnant l’icône à gauche. Une fois le déploiement achevé, l’agent est visible dans la barre latérale de l’arborescence Agents hébergés (Préversion).

Vérifier et tester votre agent

Une fois le déploiement terminé, vérifiez que votre agent est en cours d’exécution.

Vérifier l’état de l’agent

Assurez-vous de l’état de votre agent afin de confirmer qu’il fonctionne correctement.

  1. Sélectionnez votre agent hébergé dans l’arborescence des Agents hébergés (aperçu).

  2. Sélectionnez l’agent que vous venez de déployer

La page de détails affiche l’état sous la section Détails du conteneur.

Tester dans le terrain de jeu à l’aide de VS Code

Microsoft Foundry Toolkit pour VS Code inclut un terrain de jeu intégré pour discuter et interagir avec votre agent.

  1. Sélectionnez votre agent hébergé dans l’arborescence des Agents hébergés (aperçu).

  2. Sélectionnez l’option Playground et tapez un message et envoyez-le pour tester votre agent.

Vérifier l’état de l’agent

Vérifiez l’état de votre agent déployé :

azd ai agent show

Pour afficher la sortie au format de tableau :

azd ai agent show --output table

Si votre projet a plusieurs services d’agent, spécifiez le nom de l’agent comme argument positionnel :

azd ai agent show <agent-name>

Conseil / Astuce

Recherchez <agent-name> dans le azure.yaml fichier sous la services: section.

Tester l’agent déployé

Envoyez un message de test à votre agent déployé à l’aide de la même invoke commande utilisée précédemment, mais sans l’indicateur --local :

Pour les agents utilisant l’API Réponses, vous pouvez envoyer une chaîne en tant que charge utile :

azd ai agent invoke <payload>

Vous devriez voir une réponse de l’agent après quelques secondes.

Afficher les journaux d’activité de l’agent

Surveillez les journaux d'activité en temps réel de votre agent :

# Fetch recent container console logs
azd ai agent monitor

# Fetch the last N lines of console logs
azd ai agent monitor --tail 20

# Fetch system event logs (container start and stop events)
azd ai agent monitor --type system

# Stream session logs in real time
azd ai agent monitor --session <session-id> --follow

Si votre projet a plusieurs services d’agent, spécifiez le nom de l’agent comme argument positionnel :

azd ai agent monitor <agent-name> --follow

Tester dans le terrain de jeu Foundry

Accédez à l’agent dans le portail Foundry :

  1. Ouvrez le portail Foundry et connectez-vous avec votre compte Azure.

  2. Sélectionnez votre project dans la liste Recent projects ou sélectionnez All projects pour le trouver.

  3. Dans le volet de navigation de gauche, sélectionnez Générer pour développer le menu, puis sélectionnez Agents.

  4. Dans la liste des agents, recherchez votre agent déployé (il correspond au nom de l’agent à partir de votre déploiement).

  5. Sélectionnez le nom de l’agent pour ouvrir sa page de détails, puis sélectionnez Ouvrir dans le terrain de jeu dans la barre d’outils supérieure.

  6. Dans l’interface de conversation, tapez un message de test comme « Qu’est-ce que Microsoft Foundry ? » et appuyez sur Enter.

  7. Vérifiez que l’agent répond avec des informations provenant des résultats de la recherche web. La réponse peut prendre quelques secondes, car l’agent interroge des sources externes.

Conseil / Astuce

Si l’environnement de test ne se charge pas ou si l’agent ne répond pas, vérifiez que son état est Started à partir de la page Détails du conteneur mentionnée précédemment.

Nettoyer les ressources

Pour éviter les frais, supprimez les ressources lorsque vous avez terminé.

Avertissement

Cette commande supprime définitivement toutes les ressources Azure dans le groupe de ressources, notamment le projet Foundry, les déploiements de modèles, Container Registry, Application Insights et votre agent hébergé. Cette action ne peut pas être annulée. Si vous utilisez un groupe de ressources existant qui contient d’autres ressources, utilisez la prudence : azd down supprime tout ce qui se trouve dans le groupe, pas seulement les ressources créées par ce guide de démarrage rapide.

Pour afficher un aperçu de ce qui sera supprimé, exécutez la down commande :

azd down

Une fois terminé, azd vous affiche toutes les ressources qui seront supprimées et vous invite à confirmer. Sélectionnez cette option yes pour continuer ou no annuler.

Le processus de nettoyage prend environ 2 à 5 minutes.

Avertissement

La suppression de ressources supprime définitivement toutes les ressources Azure créées dans ce guide de démarrage rapide, notamment le projet Foundry, Container Registry, Application Insights et votre agent hébergé. Cette action ne peut pas être annulée.

Pour supprimer vos ressources, ouvrez le portail Azure, accédez à votre groupe de ressources et supprimez-le avec toutes les ressources contenues.

Pour vérifier que les ressources ont été supprimées, ouvrez le portail Azure, accédez à votre groupe de ressources et vérifiez que les ressources ne s’affichent plus. Si le groupe de ressources est vide, vous pouvez également le supprimer.

Résolution des problèmes

Si vous rencontrez des problèmes, essayez ces solutions pour les problèmes courants :

Problème Solution
SubscriptionNotRegistered erreur Inscrire des fournisseurs : az provider register --namespace Microsoft.CognitiveServices
AuthorizationFailed lors de l’approvisionnement Demandez le rôle Contributeur sur votre abonnement ou groupe de ressources.
L’agent ne démarre pas localement Vérifiez que les variables d’environnement sont définies et exécutées az login pour actualiser les informations d’identification.
AcrPullUnauthorized erreur Accordez le rôle AcrPull à l'identité managée du projet sur le registre de conteneurs.

Pour plus d’informations sur toutes les autorisations et toutes les attributions de rôles impliquées dans le déploiement d’un agent hébergé, consultez les informations de référence sur les autorisations de l’agent hébergé.

Problème Solution
azd ai agent init Échoue Exécutez azd version pour vérifier la version 1.24.0+. Mise à jour avec winget upgrade Microsoft.Azd (Windows) ou brew upgrade azd (macOS). Vérifiez que l’extension de l’agent est installée avec azd ext list. Veillez à disposer de la dernière version de l’extension avec azd ext upgrade azure.ai.agents, version 0.1.27-preview ou ultérieure.

Afficher les journaux de conteneur de votre agent

Consultez la console ainsi que les journaux d’activité du conteneur afin d’identifier et résoudre les anomalies.

  1. Sélectionnez votre agent hébergé dans l’arborescence des Agents hébergés (aperçu).

  2. Sélectionnez l’onglet « Playground » de votre agent hébergé

  3. Sélectionnez la section « Journaux » dans les détails de la session.

Afficher les fichiers de session de votre agent

Vous pouvez afficher tous les fichiers stockés dans le répertoire de base de votre agent ADC

  1. Sélectionnez votre agent hébergé dans l’arborescence des agents hébergés (aperçu).

  2. Sélectionnez l’onglet « Playground » de votre agent hébergé

  3. Sélectionnez la section « fichiers » dans les détails de la session.

Vous pouvez télécharger, téléverser et créer des dossiers dans le dossier actif ; cliquer sur un dossier permet d'y entrer, et cliquer sur la barre de navigation supérieure permet de revenir au niveau précédent.

Problème Solution
Extension introuvable Installez l’extension Microsoft Foundry Toolkit pour VS Code à partir de la Place de marché VS Code.

Ce que vous avez appris

Dans ce guide de démarrage rapide, vous :

  • Configurer un exemple d’agent hébergé avec les outils Foundry (recherche web et MCP)
  • Testé l’agent localement
  • Déployé dans le service d'agent Foundry
  • Vérification de votre agent dans le playground Foundry

Prochaines étapes

Maintenant que vous avez déployé votre premier agent hébergé, découvrez comment :

Gérer le cycle de vie de l’agent hébergé

Personnalisez votre agent avec des fonctionnalités supplémentaires :

Vous pouvez voir la liste complète des outils disponibles dans l’article du catalogue d’outils .

Contenu connexe

  • Last updated on