Inicialización de un proyecto de agente hospedado con la CLI para desarrolladores de Azure

Usa azd ai agent init para crear la estructura de un proyecto de agente hospedado con los archivos que necesitas para compilar, probar e implementar un agente de IA en Microsoft Foundry. En este artículo, elige un punto de partida e inicializa el proyecto a partir de una plantilla, de su propio código o de un proyecto de Foundry existente.

Si utiliza un asistente de programación como GitHub Copilot, la Microsoft Foundry Skill puede ayudarle a elegir una plantilla inicial, generar la estructura base del proyecto e interpretar la configuración azd generada.

Prerequisites

• Se instalaron las extensiones Foundry de Azure Developer CLI.
• Una sesión de Azure autenticada (azd auth login).
• Acceso como colaborador en su suscripción de Azure.

Elegir un punto de partida

Hay tres maneras de comenzar un proyecto. Elija la ruta de acceso que coincida con su situación.

Inicialización a partir de una plantilla

Ejecute el asistente interactivo en un directorio vacío y seleccione Iniciar nuevo desde una plantilla:

azd ai agent init

El asistente le guía a través de las siguientes opciones.

El nombre del agente procede de la plantilla. La CLI crea un azd entorno denominado <directory>-dev y lo configura con detalles del proyecto Foundry seleccionado. Cada plantilla incluye código fuente del agente, un Dockerfiley un azure.yaml archivo que actúa como manifiesto de proyecto unificado para la configuración del proyecto y del azd agente hospedado.

Inicializar desde una URL de azure.yaml

Si dispone de un ejemplo de agente específico, apunte -m al azure.yaml del ejemplo. La CLI adopta ese archivo como manifiesto del proyecto y descarga el origen del agente al que se hace referencia.

azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/agent-framework/responses/01-basic/azure.yaml

La opción -m sigue aceptando una URL de manifiesto de agente heredado, pero los ejemplos actuales publican un azure.yaml unificado.

Especificar un modelo

Elija un modelo en tiempo de inicialización:

azd ai agent init --model gpt-4.1

O use una implementación de modelo existente en su proyecto de Foundry:

azd ai agent init --model-deployment my-deployment

Elegir un modo de implementación

De forma predeterminada, azd ai agent init usa la implementación mediante código para proyectos de Python y .NET. La implementación del código sube el código fuente como un paquete ZIP. Para generar un proyecto basado en contenedores, pase --deploy-mode container:

azd ai agent init --deploy-mode container

Para implementar una imagen de contenedor precompilada, pase --image y --agent-name. Esta opción omite la selección de plantillas y lenguajes, el scaffolding de código, la generación de Dockerfile y la configuración de Azure Container Registry.

azd ai agent init --agent-name my-agent --image myregistry.azurecr.io/my-agent:v1

Examinar plantillas de forma no interactiva

Para examinar el catálogo antes de crear el esqueleto, o para ejecutar azd ai agent init desde un script, muestra el catálogo:

# Everything in the catalog
azd ai agent sample list

# Just the featured Python agent samples
azd ai agent sample list --featured-only --language python --type agent

# Full azd templates only, as JSON for scripting
azd ai agent sample list --type azd --output json

Cada entrada incluye un initCommand listo para ejecutarse que puedes copiar y ejecutar en el directorio en el que deseas crear el esqueleto.

Inicialización a partir del código existente

Si ya tiene código de agente en Python o .NET, ejecute azd ai agent init en el directorio que ya contiene ese código:

cd my-agent/
azd ai agent init

La CLI detecta los archivos existentes y genera una azure.yaml entrada de servicio alrededor de ellos sin sobrescribir el código. Para la implementación de contenedores, también agrega un Dockerfile. La infraestructura carece de Bicep de forma predeterminada, a menos que se implemente posteriormente la infraestructura como código.

El código del agente debe cumplir con el contrato del entorno de ejecución del agente hospedado:

• Escuche en el puerto 8088.
• Ejecuta un sondeo de estado en GET /readiness.
• Controle uno de los protocolos admitidos (responses o invocations).

Si el código aún no habla uno de estos protocolos, agregue un adaptador de protocolo, un contenedor ligero del SDK que se traduzca entre el protocolo Foundry y la lógica del agente.

Para agregar un agente a un proyecto existente azd , init detecta el proyecto y agrega una nueva entrada de servicio a la existente azure.yaml. Use --src para especificar un subdirectorio:

azd ai agent init --src src/my-agent

Conexión a un proyecto de Foundry existente

Para administrar un proyecto existente de Foundry a través de azd, ejecute el asistente y seleccione la opción para conectarse a un proyecto existente. También puede omitir la selección interactiva proporcionando directamente el identificador de recurso de Azure del proyecto:

azd ai agent init --project-id /subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.CognitiveServices/accounts/{account}/projects/{project}

Para encontrar el identificador del proyecto, abra el portal de Foundry, vaya a Administrar>Detalles del proyecto y copie el valor ID de recurso.

Revisar lo que se crea

Una vez init completado, el directorio del proyecto contiene la estructura siguiente:

.
|-- azure.yaml                  # Unified azd project and hosted agent configuration
|-- src/
|   \-- <agent-name>/
|       |-- Dockerfile          # Container build definition
|       \-- ...                 # Agent source code
|-- .azure/                     # Environment configuration
\-- infra/                      # Optional IaC, created only after you eject infrastructure

Las plantillas y los ejemplos generan un azure.yaml unificado en la raíz del proyecto. Durante init, azd adopta o genera ese archivo. Trabajas con azure.yaml de ahora en adelante. La infraestructura carece de Bicep de forma predeterminada. Expulsar la infraestructura solo cuando necesite administrar directamente los archivos IaC generados.

Contenido relacionado

• Inicio rápido: Implementación del primer agente hospedado
• Crea el archivo azure.yaml para los agentes hospedados
• Referencia de azure.yaml para agentes hospedados
• Infraestructura de agente hospedada con la CLI para desarrolladores de Azure