informations de référence sur azure.yaml pour les agents hébergés

Le azure.yaml fichier est la configuration unique Azure projet CLI développeur (azd) pour un projet d’agent hébergé. Il déclare vos ressources Foundry ( le projet, les déploiements de modèles, les connexions, les boîtes à outils, les compétences, les routines et les agents eux-mêmes) en tant qu’ensemble de services, et indique azd comment les approvisionner et les déployer. Ce fichier unifié remplace le modèle à deux fichiers précédent qui divise la configuration entre agent.manifest.yaml et agent.yaml.

Pour savoir comment composer et créer ce fichier étape par étape, consultez Créer azure.yaml pour les agents hébergés.

Utilisation d’azure.yaml

L’interface CLI Azure développeur simplifie le flux de travail développeur-à-cloud. Il gère deux choses : l’approvisionnement de Azure ressources, telles que les projets Foundry, les déploiements de modèles et les registres de conteneurs, et le déploiement de votre code sur ces ressources. Pour les agents hébergés, l’extension azure.ai.agents ajoute des commandes spécifiques à l’agent telles que azd ai agent init et azd ai agent run.

Chaque azd projet a un azure.yaml fichier à sa racine. Pour les projets d’agent, ce fichier est la source de la vérité pour la configuration de l’agent et la configuration du déploiement.

Environments

Un environnement est une configuration nommée, telle que dev, stagingou prod, qui stocke les paramètres d’un déploiement particulier. Chaque environnement suit l’abonnement et l’emplacement Azure, le groupe de ressources et les noms de ressources, ainsi que les variables personnalisées que vous définissez. Les paramètres sont stockés localement dans .azure/<env-name>/.env. Vous pouvez avoir plusieurs environnements pour le même projet.

Commandes principales

Compatibilité des extensions

L’extension azure.ai.agents fournit l’hôte azure.ai.agent . L’extension azure.ai.projects fournit l’hôte azure.ai.project et le fournisseur d’infrastructure microsoft.foundry . Utilisez azure.ai.agents une version 1.0.0-beta.8 ou une version ultérieure avec azure.ai.projects une version ou une version 1.0.0-beta.4 ultérieure. Pour obtenir des instructions d’installation et de mise à niveau, consultez Installer les extensions CLI de développement Azure.

Vous pouvez déclarer les versions minimales compatibles dans azure.yaml:

requiredVersions:
    azd: ">=1.27.1"
    extensions:
        azure.ai.agents: ">=1.0.0-beta.8"
        azure.ai.projects: ">=1.0.0-beta.4"

Cycle de vie du fournisseur de services

Installez le microsoft.foundry méta-package lorsque votre projet inclut des connexions, des boîtes à outils, des compétences ou des routines. Il installe les extensions de fournisseur qui implémentent les hôtes correspondants azure.ai.* .

Les fournisseurs de projets et de connexions appliquent leur configuration pendant azd provision. L’agent, la boîte à outils, les compétences et les fournisseurs de routine appliquent leur configuration pendant azd deploy. Exécutez azd up les deux phases. La suppression d’un service de plan de données ne azure.yamlazd peut plus la gérer ; supprimez la ressource distante séparément lorsque vous n’en avez plus besoin.

• azd down - Supprime le groupe de ressources lorsque l’environnement actuel a créé le projet Foundry. Laisse un projet existant et ses ressources en place. |
• azd env set - Définit une variable d’environnement, par exemple azd env set FOUNDRY_MODEL_NAME=gpt-5.4-mini. |

Modèle fractionné-service

Sous services, chaque entrée est un service nommé avec un host champ qui identifie le type de ressource Foundry qu’elle déclare. Les services se référencent les uns aux autres par le biais du champ, qui forme un graphique uses de dépendance qui se résout au moment de l’approvisionnement azd et du déploiement. Un projet classique possède un azure.ai.project service qui possède les déploiements de modèles et un azure.ai.agent service qui dépend de celui-ci.

Exemple minimal

# yaml-language-server: $schema=https://raw.githubusercontent.com/Azure/azure-dev/main/schemas/v1.0/azure.yaml.json
name: my-agent-project

services:
    ai-project:
        host: azure.ai.project
        deployments:
            - name: gpt-5.4-mini
              model:
                format: OpenAI
                name: gpt-5.4-mini
                version: "2026-03-17"
              sku:
                name: GlobalStandard
                capacity: 10

    my-agent:
        host: azure.ai.agent
        project: src/my-agent
        language: docker
        uses:
            - ai-project
        kind: hosted
        name: my-agent
        description: A hosted agent built from source.
        protocols:
            - protocol: responses
              version: 2.0.0
        env:
            MICROSOFT_FOUNDRY_MODEL_DEPLOYMENT_NAME: ${MICROSOFT_FOUNDRY_MODEL_DEPLOYMENT_NAME}
        container:
            resources:
                cpu: "0.25"
                memory: 0.5Gi

