AG-UI: een lichtgewicht protocol voor interactie tussen agent en gebruiker

Waarom agentische apps AG-UI nodig hebben

Voordat we naar de code kijken, leg ik uit waarom we überhaupt een nieuw protocol nodig hadden. Het komt neer op het fundamentele verschil tussen een functie en een agent.

De beperking van request/response

In traditionele webontwikkeling zijn interacties transactioneel. Je vraagt om een gebruikersprofiel en de server stuurt het terug. Het is een eenmalige uitwisseling.

Agents zijn echter onvoorspelbaar en kosten tijd. Als je een agent vraagt om "te debuggen waarom je CI-pijplijn ineens faalt na de merge van een teamgenoot", krijg je niet meteen een JSON-object terug. In plaats daarvan kan de agent:

1. De laatste 50 commitlogs van GitHub ophalen (Action).
2. Opmerken dat er een nieuwe dependency is toegevoegd zonder het lockfile te updaten (Observation).
3. Die pakketversie kruisen met bekende CVE's (Reasoning).
4. Vragen of je de merge wilt terugdraaien of vooruit wilt patchen (Human-in-the-loop).

Ik leg dit later uit in de sectie "Eventtypes", maar weet voor nu dat een standaard HTTP-verzoek zou time-outen terwijl dit allemaal gebeurt. Je hebt een manier nodig om deze gedeeltelijke updates te streamen, zodat de gebruiker niet naar een bevroren scherm staart.

De specifieke behoeften van agents

Agents hebben een bidirectionele informatiestroom nodig die verder gaat dan tekst. Ze moeten de State synchroniseren.

Stel je een agent voor die je helpt een rapport te schrijven. Het is niet alleen chatten; het is een document bewerken. Jij en de agent kunnen tegelijk typen. AG-UI behandelt dit door het "document" als gedeelde state te zien, met efficiënte updates om je scherm en het geheugen van de agent synchroon te houden zonder elkaars werk te overschrijven.

Hoe agents en UI's communiceren

AG-UI vervangt het oude Remote Procedure Call (RPC)-model door een Event-Sourcing-model. In plaats van te wachten op een definitief antwoord, stuurt de agent een gestage stroom events die beschrijven wat hij doet.

De eventstroom

Zie de AG-UI-stroom als een nieuwsticker voor het brein van je agent. De clientapplicatie (je frontend) abonneert zich op deze ticker en werkt de UI bij op basis van wat hij ziet. Deze aanpak ontkoppelt de logica: je React-frontend hoeft niet te weten hoe de agent denkt, alleen wat hij moet tonen.

AG-UI vermijdt de wachtrij. Afbeelding door de auteur.

Kern-eventtypes

Het protocol definieert standaard eventtypes die bijna elk interactiescenario afdekken. Dit zijn de belangrijkste die je zult zien:

1. TEXT_MESSAGE_*: Events die gegenereerde tekst stuk voor stuk streamen. Dit bestaat typisch uit _START, _CONTENT (de tokenstroom) en _END-events, die samen het bekende "typ"-effect creëren.

2. TOOL_CALL: Signaleert dat de agent iets wil doen, zoals het weer checken of een database bevragen. Cruciaal: AG-UI kan de argumenten van de toolaanroep streamen, zodat je UI formulieren kan vooraf invullen nog vóór de agent klaar is met "praten".

3.  STATE_DELTA: Dit is de krachtpatser voor samenwerking. In plaats van telkens het hele document te versturen als er een letter verandert, stuurt de agent een kleine "diff" (zoals "voeg 'hallo' toe op index 5").

4. INTERRUPT: De veiligheidsklep. Als een agent een gevoelige actie raakt (zoals "Database verwijderen"), zendt hij een interrupt-event uit. De flow pauzeert totdat de gebruiker een goedkeurings-event terugstuurt.

Multimodaliteit en denkstappen

Het protocol is niet beperkt tot tekst. Het ondersteunt multimodaliteit, waarmee ik bedoel: beelden, audio en bestandsbijlagen streamen naast het gesprek. Het standaardiseert ook denkstappen door de interne gedachten van de agent (reasoning traces) te scheiden van het uiteindelijke publieke antwoord. Je ziet een vergelijkbaar patroon bij tools zoals ChatGPT, waar voortgangsindicatoren of tussenstappen los staan van het eindantwoord. Dit laat je kiezen of je gebruikers de uitvoeringsvoortgang laat zien of alleen het eindresultaat.

