Prueba, implementación e integración de agentes

  • 9 minutos

Sugerencia

Consulte la pestaña Texto e imágenes para obtener más detalles.

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. Abra el agente en Foundry 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. Elija un método de implementación:
    • Código (ZIP Code Deploy) - empaqueta el código fuente e implementa directamente sin una imagen de contenedor
    • Contenedor (BYOI): implementación mediante una imagen de contenedor pregenerada desde Azure Container Registry
  5. Seleccione su modelo 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

Al crear un agente en Microsoft Foundry, recibe un punto de conexión estable, su propia identidad de agente de Entra y un plano del agente automáticamente. Publicar se refiere a la distribución del agente para que los consumidores externos y las aplicaciones (incluidos Microsoft Teams y Microsoft 365 Copilot) puedan llamarlo.

Qué incluye cada agente

Todos los agentes creados en Foundry se aprovisionan con:

  • Punto de conexión estable : una dirección URL de invocación lista para producción que permanece constante incluso cuando se actualizan las versiones del agente.
  • Identidad del agente de Entra - una identidad de Microsoft Entra dedicada con su propio ámbito de RBAC, independiente de la identidad compartida del proyecto.
  • Directiva de autenticación - autenticación integrada de Microsoft Entra ID. Las personas que llaman deben tener el rol Foundry User en el recurso del agente. No se admite la autenticación de clave de API.

Importante

Cada agente recibe su propia identidad de Entra dedicada. Los permisos no se transfieren automáticamente desde la identidad de proyecto. Debe asignar roles de RBAC a la identidad del agente para los recursos a los que accede el agente. Si omite este paso, las llamadas a herramientas que funcionan durante el desarrollo producen errores de autorización una vez publicado el agente.

Publicación en Microsoft Teams y Microsoft 365 Copilot

En el portal de Foundry, puede publicar agentes en Microsoft Teams y Microsoft 365 Copilot con un solo paso, no es necesario volver a generar. El agente se desplaza a través de un flujo unificado hacia las aplicaciones en las que los usuarios ya trabajan.

El extremo del agente

Los agentes exponen un punto de conexión estable mediante el protocolo de API de respuestas:

https://<foundry-resource-name>.services.ai.azure.com/api/projects/<project-name>/agents/<agent-name>/endpoint/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.

Verificación del punto de conexión

Después de crear y configurar el agente, 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 del agente:

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

Si recibe 403 Forbidden, confirme que la persona que llama tiene el rol Foundry User en el recurso del agente.

Actualizando agentes

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, guarde la configuración del agente actualizada.
  3. El punto de conexión enruta automáticamente el 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

Foundry Toolkit for VS Code 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 : actualmente, los puntos de conexión del agente solo admiten la API de respuestas sin estado. Almacene el historial de conversaciones en su cliente para experiencias de múltiples turnos.