Startseite / Artikel

Generative Benutzeroberflächen mit ADK Agents unter Verwendung des A2UI-Protokolls: Nachrichten und Beispiele

Erfahren Sie, wie A2UI es einem Agenten ermöglicht, eine interaktive Benutzeroberfläche als JSON zurückzugeben, wie sich dies von AG-UI unterscheidet und wie man das Beispiel für den Restaurantfinder von Google ADK lokal ausführt.

Verlag: REACTAPP.TOP6 Min. Lesezeit1361 Wörter

Quellen: Agent to UI Protocol (A2UI) with Agent Development Kit (ADK)

Vier Protokolle tauchen immer wieder auf, wenn Agenten in echte Anwendungen integriert werden: MCP, A2A, A2UI und AG-UI. AG-UI verbindet eine Frontend-Anwendung mit einem Agenten-Backend und funktioniert gut zusammen mit Googles Agent Development Kit (ADK). Der Fokus liegt hier auf A2UI – einem Protokoll mit einem verwirrend ähnlichen Namen – sowie darauf, wie es von einem ADK-Agenten gesteuert werden kann.

Was A2UI ist

A2UI ist ein generatives UI-Protokoll von Google. Es ermöglicht es KI-Agenten, reichhaltige, interaktive Benutzeroberflächen zu erstellen, die auf Web-, Mobil- und Desktop-Plattformen angezeigt werden können. Wenn beispielsweise ein Benutzer fragt: „Welche guten Restaurants gibt es in New York?“, kann der Agent mehr tun, als nur eine Textliste zurückzugeben. Er kann auch eine Beschreibung der Benutzeroberfläche liefern, und ein Renderer auf der Client-Seite wandelt diese Beschreibung in eine interaktive Anzeige der Restaurants um.

Die grundlegenden Konzepte sind auf a2ui.org dokumentiert, und die wesentlichen Punkte lassen sich in wenigen Abschnitten zusammenfassen.

Vier Nachrichtentypen

Alles, was ein Agent sendet, ist im JSON-Format, und es gibt nur vier Arten von Nachrichten:

  • createSurface erstellt eine neue Oberfläche und gibt an, welchen Komponentenkatalog sie verwendet.
  • updateComponents fügt UI-Komponenten zu einer Oberfläche hinzu oder ändert diese.
  • updateDataModel ändert den Zustand der Anwendung.
  • deleteSurface löscht eine Oberfläche.

Zusammen beschreiben sie sowohl die Schnittstelle als auch die dahinterliegenden Daten:

{
  "version": "v0.9",
  "createSurface": {
    "surfaceId": "main",
    "catalogId": "https://a2ui.org/specification/v0_9/basic_catalog.json"
  }
}
{
  "version": "v0.9",
  "updateComponents": {
    "surfaceId": "main",
    "components": [...]
  }
}
{
  "version": "v0.9",
  "updateDataModel": {
    "surfaceId": "main",
    "path": "/user",
    "value": { "name": "Alice" }
  }
}

Der Komponentenkatalog

A2UI liefert einen Standardkatalog, der nach Verwendungszweck gruppiert ist:

  • Layout: Zeile, Spalte und Liste, die andere Komponenten anordnen
  • Anzeige: Text, Bild, Icon, Video und Trenner, die Informationen darstellen
  • Interaktiv: Schaltfläche, Eingabefeld, Kontrollkästchen, Datumszeit-eingabe und Slider, die Eingaben entgegennehmen
  • Container: Karte, Tabellen und Modale Fenster, die Inhalte gruppieren

In der Dokumentation befindet sich eine vollständige Galerie mit Beispielen zu den Komponenten.

Eine Buchungsgespräch – Nachricht für Nachricht

Das Beispiel zur Restaurantbuchung in den Dokumentationen veranschaulicht den Lebenszyklus gut.

Zuerst erstellt der Agent eine Oberfläche:

{
  "version": "v0.9",
  "createSurface": {
    "surfaceId": "booking",
    "catalogId": "https://a2ui.org/specification/v0_9/basic_catalog.json"
  }
}

Zweitens definiert es die Struktur der Benutzeroberfläche:

