microsoft-foundry

Présentation

Qu’est-ce que la compétence microsoft-foundry ?

La compétence microsoft-foundry est un ensemble organisé de workflows et de documents de référence qui vous accompagne sur tout le cycle de vie des agents Azure AI Foundry. Elle se concentre sur les aspects pratiques de déploiement et d’exploitation :

• Création d’agents prompt et hosted
• Création d’images Docker et push vers Azure Container Registry (ACR)
• Déploiement des agents vers Azure AI Foundry
• Configuration des projets, RBAC, quotas et connections
• Exécution de datasets d’évaluation et gestion de agent-metadata.yaml
• Configuration d’agents en mode standard ou private-network
• Activation de l’observabilité, du tracing et du troubleshooting

Tout le contenu provient du dépôt microsoft/azure-skills et est structuré pour que vous puissiez industrialiser des agents sur Azure AI Foundry sans devoir rétro‑ingénier la structure du dépôt.

À qui s’adresse cette compétence ?

Utilisez microsoft-foundry si vous êtes :

• Un ingénieur backend ou plateforme responsable du déploiement et de l’exploitation d’agents Azure AI Foundry
• Un ingénieur IA/ML qui fait passer des prototypes en production dans un projet Foundry
• Un développeur qui intègre des agents Foundry à des services existants, des SDK ou des outils MCP
• Un responsable technique qui doit maîtriser RBAC, quotas, réseau privé et configuration d’environnement

Si vous avez uniquement besoin de déploiements d’infrastructure Azure basiques (App Service, Functions, applications web génériques), cette compétence n’est pas la plus adaptée — utilisez plutôt une compétence Azure de déploiement plus générale.

Quels problèmes microsoft-foundry permet-elle de résoudre ?

Cette compétence est conçue pour traiter les difficultés récurrentes suivantes :

• « Comment structurer mon dépôt d’agent pour Foundry ? »
  Utilisez les recommandations de references/agent-metadata-contract.md pour la structure .foundry/ et les champs de agent-metadata.yaml.

• « Comment créer et déployer des agents de façon cohérente ? »
  Utilisez les workflows foundry-agent/create et foundry-agent/deploy pour créer des agents prompt/hosted, construire les conteneurs, les pousser vers ACR et démarrer les conteneurs d’agent.

• « Comment configurer projets, connections, RBAC et quotas ? »
  Suivez project/create, rbac/rbac.md et quota/quota.md pour créer des projets, attribuer les rôles et planifier la capacité.

• « Comment évaluer et observer mes agents ? »
  Utilisez foundry-agent/eval-datasets, foundry-agent/observe et foundry-agent/trace pour lancer des évaluations batch, gérer datasets et évaluateurs, et vous connecter à vos ressources d’observabilité.

• « Comment gérer les configurations standard vs réseau privé ? »
  Utilisez references/standard-agent-setup.md et references/private-network-standard-agent-setup.md pour choisir et configurer le bon modèle réseau.

Quand microsoft-foundry est-elle un bon choix ?

Utilisez cette compétence lorsque vous devez :

• Déployer des agents prompt ou hosted sur Azure AI Foundry
• Standardiser la structure des projets d’agent avec .foundry/agent-metadata.yaml
• Intégrer des outils MCP et des SDK Azure dans un workflow reproductible
• Gérer RBAC, quotas et capacity planning pour les workloads d’agent
• Exécuter des datasets d’évaluation et suivre les résultats à travers les environnements
• Mettre en place l’observabilité avec Application Insights et des traces
• Déployer dans des configurations standard ou private-network (VNet)

N’utilisez pas cette compétence si vous avez seulement besoin :

• De déploiement générique d’applications Azure (web apps, Functions, App Service)
• De préparation de haut niveau de comptes ou abonnements Azure

Dans ces cas, combinez cette compétence avec des compétences plus générales de déploiement/préparation Azure ou utilisez une compétence dédiée comme azure-deploy / azure-prepare.

Comment l’utiliser

Installation

Pour ajouter microsoft-foundry depuis le dépôt microsoft/azure-skills, installez-la avec :

npx skills add https://github.com/microsoft/azure-skills --skill microsoft-foundry

Les workflows et contenus de référence de microsoft-foundry deviennent alors disponibles pour votre agent ou votre environnement d’outillage. Après l’installation, le point d’entrée principal est SKILL.md dans le dossier skills/microsoft-foundry.

Structure du dépôt et dossiers clés

Après avoir installé la compétence ou l’avoir ouverte dans le dépôt, vous verrez la structure suivante :

