Inicio rápido: Implementación del primer agente hospedado

• Azure CLI para desarrolladores versión 1.24.0 o posterior

• Visual Studio Code
• Microsoft Foundry Toolkit para la extensión de Visual Studio Code

Permiso necesario

Necesita el Administrador de Proyectos de Azure AI en el ámbito del proyecto para crear e implementar agentes alojados. Este rol incluye los permisos del plano de datos para crear agentes y la capacidad de asignar el rol de usuario de IA de Azure a la identidad del agente creada por la plataforma. La identidad del agente necesita el rol de "Usuario de Azure AI" en el proyecto para acceder a los modelos y artefactos durante el tiempo de ejecución.

Si usa azd o la extensión de VS Code, las herramientas controlan automáticamente la mayoría de las asignaciones de RBAC, entre las que se incluyen:

Asegúrese de que la identidad administrada de Foundry Project tenga el rol de extracción de ACR en el Azure Container Registry que use. Si prefiere y tiene acceso de propietario o "Administrador de acceso de usuario", las herramientas azd o vscode también pueden realizar esta tarea. Azure IA Usuario para la identidad de agente creada por la plataforma (acceso a modelos y herramientas en tiempo de ejecución)

Paso 1: Configurar el proyecto de ejemplo

Instale la extensión del agente de la CLI para desarrolladores de Azure e inicialice un nuevo proyecto de agente hospedado.

1. Instale la extensión ai agent para la CLI para desarrolladores de Azure:

   azd ext install azure.ai.agents
   

   Para comprobar que la extensión está instalada, ejecute:

   azd ext list
   

2. Inicialice un nuevo proyecto de agente hospedado en un directorio vacío:

   azd ai agent init
   

   El flujo interactivo le guía a través de la siguiente configuración:

   • Language: seleccione el lenguaje de programación para el que desea código de ejemplo, ya sea C# o Python.
   • Plantilla del agente : seleccione un ejemplo con el que empezar.
   • Model Configuration: seleccione esta opción para implementar un nuevo modelo en Foundry o use uno existente de un Project Foundry existente.
   • Azure suscripción: seleccione la suscripción en la que desea crear los recursos de Foundry.
   • Ubicación : seleccione una región para los recursos.
   • SKU de modelo : seleccione la SKU disponible para su región y suscripción.
   • Nombre de implementación : escriba un nombre para la implementación del modelo.
   • Tamaño del contenedor : seleccione la asignación de CPU y memoria o acepte los valores predeterminados.

   Importante

   Si seleccionó un ejemplo con herramientas y no usa un servidor MCP, comente o quite las líneas siguientes en el agent.yaml archivo:

   - name: AZURE_AI_PROJECT_TOOL_CONNECTION_ID
     value: <CONNECTION_ID_PLACEHOLDER>
   

   Propina

   Si estás ejecutando en un entorno no interactivo, como una canalización de CI/CD o una sesión SSH, utiliza el indicador --no-prompt con azd ai agent init. También debe proporcionar todos los valores necesarios como marcas de línea de comandos en lugar de responder a avisos interactivos.

3. Aprovisione los recursos Azure necesarios:

   Nota

   Necesita acceso de Contributor en su suscripción de Azure para el aprovisionamiento de recursos.

   azd provision
   

   Este comando tarda unos minutos y crea los siguientes recursos:

   Recurso	Propósito	Costo
   Grupo de recursos	Organiza todos los recursos relacionados en la misma área	Sin costo
   Implementación de modelos	Modelo usado por el agente	Consulte precios de Foundry.
   Proyecto de fundición	Hospeda tu agente y proporciona capacidades de inteligencia artificial	Basado en el consumo; consulte Precios de Foundry.
   Azure Container Registry	Almacena las imágenes de contenedor del agente.	Nivel básico; consulte precios de ACR.
   área de trabajo de Log Analytics	Administrar todos los datos de registro en un solo lugar	Sin costo directo. Consulte el costo de Log Analytics
   Application Insights	Supervisa el rendimiento y los registros del agente.	Pago por uso. Consulte precios de Azure Monitor
   Identidad administrada	Autentica al agente en servicios de Azure	Sin costo

   Propina

   Ejecute azd down cuando termine este inicio rápido para eliminar recursos y dejar de incurrir en cargos.

Paso 2: Probar el agente localmente

Antes de la implementación, compruebe que el agente funciona localmente.

