Compétence Microsoft Foundry

Cette compétence aide les développeurs à travailler avec les ressources Microsoft Foundry, couvrant la découverte et le déploiement de modèles, le cycle de vie complet du développement d'agents IA, les workflows d'évaluation et le dépannage.

Conditions préalables à l'exécution

Avant d'utiliser les opérations Foundry MCP, appelez l'outil Azure MCP foundry et inspectez les outils Foundry MCP disponibles et les paramètres associés. Traitez ceci comme l'étape de découverte/aide pour les workflows basés sur MCP.

Sous-compétences

OBLIGATOIRE : Avant d'exécuter N'IMPORTE QUELLE étape spécifique à un workflow, vous DEVEZ lire le document de sous-compétence correspondant. N'appelez pas les outils MCP spécifiques à un workflow sans lire son document de compétence. Ceci s'applique même si vous connaissez déjà les paramètres de l'outil MCP — le document de compétence contient les étapes de workflow requises, les pré-vérifications et la logique de validation qui doivent être suivies. Cette règle s'applique à chaque nouveau message utilisateur qui déclenche un workflow différent, même si la compétence est déjà chargée.

Cette compétence inclut des sous-compétences spécialisées pour des workflows spécifiques. Utilisez-les à la place de la compétence principale quand elles correspondent à votre tâche :

Sous-compétence	Quand l'utiliser	Référence
deploy	Déployer des agents hébergés vers Foundry, tester un déploiement, créer ou mettre à jour des agents de prompt, et gérer les versions d'agents et les déploiements multi-environnements.	deploy
invoke	Envoyer des messages à un agent, conversations simple ou multi-tour	invoke
routine	Planifier ou déclencher par événement les agents Foundry avec des routines ; utiliser `azd` pour CRUD, activer/désactiver, dispatch manuel et visualiser les exécutions passées, ou définir les routines dans `azure.yaml`.	routine
invocations-ws	Créer, déployer et se connecter à des agents hébergés utilisant le protocole WebSocket duplex `invocations_ws` — agents vocaux, flux en temps réel et signalisation pour les transports de médias hors bande.	invocations-ws
observe	Évaluer la qualité de l'agent, exécuter des évaluations par lot, analyser les défaillances, optimiser les prompts, améliorer les instructions de l'agent, comparer les versions, configurer la surveillance CI/CD et activer l'évaluation continue en production	observe
trace	Interroger les traces, analyser la latence/défaillances, corréler les résultats d'éval aux réponses spécifiques via App Insights `customEvents`	trace
troubleshoot	Afficher les journaux des agents hébergés, interroger la télémétrie, diagnostiquer les défaillances	troubleshoot
create (quick start)	Créer un nouvel agent Foundry hébergé à partir de zéro de bout en bout — générer la structure, provisionner ou utiliser un projet Foundry existant, déployer et tester. Chemin heureux opiné qui accepte les remplacements courants (langage, région, exemple, sujet, projet existant, modèle existant). Pour tout ce qui n'est pas couvert par le quickstart, utilisez create.	create/quick-start-hosted.md
create	À utiliser quand le chemin heureux de bout en bout standard ne convient pas — intégrer le code d'agent existant dans le projet, déployer en dehors du chemin de code par défaut, câbler les connexions au moment de la génération de la structure, configuration avancée, ou récupération après un exécution de quickstart échouée.	create
agent-optimizer	Rendre le code d'agent hébergé Python existant prêt pour l'optimisation, configurer eval.yaml, exécuter des travaux Agent Optimizer, appliquer les candidats localement et déployer via azd après examen.	agent-optimizer
eval-datasets	Récolter les traces de production dans les datasets d'évaluation, gérer les versions et divisions de datasets, suivre les métriques d'évaluation au fil du temps, détecter les régressions et maintenir la traçabilité complète de la trace au déploiement. Utiliser pour : créer un dataset à partir de traces, versioning des datasets, tendances d'évaluation, détection de régression, comparaison de datasets, traçabilité eval.	eval-datasets
project/create	Créer un nouveau projet Azure AI Foundry pour héberger des agents et des modèles. À utiliser lors de l'intégration à Foundry ou de la configuration d'une nouvelle infrastructure.	project/create/create-foundry-project.md
resource/create	Créer une ressource multi-service Azure AI Services (ressource Foundry) à l'aide d'Azure CLI. À utiliser lors du provisionnement manuel de ressources AI Services avec contrôle granulaire.	resource/create/create-foundry-resource.md
private-network	Répondre aux questions sur l'isolation du réseau Foundry et déployer Foundry avec isolation VNet (BYO VNet, VNet géré, hybride). Couvre les concepts d'architecture, la sélection de modèles, le déploiement et la validation post-déploiement.	resource/private-network/private-network.md
models/deploy-model	Déploiement unifié de modèles avec routage intelligent. Gère les déploiements rapides de présets, les déploiements entièrement personnalisés (version/SKU/capacité/RAI) et la découverte de capacité entre les régions. Route vers les sous-compétences : `preset` (déploiement rapide), `customize` (contrôle total), `capacity` (trouver la disponibilité).	models/deploy-model/SKILL.md
quota	Gérer les quotas et la capacité des ressources Microsoft Foundry. À utiliser lors de la vérification de l'utilisation des quotas, du dépannage des défaillances de déploiement dues à des quotas insuffisants, de la demande d'augmentation de quota ou de la planification de capacité.	quota/quota.md
rbac	Gérer les permissions RBAC, les attributions de rôles, les identités gérées et les principaux de service pour les ressources Microsoft Foundry. À utiliser pour le contrôle d'accès, l'audit des permissions et la configuration CI/CD.	rbac/rbac.md
finetuning	Affiner les modèles sur Azure AI Foundry — distillation SFT, optimisation de préférence DPO, RFT avec noteurs et fonction calling. Préparation des données, calibrage des noteurs, entraînement, sélection de checkpoint, déploiement, évaluation. À utiliser pour : affinage, SFT, DPO, RFT, données d'entraînement, noteur, distillation, modèle affiné, chargement de fichier volumineux.	finetuning/SKILL.md

