Partager via

Déployer un agent sur Microsoft Foundry avec l’extension d’agent AI CLI pour développeurs Azure

Dans cet article, vous allez apprendre à utiliser l’extension d’agent AI (azdAzure Developer CLI) pour configurer et déployer un agent dans Microsoft Foundry. L’extension vous permet de structurer et de déployer des agents depuis votre terminal ou éditeur, en combinant des fonctionnalités Foundry avec azd des commandes de cycle de vie (azd init, azd up) pour un flux de travail cohérent du local au cloud.

Fonctionnalités clés

  • Génération de modèles de projet : configurez des projets d’agent complets (infrastructure en tant que modèles de code, définitions d’agent, configuration) et démarrez immédiatement l’itération.
  • Configuration déclarative : définissez des services, des ressources et des déploiements de modèles dans un azure.yaml fichier pour des environnements cohérents.
  • Approvisionnement et déploiement unifiés : Exécutez azd up pour générer des conteneurs, envoyer (push) des images, créer des ressources, déployer des modèles et publier l’agent en une seule étape.
  • Gestion des définitions d’agent : importer des définitions d’agent à partir de catalogues, gitHub ou chemins locaux ; l’interface CLI mappe les paramètres requis aux variables d’environnement.
  • Sécurisé par défaut : configurez automatiquement les identités managées et la sécurité de base sans gérer manuellement les informations d’identification.
  • Approvisionnement de modèles évolutifs : spécifiez les noms de modèle, les versions et la capacité ; azd les déploie de manière cohérente entre les environnements.

Prerequisites

  • Azure Developer CLI (azd) installé (version 1.21.3 ou ultérieure) et authentifié azd auth login.
    • Extension azd ai agent installée (azd extension install azure.ai.agents). Si l’extension n’est pas installée, lorsque vous initialisez le modèle de démarrage ou exécutez azd ai agent, l’extension est installée automatiquement.
  • Un abonnement Azure avec l’autorisation de créer des groupes de ressources et des ressources Microsoft Foundry.
  • Azure CLI installé pour les opérations requises.

Configurer et déployer un agent

Complétez les sections suivantes pour provisionner et déployer un agent sur Microsoft Foundry à l’aide de l’extension IA azd.

Initialiser le modèle Foundry

  1. Initialisez un nouveau projet avec le azd-ai-starter-basic modèle. Dans un dossier vide, exécutez :

    azd init -t Azure-Samples/azd-ai-starter-basic --location northcentralus

    Note

    Les agents hébergés sont actuellement limités à la région Azure Centre Nord des États-Unis. En savoir plus sur la disponibilité régionale des agents hébergés dans la documentation Microsoft Foundry.

  2. Lorsque vous y êtes invité, entrez un nom d’environnement pour le projet d’agent (par exemple, « my-analytics-agent »).

    Le azd init processus :

    • Clone les fichiers du modèle de départ pour votre projet
    • Crée la structure de répertoires avec infra/ (Fichiers Infrastructure as Code) et src/ dossiers
    • Génère un azure.yaml fichier de configuration
    • Configurer .azure/<env>/.env pour des variables spécifiques à l'environnement

Initialiser la définition de l’agent

Le modèle de démarrage fournit la structure du projet, mais vous devez ajouter une définition d’agent spécifique. Les définitions d’agent décrivent le comportement, les outils et les fonctionnalités de votre agent. Recherchez des exemples de définitions dans le référentiel Agent Framework.

Utilisez votre propre définition d’agent ou l’une à partir du catalogue. Exécutez la azd ai agent init commande, avec votre propre <agent-definition-url> valeur :

azd ai agent init -m <agent-definition-url>

Par exemple, utilisez l’URL suivante pour un agent de calculatrice simple :

azd ai agent init -m https://github.com/azure-ai-foundry/foundry-samples/blob/main/samples/python/hosted-agents/calculator-agent/agent.yaml

