AG-UI: Ein leichtes Protokoll für die Interaktion zwischen Agenten und Benutzern

Warum Agentische Apps AG-UI brauchen

Bevor wir uns den Code anschauen, lass mich kurz erklären, warum wir überhaupt ein neues Protokoll gebraucht haben. Es geht um den grundlegenden Unterschied zwischen einer Funktion und einem Akteur.

Die Begrenzung von Anfrage/Antwort

Bei der klassischen Webentwicklung sind Interaktionen transaktional. Du fragst nach einem Benutzerprofil, und der Server schickt es dir. Das ist ein einmaliger Tausch.

Agenten sind aber unberechenbar und brauchen Zeit. Wenn du einen Agenten bittest, „zu debuggen, warum deine CI-Pipeline nach dem Merge eines Teamkollegen plötzlich nicht mehr funktioniert“, gibt er nicht sofort ein JSON-Objekt zurück. Stattdessen könnte es sein, dass:

1. Hol die letzten 50 Commit-Protokolle von GitHub (Aktion).
2. Beachte, dass eine neue Abhängigkeit hinzugefügt wurde, ohne dass die Sperrdatei aktualisiert wurde (Beobachtung).
3. Vergleiche diese Paketversion mit bekannten CVEs (Begründung).
4. Frag, ob du die Zusammenführung rückgängig machen oder nach vorne patchen willst (Human-in-the-loop).

Ich erkläre das später im Abschnitt „Ereignistypen“, aber fürs Erste reicht es zu wissen, dass eine normale HTTP-Anfrage während des Wartens auf all diese Vorgänge eine Zeitüberschreitung verursachen würde. Du musst diese Teilaktualisierungen irgendwie streamen, damit der Nutzer nicht auf einen eingefrorenen Bildschirm starren muss.

Die besonderen Bedürfnisse von Agenten

Agenten brauchen einen bidirektionalen Informationsfluss, der über Text hinausgeht. Sie müssen den Staat synchronisieren.

Stell dir vor, ein Agent hilft dir beim Schreiben eines Berichts. Es geht nicht nur ums Chatten, sondern auch ums Bearbeiten von Dokumenten. Du und der Agent könntet gleichzeitig tippen. AG-UI macht das, indem es das „Dokument” wie einen gemeinsamen Status behandelt und mit effizienten Updates dafür sorgt, dass dein Bildschirm und der Speicher des Agenten synchron bleiben, ohne dass sie sich gegenseitig überschreiben.

Wie Agenten und Benutzeroberflächen miteinander reden

AG-UI ersetzt das alte Remote Procedure Call (RPC)-Modell durch ein Event-Sourcing-Modell. Anstatt auf eine endgültige Antwort zu warten, schickt der Agent ständig Infos raus, die beschreiben, was er gerade macht.

Der Event-Stream

Stell dir den AG-UI-Stream wie einen Nachrichtenticker für das Gehirn deines Agenten vor. Die Client-App (dein Frontend) abonniert diesen Ticker und aktualisiert die Benutzeroberfläche nach dem, was sie sieht. Dieser Ansatz trennt die Logik: Dein React-Frontend muss nicht wissen, wie der Agent denkt, sondern nur, was angezeigt werden soll.

AG-UI macht Schluss mit Wartezeiten. Bild vom Autor.

Kernereignistypen

Das Protokoll legt Standardereignistypen fest, die fast jedes Interaktionsszenario abdecken. Hier sind die wichtigsten, die du sehen wirst:

1. TEXT_MESSAGE_*: Ereignisse, die Text Stück für Stück generieren. Dazu gehören normalerweise die Ereignisse „ _START ”, „ _CONTENT ” (der Token-Stream) und „ _END ”, die zusammen den bekannten „Tipp”-Effekt erzeugen.

2. TOOL_CALL: Zeigt an, dass der Agent was machen will, wie zum Beispiel das Wetter checken oder eine Datenbank abfragen. Das Wichtigste ist, dass AG-UI die„ “-Argumente des Tool-Aufrufs streamen kann, sodass deine Benutzeroberfläche Formulare schon ausfüllen kann, bevor der Agent überhaupt fertig „gesprochen“ hat.

3.  STATE_DELTA: Das ist der Kraftprotz für die Zusammenarbeit. Anstatt jedes Mal, wenn sich ein Buchstabe ändert, das ganze Dokument neu zu schicken, schickt der Agent nur eine kleine „Diff“-Datei (z. B. „add 'hello' at index 5“).

4. INTERRUPT: Das Sicherheitsventil. Wenn ein Agent eine heikle Aktion ausführt (wie „Datenbank löschen“), löst er ein Unterbrechungsereignis aus. Der Ablauf wird angehalten, bis der Benutzer ein Genehmigungsereignis zurücksendet.

Multimodalität und Denkprozesse

