Frontend-Erlebnisse mit ADK und A2UI

1. Übersicht

Die meisten Agent-Apps geben Nur-Text zurück. A2UI ändert das. Es handelt sich um ein Protokoll mit 18 deklarativen UI-Primitiven, mit denen Ihr Agent umfangreiche, interaktive Oberflächen erstellen kann. Der Client rendert sie nativ. Pro Layout ist kein neuer Frontend-Code erforderlich.

In diesem Codelab wird das Agent Development Kit (ADK) zum Erstellen des Agenten und A2UI zum Generieren der Benutzeroberfläche verwendet.

Aufgaben

Ein Mockup eines Cloud-Infrastruktur-Dashboards in drei Phasen:

1. Ein Standard-Agent, der Ressourcendaten als Nur-Text zurückgibt
2. Ein A2UI-Agent, der dieselben Daten wie strukturierte A2UI-JSON zurückgibt
3. Ein gerenderter Agent, der das A2UI-JSON als interaktive UI-Komponenten in der ADK-Entwicklungsoberfläche anzeigt

Lerninhalte

• So funktioniert A2UI: 18 Grundelemente, 3 Nachrichtentypen, flaches Komponentenmodell
• A2UI SDK verwenden, um einen ADK-Agenten aufzufordern, A2UI-JSON zu generieren
• A2UI-Komponenten in adk web rendern

Voraussetzungen

• Ein Google Cloud-Projekt mit aktivierter Abrechnungsfunktion
• Ein Webbrowser wie Chrome
• Python 3.12 und höher

Dieses Codelab richtet sich an fortgeschrittene Entwickler, die mit Python und Google Cloud vertraut sind.

Dieses Codelab dauert etwa 15 bis 20 Minuten.

Die in diesem Codelab erstellten Ressourcen sollten weniger als 5 $ kosten.

2. Umgebung einrichten

Google Cloud-Projekt erstellen

1. Wählen Sie in der Google Cloud Console auf der Seite der Projektauswahl ein Google Cloud-Projekt aus oder erstellen Sie eines.
2. Die Abrechnung für das Cloud-Projekt muss aktiviert sein. So prüfen Sie, ob die Abrechnung für ein Projekt aktiviert ist.

Cloud Shell-Editor starten

Klicken Sie zum Starten einer Cloud Shell-Sitzung in der Google Cloud Console auf Cloud Shell aktivieren.

Dadurch wird im unteren Bereich der Google Cloud Console eine Sitzung gestartet.

Klicken Sie zum Starten des Editors in der Symbolleiste des Cloud Shell-Fensters auf Editor öffnen.

Umgebungsvariablen festlegen

Klicken Sie in der Cloud Shell Editor-Symbolleiste auf Terminal und Neues Terminal und führen Sie dann die folgenden Befehle aus, um Ihr Projekt und Ihren Standort festzulegen und das ADK für die Verwendung von Gemini in Vertex AI zu konfigurieren.

export GOOGLE_CLOUD_PROJECT=<INSERT_YOUR_GCP_PROJECT_HERE>
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_VERTEXAI=True

APIs aktivieren

Führen Sie im Terminal den folgenden Befehl aus, um die erforderlichen APIs zu aktivieren:

gcloud services enable aiplatform.googleapis.com

Abhängigkeiten installieren

Führen Sie im Terminal den folgenden Befehl aus, um die neueste Version des Agent Development Kit (ADK) zu installieren:

pip install -U google-adk a2ui-agent-sdk
export PATH="$HOME/.local/bin:$PATH"

3. KI-Agenten erstellen

Beginnen Sie mit einem Standard-ADK-Agenten, der Nur-Text zurückgibt. So sehen die meisten Agent-Apps heute aus.

Agent-Ordner erstellen

Erstellen Sie einen Ordner mit dem Namen a2ui_agent, der den Quellcode für Ihren Agenten und Ihre Tools enthält.

Tool und Mock-Daten definieren

Erstellen Sie a2ui_agent/resources.py mit folgendem Inhalt. Dieses Tool gibt eine Liste von Cloud-Ressourcen mit ihrem Status zurück.