La commande azd ai agent init :

  • Télécharge le fichier YAML de définition de l’agent dans le répertoire de src/ votre projet
  • Analyse la définition de l’agent pour comprendre ses exigences
  • Met à jour azure.yaml avec les services et configurations correspondants
  • Mappe les paramètres de l’agent aux variables d’environnement

Passer en revue la structure du projet

Le modèle initialisé inclut ces fichiers clés :

├── .azure/                 # Environment-specific settings (.env)
├── infra/                  # Bicep files for Azure infrastructure
├── src/                    # Agent definition and code
└── azure.yaml              # Project configuration

Ouvrez azure.yaml pour voir comment le projet d’agent est configuré :

requiredVersions:
    extensions:
        azure.ai.agents: latest
services:
    CalculatorAgent:
        project: src/CalculatorAgent
        host: azure.ai.agent
        language: docker
        docker:
            remoteBuild: true
        config:
            container:
                resources:
                    cpu: "1"
                    memory: 2Gi
                scale:
                    maxReplicas: 3
                    minReplicas: 1
            deployments:
                - model:
                    format: OpenAI
                    name: gpt-4o-mini
                    version: "2024-07-18"
                  name: gpt-4o-mini
                  sku:
                    capacity: 10
                    name: GlobalStandard
infra:
    provider: bicep
    path: ./infra
    module: main

Cette configuration déclarative définit votre service d’agent et les ressources Azure AI dont elle a besoin, y compris les déploiements de modèles.

Approvisionner et déployer l’agent

Exécutez azd up pour déployer les ressources et l’agent :

azd up

La azd up commande orchestre le flux de travail de déploiement, de l’infrastructure à un point de terminaison d'agent actif :

  • Infrastructure de provisionnement : créez le compte Microsoft Foundry, le projet et les ressources Azure définies dans les fichiers Bicep. - Les hooks de préprovisionnement inspectent les agents et leurs dépendances, modèles et autres ressources, puis remplissent les variables d’environnement afin que Bicep sache ce qu’il faut provisionner, notamment : - AI_PROJECT_DEPLOYMENTS (JSON) : spécification des modèles à déployer. - AI_PROJECT_CONNECTIONS (JSON) : spécification des connexions à créer. - AI_PROJECT_DEPENDENT_RESOURCES (JSON) : spécification des ressources dépendantes. - ENABLE_HOSTED_AGENTS (booléen) : indique si les agents hébergés doivent être approvisionnés (avec un ACR et CapHost).
  • Déploie des modèles : provisionne les déploiements de modèles spécifiés dans azure.yaml (par exemple, GPT-4o-mini avec la capacité configurée).
  • Générez et envoyez (push) le conteneur : si l’agent a du code personnalisé, azd l’empaquette dans une image conteneur et l’envoie (push) à Azure Container Registry.
  • Publiez l’agent : créez une application agent dans Microsoft Foundry et déployez l’agent en tant que service actif et pouvant être appelé.

Une fois azd up terminée, la sortie affiche le point de terminaison du projet Microsoft Foundry, le groupe de ressources, les noms de projet et les détails de l’application d'agent. La sortie fournit également un lien direct vers le terrain de jeu de l’agent dans le portail Microsoft Foundry.

Note

Pour un nouveau projet, le processus d’approvisionnement et de déploiement prend généralement plusieurs minutes.

Identité et sécurité

azd configure automatiquement les modèles d’accès sécurisé afin que vous n’ayez pas à gérer les informations d’identification manuellement :

  • Identité managée : votre agent utilise l’identité managée affectée par le système du projet Foundry pour s’authentifier auprès d’autres ressources Azure.
  • Attributions de rôles : azd accorde automatiquement des autorisations requises (par exemple, en donnant à votre agent l’accès aux services, au stockage ou aux bases de données Azure AI).
  • Sécurité du point de terminaison : les points de terminaison de l’agent utilisent l’authentification Microsoft Entra ID (Azure AD) par défaut. Par conséquent, seuls les utilisateurs ou applications autorisés peuvent appeler votre agent.