Das Protokoll ist nicht nur auf Text beschränkt. Es kann mit mehreren Medien umgehen, also Bilder, Audio und Dateianhänge neben der Unterhaltung streamen. Außerdem werden die Denkprozesse standardisiert, indem die internen Gedanken des Agenten (Denkverläufe) von der endgültigen öffentlichen Antwort getrennt werden. Vielleicht ist dir bei der Nutzung von Tools wie chatGPT schon mal aufgefallen, dass Fortschrittsanzeigen oder Zwischenschritte separat von der endgültigen Antwort angezeigt werden. Damit kannst du entscheiden, ob du den Benutzern den Fortschritt der Ausführung oder einfach nur das Endergebnis zeigen willst.

AG-UI-Bausteine

Jetzt, wo du den Ablauf verstehst, schauen wir uns die spezifischen Funktionen an, die AG-UI für Entwickler so leistungsstark machen.

Generative Benutzeroberfläche

Text ist super, aber manchmal ist ein Diagramm besser. Mit generativer Benutzeroberfläche kann ein Agent während der Laufzeit entscheiden, dass er dir eine UI-Komponente statt Text zeigen soll.

AG-UI überträgt Ereignisse; A2UI definiert Komponenten. Bild vom Autor.

Hier gibt's einen Unterschied, der viele Leute verwirrt (ich komm im Abschnitt über das Rahmenwerk noch mal drauf zurück): AG-UI ist der Liefermechanismus (Transportschicht) und A2UI (Agent-to-User Interface) ist die UI-Definition (Nutzlast). Ein Agent kann ein AG-UI-Ereignis „ TOOL_CALL “ nutzen, um eine A2UI-Nutzlast zu transportieren, also einen deklarativen JSON-Baum, der eine UI-Komponente (wie eine „Aktienkurskarte“) beschreibt. Dein Frontend kriegt das und rendert das eigentliche Diagramm.

Gemeinsamer Status mit JSON Patch

Der Umgang mit gemeinsam genutzten Zuständen ist knifflig. Wenn der Agent jede Sekunde ein riesiges 5-MB-Kontextobjekt schickt, wird deine App total langsam.

AG-UI machtdas mit JSON Patch (RFC 6902). Wie ichschon bei der Zustandsynchronisation gesagt habe: Wenn der Agent einen Wert in seinem Speicher ändert, berechnet er die Differenz und schickt ein „STATE_DELTA “-Ereignis.

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

Der Client kriegt diese einfache Anweisung und wendet sie auf seinen lokalen Status an. Diese Effizienz macht die Zusammenarbeit mit den Agenten in Echtzeit möglich.

AG-UI in der Protokoll-Landschaft

Du hast vielleicht schon von anderen Protokollen wie MCP (Model Context Protocol) gehört. Es ist wichtig zu wissen, wo AG-UI in der Struktur hingehört, damit du nicht das falsche Tool für die Aufgabe verwendest.

Der agenzielle Stapel

Ich sehe das gerne als Kommunikationsdreieck:

1. MCP (Agent ↔ Tools): Das verbindet den Agenten mit der Backend-Welt: Datenbanken, GitHub-Repositorys und interne APIs. Es geht darum, Infos zu kriegen.
2. A2A (Agent ↔ Agent): So können Agenten miteinander quatschen und Aufgaben an Subagenten weitergeben.
3. AG-UI (Agent ↔ Benutzer): Das ist die „letzte Meile“. Es verbindet die Intelligenz des Agenten mit dem menschlichen Nutzer.

Das Protokoll Trinity verbindet Agenten. Bild vom Autor.

AG-UI interessiert sich nicht dafür, wie der Agent an die Daten gekommen ist (das ist, wie oben erwähnt, Aufgabe von MCP); es geht nur darum, wie diese Daten dir angezeigt werden sollen.

AG-UI einrichten

Schauen wir mal, wie das in der Praxis aussieht. Entwickler arbeiten mit AG-UI meistens auf drei Arten zusammen: Sie bauen 1) Agentic Apps (verbinden ein Frontend mit einem Agenten), 2) Integrationen (machen ein Framework kompatibel) oder 3) Clients (entwerfen neue Frontends). Die meisten von euch werden in die erste Kategorie fallen.

Ich erkläre dir gleich den Code, aber denk dran, dass du die Raw-Protokoll-Handler normalerweise nicht selbst schreibst. Bibliotheken kümmern sich um die Verpackung. Aber um Fehler zu finden, muss man den Ablauf verstehen.

Den Event-Kanal einrichten

Die meisten Implementierungen nutzen Server-Sent Events (SSE), weil sie einfach, firewallfreundlich und perfekt für einseitiges Streaming vom Server zum Client sind. Ich hab's schon mal angedeutet, aber SSE ist der Grund, warum dieses Protokoll im Vergleich zu WebSockets so schlank ist.

In einer typischen Konfiguration (wie beim Microsoft Agent Framework oder CopilotKit) stellt dein Server einen Endpunkt bereit, der die Verbindung zu einem Stream aufwertet.

Einfaches Abonnieren von Events

Hier ist ein Beispiel, wie ein Frontend-Client den Stream abhört. Schau dir an, wie wir verschiedene Ereignistypen verarbeiten, um die Benutzeroberfläche zu aktualisieren.

// 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;
  }
};

