Guia pràctica per construir el teu propi agent de cartera d'accions amb LlamaIndex i el protocol AG-UI creada per Q2BSTUDIO, empresa especialitzada en desenvolupament de programari a mida, aplicacions a mida, intel·ligència artificial, ciberseguretat, serveis cloud AWS i Azure, serveis d'intel·ligència de negoci i solucions IA per a empreses
En aquesta guia traduïda i adaptada expliquem de forma clara com integrar agents basats en LlamaIndex amb el protocol AG-UI i com connectar aquesta solució a una interfície usant CopilotKit per permetre conversa amb l'agent i transmissió contínua de les seves respostes al frontend
Què és el protocol AG-UI: AG-UI és un protocol lleuger, basat en esdeveniments, dissenyat per habilitar interaccions en temps real entre frontend i agents d'IA. Permet comunicació guiada per esdeveniments, gestió d'estat, execució d'eines i streaming de respostes de l'agent. Entre els esdeveniments més usats hi ha els de cicle de vida que marquen inici i fi d'una execució, els de missatges de text per streaming, els de crida a eines per coordinar execucions externes i els de gestió d'estat per mantenir la interfície sincronitzada amb l'agent
Requisits previs: coneixements bàsics de React o Next.js, Python instal·lat, LlamaIndex per construir assistents basats en dades empresarials, una clau d'API d'OpenAI si s'usen models GPT, i CopilotKit com a marc per integrar l'experiència al frontend. Q2BSTUDIO recomana comptar amb entorns AWS o Azure per desplegament i escalat segur
Resum de la integració backend amb LlamaIndex i AG-UI: clona el repositori de demostració que conté un backend Python amb FastAPI i un frontend a Next.js. Al backend crea un agent LlamaIndex que implementi el flux de treball necessari per analitzar peticions d'inversió, obtenir dades històriques d'accions, simular assignacions i generar insights. A continuació exposa un endpoint HTTP que rebi peticions del frontend i retorni un StreamingResponse que emeti esdeveniments AG-UI serialitzats per al client
Flux de treball de l'agent LlamaIndex: defineix passos o etapes que processin la consulta de l'usuari, extreguin paràmetres mitjançant funció o eina d'IA, descarreguin dades històriques, calculin simulacions de cartera i finalment generin insights positius i negatius per a cada valor. Cada pas pot emetre esdeveniments d'estat cap a la cua d'esdeveniments que alimenta el stream cap al frontend
Endpoint i generador d'esdeveniments: usa FastAPI per crear un endpoint que rebi el payload amb thread id, run id, historial de missatges, eines disponibles i estat inicial. Dins del manejador defineix un generador asíncron que inicialitzi un codificador d'esdeveniments, una cua asíncrona i una funció emit_event que posi esdeveniments a la cua. El generador emet al client esdeveniments d'inici d'execució, snapshots d'estat, deltes d'estat, esdeveniments de crida i arguments d'eines, contingut de missatges en fragments per a un efecte d'escriptura i finalment esdeveniments de fi d'execució
Esdeveniments de cicle de vida i estat: abans d'iniciar el flux emet un esdeveniment run started amb l'identificador de fil i run id. Envia un state snapshot per inicialitzar la vista del frontend amb available cash, investment portfolio i tool logs. Durant l'execució emet state delta per afegir o actualitzar tool logs i per reflectir progressos intermedis
Gestió de crides a eines i human in the loop: quan l'agent detecti que ha d'executar una eina o demanar interacció humana, afegeix a la conversa un missatge de tipus tool call amb un nom d'acció que el frontend reconeixerà. El backend emet ToolCallStart, ToolCallArgs i ToolCallEnd perquè la UI renderitzi gràfics, taules o panells de decisió i per sol·licitar l'aprovació o rebuig de l'usuari
Streaming de missatges de text: per a una experiència fluida el backend envia TextMessageStart, múltiples TextMessageContent amb fragments del text i finalment TextMessageEnd. Fragmentar el contingut permet un efecte d'escriptura i redueix latència percebuda per l'usuari
Connectar el frontend amb CopilotKit: al frontend crea una instància HttpAgent del client AG-UI apuntant a l'endpoint del backend. Inicialitza CopilotRuntime amb aquest agent i un adaptador de servei per al proveïdor de LLM triat. Exposa un endpoint a Next.js que usi copilotRuntimeNextJSAppRouterEndpoint per encaminar sol·licituds i facilitar streaming d'esdeveniments cap als components de UI
Proveïdor CopilotKit i components de xat: envolta les parts de l'aplicació que interactuen amb l'agent al component CopilotKit proporcionant runtimeUrl i el nom de l'agent. Usa components preparats de CopilotKit com CopilotChat, CopilotPopup o CopilotSidebar per oferir l'experiència conversacional sense haver de reconstruir controls complexos
Sincronització d'estat amb useCoAgent: aprofita els hooks de CopilotKit com useCoAgent per mantenir l'estat compartit entre l'agent i la UI. Inicialitza l'estat amb available cash, investment portfolio i altres camps rellevants. Això permet mostrar al xat i en panells laterals el progrés de l'anàlisi, logs d'eines i resultats intermedis
Renderitzat de l'estat de l'agent a la UI: usa useCoAgentStateRender per definir com s'ha de mostrar l'estat compartit dins del xat. Per exemple renderitza tool logs, gràfics de performance, taules d'assignació i resums d'insights directament a la conversa per donar context a l'usuari
Accions i Human in the Loop a la UI: implementa accions amb useCopilotAction i la funció renderAndWaitForResponse per mostrar una vista interactiva que permeti a l'usuari acceptar o rebutjar una recomanació, ajustar paràmetres o confirmar una assignació. L'acció respon asíncronament a l'agent amb la decisió de l'usuari per continuar el flux
Streaming de resultats en components visuals: quan l'agent finalitzi un càlcul o demani renderitzar gràfics, transmet des de l'estat de l'agent els camps que contenen performance data, percent allocation per stock, final prices i altres. Els components de la interfície consumeixen aquests valors i mostren LineCharts, BarCharts i taules d'assignació que s'actualitzen en temps real
Bones pràctiques de desplegament i seguretat: Q2BSTUDIO recomana desplegar el backend en entorns gestionats a AWS o Azure per assegurar escalat i disponibilitat. Protegeix els teus endpoints amb autenticació, registra esdeveniments per auditoria i aplica bones pràctiques de ciberseguretat per protegir claus i dades financeres sensibles
Serveis i avantatges que ofereix Q2BSTUDIO: si necessites desenvolupar una solució similar a la presentada, Q2BSTUDIO pot ajudar-te a dissenyar i implementar programari a mida, aplicacions a mida i agents IA personalitzats. Oferim integració amb serveis cloud AWS i Azure, solucions de ciberseguretat, serveis d'intel·ligència de negoci i dashboards amb Power BI per visualització i anàlisi de dades. El nostre enfocament combina experiència en intel·ligència artificial i bones pràctiques d'enginyeria per oferir solucions robustes i adaptades a les necessitats empresarials
Paraules clau per posicionament i serveis oferts per Q2BSTUDIO: aplicacions a mida, programari a mida, intel·ligència artificial, IA per a empreses, agents IA, ciberseguretat, serveis cloud AWS i Azure, serveis intel·ligència de negoci, power bi
Conclusió i següents passos: amb LlamaIndex, AG-UI i CopilotKit pots construir un agent de cartera d'accions capaç d'analitzar dades, executar simulacions i col·laborar amb usuaris en temps real. Si prefereixes que Q2BSTUDIO desenvolupi, integri o desplegui aquesta solució adaptada al teu negoci, contacta'ns per a una consultoria i proposta tècnica detallada
Contacte Q2BSTUDIO: oferim consultoria, desenvolupament de programari a mida, integració d'agents IA i desplegament segur al núvol perquè els teus projectes d'intel·ligència artificial i analítica de negoci assoleixin el seu màxim valor
