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

• CLI développeur Azure version 1.24.0 ou ultérieure

• Visual Studio Code
• Microsoft Foundry Toolkit pour l’extension Visual Studio Code

Autorisation requise

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

Si vous utilisez azd ou l’extension VS Code, les outils gèrent automatiquement la plupart des affectations RBAC, notamment :

Vérifiez que l'identité managée du projet Foundry dispose du rôle de lecteur 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éée par la plateforme (modèle d'exécution et accès aux outils)

Étape 1 : Configurer l’exemple de projet

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 :

   • Language : 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.
   • Model Configuration : sélectionnez cette option pour déployer un nouveau modèle dans Foundry ou utiliser un modèle existant à partir d’un Project Foundry existant.
   • Abonnement Azure : 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

   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 :

   Ressource	Objectif	Coût
   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	Voir la tarification de Foundry
   Projet Foundry	Héberge votre agent et fournit des fonctionnalités d’IA	Basé sur la consommation ; Voir la tarification de Foundry
   Azure Registre de Conteneurs	Stocke les images de conteneur de votre agent	Niveau de base ; voir 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 Log Analytics Cost
   Application Insights	Surveille les performances et les journaux de l’agent	Paiement à l’utilisation ; consultez Azure Monitor tarification
   Identité managée	Authentifie votre agent pour Azure services	Aucun coût

   Conseil

   Exécutez azd down lorsque vous avez terminé ce guide de démarrage rapide pour supprimer des ressources et arrêter les frais.

É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>Déploiements.
   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 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ée, la sortie affiche un lien vers le terrain de jeu de l’agent 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 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 soit l'API Responses soit l'API Invocation.

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

Exécutez et testez votre agent avant de le déployer.

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 d'agent de Foundry Toolkit 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 d'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. L'agent apparaît dans le volet de navigation latéral des Hosted Agents (Preview) une fois le déploiement terminé.

Vérifier l’état de l’agent

Vérifiez l’état de votre agent pour confirmer son exécution.

1. Sélectionnez votre agent hébergé dans l’arborescence des agents hébergés (version préliminaire).

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 (version préliminaire).

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>

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

Consultez les logs en direct 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

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.

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

Vous pouvez vérifier la console et les journaux système du conteneur pour résoudre les problèmes.

1. Sélectionnez votre agent hébergé dans l’arborescence des agents hébergés (version préliminaire).

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 (préversion).

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 actuel. Cliquer sur un dossier vous permet d'y entrer, et cliquer sur la barre de navigation supérieure vous permet de retourner dans le dossier précédent.