Exemple complet

Le projet suivant ajoute une connexion, une boîte à outils et une mise en réseau privée.

# yaml-language-server: $schema=https://raw.githubusercontent.com/Azure/azure-dev/main/schemas/v1.0/azure.yaml.json
requiredVersions:
    extensions:
        azure.ai.agents: '>=0.1.0-preview'

name: research-agent-project

services:
    ai-project:
        host: azure.ai.project
        deployments:
            - name: gpt-5.4-mini
              model:
                format: OpenAI
                name: gpt-5.4-mini
                version: "2026-03-17"
              sku:
                name: GlobalStandard
                capacity: 50

    search-conn:
        host: azure.ai.connection
        uses:
            - ai-project
        category: CognitiveSearch
        target: https://my-search.search.windows.net
        authType: ApiKey
        credentials:
            key: ${SEARCH_API_KEY}

    research-tools:
        host: azure.ai.toolbox
        uses:
            - ai-project
            - search-conn
        description: Tools used by the research agent.
        tools:
            - type: azure_ai_search
              connection: search-conn
            - type: code_interpreter

    researcher:
        host: azure.ai.agent
        project: src/researcher
        language: docker
        uses:
            - ai-project
            - search-conn
            - research-tools
        kind: hosted
        name: researcher
        description: Hosted research agent built from source.
        startupCommand: python main.py
        toolboxes:
            - research-tools
        env:
            LOG_LEVEL: info
        protocols:
            - protocol: responses
              version: 2.0.0
        container:
            resources:
                cpu: "1.0"
                memory: 2Gi

infra:
    provider: bicep
    path: ./infra

Champs de niveau supérieur

service azure.ai.project

Le service de projet provisionne ou se connecte à un projet Foundry et possède ses déploiements de modèles.

deployments

Une entrée de déploiement peut également être un fichier externe : - $ref: ./deployments/embeddings.yaml.

network

Définissez network la configuration d’un compte sécurisé par le réseau. Le peSubnet champ est requis et établit le point de terminaison privé du compte. Ajoutez agentSubnet pour injecter le runtime de l’agent dans votre propre sous-réseau (apportez votre propre réseau virtuel) ou omettez-le pour utiliser le réseau géré par Microsoft. Pour obtenir une procédure pas à pas complète, consultez Mise en réseau privée de l’agent hébergé.

Configuration du réseau privé

Utilisez network le azure.ai.project service pour configurer le point de terminaison privé de compte et la sortie de l’agent. L’exemple suivant utilise un sous-réseau géré par le client pour le runtime de l’agent :

services:
    ai-project:
        host: azure.ai.project
        network:
            peSubnet:
                vnet: ${VNET_RESOURCE_ID}
                name: private-endpoint-subnet
            agentSubnet:
                vnet: ${VNET_RESOURCE_ID}
                name: agent-subnet
            dns:
                resourceGroup: ${PRIVATE_DNS_RESOURCE_GROUP}
                subscription: ${PRIVATE_DNS_SUBSCRIPTION_ID}

La mise en réseau privée désactive l’accès au plan de données public pour le compte. Une Azure Container Registry créée automatiquement n'est pas prise en charge avec cette configuration. Utilisez le déploiement de code source ou spécifiez un prédéfini image.

service azure.ai.agent

Le service d’agent porte la définition de l’agent et ses paramètres de génération et de déploiement. C’est le service qui remplace l’ancien agent.yaml.

agentCard.skills et azure.ai.skill

agentCard.skills décrit les fonctionnalités d’un agent dans sa carte de découverte. Il fournit des métadonnées pour les clients et ne crée pas ou n’attache pas de compétence Foundry réutilisable. Chaque compétence de carte nécessite un id, nameet description.

Un azure.ai.skill service crée une compétence avec version à partir d’instructions et d’outils autorisés facultatifs. Déclarez-le séparément sous services; sa uses liste contrôle l’ordre des dépendances, mais il ne remplit agentCard.skills pas ou n’attache pas la compétence à un agent. Utiliser agentCard.skills pour les métadonnées de découverte et azure.ai.skill pour obtenir des instructions réutilisables.

agentCard:
    description: Research agent discovery card.
    skills:
        - id: research
          name: Research
          description: Researches a requested subject.

