Crea el archivo azure.yaml para los agentes hospedados

Importante

Los elementos marcados como versión preliminar en este artículo se encuentran actualmente en versión preliminar. Esta versión preliminar se proporciona sin un contrato de nivel de servicio y Microsoft no lo recomienda para cargas de trabajo de producción. Es posible que algunas características no se admitan o que tengan funcionalidades restringidas. Para más información, consulte Términos de uso complementarios para las versiones preliminares de Microsoft Azure.

Un proyecto de agente hospedado mantiene toda su configuración en un único azure.yaml archivo en la raíz del proyecto. Este archivo declara los recursos de Foundry ( el proyecto, las implementaciones de modelos, las conexiones, los cuadros de herramientas y el propio agente) como un conjunto de servicios. También indica al Azure CLI para desarrolladores (azd) cómo aprovisionarlas e implementarlas. En este artículo se explica cada parte de azure.yaml la que es probable que edite: el proyecto y su modelo, el servicio del agente, las herramientas y cómo se implementa el agente. Normalmente, se inicia desde un archivo que azd ai agent init genera, por lo que cada sección muestra un bloque cada vez para ayudarle a encontrarlo y editarlo.

Para obtener una descripción campo por campo de cada servicio y propiedad, consulta la referencia de azure.yaml para agentes hospedados.

Prerrequisitos

  • Una suscripción Azure con permiso para crear recursos, como el rol Colaborador en la suscripción de destino o el grupo de recursos.
  • Azure CLI para desarrolladores (azd) versión 1.27.1 o posterior. Para obtener instrucciones de instalación, consulte Instalación de azd.
  • Se instalaron las extensiones Foundry de Azure Developer CLI.
  • La extensión azure.ai.agents, versión 1.0.0-beta.8 o posterior, y la extensión azure.ai.projects, versión 1.0.0-beta.4 o posterior. Para la instalación y la comprobación de la versión, consulte Instalar las extensiones de Foundry de la CLI para desarrolladores de Azure.
  • Una sesión de Azure autenticada (azd auth login).
  • Un proyecto de agente alojado. Para crear uno, vea Inicializar un proyecto de agente hospedado.
  • Cuota suficiente del modelo en la región de destino para el despliegue que ha especificado.
  • Docker instalado y en ejecución, pero solo si despliegas en modo container o compilas a partir de un Dockerfile. La implementación de código no requiere Docker.

Descripción de la estructura

Cada entrada en services es un servicio con nombre con un campo host que identifica el tipo de recurso de Foundry que declara. Los servicios hacen referencia unos a otros a través del campo uses, que forma un grafo de dependencias que azd resuelve al aprovisionar e implementar. Un proyecto mínimo tiene dos servicios: un azure.ai.project servicio que posee la implementación del modelo y un azure.ai.agent servicio que depende de él.

# 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
        # ... model deployments

    my-agent:
        host: azure.ai.agent
        uses:
            - ai-project
        # ... agent configuration

La primera línea es una anotación de esquema que activa la validación y el autocompletado en los editores que admiten el servidor de lenguaje para YAML.

Inicio desde un archivo generado

Rara vez empieza con un archivo vacío. Al ejecutar azd ai agent init, la CLI genera un azure.yaml por ti, ya sea a partir de una plantilla, del azure.yaml de un ejemplo que pases con -t, o envolviendo tu código existente. El comando es interactivo y solicita valores como el proyecto Foundry, la implementación del modelo y el nombre del agente. Abra el archivo generado y ajústelo para adaptarlo a su agente. En el resto de este artículo se explica cada parte que es probable que cambie.

Declarar el proyecto y una implementación de modelo

El servicio azure.ai.project aprovisiona un proyecto de Foundry (o se conecta a él) y es propietario de sus implementaciones de modelos. Agregue un despliegue debajo de deployments:

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

Para conectarse a un proyecto existente en lugar de aprovisionar uno nuevo, establezca el campo en la endpoint dirección URL del punto de conexión del proyecto y omita las implementaciones que no quiera azd administrar.