AG-UI-bouwstenen

Nu je de flow begrijpt, bekijken we de specifieke features die AG-UI krachtig maken voor developers.

Generatieve UI

Tekst is prima, maar soms is een grafiek beter. Met generatieve UI kan een agent tijdens runtime besluiten om een UI-component te tonen in plaats van tekst.

AG-UI streamt events; A2UI definieert componenten. Afbeelding door de auteur.

Er is hier een onderscheid dat vaak verwarring geeft (ik kom hierop terug in de frameworksectie): AG-UI is het bezorgmechanisme (transportlaag) en A2UI (Agent-to-User Interface) is de UI-definitie (payload). Een agent kan een AG-UI-TOOL_CALL-event gebruiken om een A2UI-payload te vervoeren, een declaratieve JSON-boom die een UI-component beschrijft (zoals een "Aandelenkoerskaart"). Je frontend ontvangt dit en rendert de daadwerkelijke grafiek.

Gedeelde state met JSON Patch

Gedeelde state afhandelen is lastig. Als de agent elke seconde een massief contextobject van 5 MB stuurt, wordt je app tergend traag.

AG-UI lost dit op met JSON Patch (RFC 6902). Zoals ik eerder noemde over statesynchronisatie, wanneer de agent een waarde in zijn geheugen verandert, berekent hij het verschil en stuurt een STATE_DELTA-event.

[
  {
    "op": "replace",
    "path": "/user/status",
    "value": "active"
  }
]Mogelijk gemaakt door

De client ontvangt deze lichte instructie en past die toe op zijn lokale state. Deze efficiëntie maakt realtime samenwerking met agents mogelijk.

AG-UI in het protocollandschap

Misschien heb je gehoord van andere protocollen zoals MCP (Model Context Protocol). Het is belangrijk te weten waar AG-UI in de stack past, zodat je niet het verkeerde gereedschap voor de klus gebruikt.

De agentische stack

Ik zie het als een communicatie-driehoek:

1. MCP (Agent ↔ Tools): Dit verbindt de agent met de backendwereld: databases, GitHub-repo's en interne API's. Het draait om informatie verkrijgen.
2. A2A (Agent ↔ Agent): Hiermee kunnen agents met elkaar praten en taken delegeren aan subagents.
3. AG-UI (Agent ↔ Gebruiker): Dit is de "laatste kilometer". Het verbindt de intelligentie van de agent met de mens.

De Protocoldrie-eenheid die agents verbindt. Afbeelding door de auteur.

AG-UI maakt het niet uit hoe de agent de data heeft gekregen (dat is MCP's taak, zoals hierboven genoemd); het gaat hem alleen om hoe hij die data aan jou toont.

AG-UI implementeren

Laten we kijken hoe dit er in de praktijk uitziet. Developers werken doorgaans op drie manieren met AG-UI: 1) agentische apps bouwen (een frontend aan een agent koppelen), 2) integraties bouwen (een framework compatibel maken) of 3) clients bouwen (nieuwe frontends creëren). De meesten van jullie vallen in de eerste categorie.

Ik leg zo de code uit, maar begrijp eerst dat je de ruwe protocolhandlers meestal niet zelf schrijft. Bibliotheken verzorgen de verpakking. Het begrijpen van de flow is wel nodig om te debuggen.

Het eventkanaal opzetten

De meeste implementaties gebruiken Server-Sent Events (SSE) omdat ze simpel zijn, firewallvriendelijk en perfect voor eenrichtingsstreaming van server naar client. Ik hintte hier eerder op, maar SSE is de sleutel die dit protocol zo lichtgewicht maakt vergeleken met WebSockets.

In een typische setup (zoals met het Microsoft Agent Framework of CopilotKit) stelt je server een endpoint bloot dat de verbinding opwaardeert naar een stream.

Eenvoudige eventabonnementen

Hier is een conceptueel voorbeeld van hoe een frontendclient naar de stream luistert. Let op hoe we verschillende eventtypes afhandelen om de UI bij te werken.

// Connect to the AG-UI stream
const eventSource = new EventSource('/api/agent/stream');

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);

  switch (data.type) {
    case 'TEXT_MESSAGE_CONTENT':
      // Append text to the chat window
      updateChatLog(data.content);
      break;

    case 'TOOL_CALL_START':
      // Show a "Processing..." indicator or the specific tool UI
      showToolIndicator(data.tool_name);
      break;

    case 'STATE_DELTA':
      // Apply the JSON patch to our local state store
      applyPatch(localState, data.patch);
      break;

    case 'INTERRUPT':
      // Prompt the user for permission
      showApprovalModal(data.message);
      break;
  }
};Mogelijk gemaakt door