services:
    code-review:
        host: azure.ai.skill
        uses:
            - ai-project
        instructions: ./skills/code-review.md

Remplir une carte de découverte

Ajoutez version, tagset examples lorsque les clients ont besoin de métadonnées de découverte plus riches. Une carte nécessite au moins une description compétence. Chaque compétence nécessite un id, nameet description.

agentCard:
    description: Research agent discovery card.
    version: "1.0"
    skills:
        - id: research
          name: Research
          description: Researches a requested subject.
          tags:
              - research
          examples:
              - Research current product guidance.

Stratégies d’IA responsables

Permet policies d’associer une stratégie d’IA responsable à l’agent hébergé. Définissez raiPolicyName sur l’ID de ressource ARM complet de la stratégie :

policies:
    - type: rai_policy
      raiPolicyName: ${RAI_POLICY_RESOURCE_ID}

Type rai_policy et raiPolicyName requis. L’extension applique la première stratégie valide dans la liste à la configuration d’IA responsable de l’agent hébergé. Pour obtenir des conseils de création et de gestion de stratégie, consultez Ajouter des garde-fous aux agents hébergés.

Mémoires

Permet memoryStores de créer ou réutiliser des magasins de mémoire Foundry avant le déploiement. Chaque magasin nécessite des noms de déploiement de modèles de conversation existants et d’incorporation de modèles.

memoryStores:
    - name: customer-memory
      description: Stores durable customer context.
      chatModel: gpt-5.4-mini
      embeddingModel: text-embedding-3-large
      options:
          chatSummaryEnabled: true
          userProfileEnabled: true
          proceduralMemoryEnabled: false
          defaultTtlSeconds: 0

Les magasins existants ne sont pas mis à jour pendant le déploiement. Si la définition déclarée diffère du magasin existant, azd signale la différence. La déclaration d’un magasin de mémoire ne modifie pas le code de votre agent ni attache automatiquement un outil mémoire. Connectez votre application au magasin de mémoire à l’aide de l’outil de recherche de mémoire ou des API de magasin de mémoire. Pour plus d’informations, consultez Utiliser la mémoire avec les agents.

Configurer un point de terminaison d’agent

Permet agentEndpoint de configurer les protocoles et les schémas d’autorisation publiés par le point de terminaison de l’agent. Utilisez une carte d’agent avec un point de terminaison A2A afin que d’autres agents puissent découvrir les fonctionnalités que vous exposez.

agentEndpoint:
    protocols:
        - responses
        - a2a
    authorizationSchemes:
        - type: Entra

Vous pouvez également définir versionSelector.versionSelectionRules quand vous devez contrôler la version de l’agent qui reçoit le trafic de point de terminaison. Agent Service valide les valeurs de protocole de point de terminaison et d’autorisation pendant le déploiement.

protocols

protocols:
    - protocol: responses
      version: 2.0.0

Pour obtenir la spécification complète du protocole, consultez le contrat d’exécution de l’agent hébergé.

Protocoles d’exécution supplémentaires et points de terminaison d’activité

En plus de responsesla a2aprise en charge invocations_ws des invocationsagents hébergés pour les appels WebSocket et activity pour les scénarios d’activité Microsoft 365 et Teams.

protocols:
    - protocol: invocations_ws
      version: 2.0.0
    - protocol: activity
      version: 2.0.0

Pour un agent d’activité, ajoutez activity à la configuration du point de terminaison public et utilisez le schéma d’autorisation Bot Service requis :

agentEndpoint:
    protocols:
        - activity
    authorizationSchemes:
        - type: BotServiceRbac

Le protocole d’activité peut coexister avec d’autres protocoles sur le même point de terminaison d’agent. Pour connaître le comportement du protocole d’exécution, consultez Qu’est-ce que les agents hébergés ?.

environnement

env:
    MICROSOFT_FOUNDRY_MODEL_DEPLOYMENT_NAME: ${MICROSOFT_FOUNDRY_MODEL_DEPLOYMENT_NAME}
    LOG_LEVEL: info

La ${ } syntaxe fait référence aux azd variables d’environnement à partir de .azure/<env>/.env.

Environnement de plateforme, identité et points de terminaison

La plateforme réserve les préfixes et AGENT_ les FOUNDRY_ préfixes. Lisez les variables de plateforme, telles que FOUNDRY_PROJECT_ENDPOINT, à partir de votre code d’application, mais ne les définissez pas ou ne les remplacez pas.env Les valeurs d’environnement définies par l’agent sont des chaînes.