RESOURCES = [
    {
        "name": "auth-service",
        "type": "Cloud Run",
        "region": "us-west1",
        "status": "healthy",
        "cpu": "2 vCPU",
        "memory": "1 GiB",
        "instances": 3,
        "url": "https://auth-service-abc123.run.app",
        "last_deployed": "2026-04-18T14:22:00Z",
    },
    {
        "name": "events-db",
        "type": "Cloud SQL",
        "region": "us-east1",
        "status": "warning",
        "tier": "db-custom-8-32768",
        "storage": "500 GB SSD",
        "connections": 195,
        "version": "PostgreSQL 16",
        "issue": "Storage usage at 92%",
    },
    {
        "name": "analytics-pipeline",
        "type": "Cloud Run",
        "region": "us-west1",
        "status": "error",
        "cpu": "2 vCPU",
        "memory": "4 GiB",
        "instances": 0,
        "url": "https://analytics-pipeline-ghi789.run.app",
        "last_deployed": "2026-04-10T16:45:00Z",
        "issue": "CrashLoopBackOff: OOM killed",
    },
]

def get_resources() -> list[dict]:
    """Get all cloud resources in the current project.
    Returns a list of cloud infrastructure resources including their
    name, type, region, status, and type-specific details.
    Status is one of: healthy, warning, error. Resources with
    warning or error status include an 'issue' field describing
    the problem.
    """
    return RESOURCES

Agent definieren

Erstellen Sie a2ui_agent/agent.py mit folgendem Inhalt:

from google.adk.agents import Agent
from .resources import get_resources

root_agent = Agent(
    model="gemini-3-flash-preview",
    name="cloud_dashboard",
    description="A cloud infrastructure assistant that reports on project resources.",
    instruction=(
        "You are a cloud infrastructure assistant. When users ask about their "
        "cloud resources, use the get_resources tool to fetch the current state. "
        "Summarize the results clearly in plain text."
    ),
    tools=[get_resources],
)

4. KI-Agenten testen

Das ADK enthält eine Entwicklungsoberfläche, über die Sie in einem Browser mit Ihrem Agenten interagieren und ihm Prompts senden können, um ihn zu testen.

ADK-Entwicklungsoberfläche starten

Führen Sie im Cloud Shell Editor-Terminal den folgenden Befehl aus, um die ADK-Entwickler-UI zu starten:

adk web --port 8080 --allow_origins "*" --reload_agents

Es wird eine Meldung ähnlich der folgenden angezeigt:

+-----------------------------------------------------------------------------+
| ADK Web Server started                                                      |
|                                                                             |
| For local testing, access at http://127.0.0.1:8080.                         |
+-----------------------------------------------------------------------------+

ADK-Entwicklungsoberfläche öffnen

Sie können die ADK-Entwickler-UI in Ihrem Browser öffnen, indem Sie Strg oder Cmd gedrückt halten und auf die lokale Test-URL klicken oder indem Sie auf die Schaltfläche Webvorschau klicken und Vorschau auf Port 8080 auswählen.

Wählen Sie in der ADK-Entwickler-UI im Drop-down-Menü a2ui_agent aus.

Beispiel-Prompts senden

Senden Sie einen Beispiel-Prompt an den Agenten:

What's running in my project?

Probieren Sie nun eine andere Beispielaufforderung aus. Sie erhalten dann mehr Text:

Does anything need my attention?

Ihre Unterhaltung sollte in etwa so aussehen:

Sie erhalten eine Wand aus Text. Die Antwort ist zwar korrekt, aber nicht sehr nutzerfreundlich.

5. A2UI-JSON generieren

Was wäre, wenn der Agent eine Benutzeroberfläche beschreiben könnte, anstatt nur Text auszugeben? A2UI ist ein Protokoll, mit dem Agents interaktive Oberflächen aus einem Katalog von 18 Primitiven erstellen können. Der Client rendert sie nativ.

Das A2UI Python SDK enthält einen Schemamanager, der Systemprompts für Sie generiert. Damit wird dem LLM der vollständige A2UI-Komponentenkatalog, die richtigen Attributnamen und -typen sowie die JSON-Struktur beigebracht.

Agent aktualisieren

Ersetzen Sie den Inhalt von a2ui_agent/agent.py durch Folgendes:

from google.adk.agents import Agent
from a2ui.schema.manager import A2uiSchemaManager
from a2ui.basic_catalog.provider import BasicCatalog
from .resources import get_resources

schema_manager = A2uiSchemaManager(
    version="0.8",
    catalogs=[BasicCatalog.get_config("0.8")],
)