{
  "version": "v0.9",
  "updateComponents": {
    "surfaceId": "booking",
    "components": [
      {
        "id": "root",
        "component": "Column",
        "children": ["header", "guests-field", "submit-btn"]
      },
      {
        "id": "header",
        "component": "Text",
        "text": "Confirm Reservation",
        "variant": "h1"
      },
      {
        "id": "guests-field",
        "component": "TextField",
        "label": "Guests",
        "value": { "path": "/reservation/guests" }
      },
      {
        "id": "submit-btn",
        "component": "Button",
        "child": "submit-text",
        "variant": "primary",
        "action": {
          "event": {
            "name": "confirm",
            "context": {
              "details": { "path": "/reservation" }
            }
          }
        }
      }
    ]
  }
}

Drittens füllt es die Daten aus:

{
  "version": "v0.9",
  "updateDataModel": {
    "surfaceId": "booking",
    "path": "/reservation",
    "value": {
      "datetime": "2025-12-16T19:00:00Z",
      "guests": "2"
    }
  }
}

Viertens ändert der Benutzer die Anzahl der Gäste auf 3, und der Client aktualisiert automatisch /reservation/guests. Fünftens drückt der Benutzer auf Bestätigen, und der Client sendet eine Aktion zurück:

{
  "version": "v0.9",
  "action": {
    "name": "confirm",
    "surfaceId": "booking",
    "context": {
      "details": {
        "datetime": "2025-12-16T19:00:00Z",
        "guests": "3"
      }
    }
  }
}

Siebtens antwortet der Agent entweder durch eine erneute Aktualisierung der Benutzeroberfläche oder indem er die Oberfläche schließt:

{
  "version": "v0.9",
  "deleteSurface": { "surfaceId": "booking" }
}

Transport und Rendering

A2UI kümmert sich nicht darum, wie Nachrichten übertragen werden, solange alles funktioniert, was JSON transportieren kann. Derzeit werden A2A und AG-UI als Transportmethoden unterstützt, während REST, WebSockets und SSE geplant oder vorgeschlagen sind. Die Transportseite in den Dokumenten listet das Aktuelle auf.

Sobald der Agent das JSON erzeugt hat, wandelt ein Renderer es in native Komponenten um. Im Web gibt es Renderer für Lit und Angular, während Flutter’s GenUI SDK Mobilgeräte, Desktop-Systeme und das Web abdeckt. Die Renderer-Seite enthält die aktuell gepflegte Liste.

A2UI und AG-UI nebeneinander

Die Namen ähneln sich, und die Aufgaben sind unterschiedlich, aber ergänzend. AG-UI stellt die Verbindung zwischen einer benutzerorientierten Anwendung und dem agierenden Backend her. A2UI ist eine deklarative Spezifikation, die von Agenten verwendet wird, um UI-Widgets in ihren Antworten zurückzugeben.

Die Beispiele ausprobieren

Das A2UI-Repository enthält ADK-Agent-Beispiele, die lokal generiert und dargestellt werden können. Klonen Sie es zunächst:

git clone https://github.com/google/a2ui.git
cd a2ui

Eine Gemini-API-Schlüssel einstellen:

export GEMINI_API_KEY="your_gemini_api_key_here"

Jedes Beispiel besteht aus einem Server-Teil (dem Agenten) und einem Client-Teil (dem Renderer), wobei beide laufen müssen. Die ADK-Agentenbeispiele befinden sich im Ordner adk unter samples/agent, während die Client-Renderer in samples/client liegen.

Restaurantfinder

Vom Ordner samples/client/lit aus wird die Demo mit einem einzigen Befehl gestartet:

npm run demo:restaurant

Öffnen Sie http://localhost:5173/?app=restaurant und beginnen Sie mit der Abfrage, zum Beispiel „Top 5 chinesische Restaurants in New York“. Der Agent erzeugt die Benutzeroberfläche und der Client rendernt sie:

Die Protokolle zeigen das rohe A2UI-JSON an, das der Agent gesendet hat:

