Referencia de azure.yaml para agentes hospedados

El azure.yaml archivo es la configuración de proyecto de la CLI de desarrollador (azd) única Azure para un proyecto de agente hospedado. Declara los recursos de Foundry (el proyecto, las implementaciones de modelos, las conexiones, los cuadros de herramientas, las aptitudes, las rutinas y los propios agentes), como un conjunto de servicios, y le indica azd cómo aprovisionarlos e implementarlos. Este archivo unificado reemplaza el modelo de dos archivos anterior que divide la configuración entre agent.manifest.yaml y agent.yaml.

Para obtener información sobre cómo crear y crear este archivo paso a paso, consulte Author azure.yaml for hosted agents (Creación de azure.yaml para agentes hospedados).

Uso de azd azure.yaml

La CLI de Azure Developer simplifica el flujo de trabajo del desarrollador a la nube. Controla dos cosas: aprovisionar Azure recursos, como proyectos de Foundry, implementaciones de modelos y registros de contenedor, e implementar el código en esos recursos. En el caso de los agentes hospedados, la azure.ai.agents extensión agrega comandos específicos del agente, como azd ai agent init y azd ai agent run.

Cada azd proyecto tiene un azure.yaml archivo en su raíz. En el caso de los proyectos de agente, este archivo es el origen de la verdad para la configuración del agente y la configuración de implementación.

Environments

Un entorno es una configuración con nombre, como dev, stagingo prod, que almacena la configuración de una implementación determinada. Cada entorno realiza un seguimiento de la suscripción y la ubicación de Azure, el grupo de recursos y los nombres de recursos, así como las variables personalizadas que establezca. La configuración se almacena localmente en .azure/<env-name>/.env. Puede tener varios entornos para el mismo proyecto.

Comandos principales

Compatibilidad de extensiones

La azure.ai.agents extensión proporciona el azure.ai.agent host. La azure.ai.projects extensión proporciona el azure.ai.project host y el proveedor de microsoft.foundry infraestructura. Use azure.ai.agents la versión 1.0.0-beta.8 o posterior con azure.ai.projects la versión 1.0.0-beta.4 o posterior. Para obtener instrucciones de instalación y actualización, consulte Instalación de las extensiones foundry de la CLI para desarrolladores de Azure.

Puede declarar las versiones mínimas compatibles en azure.yaml:

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

Ciclo de vida del proveedor de servicios

Instale el microsoft.foundry metapaquete cuando el proyecto incluya conexiones, cuadros de herramientas, aptitudes o rutinas. Instala las extensiones de proveedor que implementan los hosts correspondientes azure.ai.* .

Los proveedores de proyectos y conexiones aplican su configuración durante azd provision. Los proveedores de agente, cuadro de herramientas, aptitud y rutina aplican su configuración durante azd deploy. Ejecute azd up para completar ambas fases. Quitar un servicio de plano de datos de deja azd de azure.yaml administrarlo; elimine el recurso remoto por separado cuando ya no lo necesite.

• azd down : elimina el grupo de recursos cuando el entorno actual creó el proyecto Foundry. Deja un proyecto existente y sus recursos en su lugar. |
• azd env set : establece una variable de entorno, por ejemplo azd env set FOUNDRY_MODEL_NAME=gpt-5.4-mini. |

El modelo de split-service

En services, cada entrada es un servicio con nombre con un host campo que identifica el tipo de recurso Foundry que declara. Los servicios se hacen referencia entre sí a través del uses campo , que forma un gráfico de dependencias que azd se resuelve en tiempo de aprovisionamiento e implementación. Un proyecto típico tiene un azure.ai.project servicio que posee las implementaciones del modelo y un azure.ai.agent servicio que depende de él.

Ejemplo mínimo

# 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

Ejemplo completo

El siguiente proyecto agrega una conexión, un cuadro de herramientas y redes privadas.

# 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

Campos de nivel superior

servicio azure.ai.project

El servicio de proyecto aprovisiona o se conecta a un proyecto foundry y posee sus implementaciones de modelo.

deployments

Una entrada de implementación también puede ser un archivo externo: - $ref: ./deployments/embeddings.yaml.

