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

• La version 1.23.0 ou ultérieure de Azure Developer CLI

• Visual Studio Code
• Microsoft Foundry pour Visual Studio Code extension

Étape 1 : Configurer l’exemple de project

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é :

   azd ai agent init
   

   Lorsque vous y êtes invité, sélectionnez Démarrer nouveau à partir d’un modèle. Le flux interactif vous guide tout au long de la configuration suivante :

   • Nom de l’environnement : détermine le nom de votre groupe de ressources (par exemple, my-hosted-agent crée rg-my-hosted-agent).
   • 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.

   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.

   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 avez besoin d’un accès Contributor sur votre abonnement Azure pour l’approvisionnement des ressources.

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

   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.

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

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

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

É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.

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

É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), 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 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 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 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 de 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.

Option 1 : Appuyez sur F5 (recommandé)

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

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.

Vérifier l’état de l’agent

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

azd ai agent show

Tester l’agent déployé

Envoyez un message de test à votre agent déployé :

azd ai agent invoke "What is Microsoft Foundry?"

Vous devez voir une réponse avec les résultats de recherche web sur Microsoft Foundry. La réponse peut prendre quelques secondes, car l’agent interroge des sources externes.

Afficher les journaux d’activité de l’agent

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

azd ai agent monitor

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.

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

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