instruction = schema_manager.generate_system_prompt(
    role_description=(
        "You are a cloud infrastructure assistant. When users ask about "
        "their cloud resources, use the get_resources tool to fetch the "
        "current state."
    ),
    workflow_description=(
        "Analyze the user's request and return structured UI when appropriate."
    ),
    ui_description=(
        "Use cards for resource summaries, rows and columns for comparisons, "
        "icons for status indicators, and buttons for drill-down actions. "
        "Do NOT use markdown formatting in text values. Use the usageHint "
        "property for heading levels instead. "
        "Respond ONLY with the A2UI JSON array. Do NOT include any text "
        "outside the JSON. Put all explanations into Text components."
    ),
    include_schema=True,
    include_examples=True,
)

root_agent = Agent(
    model="gemini-3-flash-preview",
    name="cloud_dashboard",
    description="A cloud infrastructure assistant that renders rich A2UI interfaces.",
    instruction=instruction,
    tools=[get_resources],
)

Bei der generate_system_prompt()-Methode wird Ihre Rollenbeschreibung mit dem vollständigen A2UI-JSON-Schema und Few-Shot-Beispielen kombiniert, damit das LLM genau weiß, wie es seine Ausgabe formatieren muss. Sie müssen den Komponenten-Katalog nicht manuell erstellen.

6. JSON-Ausgabe testen

Wenn die ADK-Entwickler-UI noch aus einem früheren Schritt ausgeführt wird, sollten die Änderungen, die Sie an Ihrem Agent vorgenommen haben, automatisch neu geladen werden.

Wenn Sie die ADK-Entwicklungsoberfläche noch einmal starten müssen, können Sie den folgenden Befehl verwenden:

adk web --port 8080 --allow_origins "*" --reload_agents

Öffnen Sie dann die ADK-Entwicklungsoberfläche in Ihrem Browser, indem Sie Ctrl oder Cmd auf die lokale Test-URL klicken oder auf die Schaltfläche Webvorschau klicken und Vorschau auf Port 8080 auswählen.

Wählen Sie a2ui_agent aus, starten Sie eine neue Sitzung, indem Sie rechts oben in der ADK-Entwicklungsoberfläche auf + Neue Sitzung klicken, und senden Sie dann denselben Prompt wie zuvor:

What's running in my project?

Dieses Mal antwortet der Agent mit A2UI-JSON anstelle von Klartext. In der Chatausgabe werden strukturierte Nachrichten mit beginRendering, surfaceUpdate und dataModelUpdate angezeigt.

Das JSON beschreibt eine umfangreiche Benutzeroberfläche mit Karten, Symbolen und Schaltflächen, aber adk web zeigt sie als Rohtext an. Im nächsten Schritt sorgen Sie dafür, dass sie als tatsächliche UI-Komponenten gerendert werden.

7. A2UI verstehen

Sehen Sie sich den JSON-Code an, den Ihr Agent gerade generiert hat. Sie sehen, dass sie drei Arten von Nachrichten enthält. Jede A2UI-Antwort folgt derselben Struktur:

1. beginRendering

Erstellt eine Rendering-Oberfläche und benennt die Root-Komponente:

{"beginRendering": {"surfaceId": "default", "root": "main-column"}}

2. surfaceUpdate

Sendet den Komponentenbaum als flache Liste mit ID-Referenzen (nicht verschachtelt):

{"surfaceUpdate": {"surfaceId": "default", "components": [
  {"id": "main-column", "component": {"Column": {"children": {"explicitList": ["title", "card1"]}}}},
  {"id": "title", "component": {"Text": {"text": {"literalString": "My Resources"}, "usageHint": "h1"}}},
  {"id": "card1", "component": {"Card": {"child": "card1-content"}}},
  {"id": "card1-content", "component": {"Text": {"text": {"path": "service_name"}}}}
]}}

3. dataModelUpdate

Die Daten werden separat von der Struktur gesendet:

{"dataModelUpdate": {"surfaceId": "default", "contents": [
  {"key": "service_name", "valueString": "auth-service"},
  {"key": "status", "valueString": "healthy"}
]}}

Komponenten werden mit {"path": "key"} an Daten gebunden. Sie können Daten aktualisieren, ohne den Komponentenbaum noch einmal zu senden.

Die 18 Grundlagen

Kategorie	Komponenten
Layout	Karte, Spalte, Zeile, Liste, Tabs, Trennzeichen, Modal
Display	Text, Bild, Symbol, Video, AudioPlayer
Eingabe	TextField, DateTimeInput, MultipleChoice, CheckBox, Slider
Aktion	Button

Der Agent erstellt verschiedene Layouts aus demselben Katalog. Ausführliche Informationen zu den einzelnen Primitiven finden Sie in der Komponentenreferenz. Für eine Übersichtsseite, ein Prioritäts-Dashboard und ein Konfigurationsformular werden dieselben 18 Grundelemente verwendet. Es sind keine neuen Frontend-Komponenten erforderlich.