• SKILL.md – index principal de la compétence et liste des sous‑compétences
• foundry-agent/ – workflows de bout en bout pour chaque agent
  • create/ – création d’agents prompt ou hosted
  • deploy/ – build et déploiement des agents, y compris conteneurs et ACR
  • eval-datasets/ – gestion des datasets d’évaluation et des exécutions
  • invoke/ – invocation d’agents existants
  • observe/ – configuration de l’observabilité et workflows de monitoring
  • trace/ – collecte de traces et création de datasets à partir des traces
  • troubleshoot/ – guidance de troubleshooting pour les exécutions en échec
• project/
  • create/ – création et configuration de projets Azure AI Foundry
  • connections.md – recommandations pour les connections au niveau projet
• rbac/
  • rbac.md – rôles RBAC, permissions et modèles courants
• quota/
  • quota.md – recommandations sur les quotas et la planification de capacité
  • references/ – capacity planning, résolution d’erreurs, optimisation
• references/
  • agent-metadata-contract.md – structure .foundry/ et agent-metadata.yaml
  • auth-best-practices.md – modèles d’authentification Azure et RBAC
  • standard-agent-setup.md – configuration standard (non isolée) d’agent
  • private-network-standard-agent-setup.md – configuration VNet/private-link
  • sdk/ – références pour les opérations via SDK quand les outils MCP ne sont pas disponibles

Commencez par SKILL.md pour comprendre les sous‑compétences, puis approfondissez dans le dossier correspondant à votre scénario.

Workflow de démarrage rapide : du projet à l’agent déployé

Cette section décrit un parcours pratique en s’appuyant sur le contenu de la compétence microsoft-foundry.

1. Créer ou préparer votre projet Foundry