network

Establézcalo network en aprovisionar una cuenta protegida por red. El peSubnet campo es obligatorio y establece el punto de conexión privado de la cuenta. Agregue agentSubnet para insertar el entorno de ejecución del agente en su propia subred (traiga su propia red virtual) o omita esta para usar la red administrada Microsoft. Para ver un tutorial completo, consulte Redes privadas del agente hospedado.

Configuración de red privada

Use network en el azure.ai.project servicio para configurar el punto de conexión privado de la cuenta y la salida del agente. En el ejemplo siguiente se usa una subred administrada por el cliente para el entorno de ejecución del agente:

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}

Las redes privadas deshabilitan el acceso al plano de datos público para la cuenta. No se admite una Azure Container Registry creada automáticamente con esta configuración. Use la implementación de código fuente o especifique un elemento precompilado image.

servicio azure.ai.agent

El servicio del agente lleva la definición del agente y su configuración de compilación e implementación. Es el servicio que reemplaza al antiguo agent.yaml.

agentCard.skills y azure.ai.skill

agentCard.skills describe las funcionalidades de un agente en su tarjeta de detección. Proporciona metadatos para los clientes y no crea ni adjunta una aptitud foundry reutilizable. Cada aptitud de tarjeta requiere un id, namey description.

Un azure.ai.skill servicio crea una aptitud con versiones a partir de instrucciones y herramientas permitidas opcionales. Anótelo por separado en services; su orden de dependencia controla la uses lista, pero no rellena agentCard.skills ni adjunta la aptitud a un agente. Use agentCard.skills para los metadatos de detección y azure.ai.skill para obtener instrucciones reutilizables.

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

Completar una tarjeta de detección

Agregue version, tagsy examples cuando los clientes necesiten metadatos de detección más completos. Una tarjeta requiere una description aptitud y al menos una aptitud. Cada aptitud requiere un id, namey 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.

Directivas de IA responsables

Use policies para asociar una directiva de IA responsable al agente hospedado. Establézcalo raiPolicyName en el identificador de recurso arm completo de la directiva:

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

El rai_policy tipo y raiPolicyName son necesarios. La extensión aplica la primera directiva válida de la lista a la configuración de ia responsable del agente hospedado. Para obtener instrucciones de creación y administración de directivas, consulte Incorporación de límites de protección a agentes hospedados.

Almacenes de memoria

Use memoryStores para crear o reutilizar almacenes de memoria foundry antes de la implementación. Cada almacén requiere nombres de implementación existentes del modelo de chat e inserción de modelos.

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

Los almacenes existentes no se actualizan durante la implementación. Si la definición declarada difiere del almacén existente, azd notifica la diferencia. Declarar un almacén de memoria no cambia el código del agente ni adjunta automáticamente una herramienta de memoria. Conecte la aplicación al almacén de memoria mediante la herramienta de búsqueda de memoria o las API de almacenamiento de memoria. Para más información, consulte Uso de memoria con agentes.

Configuración de un punto de conexión del agente

Use agentEndpoint para configurar los protocolos y esquemas de autorización publicados por el punto de conexión del agente. Use una tarjeta de agente con un punto de conexión A2A para que otros agentes puedan detectar las funcionalidades que expone.

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

También puede definir versionSelector.versionSelectionRules cuándo necesita controlar qué versión del agente recibe el tráfico del punto de conexión. El servicio del agente valida los valores de protocolo de punto de conexión y autorización durante la implementación.

protocols

protocols:
    - protocol: responses
      version: 2.0.0

Para obtener la especificación de protocolo completa, consulte Contrato en tiempo de ejecución del agente hospedado.

Protocolos de tiempo de ejecución adicionales y puntos de conexión de actividad

Además responsesde , invocationsy a2a, los agentes hospedados admiten invocations_ws invocaciones de WebSocket y activity para escenarios de actividad de Microsoft 365 y Teams.

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

Para un agente de actividad, agregue activity a la configuración del punto de conexión público y use el esquema de autorización Bot Service necesario:

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