Chaque agent hébergé déployé reçoit une identité et un point de terminaison d’agent dédiés Microsoft Entra ID. N’ajoutez pas de identity bloc au service d’agent. L’identité de l’agent peut utiliser le point de terminaison du projet et le stockage de session par défaut. Attribuez les rôles supplémentaires d’identité lorsque l’agent doit accéder aux ressources externes. Pour plus d’informations, consultez informations de référence sur les autorisations de l’agent hébergé.

Les protocoles que vous déclarez déterminent les points de terminaison actifs après le déploiement. Exécutez azd ai agent show pour inspecter l’agent déployé et ses URL de point de terminaison.

Après le déploiement, azd écrit les valeurs suivantes dans l’environnement actif, à l’aide du nom du service normalisé à la place de <SERVICE>:

• AGENT_<SERVICE>_NAME
• AGENT_<SERVICE>_VERSION
• AGENT_<SERVICE>_ENDPOINT
• AGENT_<SERVICE>_<PROTOCOL>_ENDPOINT pour activé responses, invocationset invocations_ws les protocoles

Utilisez la sortie spécifique au protocole lorsque votre application ou automatisation a besoin d’une URL d’appel. Le point de terminaison de base identifie la version de l’agent déployé pour les opérations de gestion de session.

container

container:
    resources:
        cpu: "0.25"
        memory: 0.5Gi

Configurer cpu à partir de "0.25" jusqu’à "4.0", et memory de 0.5Gi jusqu’à 8.0Gi.

Déploiement de code source

Définissez codeConfiguration pour déployer le code source en tant que fichier ZIP au lieu d’une image conteneur. Spécifiez un nom de fichier de point d’entrée ou un nom d’assembly. azd le combine avec le runtime sélectionné lorsqu’il crée la version de l’agent hébergé.

codeConfiguration:
    runtime: python_3_13
    entryPoint: main.py
    dependencyResolution: remote_build

Permet remote_build de restaurer des dépendances à partir des sources de projet ou d’utiliser bundled lorsque le fichier ZIP contient des dépendances compatibles Avec Linux. Ne combinez codeConfiguration pas avec la configuration du conteneur basé sur l’image. Pour obtenir des conseils sur l’empaquetage et les dépendances, consultez Déployer un agent hébergé à partir du code source.

Builds de conteneur et images prédéfinies

Utilisez un Dockerfile sous project pour générer une image conteneur ou définir image pour déployer une image prédéfinie :

image: myregistry.azurecr.io/agents/researcher:1.2.3

Quand une Dockerfile et une image sont disponibles, choisissez l’image prédéfinie dans l’invite de déploiement interactive. Pour le déploiement sans assistance, définissez-le AZD_AGENT_SKIP_ACRtrue dans l’environnement actif azd pour sélectionner l’image configurée. Pour connaître les autorisations de Registre et le déploiement de Registre privé, consultez Déployer un agent hébergé avec un Azure Container Registry privé.

Limitations des métadonnées et des schémas

Utilisez des valeurs de chaîne pour les métadonnées de l’agent déployées. La authors valeur des métadonnées peut être une liste de chaînes. Ne vous appuyez pas sur displayName, inputSchemaou outputSchema pour configurer l’agent hébergé déployé ; la configuration unifiée accepte ces champs, mais la demande de création de l’agent hébergé ne les utilise pas.

service azure.ai.connection

Une connexion lie le projet à une ressource externe. La clé de service est le nom de connexion, et le service dépend du projet via uses.

github-conn:
    host: azure.ai.connection
    uses:
        - ai-project
    category: RemoteTool
    target: https://api.githubcopilot.com/mcp
    authType: CustomKeys
    credentials:
        Authorization: ${GITHUB_PAT}

Les modifications de connexion s’appliquent pendant azd provision, et non azd deploy. Stockez les valeurs d’informations d’identification dans votre azd environnement et référencez-les ${VAR} au lieu de placer des secrets dans azure.yaml.

service azure.ai.toolbox

Une boîte à outils est un ensemble nommé d’outils référencés par les agents. Les outils soutenus par la connexion nomment un azure.ai.connection service via le connection champ.

research-tools:
    host: azure.ai.toolbox
    uses:
        - ai-project
        - search-conn
    tools:
        - type: azure_ai_search
          connection: search-conn
        - type: code_interpreter

Un agent fait référence à une boîte à outils en ajoutant le nom du service de boîte à outils à la fois uses à sa liste et à sa toolboxes liste.

Utiliser un point de terminaison de boîte à outils

