Prueba, implementación e integración de agentes

Los agentes de prueba, implementación y publicación son pasos críticos para pasar del desarrollo a la producción. Microsoft Foundry proporciona capacidades completas para validar el comportamiento del agente, implementarlo en tu proyecto Foundry y publicar los agentes como puntos de conexión que pueden ser invocados por consumidores y aplicaciones externos.

Estrategias de prueba para agentes

Las pruebas exhaustivas garantizan que los agentes se comporten de forma confiable en diversos escenarios antes de llegar a los usuarios. Tanto el portal de Foundry como la extensión Visual Studio Code proporcionan áreas de juegos para pruebas interactivas.

Usar el área de juegos de forma eficaz:

• Prueba de ruta feliz: compruebe que el agente maneja correctamente las solicitudes comunes y esperadas.
• Prueba de caso avanzado: pruebe entradas ambiguas, información incompleta y solicitudes inusuales para revelar cómo los agentes controlan la incertidumbre.
• Pruebas de límites : confirme que el agente respeta los límites definidos en sus instrucciones mediante la prueba de solicitudes fuera del ámbito.
• Prueba de conversación multiturno: compruebe que el agente mantiene el contexto en varios intercambios y construye sobre las respuestas anteriores.
• Pruebas de invocación de herramientas: compruebe que los agentes llamen a las herramientas adecuadas en los momentos adecuados e incorporen los resultados correctamente.

Registre los resultados de las pruebas para realizar un seguimiento de las mejoras y detectar regresiones.

Implementación de agentes en el proyecto

Microsoft Foundry admite la implementación de agentes desde el portal o Visual Studio Code. La implementación guarda la configuración del agente en el proyecto Foundry para que usted pueda probar e iterar.

Implementación desde el portal de Foundry

1. Acceda al agente en el portal de Foundry
2. Comprobar que la configuración y los resultados de las pruebas son satisfactorios
3. Seleccione Guardar en la página del agente.
4. Confirma los ajustes de versión y de implementación

Implementación desde Visual Studio Code

1. Abre tu agente en AI Toolkit
2. Seleccione Guardar en Foundry para insertar los cambios de configuración.
3. Para agentes hospedados, abra el menú +Compilar en las herramientas de desarrollo y seleccione Implementar en Microsoft Foundry.
4. Seleccione la configuración del contenedor y confirme

Ambos enfoques mantienen el agente dentro del área de trabajo del proyecto donde los miembros del equipo pueden acceder a él y probarlo.

Publicación de agentes en un punto de conexión

La publicación mueve un agente del área de trabajo del proyecto a un recurso de Azure administrado denominado aplicación de agente. Este paso permite que el agente pueda ser llamado externamente a través de un punto de conexión estable.

Qué crea la publicación

Al publicar una versión del agente, Foundry crea:

• Aplicación de Agente - un recurso de Azure con su URL de invocación propia, directiva de autenticación e identidad del agente Entra.
• Implementación : una instancia en ejecución de una versión específica del agente dentro de la aplicación, con la administración del ciclo de vida de inicio y detención.

La diferencia clave entre la implementación y la publicación es el ámbito. La implementación mantiene el agente dentro del proyecto. La publicación crea un punto de conexión dedicado al que los consumidores externos pueden llamar sin necesidad de acceso a su proyecto de Foundry.

Publicación desde el portal de Foundry

1. En el portal, seleccione la versión del agente que desea publicar.
2. Seleccione Publicar para crear la aplicación del agente y la implementación.

Publicación desde Visual Studio Code

1. Abra la paleta de comandos (Ctrl+Mayús+P) y ejecute Microsoft Foundry: Implementar agente hospedado para agentes hospedados.
2. Selección del área de trabajo de destino y la configuración del contenedor
3. Confirmación e implementación

Después de la publicación, el agente aparece en la sección Agentes hospedados (versión preliminar) del árbol de vista de la extensión AI Toolkit.

El punto de conexión de la aplicación del agente