💡 Conseil : Pour un flux d'intégration complet : project/create (public) ou private-network (isolation VNet) → models/deploy-model → workflows d'agent (create → deploy → invoke).

💡 Affinage : Utilisez finetuning pour toute personnalisation de modèle — distillation SFT, optimisation de préférence DPO et RFT avec noteurs. Inclut quickstart, calibrage des noteurs et analyse de courbe d'entraînement.

💡 Déploiement de modèle : Utilisez models/deploy-model pour tous les scénarios de déploiement — il route intelligemment entre déploiement rapide de preset, déploiement personnalisé avec contrôle total et découverte de capacité entre régions.

💡 Optimisation de prompt : Pour des requêtes comme « optimisez mon prompt » ou « améliorez les instructions de mon agent », chargez observe et utilisez l'outil MCP prompt_optimize via ce workflow piloté par l'évaluation.

Cycle de vie de l'infrastructure

Associez l'intention utilisateur au workflow d'infrastructure correct.

Intention utilisateur	Workflow
« Créer Foundry » / « Configurer Foundry » (ambigu)	Utilisez `AskUserQuestion` : (a) juste une ressource AI Services, (b) un projet avec accès public, ou (c) un projet avec isolation réseau ? Route : (a) → resource/create, (b) → project/create, (c) → private-network
Configurer Foundry avec isolation VNet	private-network
Créer un projet Foundry (public)	project/create
Créer une ressource Foundry brute	resource/create

Cycle de vie du développement d'agents

Associez l'intention utilisateur au workflow d'agent correct. Lisez chaque sous-compétence dans l'ordre avant d'exécuter.