Ces configurations de sécurité suivent les bonnes pratiques Azure et fonctionnent dès leur mise en place, vous offrant ainsi une base sécurisée dès le départ.

Tester l’agent dans Microsoft Foundry

  1. Ouvrez le portail Microsoft Foundry.
  2. Accédez au projet configuré par azd (le nom du projet apparaît dans la azd up sortie).
  3. Ouvrez la section Agents pour afficher votre agent déployé.
  4. Lancez l’agent dans le terrain de jeu et envoyez une requête de test telle que « Résumer vos fonctionnalités ».

Vous voyez la réponse de l’agent dans la fenêtre de conversation.

Configuration avancée

Vous pouvez personnaliser vos projets pour répondre aux exigences avancées au-delà du flux de travail par défaut.

Personnaliser les déploiements de modèles

Le azure.yaml fichier vous permet de contrôler les modèles que vous déployez. Pour ajouter ou modifier un modèle, modifiez le fichier :

services:
    CalculatorAgent:
        project: src/CalculatorAgent
        host: azure.ai.agent
        language: docker
        docker:
            remoteBuild: true
        config:
            container:
                resources:
                    cpu: "1"
                    memory: 2Gi
                scale:
                    maxReplicas: 3
                    minReplicas: 1
            deployments:
                - model:
                    format: OpenAI
                    name: gpt-4o-mini
                    version: "2024-07-18"
                  name: gpt-4o-mini
                  sku:
                    capacity: 10
                    name: GlobalStandard

Exécutez azd up pour déployer le nouveau modèle et mettre à jour votre projet.

Cet exemple de configuration déploie plusieurs modèles afin que votre agent puisse utiliser un modèle plus grand pour le raisonnement complexe et un modèle plus petit pour les requêtes simples.

Gérer les variables d’environnement

Variables d’environnement qui azd définissent ou utilisent :

Variable Objectif
AZURE_SUBSCRIPTION_ID Abonnement cible pour les ressources.
AZURE_RESOURCE_GROUP Groupe de ressources hébergeant le projet IA.
AZURE_LOCATION Région Azure (doit prendre en charge les modèles choisis).
AZURE_AI_ACCOUNT_NAME Compte Microsoft Foundry (hub)
AZURE_AI_PROJECT_NAME Projet hébergeant l’agent.
AZURE_AI_FOUNDRY_PROJECT_ENDPOINT Point de terminaison pour les appels de gestion et d’exécution de l’agent.

Ces variables sont stockées dans .azure/<environment-name>/.env. Personnalisez-les pour chaque environnement (développement, test et prod).

Exemples de cas d’usage et de scénarios

Utilisez azd et l’extension de l’agent IA pour accélérer différents scénarios d’agent avec Microsoft Foundry.

Créer des assistants conversationnels

Créez des agents qui répondent aux questions avec le contexte et connectez-vous aux données internes.

  • Déployer des variantes pour les tests A/B
  • Ajouter Azure AI Search pour les réponses augmentées par la recherche
  • Intégrer des API métier via des outils personnalisés

Créer des agents de données et d’insights

Fournissez des résumés, des calculs et des visualisations.

  • Connectez-vous à Azure SQL Database ou Cosmos DB.
  • Utiliser les outils d’interpréteur de code pour le calcul
  • Mélanger des modèles de raisonnement plus volumineux avec des modèles plus petits et plus économiques

Orchestrer plusieurs agents

Coordonnez les spécialistes pour les flux de travail complexes.

  • Ajoutez un agent coordinateur pour acheminer les demandes.
  • Définissez les relations de manière déclarative dans azure.yaml.
  • Mettez à l’échelle les agents indépendamment en fonction de la charge.

Normaliser le déploiement d’entreprise

Favoriser la cohérence entre les équipes.

  • Publier des blueprints et des modèles réutilisables
  • Appliquer une sécurité, une conformité et une surveillance cohérentes
  • Automatiser l’approvisionnement et le déploiement dans CI/CD avec azd provision et azd deploy.

Explorer l’écosystème

Ressources supplémentaires

  • Last updated on