1. Ouvrez project/create/create-foundry-project.md.
2. Suivez les étapes pour :
   • Créer un projet Azure AI Foundry
   • Confirmer l’endpoint du projet (par exemple, https://<resource>.services.ai.azure.com/api/projects/<project>)
   • Lier les connections nécessaires (Cosmos DB, Storage, Azure AI Search, etc.) pour une configuration standard
3. Passez en revue project/connections.md pour vérifier que vos connections de stockage de threads, de fichiers et de vecteurs sont correctement configurées, en particulier si vous prévoyez d’utiliser le standard agent setup.

2. Configurer RBAC et l’authentification

1. Lisez rbac/rbac.md pour vérifier :
   • Quels rôles sont nécessaires (Owner, Contributor, User Access Administrator, etc.) sur le groupe de ressources et les ressources Foundry
   • Comment attribuer les rôles en suivant les bonnes pratiques Azure RBAC
2. Ouvrez references/auth-best-practices.md et appliquez ses recommandations :
   • Utiliser les managed identities et Azure RBAC en production
   • Limiter DefaultAzureCredential au développement local
   • Choisir le type de credential adapté pour la production, le CI/CD et les environnements de développement

Cela garantit que vos déploiements et opérations d’agent peuvent s’authentifier de façon fiable sans secrets codés en dur.

3. Choisir entre configuration Basic, Standard et réseau privé

1. Ouvrez references/standard-agent-setup.md pour comprendre :
   • Les différences entre configurations Basic et Standard
   • Les connections requises pour la configuration standard : Cosmos DB, Azure Storage, Azure AI Search, et éventuellement Azure AI Services
   • Les prérequis comme les rôles RBAC sur le groupe de ressources
2. Si vous avez besoin d’une isolation réseau complète, lisez references/private-network-standard-agent-setup.md :
   • Exigences pour la VNet et les sous-réseaux (sous-réseau d’agent et sous-réseau d’endpoint privé)
   • Alignement de région entre les ressources Foundry et la VNet
   • Utilisation du modèle Bicep officiel pour la configuration standard d’agent en réseau privé

Choisissez la configuration qui correspond à vos contraintes de conformité et de réseau avant de passer à la création d’agent.

4. Standardiser la structure de votre projet d’agent

1. Ouvrez references/agent-metadata-contract.md et alignez votre projet sur la structure documentée :

   <agent-root>/
     .foundry/
       agent-metadata.yaml
       datasets/
       evaluators/
       results/
   

2. Assurez-vous que agent-metadata.yaml contient les définitions d’environnement avec des champs tels que :

   • defaultEnvironment
   • environments.<name>.projectEndpoint
   • environments.<name>.agentName
   • environments.<name>.azureContainerRegistry (pour les hosted agents)
   • environments.<name>.observability.* (pour Application Insights)
   • environments.<name>.testCases[] pour les bundles d’évaluation

Ce fichier devient la référence centrale pour la configuration spécifique à chaque environnement, et l’ensemble des workflows microsoft-foundry supposent qu’il est présent et correct.

5. Créer un agent prompt ou hosted

1. Pour les prompt agents, ouvrez foundry-agent/create/create-prompt.md :

   • Comprendre la différence entre prompt agents et workflows
   • Suivre les étapes pour résoudre le contexte du projet (endpoint, credentials)
   • Utiliser les outils MCP lorsqu’ils sont disponibles, et sinon basculer sur le SDK azure-ai-projects comme documenté
   • Fournir le nom de l’agent, le déploiement de modèle et les instructions, plus les outils optionnels (file search, code interpreter, etc.)

2. Pour les hosted agents, ouvrez foundry-agent/create/create.md :

   • Choisir si vous créez un nouvel agent (greenfield) ou si vous convertissez un projet existant (brownfield)
   • Sélectionner un framework et un langage sur la base des exemples fournis (frameworks Python ou C# comme Microsoft Agent Framework ou LangGraph)
   • Utiliser les recommandations pour s’intégrer au dépôt foundry-samples lorsque nécessaire

À la fin de cette étape, vous devez disposer d’un projet d’agent compatible Foundry prêt pour le déploiement.

6. Builder et déployer l’agent

1. Ouvrez foundry-agent/deploy/deploy.md.
2. Suivez le workflow qui couvre :
   • L’analyse du projet et la collecte des variables d’environnement
   • La génération du Dockerfile et l’usage de docker / az acr pour les hosted agents
   • L’utilisation des outils MCP comme agent_update, agent_container_control et agent_container_status_get
   • La création ou la mise à jour du déploiement et le démarrage/arrêt des conteneurs d’agent
3. Ne lancez pas azd up, azd deploy, az acr build ou docker build isolément sans avoir lu ce guide — la compétence orchestre ces commandes dans le cadre d’un pipeline de déploiement complet.

Une fois cette étape terminée, votre agent doit être déployé et accessible via Azure AI Foundry.

7. Invoquer et tester l’agent

1. Ouvrez foundry-agent/invoke/invoke.md.
2. Utilisez les modèles documentés pour :
   • Résoudre l’environnement et l’endpoint corrects à partir de agent-metadata.yaml
   • Invoquer l’agent avec des payloads exemples ou personnalisés
   • Vérifier que les réponses, outils et états se comportent comme prévu

C’est un bon moment pour effectuer des smoke tests avant de lancer des suites d’évaluation complètes.

8. Évaluer et itérer

1. Ouvrez foundry-agent/eval-datasets/eval-datasets.md.
2. Suivez les recommandations pour :
   • Gérer les datasets et évaluateurs dans .foundry/datasets et .foundry/evaluators
   • Exécuter les workflows d’évaluation en utilisant les définitions testCases de agent-metadata.yaml
   • Stocker les résultats dans .foundry/results et comparer les résultats selon l’environnement ou la version de l’agent
3. Itérez sur vos prompts ou instructions et relancez les évaluations pour suivre les améliorations dans le temps.

Observabilité, tracing et troubleshooting

Observabilité et monitoring

1. Ouvrez foundry-agent/observe/observe.md.
2. Configurez l’observabilité en suivant les recommandations :
   • Attachez Application Insights à l’aide de l’ID de ressource et de la chaîne de connexion décrits dans agent-metadata-contract.md
   • Utilisez les tableaux de bord ou requêtes recommandés pour surveiller latence, erreurs et throughput

Cela vous permet de suivre le comportement en production et de le corréler avec les changements de déploiement.

Tracing et création de datasets à partir des traces

1. Ouvrez foundry-agent/trace/trace.md.
2. Utilisez les workflows documentés pour :
   • Collecter des traces depuis vos agents
   • Constituer des datasets à partir de ces traces et les stocker dans .foundry/datasets
   • Alimenter ces datasets dans les workflows d’évaluation pour des tests plus réalistes

C’est particulièrement utile lorsque vous voulez transformer du trafic utilisateur réel en scénarios d’évaluation.

Troubleshooting des déploiements et problèmes d’exécution

1. Ouvrez foundry-agent/troubleshoot/troubleshoot.md.
2. Suivez les guides de troubleshooting pour des problèmes tels que :
   • Échecs de déploiement et erreurs de démarrage de conteneur
   • Endpoints, credentials ou connections mal configurés
   • Erreurs de quota ou de capacité (voir aussi quota/quota.md et quota/references/*.md)

Utilisez ces ressources en combinaison avec les logs et la télémétrie Application Insights pour diagnostiquer et résoudre les problèmes.

Quotas, capacité et optimisation

1. Ouvrez quota/quota.md pour une vue d’ensemble de :
   • La façon dont les quotas s’appliquent aux modèles et déploiements dans Azure AI Foundry
   • La manière de raisonner sur la capacité entre environnements et régions
2. Consultez les fichiers dans quota/references/ :
   • capacity-planning.md – vous aide à estimer la capacité nécessaire pour vos agents en fonction de l’usage
   • error-resolution.md – fait le lien entre erreurs de quota fréquentes et corrections recommandées
   • optimization.md – propose des façons d’optimiser les workloads pour rester dans les limites de quota

Ce contenu vous aide à éviter les mauvaises surprises à l’échelle et à garder vos agents réactifs.

FAQ

microsoft-foundry est-elle obligatoire pour utiliser Azure AI Foundry ?

Non. Vous pouvez utiliser Azure AI Foundry directement via le portail Azure, la CLI ou les SDK. La compétence microsoft-foundry fournit un guide structuré qui regroupe bonnes pratiques, workflows et références au même endroit pour vous aider à configurer projets, agents et environnements de façon plus cohérente.

Puis-je utiliser microsoft-foundry pour d’autres services Azure que Foundry ?

Utilisez cette compétence lorsque votre objectif principal est le déploiement et l’exploitation d’agents et de projets Azure AI Foundry. Pour le déploiement généraliste d’applications web, d’API ou d’autres services PaaS (App Service, Functions, conteneurs génériques), préférez une compétence ou une documentation Azure de déploiement dédiée.

microsoft-foundry prend-elle en charge les agents prompt et hosted ?

Oui. La compétence contient du contenu dédié aux deux :

• foundry-agent/create/create-prompt.md couvre les prompt agents.
• foundry-agent/create/create.md et foundry-agent/deploy/deploy.md couvrent les hosted agents, y compris la containerisation, ACR et la gestion du cycle de vie des conteneurs.

Comment microsoft-foundry gère-t-elle l’authentification et la sécurité ?

La sécurité et l’authentification sont traitées dans references/auth-best-practices.md et rbac/rbac.md :

• Utilisez les managed identities et Azure RBAC en production
• Réservez DefaultAzureCredential au développement local
• Choisissez les credentials adaptés pour le CI/CD et les environnements on-premises

Suivez ces documents avant de câbler vos SDK ou outils MCP pour éviter des configurations peu sûres ou fragiles.

Suis-je obligé d’utiliser les outils MCP ou puis-je me reposer uniquement sur les SDK ?

Le contenu est pensé pour fonctionner avec les outils MCP lorsqu’ils sont disponibles, mais documente également des fallbacks basés sur SDK dans le dossier references/sdk. Par exemple, create-prompt.md explique comment se rabattre sur le SDK azure-ai-projects lorsque les outils MCP ne sont pas présents.

Comment savoir si la structure de mon projet d’agent est correcte ?

Comparez votre projet aux recommandations de references/agent-metadata-contract.md. Assurez-vous d’avoir :

• Un répertoire .foundry/ à la racine de l’agent
• Un agent-metadata.yaml valide incluant environnements et cas de test
• Des dossiers datasets/, evaluators/ et results/ comme décrit

Si vous respectez ce contrat, le reste des workflows microsoft-foundry s’alignera sur la structure de votre projet.

Puis-je utiliser microsoft-foundry avec des configurations réseau privé (VNet) ?

Oui. references/private-network-standard-agent-setup.md fournit des recommandations détaillées sur :

• La configuration requise pour la VNet et les sous-réseaux
• Les contraintes régionales entre les ressources Foundry et la VNet
• L’utilisation du modèle Bicep officiel pour la configuration standard d’agent en réseau privé

Utilisez ce document avec references/standard-agent-setup.md lorsque vous devez conserver le trafic sur un réseau privé.

Par où commencer dans le dépôt après installation ?

Après avoir installé la compétence, commencez par :

1. SKILL.md – pour une vue d’ensemble de toutes les sous‑compétences
2. project/create/create-foundry-project.md – pour configurer votre projet Foundry
3. references/agent-metadata-contract.md – pour standardiser la structure de l’agent
4. foundry-agent/create/ et foundry-agent/deploy/ – pour créer et déployer votre premier agent

Vous pourrez ensuite passer à eval-datasets, observe, trace, rbac et quota selon vos besoins.