La versión del modelo y la SKU son ilustrativas. Al ejecutar azd ai agent init, la CLI resuelve los valores actuales del catálogo de modelos.

Para hacer referencia a la implementación desde el agente, exponga el nombre de implementación como una variable de entorno. Durante azd ai agent init, la CLI registra el nombre de implementación que seleccione en el azd entorno como MICROSOFT_FOUNDRY_MODEL_DEPLOYMENT_NAMEy el agente lo lee con ${MICROSOFT_FOUNDRY_MODEL_DEPLOYMENT_NAME}, como se muestra en el paso siguiente. Para cambiar la implementación más adelante, ejecute azd env set MICROSOFT_FOUNDRY_MODEL_DEPLOYMENT_NAME <deployment-name>.

Configuración del servicio del agente

El azure.ai.agent servicio incluye la definición del agente. Establezca kind: hosted para un agente en contenedor creado a partir del origen, apunte project al directorio de origen y declare el protocolo que implementa el agente:

    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}
            PYTHONNOUSERSITE: "1"
        startupCommand: python main.py
        container:
            resources:
                cpu: "0.25"
                memory: 0.5Gi

El directorio src/my-agent contiene el código de su agente y, para compilaciones de contenedores, un Dockerfile. Al ejecutar azd ai agent init, se generan ambos. Consulte Inicialización de un proyecto de agente hospedado.

Los ejemplos de Python establecen PYTHONNOUSERSITE antes de que el intérprete se inicie para deshabilitar la carga de paquetes del sitio del usuario. Instale las dependencias en un entorno virtual o en la imagen, no con pip install --user. Consulte Configurar el inicio de Python.

Campos clave que se van a establecer:

  • language identifica el lenguaje de compilación. Utilice docker. En el ejemplo se muestra la ruta de acceso de compilación del contenedor (Dockerfile, startupCommandy container.resources); el modo de implementación es una opción independiente, que se describe en Elegir un modo de implementación.
  • kind establece el tipo de agente. Usa hosted para que Foundry compile y ejecute el código fuente del agente, en cualquiera de los dos modos de implementación.
  • uses enumera los servicios de los que depende este agente. Comience con el proyecto y agregue conexiones y cuadros de herramientas a medida que los introduzca.
  • protocols declara el contrato HTTP que sirve el agente. Use responses para la API de respuestas de OpenAI; invocations y a2a también está disponible.
  • env pasa variables de entorno al contenedor. Use ${VAR_NAME} para leer los valores del entorno activo azd (.azure/<env>/.env). Las variables que defina usan sus propios nombres; Las variables insertadas en la plataforma usan el prefijo reservado FOUNDRY_ , como FOUNDRY_PROJECT_ENDPOINT.
  • startupCommand inicia el servidor del agente. azd ai agent run lo usa localmente y el contenedor lo usa en el inicio.
  • container.resources establece la CPU y la memoria. Establezca cpu de "0.25" en "4.0" y memory de 0.5Gi a 8.0Gi.

Note

No declare FOUNDRY_PROJECT_ENDPOINT en env. La plataforma lo inserta en contenedores hospedados automáticamente y azd ai agent run lo establece para el desarrollo local.

Adición de una conexión

Una conexión vincula el proyecto a un recurso externo, como un servidor remoto del Protocolo de contexto de modelo (MCP) o un índice de búsqueda. Anótelo como un azure.ai.connection servicio cuya clave sea el nombre de la conexión y dependa del proyecto:

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

Almacene valores secretos en el azd entorno y haga referencia a ellos con ${VAR} en lugar de codificarlos de forma rígida. Establezca el secreto con azd env set GITHUB_PAT <value>.

Agregar una caja de herramientas y conectarla al agente

Un cuadro de herramientas es un conjunto con nombre de herramientas que el agente usa en tiempo de ejecución. Declare un servicio azure.ai.toolbox, enumere sus herramientas y asigne las herramientas que requieren conexión a un servicio de conexión:

    agent-tools:
        host: azure.ai.toolbox
        uses:
            - ai-project
            - github-conn
        description: Web search and GitHub MCP tools.
        tools:
            - type: web_search
            - type: mcp
              connection: github-conn