Los agentes publicados exponen un punto de conexión estable utilizando el protocolo API de Respuestas.

https://<foundry-resource-name>.services.ai.azure.com/api/projects/<project-name>/applications/<app-name>/protocols/openai/responses

Esta dirección URL permanece igual incluso al implementar nuevas versiones del agente, por lo que los consumidores posteriores no se ven interrumpidos por las actualizaciones.

Autenticación e identidad

Las aplicaciones del agente usan el identificador de Microsoft Entra para la autenticación. Los llamantes deben tener el rol Usuario de Azure AI en el recurso Aplicación de Agente. La autenticación de clave de API no se admite para las aplicaciones del agente.

Verificación del punto de conexión

Después de publicar, compruebe que el punto de conexión funciona:

1. Obtener un token de acceso:

   az account get-access-token --resource https://ai.azure.com
   

2. Llame al punto de conexión de la aplicación del agente:

   curl -X POST \
     "https://<foundry-resource-name>.services.ai.azure.com/api/projects/<project-name>/applications/<app-name>/protocols/openai/responses?api-version=2025-11-15-preview" \
     -H "Authorization: Bearer <access-token>" \
     -H "Content-Type: application/json" \
     -d '{"input":"Say hello"}'
   

Si recibe 403 Forbidden, confirme que el autor de la llamada tiene el rol de usuario de Azure AI en el recurso Aplicación del agente.

Actualización de agentes publicados

Para implementar una nueva versión del agente:

1. Realizar cambios en el entorno de desarrollo y probar exhaustivamente
2. En el portal de Foundry, seleccione Publicar actualizaciones en el área de juegos del agente.
3. La aplicación del agente enruta automáticamente 100% de tráfico a la nueva versión.

La dirección URL del punto de conexión permanece sin cambios, por lo que las integraciones existentes siguen funcionando.

Generación de código de integración

La extensión de VS Code de Microsoft Foundry genera código de integración de ejemplo para conectar la aplicación a un agente publicado:

1. Seleccione el agente implementado en la vista Mis recursos.
2. Seleccionar Ver código
3. Elección de la carpeta
4. La extensión genera código para autenticar, conectar, enviar mensajes y procesar respuestas.

Patrones de integración

Entre los patrones comunes para integrar agentes publicados se incluyen:

• Aplicaciones web : envíe mensajes de usuario al punto de conexión de la API de respuestas y muestre las respuestas en la interfaz de usuario. Almacene el historial de conversaciones del lado del cliente para las interacciones de varios turnos.
• Flujos de trabajo controlados por API - Llamar al punto de conexión del agente desde servicios de backend desencadenados por eventos o horarios. Procese las respuestas de forma programática para impulsar acciones posteriores.
• Interfaces de chatbot - Mapear sesiones de usuario a conversaciones. Controle el intercambio de mensajes en tiempo real a través del punto de conexión.
• Automatización en segundo plano : programe llamadas de agente para tareas periódicas. Proporcionar datos del sistema a agentes y procesar salidas para actualizar los sistemas empresariales.

Consideraciones de producción

La ejecución de agentes en producción requiere que se preste atención a varias áreas operativas:

• Supervisión : realice un seguimiento de los tiempos de respuesta, las tasas de éxito de invocación de herramientas, los patrones de error y el consumo de tokens mediante la integración de Application Insights.
• Seguridad: use identidades administradas para la autenticación, aplique el acceso con privilegios mínimos y defina directivas de retención de datos.
• Administración de costos : supervise el uso de tokens, establezca los límites de longitud de respuesta e implemente la limitación de velocidad para evitar picos inesperados.
• Control de errores : implemente la lógica de reintento con retroceso exponencial para errores transitorios. Controle la limitación de velocidad con estrategias de retroceso. Valide los datos de entrada antes de enviarlos a los agentes.
• Administración de conversaciones : los puntos de conexión de aplicación del agente solo admiten actualmente la API de respuestas sin estado. Almacene el historial de conversaciones en su cliente para experiencias de múltiples turnos.