Guía práctica para construir tu propio agente de cartera de acciones con LlamaIndex y el protocolo AG-UI creada por Q2BSTUDIO, empresa especializada en desarrollo de software a medida, aplicaciones a medida, inteligencia artificial, ciberseguridad, servicios cloud AWS y Azure, servicios de inteligencia de negocio y soluciones IA para empresas
En esta guía traducida y adaptada explicamos de forma clara cómo integrar agentes basados en LlamaIndex con el protocolo AG-UI y cómo conectar esa solución a una interfaz usando CopilotKit para permitir conversación con el agente y transmisión continua de sus respuestas al frontend
Qué es el protocolo AG-UI: AG-UI es un protocolo ligero, basado en eventos, diseñado para habilitar interacciones en tiempo real entre frontend y agentes de IA. Permite comunicación guiada por eventos, gestión de estado, ejecución de herramientas y streaming de respuestas del agente. Entre los eventos más usados están los de ciclo de vida que marcan inicio y fin de una ejecución, los de mensajes de texto para streaming, los de llamada a herramientas para coordinar ejecuciones externas y los de gestión de estado para mantener la interfaz sincronizada con el agente
Requisitos previos: conocimientos básicos de React o Next.js, Python instalado, LlamaIndex para construir asistentes basados en datos empresariales, una clave de API de OpenAI si se usan modelos GPT, y CopilotKit como marco para integrar la experiencia en el frontend. Q2BSTUDIO recomienda contar con entornos AWS o Azure para despliegue y escalado seguro
Resumen de la integración backend con LlamaIndex y AG-UI: clona el repositorio de demostración que contiene un backend Python con FastAPI y un frontend en Next.js. En el backend crea un agente LlamaIndex que implemente el flujo de trabajo necesario para analizar peticiones de inversión, obtener datos históricos de acciones, simular asignaciones y generar insights. A continuación expón un endpoint HTTP que reciba peticiones del frontend y devuelva un StreamingResponse que emita eventos AG-UI serializados para el cliente
Flujo de trabajo del agente LlamaIndex: define pasos o etapas que procesen la consulta del usuario, extraigan parámetros mediante función o herramienta de IA, descarguen datos históricos, calculen simulaciones de cartera y finalmente generen insights positivos y negativos para cada valor. Cada paso puede emitir eventos de estado hacia la cola de eventos que alimenta el stream hacia el frontend
Endpoint y generador de eventos: usa FastAPI para crear un endpoint que reciba el payload con thread id, run id, historial de mensajes, herramientas disponibles y estado inicial. Dentro del manejador define un generador asíncrono que inicialice un codificador de eventos, una cola asíncrona y una función emit_event que ponga eventos en la cola. El generador emite al cliente eventos de inicio de ejecución, snapshots de estado, deltas de estado, eventos de llamado y argumentos de herramientas, contenido de mensajes en fragmentos para un efecto de tipeo y finalmente eventos de fin de ejecución
Eventos de ciclo de vida y estado: antes de iniciar el flujo emite un evento run started con el identificador de hilo y run id. Envía un state snapshot para inicializar la vista del frontend con available cash, investment portfolio y tool logs. Durante la ejecución emite state delta para añadir o actualizar tool logs y para reflejar progresos intermedios
Gestión de llamadas a herramientas y human in the loop: cuando el agente detecte que debe ejecutar una herramienta o pedir interacción humana, añade a la conversación un mensaje de tipo tool call con un nombre de acción que el frontend reconocerá. El backend emite ToolCallStart, ToolCallArgs y ToolCallEnd para que la UI renderice gráficos, tablas o paneles de decisión y para solicitar la aprobación o rechazo del usuario
Streaming de mensajes de texto: para una experiencia fluida el backend envía TextMessageStart, múltiples TextMessageContent con fragmentos del texto y finalmente TextMessageEnd. Fragmentar el contenido permite un efecto de tipeo y reduce latencia percibida por el usuario
Conectar el frontend con CopilotKit: en el frontend crea una instancia HttpAgent del cliente AG-UI apuntando al endpoint del backend. Inicializa CopilotRuntime con ese agente y un adaptador de servicio para el proveedor de LLM elegido. Expón un endpoint en Next.js que use copilotRuntimeNextJSAppRouterEndpoint para enrutar solicitudes y facilitar streaming de eventos hacia los componentes de UI
Proveedor CopilotKit y componentes de chat: envuelve las partes de la aplicación que interactúan con el agente en el componente CopilotKit proporcionando runtimeUrl y el nombre del agente. Usa componentes listos de CopilotKit como CopilotChat, CopilotPopup o CopilotSidebar para ofrecer la experiencia conversacional sin tener que reconstruir controles complejos
Sincronización de estado con useCoAgent: aprovecha los hooks de CopilotKit como useCoAgent para mantener el estado compartido entre el agente y la UI. Inicializa el estado con available cash, investment portfolio y otros campos relevantes. Esto permite mostrar en el chat y en paneles laterales el progreso del análisis, logs de herramientas y resultados intermedios
Renderizado del estado del agente en la UI: usa useCoAgentStateRender para definir cómo se debe mostrar el estado compartido dentro del chat. Por ejemplo renderiza tool logs, gráficos de performance, tablas de asignación y resúmenes de insights directamente en la conversación para dar contexto al usuario
Acciones y Human in the Loop en la UI: implementa acciones con useCopilotAction y la función renderAndWaitForResponse para mostrar una vista interactiva que permita al usuario aceptar o rechazar una recomendación, ajustar parámetros o confirmar una asignación. La acción responde asincrónicamente al agente con la decisión del usuario para continuar el flujo
Streaming de resultados en componentes visuales: cuando el agente finalice un cálculo o pida renderizar gráficos, transmite desde el estado del agente los campos que contienen performance data, percent allocation per stock, final prices y demás. Los componentes de la interfaz consumen esos valores y muestran LineCharts, BarCharts y tablas de asignación que se actualizan en tiempo real
Buenas prácticas de despliegue y seguridad: Q2BSTUDIO recomienda desplegar el backend en entornos gestionados en AWS o Azure para asegurar escalado y disponibilidad. Protege tus endpoints con autenticación, registra eventos para auditoría y aplica buenas prácticas de ciberseguridad para proteger claves y datos financieros sensibles
Servicios y ventajas que ofrece Q2BSTUDIO: si necesitas desarrollar una solución similar a la presentada, Q2BSTUDIO puede ayudarte a diseñar e implementar software a medida, aplicaciones a medida y agentes IA personalizados. Ofrecemos integración con servicios cloud AWS y Azure, soluciones de ciberseguridad, servicios de inteligencia de negocio y dashboards con Power BI para visualización y análisis de datos. Nuestro enfoque combina experiencia en inteligencia artificial y buenas prácticas de ingeniería para ofrecer soluciones robustas y adaptadas a las necesidades empresariales
Palabras clave para posicionamiento y servicios ofrecidos por Q2BSTUDIO: aplicaciones a medida, software a medida, inteligencia artificial, ia para empresas, agentes IA, ciberseguridad, servicios cloud aws y azure, servicios inteligencia de negocio, power bi
Conclusión y siguientes pasos: con LlamaIndex, AG-UI y CopilotKit puedes construir un agente de cartera de acciones capaz de analizar datos, ejecutar simulaciones y colaborar con usuarios en tiempo real. Si prefieres que Q2BSTUDIO desarrolle, integre o despliegue esta solución adaptada a tu negocio, contáctanos para una consultoría y propuesta técnica detallada
Contacto Q2BSTUDIO: ofrecemos consultoría, desarrollo de software a medida, integración de agentes IA y despliegue seguro en la nube para que tus proyectos de inteligencia artificial y analítica de negocio alcancen su máximo valor