Nota:
El acceso a esta página requiere autorización. Puede intentar iniciar sesión o cambiar directorios.
El acceso a esta página requiere autorización. Puede intentar cambiar los directorios.
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ón1.0.0-beta.8o posterior, y la extensiónazure.ai.projects, versión1.0.0-beta.4o 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
containero compilas a partir de unDockerfile. 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:
-
languageidentifica el lenguaje de compilación. Utilicedocker. En el ejemplo se muestra la ruta de acceso de compilación del contenedor (Dockerfile,startupCommandycontainer.resources); el modo de implementación es una opción independiente, que se describe en Elegir un modo de implementación. -
kindestablece el tipo de agente. Usahostedpara que Foundry compile y ejecute el código fuente del agente, en cualquiera de los dos modos de implementación. -
usesenumera los servicios de los que depende este agente. Comience con el proyecto y agregue conexiones y cuadros de herramientas a medida que los introduzca. -
protocolsdeclara el contrato HTTP que sirve el agente. Useresponsespara la API de respuestas de OpenAI;invocationsya2atambién está disponible. -
envpasa variables de entorno al contenedor. Use${VAR_NAME}para leer los valores del entorno activoazd(.azure/<env>/.env). Las variables que defina usan sus propios nombres; Las variables insertadas en la plataforma usan el prefijo reservadoFOUNDRY_, comoFOUNDRY_PROJECT_ENDPOINT. -
startupCommandinicia el servidor del agente.azd ai agent runlo usa localmente y el contenedor lo usa en el inicio. -
container.resourcesestablece la CPU y la memoria. Establezcacpude"0.25"en"4.0"ymemoryde0.5Gia8.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