El protocolo de actividad puede coexistir con otros protocolos en el mismo punto de conexión del agente. Para ver el comportamiento del protocolo en tiempo de ejecución, consulte ¿Qué son los agentes hospedados?.

Entorno

env:
    MICROSOFT_FOUNDRY_MODEL_DEPLOYMENT_NAME: ${MICROSOFT_FOUNDRY_MODEL_DEPLOYMENT_NAME}
    LOG_LEVEL: info

La ${ } sintaxis hace referencia a azd variables de entorno de .azure/<env>/.env.

Entorno de plataforma, identidad y puntos de conexión

La plataforma reserva los FOUNDRY_ prefijos y AGENT_ . Lea las variables de plataforma, como FOUNDRY_PROJECT_ENDPOINT, desde el código de la aplicación, pero no las defina ni invalide en env. Los valores de entorno definidos por el agente son cadenas.

Cada agente hospedado implementado recibe una identidad y un punto de conexión de agente de Microsoft Entra ID dedicados. No agregue un identity bloque al servicio del agente. La identidad del agente puede usar el punto de conexión del proyecto y el almacenamiento de sesión de forma predeterminada. Asigne los roles adicionales de identidad cuando el agente necesite acceder a los recursos externos. Para más información, consulte Referencia de permisos del agente hospedado.

Los protocolos que declara determinan los puntos de conexión que están activos después de la implementación. Ejecute azd ai agent show para inspeccionar el agente implementado y sus direcciones URL de punto de conexión.

Después de la implementación, azd escribe los siguientes valores en el entorno activo mediante el nombre del servicio normalizado en lugar de <SERVICE>:

• AGENT_<SERVICE>_NAME
• AGENT_<SERVICE>_VERSION
• AGENT_<SERVICE>_ENDPOINT
• AGENT_<SERVICE>_<PROTOCOL>_ENDPOINTpara protocolos habilitadosresponses, invocations, y invocations_ws

Use la salida específica del protocolo cuando la aplicación o automatización necesite una dirección URL de invocación. El punto de conexión base identifica la versión del agente implementada para las operaciones de administración de sesión.

container

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

Configure cpu de "0.25" hasta "4.0"y memory de 0.5Gi hasta 8.0Gi.

Implementación de código fuente

Establezca codeConfiguration para implementar el código fuente como un archivo ZIP en lugar de una imagen de contenedor. Especifique un nombre de archivo de punto de entrada o un nombre de ensamblado. azd lo combina con el tiempo de ejecución seleccionado cuando crea la versión del agente hospedado.

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

Use remote_build para restaurar las dependencias de los orígenes del proyecto o use bundled cuando el archivo ZIP contiene dependencias compatibles con Linux. No se combine codeConfiguration con la configuración de contenedor basada en imágenes. Para obtener instrucciones de empaquetado y dependencia, consulte Implementación de un agente hospedado desde el código fuente.

Compilaciones de contenedores e imágenes precompiladas

Use un Dockerfile elemento en project para compilar una imagen de contenedor o establecer image para implementar una imagen precompilada:

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

Dockerfile Cuando una y están image disponibles, elija la imagen precompilada en el símbolo del sistema de implementación interactiva. Para la implementación desatendida, establezca AZD_AGENT_SKIP_ACRtrue en el entorno activo azd para seleccionar la imagen configurada. Para obtener permisos del Registro y la implementación del registro privado, consulte Implementación de un agente hospedado con un Azure Container Registry privado.

Limitaciones de metadatos y esquemas

Use valores de cadena para los metadatos del agente implementados. El authors valor de metadatos puede ser una lista de cadenas. No confíe en displayName, inputSchemao outputSchema para configurar el agente hospedado implementado; la configuración unificada acepta estos campos, pero la solicitud de creación del agente hospedado no las usa.

servicio azure.ai.connection

Una conexión vincula el proyecto a un recurso externo. La clave de servicio es el nombre de conexión y el servicio depende del proyecto a través usesde .

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

Los cambios de conexión se aplican durante azd provision, no azd deploy. Almacene los valores de credenciales en el azd entorno y haga referencia a ellos con ${VAR} en lugar de colocar secretos en azure.yaml.

servicio azure.ai.toolbox