Dieses Muster macht die Komplexität der internen Logik des Agenten unsichtbar. Dein Frontend ist nur ein „Player“ für die Events, die der Agent verschickt.

Integrationen und Unterstützung des Ökosystems

Du musst das alles nicht von Grund auf neu aufbauen. Das Ökosystem entwickelt sich schnell weiter, und die großen Plattformen und Frameworks kommen sich mit ähnlichen ereignisgesteuerten Interaktionsmustern immer näher.

Das „Goldene Dreieck“ der Tools

Microsoft redet von einem „Goldenen Dreieck“ für die Entwicklung von Agenten:

1. DevUI: Um zu sehen, wie der Agent denkt (Debugging).
2. OpenTelemetry: Zur Messung von Leistung und Kosten.
3. AG-UI: Zum Verbinden mit dem Benutzer.

Unterstützte Frameworks

Das Ökosystem wächst echt schnell. Abgesehen von den großen Akteuren wächst die Unterstützung überall:

1. Microsoft Agent Framework: Hat native Middleware für ASP.NET Core (Microsoft.Agents.AI.Hosting.AGUI).

2. CopilotKit: Fungiert als „Browser“ für AG-UI und bietet ein komplettes React-Frontend, das diese Ereignisse sofort rendern kann.

3. Python Ecosystem: Framewer wie LangGraph, CrewAI, Mastra, Pydantic AI, Agno und LlamaIndex können alle als AG-UI-Endpunkte genutzt werden.

4. SDKs: Während JavaScript, TypeScript und Python die gängigsten Sprachen sind, gibt's SDKs für Kotlin, Go, Dart, Java undRust, die entweder schon laufen oder gerade entwickelt werden.

Zuverlässigkeit, Fehlerbehebung und Sicherheit

Eine direkte Verbindung zwischen einer KI und einem Browser aufzubauen, bringt Risiken mit sich. Hier erfährst du, wie du deine Anwendung sicher halten kannst.

Der vertrauenswürdige Frontend-Server

Lass niemals einen Kunden direkt mit deiner Raw-Agent-Laufzeitumgebung verbinden. Wie ich im Abschnitt „Warum Agentic Apps AG-UI brauchen“ gesagt habe, solltest du immer einen Trusted Frontend Server (BFF-Muster) nutzen. Dieser Server ist wie ein Torwächter. Es fügt Authentifizierung, Ratenbegrenzung und Eingabevalidierung hinzu, bevor die Nachricht des Benutzers an den Agenten weitergeleitet wird.

Sicherheitsüberlegungen

Sofortige Injektion

Böswillige Nutzer könnten versuchen, die Anweisungen deines Agentendurch Prompt-Injection-Angriffezu umgehen. Wie ichschon gesagt habe, sollte deine Middleware Eingaben bereinigen.

Nicht genehmigte Tool-Aufrufe

Nur weil ein Agent eine Datei löschen kann, heißt das nicht, dass der aktuelle Benutzer dasauch darf. Dein vertrauenswürdiger Server muss die Tools, die dem Agenten zur Verfügung stehen, nach den Berechtigungen des Benutzers filtern.

Staatssicherheit

Da der Status über JSON-Patches geteilt wird, pass auf, dass es nicht zu Prototyp-Verschmutzung kommt. Stell sicher, dass deine Patching-Bibliothek Änderungen an geschützten Eigenschaften wie „ __proto__ “ nicht zulässt.

Debuggen mit dem Dojo

Wenn dein Agent sich komisch verhält, probiermal das AG-UI Dojoaus. Es ist eine Test-Su-Seite, mit der du den rohen Ereignisstrom sehen kannst. Es hilft dir dabei, Probleme wie fehlerhafte JSON-Patches oder Tool-Aufrufe zu erkennen, die zwar ausgelöst werden, aber keine Ergebnisse liefern.

Fazit

Wir haben die Architektur, die Ereignistypen und die Implementierungsmuster von AG-UI behandelt.

Ich weiß, dass der durchschnittliche Solo-Entwickler oder jemand in einem kleinen Unternehmen realistisch gesehen nicht einfach „AG-UI übernehmen” und plötzlich „sein Frontend vom Backend trennen” wird. All das würde große architektonische Entscheidungen, die Zustimmung mehrerer Teams und Ressourcen erfordern, die die meisten Leute nicht haben.

Aber es ist wichtig, AG-UI zu verstehen, auch wenn du es nicht einsetzt. Wenn du Agent-Frameworks checkst oder überlegst, ob du was selbst entwickeln oder eine Plattform nutzen willst, hilft es dir, zu wissen, wie eine „gute“ Kommunikation zwischen Agent und Benutzeroberfläche aussieht, um eine bessere Entscheidung zu treffen. Du merkst, wenn ein Tool dich in starre Muster zwingt.

Wenn du dich näher mit der Entwicklung dieser Systeme beschäftigen möchtest, schau dir unsere Kurse „Einführung in KI-Agenten“ und „Entwicklung skalierbarer agentenbasierter Systeme“ an, um deine Fähigkeiten auf die nächste Stufe zu heben.