1. Inicie el agente localmente:

   azd ai agent run
   

   Este comando configura automáticamente el entorno, instala dependencias e inicia el agente. Usa el startupCommand definido en azure.yaml para iniciar tu agente.

   Nota

   Los paquetes de versión preliminar pueden generar advertencias de conflicto de versión de dependencia de Pip durante el proceso de instalación. Estas advertencias no son bloqueantes: el agente se inicia y responde correctamente independientemente de ellas.

   Si el agente no se inicia, compruebe estos problemas comunes:

   Error	Solución
   AuthenticationError o DefaultAzureCredential falla	Ejecute azd auth logout y, a continuación, azd auth login para actualizar la sesión.
   ResourceNotFound	Compruebe que las direcciones URL del punto de conexión coinciden con los valores del portal de Foundry.
   DeploymentNotFound	Compruebe el nombre de implementación en Compilación>Implementaciones.
   Connection refused	Asegúrese de que ningún otro proceso use el puerto 8088.

2. En un terminal independiente, envíe un mensaje de prueba al agente local.

   En el caso de los agentes que usan la API de respuestas, puede enviar una cadena como carga útil:

   azd ai agent invoke --local "What is Microsoft Foundry?"
   

   Para los agentes que usan la API de invocaciones, compruebe el README.md payload esperado. En general, los ejemplos requieren un contenido JSON, pero revise lo que se encuentra en el README.md de ese ejemplo para un ejemplo específico.

   Debería ver una respuesta del agente.

Paso 3: Desplegar en el servicio del agente Foundry

Puesto que ya ha aprovisionado la infraestructura en el paso 1, implemente el código del agente en Azure:

azd deploy

El contenedor del agente se compila de forma remota, por lo que Docker Desktop no es necesario en la máquina.

Cuando se complete, la salida muestra un enlace al entorno de pruebas del agente y el punto de acceso para invocar al agente de forma programática.

Deploying services (azd deploy)

  (✓) Done: Deploying service af-agent-with-foundry-tools
  - Agent playground (portal): https://ai.azure.com/nextgen/.../build/agents/af-agent-with-foundry-tools/build?version=1 
  - Agent endpoint: https://ai-account-<name>.services.ai.azure.com/api/projects/<project>/agents/af-agent-with-foundry-tools/versions/1

Paso 1: Crear un proyecto Foundry

Use la extensión Microsoft Foundry Toolkit en VS Code para crear un nuevo recurso Microsoft Foundry Project.

1. Abra la paleta de comandos (Ctrl+Mayús+P) y seleccione Microsoft Foundry: Create Project.

2. Seleccione la suscripción de Azure.

3. Cree un nuevo grupo de recursos o seleccione uno existente.

4. Escriba un nombre para el recurso del proyecto Foundry.

Una vez completada la creación del proyecto, continúe con el paso siguiente e implemente un modelo.

Paso 2: Implementación de un modelo

Use la extensión Microsoft Foundry Toolkit en VS Code para implementar un modelo en Foundry.

1. Abra la paleta de comandos (Ctrl+Mayús+P) y seleccione Microsoft Foundry: Open Model Catalog.

2. Examine el catálogo de modelos o busque gpt-4.1 y seleccione el botón Implementar .

3. En la página Implementación de modelos, seleccione el botón Deploy to Microsoft Foundry.

Una vez implementado correctamente el modelo, vaya al paso siguiente y cree un proyecto de Agente hospedado.

Paso 3: Crear un proyecto de agente hospedado

Usa la extensión "Microsoft Foundry Toolkit" en VS Code para generar la estructura de un nuevo proyecto de agente hospedado.

1. Abra la paleta de comandos (Ctrl+Mayús+P) y seleccione Microsoft Foundry: Create new Hosted Agent.

2. Seleccione el marco que desea usar.

3. Seleccione un lenguaje de programación, Python o C#.

4. Seleccione API de respuestas o API de invocación.

5. Seleccione el código de ejemplo que desea usar.

6. Elija la carpeta donde desea que se guarden los archivos del proyecto.

7. Escriba un nombre para el agente hospedado.

Se iniciará una nueva ventana de VS Code con la nueva carpeta del proyecto del agente como área de trabajo activa.

Paso 4: Instalación de dependencias

Se recomienda usar un entorno virtual para aislar las dependencias del proyecto:

macOS/Linux:

python -m venv .venv
source .venv/bin/activate

Windows (PowerShell):

python -m venv .venv
.\.venv\Scripts\Activate.ps1

Instalación de dependencias

Instale las dependencias de Python necesarias mediante pip:

pip install -r requirements.txt

Consulte el requirement.txt para obtener una lista de los paquetes necesarios.

Paso 5: Probar el agente localmente

Ejecute y pruebe el agente antes de implementarlo.

Opción 1: Presione F5 (recomendado)

Presione F5 en VS Code para iniciar la depuración. Como alternativa, puede usar el menú depuración de VS Code:

1. Abra la vista Ejecutar y depurar (Ctrl+Mayús+D/ Cmd+Mayús+D)
2. Seleccione "Depurar servidor HTTP de flujo de trabajo local" en la lista desplegable.
3. Haga clic en el botón verde Iniciar depuración (o presione F5).

Esto hará lo siguiente:

1. Iniciar el servidor HTTP con la depuración habilitada
2. Abra el inspector del agente de Foundry Toolkit para realizar pruebas interactivas.
3. Le permite establecer puntos de interrupción e inspeccionar el flujo de trabajo.

Opción 2: Ejecutar en terminal

Ejecute como servidor HTTP (valor predeterminado):

python main.py

Esto iniciará el agente hospedado localmente en http://localhost:8088/.

PowerShell (Windows):

$body = @{
   input = "I need a hotel in Seattle from 2025-03-15 to 2025-03-18, budget under `$200 per night"
    stream = $false
} | ConvertTo-Json

Invoke-RestMethod -Uri http://localhost:8088/responses -Method Post -Body $body -ContentType "application/json"

Bash/curl (Linux/macOS):

curl -sS -H "Content-Type: application/json" -X POST http://localhost:8088/responses \
   -d '{"input": "Find me hotels in Seattle for March 20-23, 2025 under $200 per night","stream":false}'

El agente usará la get_available_hotels herramienta para buscar hoteles disponibles que coincidan con sus criterios.

Paso 6: Implementación en el servicio del Agente Foundry

Implemente el agente directamente desde VS Code.

1. Abra la paleta de comandos (Ctrl+Mayús+P) y seleccione Microsoft Foundry: Deploy Hosted Agent.

2. Seleccione "ACR predeterminado"

3. Seleccione la configuración de CPU y memoria para el contenedor del agente hospedado.

Cambie al explorador de Microsoft Foundry Toolkit seleccionando el icono de la izquierda. El agente aparece en la barra lateral de la vista de árbol Agentes Hospedados (Versión Preliminar) una vez completada la implementación.

Comprobación del estado del agente

Compruebe el estado del agente para confirmar que se está ejecutando.

1. Seleccione el agente hospedado en la vista de árbol Agentes hospedados (versión preliminar).

2. Seleccione el agente que acaba de implementar.

La página de detalles muestra el estado en la sección Detalles del contenedor.

Prueba en el área de juegos mediante VS Code

Microsoft Foundry Toolkit para VS Code incluye un área de juegos integrada para chatear e interactuar con el agente.

1. Seleccione el agente hospedado en la vista de árbol Agentes hospedados (versión preliminar).

2. Seleccione la opción Parque infantil y escriba un mensaje y envíe para probar el agente.

Comprobación del estado del agente

Verifique el estado del agente desplegado.

azd ai agent show

Para mostrar la salida en formato de tabla:

azd ai agent show --output table

Si el proyecto tiene varios servicios de agente, especifique el nombre del agente como argumento posicional:

azd ai agent show <agent-name>

Prueba el agente implementado

Envíe un mensaje de prueba al agente implementado con el mismo invoke comando usado anteriormente, pero sin la --local marca :

En el caso de los agentes que usan la API de respuestas, puede enviar una cadena como carga útil:

azd ai agent invoke <payload>

Debería ver una respuesta del agente después de unos segundos.

Visualización de los registros del agente

Monitorea los registros en vivo de tus agentes:

# Fetch recent container console logs
azd ai agent monitor

# Fetch the last N lines of console logs
azd ai agent monitor --tail 20

# Fetch system event logs (container start and stop events)
azd ai agent monitor --type system

# Stream session logs in real time
azd ai agent monitor --session <session-id> --follow

Si el proyecto tiene varios servicios de agente, especifique el nombre del agente como argumento posicional:

azd ai agent monitor <agent-name> --follow

Para obtener una vista previa de lo que se eliminará, ejecute el down comando :

azd down

Cuando haya finalizado, azd muestra todos los recursos que se eliminarán y le pedirá que confirme. Seleccione yes esta opción para continuar o no cancelarla.

El proceso de limpieza tarda aproximadamente entre 2 y 5 minutos.

Para eliminar los recursos, abra el portal Azure, vaya al grupo de recursos y elimínelo junto con todos los recursos contenidos.

Ver los registros del contenedor de su agente

Puede comprobar los registros de la consola y del sistema del contenedor para solucionar problemas.

1. Seleccione el agente hospedado en la vista de árbol Agentes hospedados (versión preliminar).

2. Seleccione la pestaña "Parque infantil" del agente hospedado.

3. Seleccione la sección "Registros" en los detalles de la sesión.

Visualización de los archivos de sesión del agente

Puede ver todos los archivos almacenados en el directorio principal del agente basado en ADC.

1. Seleccione su agente hospedado en la vista de árbol de Agentes Hospedados (versión preliminar).

2. Seleccione la pestaña "Parque infantil" del agente hospedado.

3. Seleccione la sección "archivos" en los detalles de la sesión.

Puede descargar, cargar y crear carpetas dentro de la carpeta actual; al hacer clic en una carpeta, se entrará en ella, y al hacer clic en la barra de navegación superior, se regresará a la carpeta anterior.