Initialiser un projet d’agent hébergé avec l’interface CLI Azure développeur

Utilisez azd ai agent init pour créer la structure de base d’un projet d’agent hébergé avec les fichiers nécessaires pour créer, tester et déployer un agent d’IA vers Microsoft Foundry. Dans cet article, vous choisissez un point de départ et initialisez le projet à partir d’un modèle, à partir de votre propre code ou par rapport à un projet Foundry existant.

Si vous utilisez un agent de codage comme GitHub Copilot, la compétence Microsoft Foundry peut vous aider à choisir un modèle de démarrage, à générer la structure du projet et à interpréter la configuration généréeazd.

Prerequisites

• Les extensions Azure Developer CLI Foundry ont été installées.
• Session Azure authentifiée (azd auth login).
• Accès contributeur sur votre abonnement Azure.

Choisir un point de départ

Il existe trois façons de commencer un projet. Choisissez le chemin qui correspond à votre situation.

Initialiser à partir d’un modèle

Exécutez l’Assistant interactif dans un répertoire vide, puis sélectionnez Démarrer à partir d’un modèle :

azd ai agent init

L’Assistant vous guide tout au long des options suivantes :

Le nom de l’agent provient du modèle. L’interface CLI crée un azd environnement nommé <directory>-dev et le configure avec les détails de votre projet Foundry sélectionné. Chaque modèle inclut le code source de l’agent, un Dockerfilefichier et un azure.yaml fichier qui agit comme manifeste de projet unifié pour le projet et la configuration de l’agent azd hébergé.

Initialiser à partir d’une URL azure.yaml

Si vous avez un exemple d’agent spécifique, faites pointer -m vers le azure.yaml de l’exemple. L’interface CLI adopte ce fichier en tant que manifeste du projet et télécharge la source de l’agent référencée.

azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/agent-framework/responses/01-basic/azure.yaml

L’option -m accepte toujours une URL de manifeste d’agent héritée, mais les exemples actuels publient un manifeste unifié azure.yaml.

Spécifier un modèle

Choisissez un modèle au moment de l’init :

azd ai agent init --model gpt-4.1

Vous pouvez également utiliser un déploiement de modèle existant dans votre projet Foundry :

azd ai agent init --model-deployment my-deployment

Choisir un mode de déploiement

Par défaut, azd ai agent init utilise le déploiement de code pour les projets Python et .NET. Le déploiement de code télécharge votre source sous la forme d’une archive ZIP. Pour créer à la place la structure d’un projet basé sur des conteneurs, spécifiez --deploy-mode container:

azd ai agent init --deploy-mode container

Pour déployer une image conteneur prédéfinie, passez --image et --agent-name. Cette option ignore la sélection du modèle et de la langue, la génération d’une structure de code, la génération du fichier Dockerfile et la configuration d’Azure Container Registry.

azd ai agent init --agent-name my-agent --image myregistry.azurecr.io/my-agent:v1

Parcourir les modèles de manière noninteractive

Pour inspecter le catalogue avant de générer la structure (scaffolding), ou pour piloter azd ai agent init à partir d’un script, listez le catalogue :

# Everything in the catalog
azd ai agent sample list

# Just the featured Python agent samples
azd ai agent sample list --featured-only --language python --type agent

# Full azd templates only, as JSON for scripting
azd ai agent sample list --type azd --output json

Chaque entrée inclut une commande prête à l’emploi initCommand que vous copiez et exécutez dans le répertoire où vous souhaitez générer la structure du projet.

Initialiser à partir du code existant

Si vous avez un code d’agent Python ou .NET existant, exécutez azd ai agent init dans le répertoire qui contient déjà votre code :

cd my-agent/
azd ai agent init

L’interface CLI détecte les fichiers existants et génère une azure.yaml entrée de service autour d’elles sans remplacer votre code. Pour le déploiement de conteneurs, il ajoute également un fichier Dockerfile. L’infrastructure reste sans bicep par défaut, sauf si vous éjectez l’infrastructure en tant que code ultérieurement.

Votre code d’agent doit respecter le contrat d’exécution de l’agent hébergé :

• Écoutez le port 8088.
• Exposez une sonde d'intégrité à l’adresse GET /readiness.
• Gérer l’un des protocoles pris en charge (responses ou invocations).

Si votre code ne parle pas déjà de l’un de ces protocoles, ajoutez un adaptateur de protocole, un wrapper sdk léger qui se traduit entre le protocole Foundry et la logique de votre agent.

Pour ajouter un agent à un projet existant azd , init détecte le projet et ajoute une nouvelle entrée de service à votre projet existant azure.yaml. Permet --src de spécifier un sous-répertoire :

azd ai agent init --src src/my-agent

Se connecter à un projet Foundry existant

Pour gérer un projet Foundry existant via azd, exécutez l’Assistant et sélectionnez l’option permettant de se connecter à un projet existant. Vous pouvez également ignorer la sélection interactive en fournissant directement l'ID de ressource Azure du projet :

azd ai agent init --project-id /subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.CognitiveServices/accounts/{account}/projects/{project}

Pour rechercher l’ID project, ouvrez le portail Foundry, accédez à Gérer>Project détails et copiez la valeur de l’ID de ressource.

Vérifiez ce qui est créé

Une fois init l’opération terminée, votre répertoire de projet contient la structure suivante :

.
|-- azure.yaml                  # Unified azd project and hosted agent configuration
|-- src/
|   \-- <agent-name>/
|       |-- Dockerfile          # Container build definition
|       \-- ...                 # Agent source code
|-- .azure/                     # Environment configuration
\-- infra/                      # Optional IaC, created only after you eject infrastructure

Les modèles et les exemples génèrent un azure.yaml unifié à la racine du projet. Pendant l’init, azd adopte ou génère ce fichier. Tu travailleras désormais avec azure.yaml. L’infrastructure est sans bicep par défaut. Éjectez l’infrastructure uniquement lorsque vous devez gérer directement les fichiers IaC générés.

Contenu connexe

• Démarrage rapide : Déployer votre premier agent hébergé
• Créer un fichier azure.yaml pour les agents hébergés
• référence azure.yaml pour les agents hébergés
• Infrastructure d’agent hébergé avec Azure Developer CLI