Frontend-Erlebnisse mit ADK und A2UI

1. Übersicht

Die meisten Agent-Apps geben Nur-Text zurück. Mit A2UI ändert sich das. A2UI ist ein Protokoll mit 18 deklarativen UI-Primitiven, mit denen Ihr Agent komplexe, 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) verwendet, um den Agenten zu erstellen, und A2UI, um die Benutzeroberfläche zu generieren.

Aufgaben

Ein Dashboard für die Cloud-Infrastruktur in drei Phasen:

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

Lerninhalte

• Funktionsweise von A2UI: 18 Primitive, 3 Nachrichtentypen, flaches Komponentenmodell
• Verwenden des A2UI SDK, um einen ADK-Agenten aufzufordern, A2UI-JSON zu generieren
• Rendern von A2UI-Komponenten in adk web

Voraussetzungen

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

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

Die Bearbeitung dieses Codelabs 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 Symbolleiste des Cloud Shell-Editors auf Terminal und Neues Terminal und führen Sie dann die folgenden Befehle aus, um Ihr Projekt und Ihren Standort festzulegen und ADK so zu konfigurieren, dass Gemini in Vertex AI verwendet wird.

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. Agent 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 dem folgenden 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 dem folgenden 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 Terminal des Cloud Shell-Editors den folgenden Befehl aus, um die ADK-Entwicklungsoberfläche 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-Entwicklungsoberfläche in Ihrem Browser öffnen, indem Sie bei gedrückter Strg - oder Befehlstaste auf die lokale Test-URL klicken oder auf die Schaltfläche Webvorschau klicken und Vorschau auf Port 8080 auswählen.

Wählen Sie in der ADK-Entwicklungsoberfläche a2ui_agent aus dem Drop-down-Menü aus.

Beispiel-Prompts senden

Senden Sie einen Beispiel-Prompt an den Agenten:

What's running in my project?

Probieren Sie jetzt einen weiteren Beispiel-Prompt aus. Sie erhalten mehr Textausgabe:

Does anything need my attention?

Ihre Unterhaltung sollte in etwa so aussehen:

Sie erhalten eine Wand aus Text. Das ist zwar genau, aber nicht sehr nutzerfreundlich.

5. A2UI-JSON generieren

Was wäre, wenn der Agent eine Benutzeroberfläche beschreiben könnte, anstatt Text auszugeben? A2UI ist ein Protokoll, mit dem Agenten 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 System-Prompts für Sie generiert. Er vermittelt dem LLM den vollständigen A2UI-Komponentenkatalog, die korrekten Attributnamen und -typen sowie die JSON-Struktur.

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],
)

Die Methode generate_system_prompt() kombiniert Ihre Rollenbeschreibung mit dem vollständigen A2UI-JSON-Schema und wenigen Beispielen, sodass das LLM genau weiß, wie die Ausgabe formatiert werden muss. Sie müssen den Komponentenkatalog nicht manuell erstellen.

6. JSON-Ausgabe testen

Wenn die ADK-Entwicklungsoberfläche noch von früher ausgeführt wird, sollten die Änderungen, die Sie an Ihrem Agenten vorgenommen haben, automatisch neu geladen werden.

Wenn Sie die ADK-Entwicklungsoberfläche neu 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 bei gedrückter Strg - oder Befehlstaste 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 denselben Prompt wie zuvor:

What's running in my project?

Dieses Mal antwortet der Agent mit A2UI-JSON anstelle von Nur-Text. In der Chat-Ausgabe werden strukturierte Nachrichten mit beginRendering, surfaceUpdate und dataModelUpdate angezeigt.

Das JSON beschreibt eine komplexe Benutzeroberfläche mit Karten, Symbolen und Schaltflächen, aber adk web zeigt sie als Nur-Text an. Im nächsten Schritt wird sie als tatsächliche UI-Komponenten gerendert.

7. A2UI verstehen

Sehen Sie sich das JSON an, das Ihr Agent gerade generiert hat. Es enthält drei Arten von Nachrichten. 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 die Komponentenhierarchie 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

Sendet die Daten getrennt von der Struktur:

{"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 die Komponentenhierarchie noch einmal zu senden.

Die 18 Primitive

Kategorie	Komponenten
Layout	Karte, Spalte, Zeile, Liste, Tabs, Trennlinie, Modal
Display	Text, Bild, Symbol, Video, Audioplayer
Eingabe	Textfeld, Datum/Uhrzeit-Eingabe, Mehrfachauswahl, Kästchen, Schieberegler
Aktion	Schaltfläche

Der Agent erstellt verschiedene Layouts aus demselben Katalog. In der Komponentenreferenz finden Sie alle Details zu den einzelnen Primitiven. Eine Browseransicht, ein Prioritätsdashboard und ein Konfigurationsformular verwenden alle dieselben 18 Primitive. Es sind keine neuen Frontend-Komponenten erforderlich.

8. A2UI-Komponenten rendern

Der Agent generiert gültiges A2UI-JSON, aber adk web zeigt es als Nur-Text an. Damit es als tatsächliche UI-Komponenten gerendert wird, 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-Dienstprogramm erstellen

Erstellen Sie a2ui_agent/a2ui_utils.py mit dem folgenden 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 Dienstprogramm führt zwei Aufgaben aus:

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-Entwicklungsoberfläche noch von früher ausgeführt wird, sollten die Änderungen, die Sie an Ihrem Agenten vorgenommen haben, automatisch neu geladen werden.

Wenn Sie die ADK-Entwicklungsoberfläche neu 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 bei gedrückter Strg - oder Befehlstaste 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, starten Sie eine neue Sitzung, indem Sie rechts oben in der ADK-Entwicklungsoberfläche auf + Neue Sitzung klicken, und 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 eine andere Benutzeroberfläche aus derselben Gruppe von Primitiven erstellt:

Does anything need my attention?

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

Probieren Sie schließlich einen weiteren Prompt aus, 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 Primitive gesendet. Jeder Prompt führt jedoch zu einer anderen Benutzeroberfläche für eine andere Absicht.

10. Bereinigen

Um zu vermeiden, dass lokale Server ausgeführt werden, bereinigen Sie die Ressourcen:

• Drücken Sie im Terminal, auf dem adk web ausgeführt wird, Strg + C , um den Agent-Server 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 erstellt, der mit A2UI komplexe, interaktive Benutzeroberflächen generiert.

Das haben Sie gelernt

• A2UI ist ein Protokoll mit 18 deklarativen Primitiven und 3 Nachrichtentypen.
• Das A2UI SDK generiert System-Prompts, die dem LLM den Komponentenkatalog vermitteln.
• Derselbe Agent, dasselbe Tool und dieselben Primitive erstellen verschiedene Benutzeroberflächen für verschiedene Absichten.
• A2UI-Komponenten können während der Entwicklung direkt in adk web gerendert werden.

Produktions-Frontend erstellen

In diesem Codelab haben Sie A2UI in adk web für die Entwicklung und das Testen 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/Desktop	Flutter GenUI SDK	Erste Schritte

Referenzdokumente

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