A continuación, integre el conjunto de herramientas en el agente añadiendo su nombre de servicio tanto a la lista uses del agente como a su lista toolboxes:

    my-agent:
        host: azure.ai.agent
        uses:
            - ai-project
            - github-conn
            - agent-tools
        toolboxes:
            - agent-tools
        # ... rest of the agent configuration

Note

En un proyecto de servicios divididos, uses ordena la implementación, pero tu aplicación se conecta al punto de conexión de la caja de herramientas en tiempo de ejecución. Pase el nombre de la toolbox o el endpoint mediante env, y luego use FOUNDRY_PROJECT_ENDPOINT en el código del agente para construir el endpoint del consumidor. Para obtener un patrón completo, consulte Uso de un cuadro de herramientas con un agente hospedado.

Dividir definiciones grandes con $ref

A medida que crece un proyecto, puede mover un servicio o una entrada de lista a su propio archivo e incluirlo con $ref. Las rutas relativas se resuelven desde el archivo que contiene la referencia:

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

Las inclusiones de archivos mantienen legible azure.yaml y permiten compartir definiciones entre proyectos. No se admiten direcciones URL remotas.

Elegir un modo de implementación

El modo de implementación es una opción independiente de la language: docker configuración de compilación. Un agente hospedado se implementa en uno de los dos modos:

Mode Qué hace Valor predeterminado para Docker obligatorio Campos del servicio de agente
code Carga el origen como un archivo ZIP y lo compila de forma remota. proyectos de Python y .NET No azd agrega un codeConfiguration bloque con el tiempo de ejecución y el punto de entrada.
container Compila una imagen de Docker a partir de Dockerfile e la implementa. -- Sí, para compilaciones locales Dockerfile, startupCommandy container.resources se muestran anteriormente.

Seleccione el modo en tiempo de inicialización:

azd ai agent init --deploy-mode code

Para desplegar una imagen precompilada en lugar de compilarla a partir del código fuente, establezca el campo image del servicio de agente en la URL de la imagen. Para los codeConfiguration campos que utiliza el modo code, consulte Implementar un agente hospedado desde el código fuente.

Note

En Unified azure.yaml, codeConfiguration.entryPoint es el nombre de un único archivo de código fuente o un nombre de ensamblado. azd lo combina con el tiempo de ejecución configurado cuando crea la versión del agente hospedado.

Elección de la infraestructura

El azd ai agent init comando no usa Bicep de forma predeterminada. No crea un infra/ directorio. En su lugar, azd genera la infraestructura a partir de sus servicios azure.yaml cuando realiza el aprovisionamiento. Para crear archivos de infraestructura como código que puedas personalizar y registrar, extráelos:

# Eject Bicep into ./infra/
azd ai agent init --infra

# Eject Terraform and set infra.provider: terraform
azd ai agent init --infra=terraform

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

Exploración de funcionalidades avanzadas

Agregue estas configuraciones opcionales cuando el agente necesite funcionalidades más allá del proyecto básico, el modelo, la conexión, el cuadro de herramientas y la configuración del modo de implementación.

Capability Úselo cuando Reference
Redes privadas Se necesita un punto de conexión privado de la cuenta y una salida del agente administrada por el cliente o por Microsoft. Configuración de red privada
Implementación de código fuente Quiere que Agent Service genere un paquete ZIP a partir del código fuente de Python o .NET. Implementación de código fuente
Despliegue de imagen precompilada El sistema de CI compila, examina y publica la imagen de contenedor. Compilaciones de contenedores e imágenes precompiladas
Directivas de IA responsables Necesitas una política de IA responsable en la versión con agente hospedado. Directivas de IA responsables
Almacenes de memoria Su aplicación usa memoria persistente con implementaciones de modelos de chat y de incrustación. Almacenamiento en memoria
Punto de conexión del agente y tarjeta de detección Expones los protocolos del agente para el descubrimiento, la autorización de punto de conexión o A2A. Configuración de un punto de conexión del agente
Protocolos de actividad y WebSocket Necesita Microsoft 365 y compatibilidad con la actividad de Teams o invocaciones mediante WebSocket. Protocolos adicionales del entorno de ejecución y extremos de Activity
Identidad del agente y entorno de plataforma El código usa la identidad de la plataforma, las variables de entorno insertadas o las direcciones URL de punto de conexión implementadas. Entorno de plataforma, identidad y puntos de conexión

