AG-UI-Protokoll erklärt: Der neue Standard für Mensch-Agent-Schnittstellen

AG-UI ist das offene Protokoll für Echtzeit-Streaming zwischen KI-Agenten und Frontend-UIs. So funktioniert das Ereignismodell, welche Nachrichtentypen es unterstützt und warum es für Entwickler agentischer Apps wichtig ist.

by AnyCap

AG-UI-Protokoll-Architekturdiagramm — zeigt bidirektionale Streaming-Ereignisse zwischen einem UI-Frontend und einem KI-Agenten

Da KI-Agenten inzwischen leistungsfähig genug sind, um echte Workflows zu übernehmen, ist eine neue Infrastrukturherausforderung entstanden: Wie kommunizieren Menschen und Agenten während der Ausführung — nicht nur am Anfang und am Ende, sondern durchgehend?

Das AG-UI-Protokoll ist eine offene Spezifikation, die genau dieses Problem lösen soll. Es definiert einen Standard dafür, wie KI-Agenten Ereignisse streamen, Eingaben anfordern und Statusinformationen in Echtzeit an Frontend-Anwendungen und menschliche Operatoren übermitteln. Wenn MCP (Model Context Protocol) standardisiert hat, wie Agenten auf Tools zugreifen, dann standardisiert AG-UI, wie Agenten mit Nutzern sprechen.

Dieser Leitfaden erklärt, was AG-UI ist, warum es wichtig ist, wie es funktioniert und wie du es in deinem Agent-Stack einsetzen kannst.

Das Problem, das AG-UI löst

Vor AG-UI musste jedes Team, das eine menschenzentrierte KI-Agenten-Anwendung entwickelte, sein eigenes Kommunikationsprotokoll erfinden. Wie teilt der Agent dem Frontend mit, dass er nachdenkt? Wie fordert er eine menschliche Entscheidung an? Wie sendet der Nutzer während einer laufenden Aufgabe eine Korrektur? Wie wird Fortschritt angezeigt?

Die Antworten fielen in jedem Team anders aus — oft ad hoc, schlecht dokumentiert und schwer wiederverwendbar. Dadurch entstand ein fragmentiertes Ökosystem, in dem:

  • Agenten-Frameworks keine Frontend-Komponenten teilen konnten
  • Entwickler die Streaming-UI-Infrastruktur für jedes Projekt von Grund auf neu bauen mussten
  • Nutzer in agentengestützten Produkten inkonsistente Erfahrungen bekamen
  • das Debugging des Agentenverhaltens in jeder Implementierung eigenes Logging erforderte

AG-UI etabliert ein gemeinsames Vokabular und eine gemeinsame Ereignisstruktur, sodass jedes Agenten-Framework Ereignisse erzeugen kann, die jedes AG-UI-kompatible Frontend rendern kann — ohne benutzerdefinierten Integrationscode.

Was ist AG-UI?

AG-UI ist ein offenes Streaming-Ereignisprotokoll, das Format und Semantik der Nachrichten definiert, die zwischen KI-Agenten und nutzerseitigen Oberflächen ausgetauscht werden.

Es ist:

  • transportagnostisch: funktioniert über HTTP (Server-Sent Events), WebSockets oder jeden anderen Streaming-Transport
  • frameworkagnostisch: kann in jeder Sprache und jedem Agenten-Framework implementiert werden
  • bidirektional: Agenten senden Ereignisse an das Frontend; Nutzer senden Nachrichten und Unterbrechungen an den Agenten
  • zustandsbehaftet: das Protokoll enthält Zustands-Snapshots, sodass Frontends den vollständigen Agentenkontext jederzeit rekonstruieren können

Es ist nicht:

  • ein Tool-Protokoll, das ist MCPs Aufgabe
  • selbst ein Agenten-Framework
  • eine UI-Komponentenbibliothek, auch wenn Referenzimplementierungen existieren

AG-UI vs. MCP: Den Unterschied verstehen

Eine häufige Quelle von Verwirrung ist die Beziehung zwischen AG-UI und Anthropics Model Context Protocol (MCP).

Dimension MCP AG-UI
Zweck Kommunikation Agent ↔ Tool Kommunikation Agent ↔ Mensch/Frontend
Richtung Agent ruft Tools auf und erhält Ergebnisse Agent streamt Ereignisse; Mensch sendet Nachrichten
Zielgruppe Tool-/Server-Entwickler Frontend- und Agenten-Framework-Entwickler
Fokus Welche Fähigkeiten der Agent nutzen kann Wie der Agent seinen Zustand und Fortschritt kommuniziert
Beziehung Behandelt die Tool-Seite des Agenten Behandelt die Benutzeroberflächen-Seite