Dans un projet fractionné, uses contrôle l’ordre de déploiement. Votre application se connecte au point de terminaison MCP de la boîte à outils au moment de l’exécution. Transmettez le nom ou le point de terminaison de la boîte à outils à votre application env, puis construisez le point de terminaison du consommateur à partir de FOUNDRY_PROJECT_ENDPOINT votre code d’agent. Pour obtenir un exemple de bout en bout, consultez Utiliser une boîte à outils avec un agent hébergé.

azure.ai.skill et azure.ai.routine services

Un azure.ai.skill service définit une directive comportementale réutilisable que les agents référencent par nom. Un azure.ai.routine service définit un déclencheur (planification ou événement) et une action qui appelle un agent. Les deux dépendent des ressources qu’ils utilisent via uses. Pour en savoir plus sur l’ajout d’outils pour l’utilisation de l’agent, consultez La boîte à outils dans Foundry etutiliser des routines.

Les compétences et les routines sont des ressources distinctes. La déclaration d’un service contrôle son cycle de vie, mais n’attache pas automatiquement une compétence à l’agent ou déduit une cible d’action de routine. Configurez explicitement l’application consommatrice ou l’action de routine.

Dépendances avec utilisations

Le uses champ déclare les services dont dépend un service donné. azd utilise ce graphique pour commander l’approvisionnement et les références filaires, telles que les connexions et les boîtes à outils d’un agent.

uses:
    - ai-project
    - search-conn
    - research-tools

Le fichier inclut des $ref

Toute entrée de service ou de liste peut être remplacée par une référence à un fichier YAML ou JSON externe. Les chemins relatifs sont résolus à partir du fichier qui contient le $reffichier . Les URL distantes ne sont pas prises en charge.

services:
    triage:
        host: azure.ai.agent
        uses:
            - ai-project
        $ref: ./agents/triage.yaml

Les fichiers incluent vous permettent de conserver des définitions d’agent volumineuses dans leurs propres fichiers et de partager des définitions entre les projets.

Conservez les champs de service principaux dans l’entrée racine azure.yaml lorsque vous utilisez un service $ref: host, , uses, project, language, imageet docker. Placez les champs de définition appartenant au fournisseur, tels que kind, , namedescriptionet protocols, dans le mappage référencé. $ref résout les fichiers YAML ou JSON locaux de manière récursive ; Les URL et les cycles de référence ne sont pas pris en charge.

Substitution de variable

Deux syntaxes de substitution peuvent apparaître dans azure.yaml:

Modes d’infrastructure et de déploiement

Bicep-moins par défaut

azd ai agent init est moins bicep par défaut : il n’écrit pas de infra/ répertoire et azd synthétise l’infrastructure à partir de vos azure.yaml services au moment de l’approvisionnement. Pour matérialiser les fichiers infrastructure-as-code, éjectez-les :

Lorsqu’il infra est présent, azure.yamlazd utilise ces fichiers au lieu de synthétiser l’infrastructure.

Modes de déploiement

Un agent hébergé se déploie dans l’un des deux modes suivants :

Pour les déploiements sources, le codeConfiguration champ sur le service d’agent capture le runtime et le point d’entrée. Pour les images prédéfinies, définissez le image champ sur le service d’agent et ignorez la build Dockerfile.

Migration de la configuration héritée

Les définitions d’agent plus anciennes peuvent imbriquer des variables d’environnement sous config: env. Dans l’unité unifiée azure.yaml, déplacez le env mappage vers le service d’agent :

# Legacy
services:
    my-agent:
        host: azure.ai.agent
        config:
            env:
                MICROSOFT_FOUNDRY_MODEL_DEPLOYMENT_NAME: ${MICROSOFT_FOUNDRY_MODEL_DEPLOYMENT_NAME}

# Unified azure.yaml
services:
    my-agent:
        host: azure.ai.agent
        env:
            MICROSOFT_FOUNDRY_MODEL_DEPLOYMENT_NAME: ${MICROSOFT_FOUNDRY_MODEL_DEPLOYMENT_NAME}

Validation du schéma JSON

Ajoutez la référence de schéma pour la saisie automatique de l’IDE :

# yaml-language-server: $schema=https://raw.githubusercontent.com/Azure/azure-dev/main/schemas/v1.0/azure.yaml.json

Contenu connexe

• Créer azure.yaml pour les agents hébergés
• Initialiser un projet d’agent hébergé avec l’interface CLI Azure développeur
• Infrastructure de l’agent hébergé avec l’interface CLI Azure développeur
• Contrat de l’environnement d’exécution de l’agent hébergé
• Qu’est-ce que les agents hébergés ?