Ejemplo completo

A continuación azure.yaml se combinan todos los bloques de este artículo en un archivo: el proyecto y su implementación de modelos, una conexión, un cuadro de herramientas conectado al agente y el propio agente hospedado. No presenta campos nuevos. Úsalo para comprobar la sangría y las referencias uses entre servicios en tu propio archivo.

# 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

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

    agent-tools:
        host: azure.ai.toolbox
        uses:
            - ai-project
            - github-conn
        description: Web search and GitHub MCP tools.
        tools:
            - type: web_search
            - type: mcp
              connection: github-conn

    my-agent:
        host: azure.ai.agent
        project: src/my-agent
        language: docker
        uses:
            - ai-project
            - github-conn
            - agent-tools
        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}
            PYTHONNOUSERSITE: "1"
        startupCommand: python main.py
        toolboxes:
            - agent-tools
        container:
            resources:
                cpu: "0.25"
                memory: 0.5Gi

Los campos uses forman el grafo de dependencias que azd resuelve durante el aprovisionamiento y la implementación. Cada flecha apunta de un servicio al servicio del que depende:

flowchart TD
    agent[my-agent]
    tools[agent-tools]
    conn[github-conn]
    project[ai-project]
    agent --> project
    agent --> conn
    agent --> tools
    tools --> project
    tools --> conn
    conn --> project

Valida tu azure.yaml

Confirma que el archivo se aprovisiona y se implementa según lo esperado:

# Provision the declared resources
azd provision

# Run the agent locally
azd ai agent run

Si la operación azd provision se realiza correctamente, se muestra un resumen de los recursos que ha creado o reutilizado. azd ai agent run compila e inicia el agente localmente y muestra la URL local en la que está disponible la Responses API. Para confirmar que el agente responde, envíe una solicitud a esa dirección URL o ejecute azd ai agent invoke --local.

Si tu editor es compatible con el servidor de lenguaje YAML, la anotación de esquema situada al principio del archivo ofrece autocompletado y señala las discrepancias de tipos básicos a medida que escribes.

Troubleshoot

Problema Causa Corregir
azd provision falla con un error de autorización Has cerrado sesión o tu cuenta no tiene permisos en la suscripción de destino. Ejecute azd auth login, y confirme que tiene un rol como el de Colaborador en la suscripción o el grupo de recursos.
Error en la implementación del modelo El nombre o la versión del modelo no está disponible, o se ha agotado la cuota en la región. Comprueba que el model.name y el model.version de la implementación existan en el catálogo y confirma la cuota en tu región de destino.
Aparece un servicio desconocido en uses Un nombre de una uses lista no coincide con una clave de servicio. Asegúrese de que cada entrada de uses coincide con un nombre de servicio definido en services.
Un ${VAR} valor está vacío en tiempo de ejecución La variable no se establece en el entorno activo azd . Establézcalo con azd env set <VAR> <value> antes de aprovisionar o ejecutar.
azd ai agent run no se puede acceder al modelo El nombre de la implementación o el punto de conexión del agente son incorrectos. Confirme que MICROSOFT_FOUNDRY_MODEL_DEPLOYMENT_NAME corresponde a un despliegue y no sobrescriba el FOUNDRY_PROJECT_ENDPOINT inyectado por la plataforma.

Limpieza de recursos

Cuando haya terminado, elimine los recursos que aprovisionó para que no sigan incurriendo en costos:

azd down