AG-UI, cunoscut drept Agent-User Interaction Protocol, este un protocol open-source, bazat pe evenimente, care facilitează comunicarea în timp real între agenți AI din backend și aplicații frontend. Acesta standardizează interacțiunea agent-utilizator, permițând dezvoltatorilor să creeze aplicații interactive în care agenții AI pot colabora direct cu utilizatorii. În acest articol, vom explora pas cu pas cum să integrezi AG-UI într-un proiect, adresându-ne dezvoltatorilor interesați de construirea unor astfel de soluții.
Ce este AG-UI ?
AG-UI face parte dintr-un ecosistem mai larg de protocoale pentru agenți AI:
-
MCP (Machine-Client Protocol) conectează agenții la unelte externe.
-
A2A (Agent-to-Agent) permite comunicarea între agenți.
-
AG-UI conectează agenții la utilizatori prin intermediul aplicațiilor frontend.
Acest protocol este construit pe HTTP, folosind Server-Sent Events (SSE) și webhooks, și suportă funcționalități esențiale pentru aplicații AI interactive:
-
Actualizări în timp real.
-
Gestionarea stării partajate (shared mutable state) prin diferențe structurate.
-
Controlul concurenței și securitate, inclusiv suport CORS și autentificare.
AG-UI este compatibil cu framework-uri precum LangGraph, CrewAI, Mastra și AG2, fiind ușor de integrat cu backend-uri AI precum OpenAI, Ollama sau cod personalizat.
Pasul 1: Înțelege arhitectura AG-UI
AG-UI funcționează ca un pod bidirecțional între backend-ul agentului AI și frontend-ul aplicației tale. Procesul de bază este următorul:
-
Frontend-ul trimite o cerere POST către endpoint-ul agentului.
-
Agentul emite un flux de evenimente în timp real, pe care frontend-ul le ascultă.
-
Fiecare eveniment are un tip specific (de exemplu, TEXT_MESSAGE_CONTENT, TOOL_CALL_START, STATE_DELTA) și un payload minim.
-
Frontend-ul reacționează la aceste evenimente și poate emite, la rândul său, evenimente sau contexte înapoi către agent.
Această arhitectură permite agenților să reacționeze dinamic la acțiunile utilizatorului, iar utilizatorilor să interacționeze cu agenții în timp real.
Pasul 2: Configurează mediul de lucru
Pentru a începe, ai nevoie de:
-
Un backend AI compatibil (de exemplu, LangGraph, OpenAI sau Ollama).
-
Un frontend construit cu un framework precum React (CopilotKit oferă componente React predefinite).
-
Node.js sau Python instalat pentru a folosi SDK-urile AG-UI.
Instalează dependințele
Dacă folosești TypeScript/JavaScript:
bash
npm install @copilotkit/ag-uiPentru Python:
bash
pip install ag-uiConfigurează un agent simplu
Să presupunem că ai un agent care generează text, construit cu LangGraph. Configurează-l să emită evenimente compatibile cu AG-UI. De exemplu, un agent care răspunde la cereri de text poate emite un eveniment de tip TEXT_MESSAGE_CONTENT.
python
from ag_ui import emit_event
def text_generation_agent(user_input):
response = "Răspuns generat pentru: " + user_input
emit_event(event_type="TEXT_MESSAGE_CONTENT", payload={"content": response})
return responsePasul 3: Configurează comunicarea HTTP/SSE
AG-UI folosește HTTP pentru a iniția comunicarea și SSE pentru a menține un flux de evenimente în timp real. Configurează un endpoint în backend-ul tău care să gestioneze cererile POST și să emită evenimente.
Creează un endpoint SSE
Într-un server Node.js cu Express:
javascript
const express = require('express');
const app = express();
app.post('/agent', (req, res) => {
res.setHeader('Content-Type', 'text/event-stream');
res.setHeader('Cache-Control', 'no-cache');
res.setHeader('Connection', 'keep-alive');
const userInput = req.body.input;
const response = textGenerationAgent(userInput);
res.write(`event: TEXT_MESSAGE_CONTENT\ndata: ${JSON.stringify({ content: response })}\n\n`);
res.end();
});
app.listen(3000, () => console.log('Server pornit pe port 3000'));Acest endpoint primește cererea POST, procesează input-ul utilizatorului și emite un eveniment SSE cu tipul TEXT_MESSAGE_CONTENT.
Pasul 4: Integrează AG-UI în frontend
În frontend, vei asculta fluxul de evenimente emis de backend și vei afișa răspunsurile utilizatorului. Folosind biblioteca @copilotkit/ag-ui, procesul este simplificat.
Configurează un client AG-UI
javascript
import { AgUiClient } from '@copilotkit/ag-ui';
import { useEffect, useState } from 'react';
function App() {
const [messages, setMessages] = useState([]);
useEffect(() => {
const client = new AgUiClient({
endpoint: 'http://localhost:3000/agent',
});
client.onEvent((event) => {
if (event.type === 'TEXT_MESSAGE_CONTENT') {
setMessages((prev) => [...prev, event.payload.content]);
}
});
client.start();
}, []);
const sendMessage = async (input) => {
await fetch('http://localhost:3000/agent', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ input }),
});
};
return (
<div>
<div>
{messages.map((msg, index) => (
<p key={index}>{msg}</p>
))}
</div>
<input
type="text"
onKeyDown={(e) => {
if (e.key === 'Enter') {
sendMessage(e.target.value);
e.target.value = '';
}
}}
placeholder="Trimite un mesaj..."
/>
</div>
);
}
export default App;Acest cod:
-
Creează un client AG-UI care se conectează la endpoint-ul /agent.
-
Ascultă evenimentele emise de backend și actualizează starea aplicației.
-
Permite utilizatorului să trimită mesaje prin intermediul unui input.
Pasul 5: Adaugă funcționalități avansate
AG-UI suportă mai multe tipuri de evenimente și funcționalități avansate. Iată câteva exemple:
Gestionarea stării partajate
Dacă agentul și utilizatorul lucrează pe un obiect comun (de exemplu, un tabel de date), AG-UI permite trimiterea de diferențe structurate (STATE_DELTA) în loc de obiectul complet.
javascript
// Backend emite o modificare a stării
res.write(`event: STATE_DELTA\ndata: ${JSON.stringify({ path: "table.row1", value: "noua valoare" })}\n\n`);
// Frontend actualizează starea
client.onEvent((event) => {
if (event.type === 'STATE_DELTA') {
updateTable(event.payload.path, event.payload.value);
}
});Controlul concurenței
AG-UI gestionează situațiile în care utilizatorul trimite mai multe cereri simultan sau anulează o acțiune. Fiecare cerere poate avea un ID unic de sesiune pentru a urmări starea.
javascript
// Adaugă un ID de sesiune la cerere
await fetch('http://localhost:3000/agent', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ input, sessionId: '123' }),
});Pasul 6: Testează și optimizează
Testează aplicația pentru a verifica:
-
Dacă evenimentele sunt emise și recepționate corect.
-
Dacă starea partajată se actualizează fără erori.
-
Dacă securitatea (CORS, autentificare) este configurată corect.
AG-UI oferă un playground interactiv la docs.ag-ui.com, unde poți experimenta cu evenimentele și configurațiile.
Pasul 7: Extinde integrarea
AG-UI este compatibil cu mai multe framework-uri și backend-uri. Poți:
-
Integra cu LangGraph pentru a construi agenți multi-pas.
-
Folosi Mastra pentru a adăuga confirmări utilizator înainte de executarea codului.
-
Combina cu AG2 pentru orchestrarea mai multor agenți.
Explorează documentația oficială și comunitatea de pe GitHub (ag-ui-protocol/ag-ui) pentru a contribui sau a solicita suport pentru noi framework-uri.
Concluzie
AG-UI simplifică dezvoltarea aplicațiilor interactive cu agenți AI, oferind un protocol standardizat pentru comunicarea agent-utilizator. Prin configurarea unui backend care emite evenimente și a unui frontend care le procesează, poți construi aplicații în care agenții AI colaborează în timp real cu utilizatorii. Urmează pașii de mai sus pentru a integra AG-UI în proiectul tău și explorează documentația pentru a descoperi toate posibilitățile pe care le oferă acest protocol.