8. A2UI-Komponenten rendern

Der Agent generiert gültiges A2UI-JSON, aber adk web zeigt es als Rohtext an. Damit die Ausgabe als tatsächliche UI-Komponenten gerendert werden kann, benötigen Sie ein kleines Dienstprogramm, das die A2UI-JSON-Ausgabe des Agenten in das Format konvertiert, das der integrierte Renderer von adk web erwartet.

A2UI-Rendering-Tool erstellen

Erstellen Sie a2ui_agent/a2ui_utils.py mit folgendem Inhalt:

import json
import re
from google.genai import types
from google.adk.agents.callback_context import CallbackContext
from google.adk.models.llm_response import LlmResponse

def _wrap_a2ui_part(a2ui_message: dict) -> types.Part:
    """Wrap a single A2UI message for rendering in adk web."""
    datapart_json = json.dumps({
        "kind": "data",
        "metadata": {"mimeType": "application/json+a2ui"},
        "data": a2ui_message,
    })
    blob_data = (
        b"<a2a_datapart_json>"
        + datapart_json.encode("utf-8")
        + b"</a2a_datapart_json>"
    )
    return types.Part(
        inline_data=types.Blob(
            data=blob_data,
            mime_type="text/plain",
        )
    )

def a2ui_callback(
    callback_context: CallbackContext,
    llm_response: LlmResponse,
) -> LlmResponse | None:
    """Convert A2UI JSON in text output to rendered components."""
    if not llm_response.content or not llm_response.content.parts:
        return None
    for part in llm_response.content.parts:
        if not part.text:
            continue
        text = part.text.strip()
        if not text:
            continue
        if not any(k in text for k in ("beginRendering", "surfaceUpdate", "dataModelUpdate")):
            continue
        # Strip markdown fences
        if text.startswith("```"):
            text = text.split("\n", 1)[-1]
            if text.endswith("```"):
                text = text[:-3].strip()
        # Find where JSON starts (skip conversational prefix)
        json_start = None
        for i, ch in enumerate(text):
            if ch in ("[", "{"):
                json_start = i
                break
        if json_start is None:
            continue
        json_text = text[json_start:]
        # raw_decode parses JSON and ignores trailing text
        try:
            parsed, _ = json.JSONDecoder().raw_decode(json_text)
        except json.JSONDecodeError:
            # Handle concatenated JSON objects: {"a":1} {"b":2}
            try:
                fixed = "[" + re.sub(r'\}\s*\{', '},{', json_text) + "]"
                parsed, _ = json.JSONDecoder().raw_decode(fixed)
            except json.JSONDecodeError:
                continue
        if not isinstance(parsed, list):
            parsed = [parsed]
        a2ui_keys = {"beginRendering", "surfaceUpdate", "dataModelUpdate", "deleteSurface"}
        a2ui_messages = [msg for msg in parsed if isinstance(msg, dict) and any(k in msg for k in a2ui_keys)]
        if not a2ui_messages:
            continue
        new_parts = [_wrap_a2ui_part(msg) for msg in a2ui_messages]
        return LlmResponse(
            content=types.Content(role="model", parts=new_parts),
            custom_metadata={"a2a:response": "true"},
        )
    return None

Dieses Tool hat zwei Funktionen:

1. Extrahiert A2UI-JSON aus der Textausgabe des Agenten
2. Umschließt jede A2UI-Nachricht im Format, das der integrierte A2UI-Renderer von adk web erwartet.

Agent aktualisieren

Ersetzen Sie den Inhalt von a2ui_agent/agent.py durch Folgendes. Die einzige Änderung gegenüber dem vorherigen Schritt ist der Import von a2ui_callback und der Parameter after_model_callback für den Agenten:

from google.adk.agents import Agent
from a2ui.schema.manager import A2uiSchemaManager
from a2ui.basic_catalog.provider import BasicCatalog
from .resources import get_resources
from .a2ui_utils import a2ui_callback

schema_manager = A2uiSchemaManager(
    version="0.8",
    catalogs=[BasicCatalog.get_config("0.8")],
)