Un cuadro de herramientas es un conjunto con nombre de herramientas a las que hacen referencia los agentes. Las herramientas respaldadas por la conexión asignan un nombre a un azure.ai.connection servicio a través del connection campo .

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

Un agente hace referencia a un cuadro de herramientas agregando el nombre del servicio del cuadro de herramientas a y uses su toolboxes lista.

Consumo de un punto de conexión del cuadro de herramientas

En un proyecto de servicio dividido, uses controla el orden de implementación. La aplicación se conecta al punto de conexión MCP del cuadro de herramientas en tiempo de ejecución. Pase el nombre del cuadro de herramientas o el punto de conexión a la aplicación a través envde y, a continuación, construya el punto de conexión de consumidor desde FOUNDRY_PROJECT_ENDPOINT en el código del agente. Para obtener un ejemplo completo, consulte Uso de un cuadro de herramientas con un agente hospedado.

servicios azure.ai.skill y azure.ai.routine

Un azure.ai.skill servicio define una guía de comportamiento reutilizable que los agentes hacen referencia por nombre. Un azure.ai.routine servicio define un desencadenador (programación o evento) y una acción que invoca a un agente. Ambos dependen de los recursos que usan a través de uses. Para obtener más información sobre cómo agregar herramientas para el uso del agente, consulte ¿Qué es el cuadro de herramientas en Foundry? y Usar rutinas.

Las aptitudes y rutinas son recursos independientes. Declarar el servicio controla su ciclo de vida, pero no asocia automáticamente una aptitud al agente ni deduce un destino de acción rutinaria. Configure explícitamente la aplicación de consumo o la acción rutinaria.

Dependencias con usos

El uses campo declara los servicios de los que depende un servicio determinado. azd usa este gráfico para ordenar el aprovisionamiento y para conectar las referencias, como las conexiones y cuadros de herramientas de un agente.

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

El archivo incluye con $ref

Cualquier entrada de servicio o lista se puede reemplazar por una referencia a un archivo YAML o JSON externo. Las rutas de acceso relativas se resuelven desde el archivo que contiene .$ref No se admiten direcciones URL remotas.

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

Los archivos incluyen permiten mantener definiciones de agente grandes en sus propios archivos y compartir definiciones entre proyectos.

Mantenga los campos de servicio principales en la entrada raíz azure.yaml cuando use un servicio$ref: host, uses, project, language, y dockerimage. Coloque los campos de definición propiedad del proveedor, como kind, name, descriptiony protocols, en la asignación a la que se hace referencia. $ref resuelve archivos YAML o JSON locales de forma recursiva; No se admiten direcciones URL ni ciclos de referencia.

Sustitución de variables

Dos sintaxis de sustitución pueden aparecer en azure.yaml:

Modos de infraestructura e implementación

Bicep menos de forma predeterminada

azd ai agent init es menos de bicep de forma predeterminada: no escribe un infra/ directorio y azd sintetiza la infraestructura de azure.yaml los servicios en el momento del aprovisionamiento. Para materializar los archivos de infraestructura como código, expulselos:

Cuando infra está presente en azure.yaml, azd usa esos archivos en lugar de sintetizar la infraestructura.

Modos de implementación

Un agente hospedado se implementa en uno de los dos modos:

En el caso de las implementaciones de origen, el codeConfiguration campo del servicio del agente captura el tiempo de ejecución y el punto de entrada. Para las imágenes precompiladas, establezca el image campo en el servicio del agente y omita la compilación de Dockerfile.

Migración de configuración heredada

Las definiciones de agente anteriores pueden anidar variables de entorno en config: env. En el unificado azure.yaml, mueva la env asignación al servicio del agente:

# 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}

Validación del esquema JSON

Agregue la referencia de esquema para autocompletar del IDE:

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

Contenido relacionado

• Creación de azure.yaml para agentes hospedados
• Inicialización de un proyecto de agente hospedado con la CLI para desarrolladores de Azure
• Infraestructura de agente hospedada con la CLI para desarrolladores de Azure
• Contrato del entorno de ejecución del agente alojado
• ¿Qué son los agentes alojados?