Beide sind komplementär. Ein Agent im Produktiveinsatz verwendet typischerweise MCP, um auf Tools zuzugreifen, etwa Websuche, Bildgenerierung oder Codeausführung, und AG-UI, um seinen Fortschritt zu kommunizieren und menschliche Eingaben anzufordern.

Zentrale Konzepte in AG-UI

Ereignistypen

AG-UI definiert einen Standardsatz von Ereignistypen, die Agenten ausgeben:

Lifecycle-Ereignisse:

  • RUN_STARTED / RUN_FINISHED — der Agent hat die Ausführung begonnen oder abgeschlossen
  • STEP_STARTED / STEP_FINISHED — ein einzelner Schritt innerhalb des Workflows hat begonnen oder geendet
  • RUN_ERROR — der Agent ist auf einen nicht behebbaren Fehler gestoßen

Nachrichtenereignisse:

  • TEXT_MESSAGE_START / TEXT_MESSAGE_CONTENT / TEXT_MESSAGE_END — gestreamte Textausgabe des Agenten
  • TOOL_CALL_START / TOOL_CALL_ARGS / TOOL_CALL_END — der Agent ruft ein Tool auf

Zustandsereignisse:

  • STATE_SNAPSHOT — ein vollständiger Snapshot des aktuellen Agentenzustands
  • STATE_DELTA — eine inkrementelle Aktualisierung des Zustands
  • MESSAGES_SNAPSHOT — der vollständige Gesprächsverlauf zu einem bestimmten Zeitpunkt

Benutzerdefinierte Ereignisse:

  • CUSTOM — für anwendungsspezifische Ereignisse, die nicht vom Standardsatz abgedeckt werden

Die menschliche Eingriffsphase

AG-UI standardisiert auch, wie Menschen mit laufenden Agenten interagieren. Das Frontend sendet ein AgentInput, um den Agenten während der Ausführung zu unterbrechen, umzulenken oder ihm Informationen bereitzustellen. Das ist etwas anderes als ein neuer Gesprächszug — der Agent läuft bereits, und der Mensch beeinflusst seine aktuelle Aufgabe.

Thread-basierte Architektur

AG-UI organisiert Agentenläufe in Threads — persistente Gesprächskontexte, die den Zustand über mehrere Läufe hinweg erhalten. Ein Thread in AG-UI entspricht grob einer Sitzung oder Unterhaltung in anderen Frameworks, bietet aber explizite Protokollunterstützung für Fortsetzen, Verzweigen und Wiedergeben.

So funktioniert AG-UI: Ein typischer Ablauf

1. Der Nutzer sendet über das Frontend eine Aufgabe ab
2. Das Frontend sendet eine InitialRun-Anfrage mit RunAgentInput an das Agenten-Backend
3. Der Agent beginnt die Ausführung und sendet das Ereignis RUN_STARTED
4. Der Agent sendet STEP_STARTED für jeden Planungsschritt
5. Der Agent ruft ein Tool auf → sendet TOOL_CALL_START, TOOL_CALL_ARGS, TOOL_CALL_END
6. Der Agent generiert Text → sendet TEXT_MESSAGE_START, TEXT_MESSAGE_CONTENT (Streaming), TEXT_MESSAGE_END
7. Der Agent sendet STATE_DELTA, um den Frontend-Zustand in Echtzeit zu aktualisieren
8. Der Nutzer entscheidet, den Agenten umzulenken → sendet AgentInput mit Korrektur
9. Der Agent verarbeitet die Korrektur und macht weiter
10. Der Agent sendet RUN_FINISHED

Das Frontend empfängt diese Ereignisse als Stream und rendert sie schrittweise — zeigt Tool-Aufrufe an, während sie passieren, streamt Text in Echtzeit und aktualisiert anhand der Schritt-Ereignisse einen Fortschrittsindikator.

AG-UI implementieren

Unterstützung durch Frameworks