Dit patroon verbergt de complexiteit van de interne logica van de agent. Je frontend is gewoon een "speler" voor de events die de agent verstuurt.

Integraties en ecosysteemondersteuning

Je hoeft dit niet allemaal from scratch te bouwen. Het ecosysteem wordt snel volwassener, waarbij grote platforms en frameworks naar vergelijkbare eventgestuurde interactiepatronen toegroeien.

De "Gouden Driehoek" van tools

Microsoft beschrijft een "Gouden Driehoek" voor agentontwikkeling:

1. DevUI: Voor het visualiseren van het denkproces van de agent (debuggen).
2. OpenTelemetry: Voor het meten van performance en kosten.
3. AG-UI: Voor de verbinding met de gebruiker.

Ondersteunde frameworks

Het ecosysteem breidt snel uit. Naast de grote spelers groeit de ondersteuning overal:

1. Microsoft Agent Framework: Heeft native middleware voor ASP.NET Core (Microsoft.Agents.AI.Hosting.AGUI).

2. CopilotKit: Werkt als de "browser" voor AG-UI en levert een volledige React-frontend die deze events out-of-the-box kan renderen.

3. Python-ecosysteem: Frameworks zoals LangGraph, CrewAI, Mastra, Pydantic AI, Agno en LlamaIndex kunnen allemaal als AG-UI-endpoints worden blootgesteld.

4. SDK's: Terwijl TypeScript en Python dominant zijn, zijn SDK's actief of in ontwikkeling voor Kotlin, Go, Dart, Java en Rust.

Betrouwbaarheid, debuggen en security

Een rechtstreekse communicatielijn tussen een AI en een browser openen brengt risico's met zich mee. Zo houd je je applicatie veilig.

De vertrouwde frontendserver

Laat een client nooit direct verbinden met je ruwe agentruntime. Zoals ik benadrukte in de sectie "Waarom agentische apps AG-UI nodig hebben": gebruik altijd een vertrouwde frontendserver (BFF-patroon). Deze server fungeert als poortwachter. Hij voegt authenticatie, rate limiting en inputvalidatie toe voordat hij het bericht van de gebruiker aan de agent doorgeeft.

Beveiligingsoverwegingen

Prompt injection

Kwaadwillende gebruikers kunnen proberen de instructies van je agent te overschrijven via prompt injection-aanvallen. Zoals ik eerder al aangaf, moet je middleware inputs opschonen.

Ongeautoriseerde toolaanroepen

Dat een agent kan een bestand verwijderen, betekent niet dat de huidige gebruiker dat ook mag. Je vertrouwde server moet de tools die voor de agent beschikbaar zijn filteren op basis van de rechten van de gebruiker.

State-beveiliging

Omdat state wordt gedeeld via JSON-patches, wees alert op prototype pollution. Zorg dat je patchbibliotheek wijzigingen aan beschermde properties zoals __proto__ verbiedt.

Debuggen met de Dojo

Als je agent zich vreemd gedraagt, gebruik de AG-UI Dojo. Het is een testsuite waarmee je de ruwe eventstroom kunt visualiseren. Zo spoor je problemen op zoals onjuiste JSON-patches of toolaanroepen die wel vuren maar geen resultaat teruggeven.

Conclusie

We hebben de architectuur, de eventtypes en de implementatiepatronen van AG-UI behandeld.

Ik besef dat de gemiddelde solodeveloper of iemand bij een klein bedrijf niet realistisch gezien "AG-UI gaat adopteren" en ineens "de frontend van de backend loskoppelt". Dit vergt forse architectuurkeuzes, draagvlak bij meerdere teams en middelen die de meesten niet hebben.

Maar AG-UI begrijpen is waardevol, ook als je het niet implementeert. Als je agentframeworks evalueert of beslist om in-house te bouwen of een platform te gebruiken, helpt weten hoe "goede" communicatie tussen agent en UI eruitziet je om beter te oordelen. Je herkent wanneer een tool je in breekbare patronen dwingt.

Wil je dieper duiken in het bouwen van dit soort systemen? Bekijk dan onze cursussen Introduction to AI Agents en Building Scalable Agentic Systems om je skills naar het volgende niveau te brengen.