Este es la Parte 2 de una serie de dos artículos. Si aún no has leído la visión general de la arquitectura, te recomiendo empezar por la Parte 1 para comprender los conceptos antes de entrar en la implementación. En esta guía completa describimos paso a paso la puesta en marcha: stacks en AWS CDK, código del agente, flujo de autenticación y despliegue. Al finalizar tendrás un agente de streaming listo para producción y protegido mediante API Gateway.
Requisitos previos: cuenta de AWS con permisos adecuados, AWS CDK instalado, Python 3.11 o superior, y conocimientos básicos de CDK, API Gateway y Cognito. Esta solución se basa en tres stacks que debes desplegar en orden: Cognito Stack para la autenticación OAuth2 y emisión de JWT, Runtime Stack para el AgentCore Runtime con autorizador JWT, y API Gateway Stack para exponer un REST API con streaming habilitado. El orden es importante porque cada stack depende de salidas del anterior.
Estructura del proyecto típica: un app.py que orquesta los stacks, un stack para Cognito, otro para AgentCore Runtime, carpeta agent con el código del agente y una SPA para el frontend. El parameter resource prefix ayuda a identificar recursos en la consola.
CDK App Setup: el app principal crea primero el stack de Cognito sin backend, luego el runtime que referencia el User Pool y su cliente, y finalmente el stack de API Gateway que apunta al endpoint del runtime. Esto asegura que el User Pool exista antes de configurar el runtime y que el runtime exista antes de crear la API.
Cognito Stack: crea un User Pool configurado para inicio de sesión por email, con verificación automática de correo, y sin signup público si se desea controlar el acceso. Se configura un dominio para el Hosted UI y un cliente OAuth2 público para aplicaciones web usando authorization code grant. Las propiedades críticas son la habilitación de OPENID scope para obtener ID tokens y las URLs de callback y logout para la SPA.
AgentCore Runtime Stack: empaqueta el código del agente incluyendo dependencias y sube el artefacto a S3. Configura el runtime mediante un recurso CfnResource porque aún no hay construcciones de nivel 2 en CDK para AgentCore. La configuración del autorizador JWT usa la URL de descubrimiento OIDC de Cognito y el client id como audiencia permitida. El endpoint de invocaciones del runtime es la URL que API Gateway usará para proxy y streaming.
API Gateway Stack: crea un REST API con CORS apropiado para la SPA y un autorizador Cognito que valide tokens. La integración HTTP proxy apunta al endpoint del runtime y debe permitir tiempo suficiente para streaming prolongado. Importante: habilitar ResponseTransferMode con valor STREAM en el recurso CloudFormation subyacente mediante escape hatch, ya que la API debe transmitir la respuesta en flujo en lugar de bufferizarla. Con esto API Gateway valida el JWT, reenvía la cabecera Authorization al runtime y transmite los fragmentos de respuesta al cliente en tiempo real.
Implementación del agente: el agente debe devolver un generador asíncrono para soportar streaming. Una práctica recomendada es lazy load del agente, inicializando la instancia la primera vez y reutilizándola en invocaciones posteriores para conservar contexto y memoria de conversación. El runtime detecta el generador asíncrono y maneja el protocolo de streaming, enviando cada yield como un fragmento al cliente.
En la práctica, el agente puede usar SDKs que facilitan flujos y herramientas, pero cualquier framework que devuelva un async generator sirve. A nivel de diseño, es clave que el agente produzca datos parciales mediante yields y no construya la respuesta completa antes de devolverla.
Frontend: la SPA realiza el flujo OAuth2 contra el Hosted UI de Cognito usando authorization code grant. Tras intercambiar el código por tokens, guarda el ID token y lo envía en la cabecera Authorization con esquema Bearer cuando llama al endpoint chat expuesto por API Gateway. Para leer el stream en el navegador utiliza el reader del body y TextDecoder con stream true para manejar posibles fragmentos UTF-8 incompletos en los límites de chunk.
Despliegue: realizar bootstrap de CDK, desplegar los stacks en orden y actualizar la configuración del frontend con la URL de la API. Incluir scripts de utilidad para crear un usuario de prueba facilita las primeras pruebas. Pruebas con curl usando la opción no buffering permiten observar la respuesta incremental. Desde el frontend, iniciar sesión y enviar mensajes debe mostrar la respuesta en tiempo real.
Solución de problemas común: si el streaming llega todo de golpe, revisar que ResponseTransferMode esté en STREAM, que la integración apunte al endpoint de invocaciones y que el agente devuelva un generador asíncrono. Para errores 401 comprobar que el token sea un ID token válido, que esté en la cabecera Authorization y que la configuración del autorizador coincida con el User Pool. Para 502 verificar la URL del runtime y la correcta configuración del autorizador. Si la conexión se corta alrededor de 30 segundos, usar endpoint regional en API Gateway en lugar de edge optimized.
Optimización y buenas prácticas: lazy loading del agente para mantener estado entre invocaciones y habilitar logs para diagnosticar generación y uso de herramientas. Controlar tiempo máximo de conversación y límites de memoria del runtime para evitar reinicios inesperados. Para mayor seguridad, controlar quién puede crear usuarios y usar políticas IAM adecuadas para el role del runtime.
En Q2BSTUDIO somos expertos en el diseño y la implementación de soluciones como esta. Ofrecemos desarrollo de aplicaciones a medida y software a medida orientado a integrar agentes IA y servicios cloud. Si te interesa migrar o construir agentes IA en AWS o Azure, podemos ayudarte con la arquitectura y el despliegue completo, y con la integración en tus sistemas empresariales. Conecta los beneficios de la nube y la automatización con una consultoría especializada en servicios cloud AWS y Azure y en inteligencia artificial para empresas.
Palabras clave incluidas de forma natural para mejorar posicionamiento: aplicaciones a medida, software a medida, inteligencia artificial, ciberseguridad, servicios cloud aws y azure, servicios inteligencia de negocio, ia para empresas, agentes IA y power bi. Si necesitas una solución adaptada, desde la arquitectura hasta la puesta en producción y soporte, Q2BSTUDIO ofrece servicios completos en desarrollo, ciberseguridad y business intelligence para convertir conceptos de IA en valor real para tu empresa.
Referencias y recursos adicionales: revisar la documentación de API Gateway sobre response streaming, la guía de Cognito para OIDC y el repositorio del ejemplo para ver la estructura completa del proyecto y los scripts de despliegue. Si quieres que te acompañemos en la implementación práctica de un agente de streaming seguro y escalable, contacta con nuestro equipo y diseñaremos la solución a medida para tu caso de uso.