instruction = schema_manager.generate_system_prompt(
    role_description=(
        "You are a cloud infrastructure assistant. When users ask about "
        "their cloud resources, use the get_resources tool to fetch the "
        "current state."
    ),
    workflow_description=(
        "Analyze the user's request and return structured UI when appropriate."
    ),
    ui_description=(
        "Use cards for resource summaries, rows and columns for comparisons, "
        "icons for status indicators, and buttons for drill-down actions. "
        "Do NOT use markdown formatting in text values. Use the usageHint "
        "property for heading levels instead. "
        "Respond ONLY with the A2UI JSON array. Do NOT include any text "
        "outside the JSON. Put all explanations into Text components."
    ),
    include_schema=True,
    include_examples=True,
)

root_agent = Agent(
    model="gemini-3-flash-preview",
    name="cloud_dashboard",
    description="A cloud infrastructure assistant that renders rich A2UI interfaces.",
    instruction=instruction,
    tools=[get_resources],
    after_model_callback=a2ui_callback,
)

9. Gerenderte Benutzeroberfläche testen

Wenn die ADK-Entwickler-UI noch aus einem früheren Schritt ausgeführt wird, sollten die Änderungen, die Sie an Ihrem Agent vorgenommen haben, automatisch neu geladen werden.

Wenn Sie die ADK-Entwicklungsoberfläche noch einmal starten müssen, können Sie den folgenden Befehl verwenden:

adk web --port 8080 --allow_origins "*" --reload_agents

Öffnen Sie dann die ADK-Entwicklungsoberfläche in Ihrem Browser, indem Sie Ctrl oder Cmd auf die lokale Test-URL klicken oder auf die Schaltfläche Webvorschau klicken und Vorschau auf Port 8080 auswählen.

Aktualisieren Sie den Browsertab, wählen Sie a2ui_agent aus und starten Sie dann eine neue Sitzung, indem Sie rechts oben in der ADK-Entwicklungsoberfläche auf + Neue Sitzung klicken. Senden Sie denselben Prompt wie zuvor:

What's running in my project?

Dieses Mal rendert adk web die A2UI-Komponenten als tatsächliche Benutzeroberfläche: Karten mit Statusanzeigen, Ressourcendetails und Aktionsschaltflächen.

Probieren Sie einen anderen Prompt aus, um zu sehen, wie der Agent aus denselben Primitiven eine andere Benutzeroberfläche erstellt:

Does anything need my attention?

Wenn die A2UI-Komponenten nach dem Neuladen des Agents nicht gerendert werden, aktualisieren Sie den Browsertab, um die aktualisierten A2UI-Assets zu laden.

Versuchen Sie es schließlich mit einem anderen Prompt, um eine andere Benutzeroberfläche zum Bereitstellen eines neuen Dienstes zu generieren:

I need to deploy a new service

Jeder Prompt wird an denselben Agenten, dasselbe Tool und dieselben 18 Grundfunktionen gesendet. Jeder Prompt führt jedoch zu einer anderen Benutzeroberfläche für eine andere Intention.

10. Bereinigen

So vermeiden Sie, dass lokale Server weiter ausgeführt werden:

• Drücken Sie im Terminal, in dem adk web ausgeführt wird, Strg + C, um den Agentenserver zu beenden.

Wenn Sie ein Projekt speziell für dieses Codelab erstellt haben, können Sie das gesamte Projekt löschen:

gcloud projects delete ${GOOGLE_CLOUD_PROJECT}

11. Glückwunsch

Sie haben einen ADK-Agenten entwickelt, der mit A2UI eine umfangreiche, interaktive Benutzeroberfläche generiert.

Das haben Sie gelernt

• A2UI ist ein Protokoll mit 18 deklarativen Primitiven und 3 Nachrichtentypen.
• Das A2UI SDK generiert Systemprompts, mit denen das LLM den Komponenten-Katalog kennenlernt.
• Derselbe Agent, dasselbe Tool und dieselben Primitives bilden unterschiedliche UIs für unterschiedliche Intentionen.
• A2UI-Komponenten können während der Entwicklung direkt in adk web gerendert werden.

Produktions-Frontend erstellen

In diesem Codelab haben Sie A2UI für die Entwicklung und das Testen in adk web gerendert.

Für die Produktion würden Sie ein Frontend mit einem der offiziellen A2UI-Renderer erstellen:

Plattform	Renderer	Installieren
Web (React)	@a2ui/react	npm install @a2ui/react
Web (Lit)	@a2ui/lit	npm install @a2ui/lit
Web (Angular)	@a2ui/angular	npm install @a2ui/angular
Mobilgerät/Computer	Flutter GenUI SDK	Erste Schritte

Referenzdokumente

• A2UI-Spezifikation und -Dokumentation
• A2UI-GitHub-Repository
• A2UI-Renderer
• ADK-Dokumentation
• ADK A2UI-Integration