Partage via

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 la recherche web et éventuellement les outils MCP 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.

Étape 1 : Configurer l’exemple de project

Initialisez un nouveau projet avec le modèle de démarrage de Foundry et configurez-le avec l'exemple agent-with-foundry-tools.

  1. Initialisez le modèle de démarrage dans un répertoire vide :

    azd init -t https://github.com/Azure-Samples/azd-ai-starter-basic

    Cette commande interactive vous invite à entrer un nom d’environnement (par exemple, my-hosted-agent). Le nom de l’environnement détermine le nom de votre groupe de ressources (rg-my-hosted-agent).

    Note

    Si un groupe de ressources portant le même nom existe déjà, azd provision utilise le groupe existant. Pour éviter les conflits, choisissez un nom d’environnement unique ou supprimez d’abord le groupe de ressources existant.

  2. Initialisez l’agent modèle :

    azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/agent-framework/agent-with-foundry-tools/agent.yaml

    Cette commande interactive vous invite à entrer les valeurs de configuration suivantes :

    • abonnement Azure : sélectionnez l’abonnement Azure où vous souhaitez créer les ressources Foundry.
    • 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
    • Mémoire du conteneur : entrez une valeur pour l’allocation de mémoire du conteneur ou acceptez les valeurs par défaut
    • Processeur du conteneur - entrez une valeur pour l’allocation du processeur du conteneur ou acceptez la valeur par défaut
    • Répliques minimales - entrez une valeur pour les répliques minimales du conteneur
    • Nombre maximal de réplicas : entrez une valeur pour le nombre maximal de réplicas du conteneur

    Important

    Si 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>

  3. Provisionnez les ressources Azure requises :

    Note

    Vous devez disposer d’un accès Contributor sur votre abonnement Azure pour mettre les ressources à disposition.

    azd provision

    Cette commande prend environ 5 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 les tarifs Azure Monitor
    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. Créez et activez un environnement virtuel Python :

    Bash:

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

    PowerShell :

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

  2. Installez des dépendances :

    pip install -r ./src/af-agent-with-foundry-tools/requirements.txt

  3. Copiez les variables d’environnement requises utilisées dans le code de l’agent dans un fichier .env local :

    Bash:

    azd env get-values > .env

    PowerShell :

    azd env get-values > .env

  4. Ajoutez la AZURE_OPENAI_CHAT_DEPLOYMENT_NAME variable à votre .env fichier avec le nom du déploiement du modèle :

    AZURE_OPENAI_CHAT_DEPLOYMENT_NAME="gpt-4.1"

  5. Exécutez l’agent sur votre machine locale:

    python ./src/af-agent-with-foundry-tools/main.py

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

    Erreur Solution
    AuthenticationError ou DefaultAzureCredential échec Réexécutez 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.

  6. Testez avec un client REST. L’agent s’exécute sur localhost:8088:

    Bash:

    curl -X POST http://localhost:8088/responses \
    -H "Content-Type: application/json" \
    -d '{"input": "What is Microsoft Foundry?"}'

    PowerShell :

    Invoke-RestMethod -Method Post `
    -Uri "http://localhost:8088/responses" `
    -ContentType "application/json" `
    -Body '{"input":"What is Microsoft Foundry?"}'

    Vous devez voir une réponse avec les résultats de la recherche web sur Microsoft Foundry.

  7. Arrêtez le serveur local avec Ctrl+C.

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

La commande azd up combine trois étapes en une : l’infrastructure d’approvisionnement, l’empaquetage de votre application et son déploiement sur Azure. Cela équivaut à exécuter azd provision, azd packageet azd deploy séparément.

Avant de commencer, vérifiez que Docker Desktop est en cours d’exécution :

docker info

Si cette commande échoue, démarrez Docker Desktop et attendez son initialisation avant de continuer.

Déployez votre agent :

azd up

Le premier déploiement prendra plus de temps, car Docker doit générer l’image.

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é, vous verrez un lien vers le terrain de jeu de l’agent et le point de terminaison de l’agent qui peut être utilisé 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

Étape 1 : Créer un projet Foundry

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

  1. Ouvrez la palette de commandes (Ctrl+Maj+P) et sélectionnez Microsoft Foundry : Créer un projet.

  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 Projet 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 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 : Ouvrir le catalogue de modèles.

  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 de modèle, sélectionnez le bouton Déployer sur 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 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) et sélectionnez Microsoft Foundry : Créer un agent hébergé.

  2. Sélectionnez le modèle de flux de travail agent unique ou multi-agent

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

  4. Choisissez le modèle gpt-4.1 existant que vous avez déployé à l’étape précédente.

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

  6. 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 Python requises à l’aide de pip :

pip install -r requirements.txt

Les packages requis sont les suivants :

  • azure-ai-agentserver-agentframework - Kit de développement logiciel (SDK) Agent Framework et AgentServer

É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 d’Agent du Toolkit AI pour des 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) et sélectionnez Microsoft Foundry : Déployer l’agent hébergé.

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

  3. Dans la boîte de dialogue qui s’affiche, sélectionnez le bouton Confirmer et déployer.

Basculez vers l’Explorateur Microsoft Foundry 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 une version (v1) pour ouvrir la page de détails.

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 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 Agents hébergés (version préliminaire).

  2. Sélectionnez une version (v1) pour ouvrir la page de détails.

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

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 Entrée.

  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 créées dans ce guide de démarrage rapide, notamment le project Foundry, Container Registry, Application Insights et votre agent hébergé. Cette action ne peut pas être annulée.

Pour afficher un aperçu de ce qui sera supprimé avant de confirmer :

azd down --preview

Lorsque vous êtes prêt à supprimer, exécutez :

azd down

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-la 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 confirmez que les ressources n’apparaissent 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
Erreurs de build Docker Vérifiez que Docker Desktop est en cours d’exécution. Exécutez docker info pour vérifier.
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.
Problème Solution
azd init Échoue Exécutez azd version pour vérifier la version 1.23.0+. Mettre à jour avec winget upgrade Microsoft.Azd (Windows) ou brew upgrade azd (macOS).
Modèle introuvable dans le catalogue Dupliquez l’échantillon agent.yaml et changez le déploiement du modèle pour en utiliser un disponible dans votre abonnement comme gpt-4.1. Supprimez ensuite la valeur AZURE_LOCATION dans le fichier .azure/<environment name>/.env. Réexécutez la azd ai agent init commande avec votre fichier dupliqué agent.yaml .

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 Agents hébergés (aperçu).

  2. Sélectionnez une version (v1) pour ouvrir la page de détails.

  3. Sélectionnez le bouton Journaux sur la droite pour ouvrir la visionneuse de journaux.

Problème Solution
Extension introuvable Installez l’extension Microsoft Foundry 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