[REST] LiteLLM completion() model= gemini-2.5-flash; provider = gemini
[REST] INFO:agent:Event from runner: model_version='gemini-2.5-flash' content=Content(
[REST]   parts=[
[REST]     Part(
[REST]       text="""<a2ui-json>
[REST] [
[REST]   {
[REST]     "beginRendering": {
[REST]       "surfaceId": "default",
[REST]       "root": "root-column",
[REST]       "styles": {
[REST]         "primaryColor": "#FF0000",
[REST]         "font": "Roboto"
[REST]       }
[REST]     }
[REST]   },
[REST]   {
[REST]     "surfaceUpdate": {
[REST]       "surfaceId": "default",
[REST]       "components": [
[REST]         {
[REST]           "id": "root-column",
[REST]           "component": {
[REST]             "Column": {
[REST]               "children": {
[REST]                 "explicitList": [
[REST]                   "title-heading",
[REST]                   "item-list"
[REST]                 ]
[REST]               }
[REST]             }
[REST]           }
[REST]         },
...

Was geschieht im Inneren

Der Agent-Code befindet sich in samples/agent/adk/restaurant_finder. prompt_builder.py zeigt, wie die Anfrage erstellt wird, damit der Agent in A2UI antwortet. Die Rollenbeschreibung beginnt mit einer klaren Anweisung, dass die endgültige Ausgabe eine A2UI-JSON-Antwort sein muss:

ROLE_DESCRIPTION = (
    "You are a helpful restaurant finding assistant. Your final output MUST be a a2ui"
    " UI JSON response."
)

UI_DESCRIPTION = """
-   If the query is for a list of restaurants, use the restaurant data you have already received from the `get_restaurants` tool to populate the `dataModelUpdate.contents` array (e.g., as a `valueMap` for the "items" key).
-   If the number of restaurants is 5 or fewer, you MUST use the `SINGLE_COLUMN_LIST_EXAMPLE` template.
-   If the number of restaurants is more than 5, you MUST use the `TWO_COLUMN_LIST_EXAMPLE` template.
-   If the query is to book a restaurant (e.g., "USER_WANTS_TO_BOOK..."), you MUST use the `BOOKING_FORM_EXAMPLE` template.
-   If the query is a booking submission (e.g., "User submitted a booking..."), you MUST use the `CONFIRMATION_EXAMPLE` template.
"""

Die Klasse A2uiSchemaManager lädt Komponentenkataloge und erzeugt Systemanweisungen, die das Modell bei der Erstellung gültiger A2UI-JSON-Daten unterstützen. Durch Aufruf von generate_system_prompt werden die Rollenbeschreibung des Agenten mit dem Schema sowie einige Beispielfälle kombiniert, wodurch das Modell präzise Anleitung zur Formatierung erhält:

version = VERSION_0_9
restaurant_prompt = A2uiSchemaManager(
    version,
    catalogs=[
        BasicCatalog.get_config(
            version=version,
            examples_path=f"examples/{version}",
        )
    ],
    schema_modifiers=[remove_strict_validation],
).generate_system_prompt(
    role_description=ROLE_DESCRIPTION,
    ui_description=UI_DESCRIPTION,
    include_schema=True,
    include_examples=True,
    validate_examples=True,
)

agent.py erstellt anschließend den Agenten mit dieser Systemanweisung:

return LlmAgent(
    model=LiteLlm(model=LITELLM_MODEL),
    name="restaurant_agent",
    description="An agent that finds restaurants and helps book tables.",
    instruction=instruction,
    tools=[get_restaurants],
)

Nachdem der Agent JSON ausgesendet hat, sollte es vor dem Streamen an den Client gegen das A2UI-Schema überprüft werden:

# --- Validation Steps ---
# Check if it validates against the A2UI_SCHEMA
# This will raise jsonschema.exceptions.ValidationError if it fails
logger.info(
    "--- RestaurantAgent.stream: Validating against A2UI_SCHEMA... ---"
)
selected_catalog.validator.validate(parsed_json_data)

In der ADK-Dokumentation gibt es eine Integrationseite für A2UI mit weiteren Details. Auf der Client-Seite enthält renderers/lit die Lit-Implementierung, die das generierte JSON entgegennimmt und darstellt.

Tools zum Einstieg

CopilotKit stellt ein A2UI-Startvorlage sowie einen A2UI Composer zur Verfügung, um mit Komponenten zu experimentieren.

Nützliche Quellen zum Weiterlesen sind die A2UI-Protokoll-Dokumentationen und Spezifikationen, das GitHub-Repositorium, Googles Ankündigungsbeitrag zu agentgesteuerten Schnittstellen, die ADK-Integrationseite, der CopilotKit Composer und die Startvorlage sowie einige YouTube-Vorträge über Agenten, die in Echtzeit UIs erstellen.