Intention utilisateur	Workflow (lire dans l'ordre)
Créer un nouvel agent hébergé de bout en bout (générer + déployer + tester)	quick-start-hosted (autosuffisant de bout en bout)
N'importe quoi au-delà du quickstart standard (code existant, personnalisation du déploiement, connexions au moment de la génération, récupération)	create → deploy → invoke
Optimiser un agent hébergé Python existant	agent-optimizer → générer/examiner → eval.yaml → optimiser → appliquer le candidat → déployer → invoquer
Déployer un agent (le code existe déjà)	deploy (inclut la configuration eval-suite) → invoke → observe (évaluer/optimiser)
Mettre à jour/redéployer un agent après des modifications de code	deploy (inclut la configuration eval-suite) → invoke → observe (évaluer/optimiser)
Invoquer/tester/converser avec un agent	invoke
Planifier/déclencher par événement un agent, ou CRUD/activer/désactiver/dispatcher une routine	routine
Optimiser / améliorer le prompt ou les instructions de l'agent	observe (Étape 4 : Optimiser)
Évaluer et optimiser l'agent (boucle complète)	observe
Activer la surveillance d'évaluation continue	observe (Étape 6 : CI/CD et surveillance)
Dépanner un problème d'agent	invoke → troubleshoot
Corriger un agent cassé (dépanner + redéployer)	invoke → troubleshoot → appliquer des corrections → deploy → invoke

Agent : Norme d'espace de travail .foundry

Chaque dossier source d'agent peut conserver le cache spécifique à Foundry et l'état de superposition sous .foundry/ :

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

Dans les projets azd, dérivez le contexte de déploiement (endpoint de projet, nom/version de l'agent, ACR, App Insights) de azure.yaml plus azd env get-values ; ne dupliquez pas ces valeurs dans les métadonnées quand azd les fournit déjà.
agent-metadata.yaml est la superposition locale/dev préférée pour les valeurs non-azd, les références distantes de suite Foundry, les chemins du cache local, les résumés de résultats et les overrides explicites. Les fichiers sidecar optionnels comme agent-metadata.prod.yaml peuvent contenir un seul overlay ciblé prod ou CI sans mélanger plusieurs environnements dans un seul fichier.
suites/, datasets/ et evaluators/ sont des dossiers du cache local. Réutilisez-les quand ils sont à jour, et demandez avant de les rafraîchir ou de les écraser.
Voir Agent Metadata Contract pour le schéma canonique et les règles de workflow.

Agent : Références de configuration

Standard Agent Setup — configuration avancée pour les workloads de production qui ont besoin d'un contrôle de résidence des données (apporter votre propre Cosmos DB / Storage / AI Search via un capability host Foundry). Le flux azd ai agent par défaut utilise Basic Agent Setup et ne provisionne pas capabilityHosts/agents — ne signalez pas son absence comme un bug. Pour l'état post-provision attendu, voir la section « Expected env-var fingerprint » dans foundry-agent/create/create-hosted.md.

Agent : Résolution courante du contexte de projet

Les compétences d'agent doivent exécuter cette étape uniquement quand elles ont besoin de valeurs de configuration qu'elles ne possèdent pas déjà. Si une valeur (par exemple, agent root, environnement, endpoint de projet ou nom d'agent) est déjà connue du message de l'utilisateur ou d'une compétence précédente dans la même session, ignorez la résolution pour cette valeur.

Étape 1 : Découvrir les racines d'agent et le contexte azd

Vérifiez d'abord si l'espace de travail a azure.yaml avec des services utilisant host: azure.ai.agent.

Un service azd agent -> utiliser le dossier project de ce service comme racine d'agent.
Plusieurs services azd agent -> exiger que l'utilisateur choisisse le service/dossier cible.
Aucun service azd agent -> parcourir l'espace de travail pour les dossiers .foundry/ qui contiennent agent-metadata.yaml ou agent-metadata.<env>.yaml.
- Une correspondance -> utiliser cette racine d'agent.
- Plusieurs correspondances -> exiger que l'utilisateur choisisse le dossier d'agent cible.
- Aucune correspondance -> pour les workflows create/deploy, amorcer un nouveau dossier .foundry/ lors de la configuration ; pour tous les autres workflows, arrêter et demander à l'utilisateur quel dossier source d'agent initialiser.

Après avoir sélectionné une racine d'agent, gardez toute l'inspection du cache local .foundry, l'inspection des sources, les suggestions d'évaluateur, les suggestions de dataset et le contexte d'optimisation de prompt à l'intérieur de ce dossier uniquement. Ne pas scanner les dossiers d'agents voisins sauf si l'utilisateur bascule explicitement les racines.

Étape 2 : Résoudre le contexte d'environnement et de déploiement

Si azure.yaml est présent, résolvez d'abord l'environnement azd :

Environnement explicitement nommé par l'utilisateur
AZURE_ENV_NAME de azd env get-values
Environnement par défaut azd de .azure/config.json
Environnement déjà sélectionné plus tôt dans la session

Exécutez azd env get-values pour l'environnement sélectionné quand les valeurs de projet/déploiement ne sont pas déjà connues. Préférer les valeurs azd pour le contexte de déploiement :

Variable azd	Résout en
`AZURE_AI_PROJECT_ENDPOINT` ou `AZURE_AIPROJECT_ENDPOINT`	Endpoint de projet
`AGENT_<SERVICE>_NAME`	Nom d'agent pour le service azd sélectionné
`AGENT_<SERVICE>_VERSION`	Version d'agent pour le service azd sélectionné
`AZURE_CONTAINER_REGISTRY_NAME` ou `AZURE_CONTAINER_REGISTRY_ENDPOINT`	Nom du registre ACR / préfixe URL d'image
`APPLICATIONINSIGHTS_CONNECTION_STRING`	Chaîne de connexion App Insights pour les workflows de trace
`AZURE_SUBSCRIPTION_ID`, `AZURE_RESOURCE_GROUP`, `AZURE_AI_ACCOUNT_NAME`, `AZURE_AI_PROJECT_NAME`	Lookup de ressource Azure et liens Playground

Quand azd fournit ces valeurs, les utiliser comme source de vérité et ne pas les copier dans .foundry/agent-metadata*.yaml lors des écritures de métadonnées.

Étape 3 : Sélectionner la superposition de métadonnées et résoudre l'environnement

À l'intérieur de la racine d'agent sélectionnée, choisir le fichier de métadonnées dans cet ordre :

Nom ou chemin du fichier de métadonnées explicitement fourni par l'utilisateur ou le workflow
Si un environnement explicite est déjà connu et .foundry/agent-metadata.<env>.yaml existe, utiliser ce fichier
.foundry/agent-metadata.yaml
Si plusieurs fichiers de métadonnées restent et aucune règle ci-dessus n'en sélectionne un, inviter l'utilisateur à choisir

Lire le fichier de métadonnées sélectionné et résoudre tout choix d'environnement restant dans cet ordre :

Environnement explicitement nommé par l'utilisateur
Si le fichier de métadonnées sélectionné définit exactement un environnement, l'utiliser
Environnement déjà sélectionné plus tôt dans la session
defaultEnvironment des métadonnées

Si le fichier de métadonnées sélectionné contient toujours plusieurs environnements et aucune des règles ci-dessus n'en sélectionne un, inviter l'utilisateur à choisir. Garder visible la racine d'agent sélectionnée, le fichier de métadonnées, l'environnement et si le contexte provient d'azd ou des métadonnées dans chaque résumé de workflow.

Si l'environnement sélectionné expose les métadonnées plus anciennes testSuites[] mais pas evaluationSuites[], traiter testSuites[] comme la source pour cette session et normaliser chaque entrée en mémoire en la forme evaluationSuites[] avant de continuer. Si les métadonnées sont encore plus anciennes et exposent uniquement testCases[] hérité, normaliser cette liste de la même façon. Préserver les champs dataset et evaluator, conserver tous les tags existants et mapper l'héritage priority en tags.tier uniquement quand tags.tier est manquant : P0 -> smoke, P1 -> regression, P2 -> coverage.

Étape 4 : Résoudre l'intention d'évaluation locale eval.yaml

Si eval.yaml existe dans la racine d'agent sélectionnée, l'analyser avant de générer de nouvelles suites :

agent.name -> candidat agent cible ; vérifier qu'il correspond à l'agent azd/metadata sélectionné avant de l'utiliser.
dataset.local_uri -> candidat dataset de base local ; l'héritage dataset_file peut être normalisé en mémoire.
dataset.name / dataset.version -> candidat dataset enregistré.
validation_dataset -> candidat dataset de validation optionnel.
evaluators[] -> noms d'évaluateurs Foundry candidats ; vérifier avec evaluator_catalog_get avant de les traiter comme des évaluateurs distants.
name -> candidat eval/suite local ; vérifier à distance avant de persister comme suiteName.
options.eval_model, options.optimization_model, options.max_candidates, options.optimization_config.model_search_space, options.pass_threshold, max_samples, trace_days et generation_instruction -> paramètres par défaut de configuration.

Traiter eval.yaml comme intention d'évaluation locale, pas preuve qu'une suite Foundry existe. Persister les références synced de suite/dataset/evaluator vers .foundry uniquement après la réussite de la lookup distante ou de l'enregistrement.

Étape 5 : Résoudre la configuration courante

Mettre en couches les sources dans cet ordre :

Entrée utilisateur explicite et valeurs déjà sélectionnées dans la session
Valeurs d'environnement azd pour le contexte de déploiement
Valeurs de superposition .foundry/agent-metadata*.yaml et références distantes de suite/cache
Configuration source locale azure.yaml et eval.yaml
Invites utilisateur pour tout ce qui reste manquant

Si azd et les métadonnées fournissent tous les deux la même valeur et qu'elles diffèrent, arrêter et demander quelle source est autorisée. S'ils correspondent, utiliser la valeur azd et éviter de réécrire le doublon lors des écritures de métadonnées futures.

Valeur effective	Source préférée	Utilisée par
Endpoint de projet	azd env	deploy, invoke, observe, trace, troubleshoot
Nom/version d'agent	Variables agent azd, puis `azure.yaml`	invoke, observe, trace, troubleshoot
ACR	azd env	deploy
Suites d'évaluation et chemins du cache	`.foundry/agent-metadata*.yaml`	observe, eval-datasets
Intention de dataset de base local/évaluateur	`eval.yaml`	observe, eval-datasets

Étape 6 : Écrire la superposition de métadonnées (Create/Deploy/Observe uniquement)

À toute écriture de métadonnées (deploy, configuration automatique, actualisation de dataset ou mise à jour trace-to-dataset), persister uniquement l'état de superposition/cache non-dérivable dans le fichier de métadonnées sélectionné :

Liaison azd (azd.environmentName, azd.service) quand utile pour la résolution future
evaluationSuites[] avec références distantes de suite/dataset/evaluator et chemins du cache local
lastEval, fichiers de résultats, résumés de comparaison ou overrides non-azd explicites

Ne pas copier les valeurs de déploiement appartenant à azd dans les métadonnées quand azd les fournit déjà. Si le fichier sélectionné est un fichier mono-environnement préféré, réécrire uniquement ce bloc d'environnement. Si le fichier sélectionné est un fichier multi-environnements hérité, réécrire uniquement le bloc d'environnement sélectionné. Ne jamais copier ou fusionner automatiquement les environnements sur les fichiers de métadonnées frères. Si l'environnement sélectionné utilise toujours testSuites[] plus ancien ou testCases[] hérité, le réécrire en evaluationSuites[] et supprimer les champs priority migrés des entrées réécrites.

Étape 7 : Rassembler les valeurs manquantes

Utiliser l'outil ask_user ou askQuestions uniquement pour les valeurs non résolues du message de l'utilisateur, du contexte de session, des métadonnées ou du bootstrap azd. Valeurs courantes que les compétences peuvent nécessiter :

Racine d'agent — Dossier de projet du service azd cible ou dossier contenant .foundry/agent-metadata*.yaml
Fichier de métadonnées — agent-metadata.yaml pour local/dev, ou un sidecar explicite comme agent-metadata.prod.yaml
Environnement — Environnement azd, dev, prod ou une autre clé d'environnement des métadonnées
Endpoint de projet — URL endpoint du projet AI Foundry
Nom d'agent — Nom de l'agent cible

💡 Conseil : Si l'utilisateur fournit déjà le chemin de l'agent, l'environnement, l'endpoint de projet ou le nom d'agent, l'extraire directement — ne pas demander à nouveau.

Agent : Types d'agents

Toutes les compétences d'agent supportent deux types d'agents :

Type	Kind	Description
Prompt	`"prompt"`	Agents basés sur LLM soutenus par un déploiement de modèle
Hosted	`"hosted"`	Agents basés sur container exécutant du code personnalisé

Utilisez l'outil MCP agent_get pour déterminer le type d'un agent quand nécessaire.

Conventions d'utilisation des outils

Utiliser l'outil ask_user ou askQuestions quand on collecte des informations de l'utilisateur
Utiliser l'outil task ou runSubagent pour déléguer des sous-tâches longues ou indépendantes (par ex. scan de var d'env, polling de statut, génération de Dockerfile)
Préférer les outils Azure MCP aux commandes CLI directes quand disponibles
Référencer les URLs de documentation officielle Microsoft au lieu d'intégrer la syntaxe des commandes CLI

Ressources supplémentaires

Référence rapide SDK

Python

Erreurs d'isolation réseau

S'applique à tout appel contre un projet Foundry ou son compte Foundry parent — outils Foundry MCP, azd, CLI az, curl, REST ou SDK.

Si une erreur correspond à Public access is disabled / PublicNetworkAccessDisabled / 403 Forbidden d'un endpoint privé / timeout de connexion / le FQDN de l'endpoint de projet résout en IP publique, ceci indique typiquement que le compte Foundry parent a publicNetworkAccess=Disabled ou Enabled from selected IP addresses, et le shell actuel est en dehors de son VNet.

Uniquement si l'erreur est ambiguë, confirmer contre le compte Foundry en utilisant un appel du plan de gestion (fonctionne de n'importe où avec accès reader) :

az cognitiveservices account show \
  --name <account> --resource-group <rg> \
  --query "properties.{publicNetworkAccess:publicNetworkAccess, networkAcls:networkAcls, privateEndpointConnections:privateEndpointConnections[].properties.privateLinkServiceConnectionState.status}"

publicNetworkAccess: "Disabled" — ou "Enabled" ensemble avec non-vide networkAcls.ipRules / virtualNetworkRules — confirme l'isolation. Si publicNetworkAccess: "Enabled" et networkAcls est vide, la défaillance est un problème réseau côté appelant (par ex. Private DNS résolvant le FQDN en IP publique depuis l'intérieur d'un VNet avec un endpoint privé), pas un problème de config de compte.

Si c'est vraiment un problème d'isolation réseau, les options de connexion supportées sont documentées dans Choose a secure connection method to Foundry.

ℹ️ Les outils Foundry MCP ne peuvent pas atteindre un projet isolé en VNet même depuis l'intérieur du VNet.

microsoft-foundry