AG-UI wird zunehmend von großen Agenten-Frameworks unterstützt:

  • LangGraph: AG-UI-Ereignisse können mit dem AG-UI-Python-SDK aus Graph-Knoten ausgegeben werden
  • AG-UI-CopilotKit-Integration: CopilotKit, ein React-Frontend-Framework für KI, bietet native AG-UI-Unterstützung
  • Benutzerdefinierte Implementierungen: Die AG-UI-Spezifikation ist offen; jedes Framework kann sie mit den definierten Ereignistypen implementieren

Schnellstart (Python)

from ag_ui.core import (
    RunAgentInput, EventType,
    RunStartedEvent, TextMessageStartEvent,
    TextMessageContentEvent, TextMessageEndEvent,
    RunFinishedEvent,
)
import uuid

async def run_agent(input: RunAgentInput):
    run_id = str(uuid.uuid4())

    yield RunStartedEvent(
        type=EventType.RUN_STARTED,
        thread_id=input.thread_id,
        run_id=run_id,
    )

    msg_id = str(uuid.uuid4())
    yield TextMessageStartEvent(type=EventType.TEXT_MESSAGE_START, message_id=msg_id, role="assistant")
    
    for chunk in agent.stream(input.messages):
        yield TextMessageContentEvent(
            type=EventType.TEXT_MESSAGE_CONTENT,
            message_id=msg_id,
            delta=chunk
        )

    yield TextMessageEndEvent(type=EventType.TEXT_MESSAGE_END, message_id=msg_id)
    yield RunFinishedEvent(type=EventType.RUN_FINISHED, thread_id=input.thread_id, run_id=run_id)

Verbindung mit AnyCap

Wenn dein AG-UI-gestützter Agent reale Fähigkeiten benötigt, etwa Websuche, Bildgenerierung oder Dateispeicherung, integriert sich AnyCap als Tool-Schicht unterhalb der Orchestrierung. Der Agent ruft während seiner Ausführungsschleife AnyCap-Tools auf und sendet die entsprechenden TOOL_CALL_*-Ereignisse, damit das Frontend zeigt, was passiert:

User: "Recherchiere die Top 5 KI-Frameworks und erstelle ein Übersichtsbild"

Agent emits: TOOL_CALL_START (tool: "anycap_search", args: {...})
Agent emits: TOOL_CALL_END (result: search results)
Agent emits: TOOL_CALL_START (tool: "anycap_image_generate", args: {...})
Agent emits: TOOL_CALL_END (result: image URL)
Agent emits: TEXT_MESSAGE (streaming summary with embedded image)

Diese vollständige Transparenz — sichtbar gemacht durch AG-UI-Ereignisse — unterscheidet eine vertrauenswürdige Mensch-Agent-Schnittstelle von einer Black Box.

Warum AG-UI für produktive Agentenanwendungen wichtig ist

Wenn du agentengestützte Produkte entwickelst, bietet AG-UI:

Wiederverwendbarkeit von Komponenten. Frontend-Komponenten, die nach der AG-UI-Spezifikation gebaut sind, funktionieren mit jedem kompatiblen Backend. Baue eine Streaming-Chat-UI einmal und nutze sie ohne Änderungen mit LangGraph, CrewAI und AutoGen.

Konsistente Nutzererfahrung. Nutzer sehen in verschiedenen Agenten-Workflows dieselben Interaktionsmuster, weil die Ereignistypen standardisiert sind.

Debugging. Die Zustands-Snapshots und der Ereignisstrom von AG-UI liefern dir einen vollständigen Datensatz der Agentenausführung. Das Wiedergeben eines Ereignisstroms zeigt genau, was der Agent in jedem Schritt gesehen und getan hat.

Menschliche Aufsicht. Der AgentInput-Mechanismus für menschliche Eingriffe während einer laufenden Aufgabe ist in das Protokoll integriert — nicht nachträglich angeflanscht.

Fazit

AG-UI schließt eine echte Lücke im Infrastruktur-Stack für agentische KI. Je leistungsfähiger und nutzernäher Agenten werden, desto wichtiger wird das Protokoll dafür, wie sie ihren Zustand kommunizieren und menschliche Eingaben empfangen — genauso wichtig wie die Tools, auf die sie zugreifen können.

Für Entwickler, die 2026 agentengestützte Produkte bauen, bedeutet eine frühe Einführung von AG-UI, auf einer Grundlage aufzubauen, auf die sich das Ökosystem zubewegt — statt eine maßgeschneiderte Kommunikationsschicht zu pflegen, die mit dem Wachstum des Produkts zur Belastung wird.

Weiterführende Lektüre: