En esta guía práctica aprenderás a integrar agentes Agno con el protocolo AG-UI y a conectar esa integración con una interfaz web usando CopilotKit para chatear con el agente y transmitir sus respuestas en tiempo real
Presentamos los puntos clave que cubriremos en este artículo: qué es el protocolo AG-UI, cómo integrar agentes Agno con AG-UI y cómo añadir un frontend con CopilotKit para recibir respuestas en streaming y soportar puntos de intervención humana
Resumen conceptual del protocolo AG-UI: AG-UI es un protocolo ligero y basado en eventos diseñado para facilitar la interacción en tiempo real entre frontends y agentes de IA. Permite transmitir mensajes de texto de forma incremental, notificar el inicio y el fin de ejecuciones, gestionar llamadas a herramientas y sincronizar el estado entre cliente y agente
Eventos centrales del protocolo AG-UI: eventos de ciclo de vida como RUN_STARTED y RUN_FINISHED; eventos de texto para streaming como TEXT_MESSAGE_START, TEXT_MESSAGE_CONTENT y TEXT_MESSAGE_END; eventos para llamadas a herramientas como TOOL_CALL_START, TOOL_CALL_ARGS y TOOL_CALL_END; y eventos de gestión de estado como STATE_SNAPSHOT y STATE_DELTA
Requisitos previos: conocimientos básicos de React o Next.js, Python instalado para el backend, una clave de OpenAI con acceso a modelos compatibles y las librerías Agno y CopilotKit instaladas en los proyectos correspondientes
Creación del agente Agno: diseña tu flujo de trabajo en Agno definiendo pasos claros para recibir la solicitud del usuario, extraer parámetros, obtener datos externos como históricos financieros, calcular simulaciones y generar insights. Cada paso puede emitir eventos para actualizar la interfaz mediante el callback de emisión de eventos
Endpoint backend con FastAPI: expone un endpoint HTTP que recibe la petición de ejecución del agente. En el backend crea un generador de eventos asíncrono que inicialice un codificador de eventos AG-UI, una cola de eventos y devuelva un StreamingResponse tipo text/event-stream para que el frontend pueda suscribirse y procesar los eventos en tiempo real
Generación y envío de eventos: al comenzar una ejecución envía un evento RUN_STARTED. Envía un STATE_SNAPSHOT para inicializar el estado visible en el cliente incluyendo efectivo disponible, cartera y logs. Durante la ejecución, cada paso del workflow puede invocar emit_event para encolar eventos STATE_DELTA que apliquen parches JSON y actualicen la UI incrementalmente
Integración de llamadas a herramientas y Human in the Loop: cuando el agente requiera interacción humana genera mensajes con tool_calls y emite eventos TOOL_CALL_START, TOOL_CALL_ARGS y TOOL_CALL_END de forma que el frontend pueda renderizar controles, pedir confirmación o mostrar visualizaciones. Así se habilita un flujo HITL para revisar resultados o aprobar acciones
Streaming de respuestas de texto: para respuestas verbales del asistente envía TEXT_MESSAGE_START, luego múltiples TEXT_MESSAGE_CONTENT con fragmentos del mensaje para crear un efecto de tipeo o streaming y finalmente TEXT_MESSAGE_END. Esto mejora la experiencia de conversación y permite renderizar progresos parciales
Sincronización del estado agente frontend: utiliza STATE_SNAPSHOT al inicio y STATE_DELTA para actualizaciones incrementales. En cada paso del workflow agrega registros a tool_logs y modifica campos de estado relevantes para que la UI muestre progreso, errores o resultados parciales en tiempo real
Frontend con CopilotKit: en el proyecto frontend crea un HttpAgent que apunte al endpoint FastAPI del agente Agno. Inicializa CopilotRuntime con ese agente y expone un endpoint de la aplicación que delegue en copilotRuntime para enrutar las solicitudes de chat hacia el agente backend
Proveedor CopilotKit y componentes de chat: envuelve las partes de la app que necesiten acceso al agente con el componente CopilotKit provider. Usa los componentes de UI de CopilotKit como CopilotChat, CopilotPopup o CopilotSidebar para proporcionar una experiencia conversacional lista para usar
Hooks para estado compartido y renderizado: emplea useCoAgent para mantener un estado compartido entre UI y agente y useCoAgentStateRender para representar fragmentos del estado dentro de la conversación. Esto permite mostrar tool_logs, avances de simulación y resultados directamente en el hilo del chat
Implementación de acciones frontend y retorno de resultados: registra acciones con useCopilotAction y la función renderAndWaitForResponse para renderizar visualizaciones complejas como gráficos y tablas y devolver de forma asíncrona la respuesta del usuario al agente. Así el agente puede pausar su ejecución hasta recibir la aprobación o el rechazo del humano
Streaming en la UI: liga los campos del estado compartido a componentes visuales del frontend. Por ejemplo actualiza paneles de efectivo, tablas de asignación y gráficos de rendimiento conforme llegan eventos STATE_DELTA y TEXT_MESSAGE_CONTENT para ofrecer retroalimentación inmediata al usuario
Ejemplo de flujo de trabajo simplificado: el usuario solicita analizar una inversión, el backend inicia el workflow y envía RUN_STARTED y STATE_SNAPSHOT, el agente ejecuta pasos intermedios emitiendo STATE_DELTA con logs y luego solicita al frontend renderizar gráficos mediante un tool_call. El frontend muestra la visualización y el usuario acepta o rechaza. Finalmente el agente envía el texto final en streaming y el evento RUN_FINISHED
Beneficios de esta arquitectura: respuestas más rápidas y fluidas, capacidad de intervención humana en puntos críticos, trazabilidad de las acciones del agente y una interfaz moderna que facilita la adopción por usuarios finales
Sobre Q2BSTUDIO: Q2BSTUDIO es una empresa especializada en desarrollo de software a medida y aplicaciones a medida con un enfoque en soluciones de inteligencia artificial para empresas. Nuestro equipo ofrece servicios integrales que incluyen desarrollo de software a medida, arquitectura y migración cloud con servicios cloud aws y azure, ciberseguridad para proteger entornos críticos, y soluciones de inteligencia de negocio con herramientas como power bi
Servicios que ofrecemos en Q2BSTUDIO: desarrollo de aplicaciones y software a medida, consultoría en inteligencia artificial y ia para empresas, diseño e implementación de agentes IA integrados en flujos de trabajo corporativos, servicios de ciberseguridad y gestión de riesgos, implantación de soluciones cloud en aws y azure y creación de cuadros de mando y pipelines de datos para inteligencia de negocio
Palabras clave para posicionamiento: aplicaciones a medida software a medida inteligencia artificial ciberseguridad servicios cloud aws y azure servicios inteligencia de negocio ia para empresas agentes IA power bi
Conclusión y próximos pasos: con Agno y AG-UI puedes construir agentes sofisticados que interactúen en tiempo real con usuarios y herramientas. Extender esa integración con CopilotKit permite crear frontends conversacionales potentes con soporte HITL y streaming. Si deseas ayuda para implementar una solución completa a medida o para integrar agentes IA en tus procesos corporativos, en Q2BSTUDIO podemos acompañarte desde el diseño hasta la puesta en producción
Contacto y colaboración: si quieres construir tu propio agente de cartera de acciones con Agno AG-UI y CopilotKit o necesitas una solución personalizada en inteligencia artificial ciberseguridad o servicios cloud aws y azure ponte en contacto con Q2BSTUDIO para una consultoría a medida