Frontend-Erlebnisse mit ADK und A2UI

1. Übersicht

Die meisten KI-Agents antworten mit Text. In diesem Codelab verwenden Sie A2UI, damit Ihr Agent stattdessen mit einer Benutzeroberfläche antwortet. Der Agent beschreibt Karten, Listen, Schaltflächen und Formulare in JSON mithilfe eines Katalogs von Standardkomponenten. Der Client rendert sie mit seinen eigenen nativen Widgets. Für neue Layouts ist also kein neuer Frontend-Code erforderlich.

Sie erstellen den Agenten mit dem Agent Development Kit (ADK).

Aufgaben

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

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

ADK A2UI-Agent

Lerninhalte

  • So funktioniert A2UI: 18 Grundelemente, die Nachrichten, aus denen eine Benutzeroberfläche besteht, und das flache 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 uv, wenn Sie den Code auf Ihrem eigenen Computer anstelle von Cloud Shell ausführen

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

Dieses Codelab dauert etwa 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 zur 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.

APIs aktivieren

Klicken Sie in der Cloud Shell Editor-Symbolleiste auf Terminal und Neues Terminal und führen Sie dann den folgenden Befehl aus, um die erforderlichen APIs zu aktivieren:

gcloud services enable aiplatform.googleapis.com

Abhängigkeiten installieren

Führen Sie im Terminal die folgenden Befehle aus, um einen Ordner für dieses Codelab mit einem a2ui_agent-Ordner für Ihren Agent-Code zu erstellen und das Agent Development Kit (ADK) und das A2UI SDK zu installieren:

mkdir -p ~/adk-a2ui/a2ui_agent
cd ~/adk-a2ui
uv init --bare
uv add google-adk a2ui-agent-sdk

uv erstellt eine isolierte Python-Umgebung für dieses Codelab, sodass Sie nichts aktivieren müssen. Stellen Sie Python-Befehlen das Präfix uv run voran.

3. KI-Agenten erstellen

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

Projekteinstellungen konfigurieren

Führen Sie im Terminal den folgenden Befehl aus, um a2ui_agent/.env mit Ihrem Projekt und Standort zu erstellen und Gemini über Ihr Google Cloud-Projekt aufrufen zu lassen. Das ADK lädt diese Datei automatisch, sodass die Einstellungen auch in neuen Terminals funktionieren.

cat > ~/adk-a2ui/a2ui_agent/.env <<EOF
GOOGLE_CLOUD_PROJECT=$(gcloud config get project)
GOOGLE_CLOUD_LOCATION=global
GOOGLE_GENAI_USE_ENTERPRISE=True
EOF

Tool und Mock-Daten definieren

Erstellen Sie a2ui_agent/resources.py mit folgendem Inhalt. Dieses Tool gibt eine Liste der 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 google.adk.models import Gemini
from google.genai import types
from .resources import get_resources

root_agent = Agent(
    model=Gemini(
        model="gemini-3.8-flash",
        retry_options=types.HttpRetryOptions(attempts=5),
    ),
    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 KI-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-Entwickler-UI zu starten:

uv run 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 bei gedrückter Strg- oder Cmd-Taste auf die URL für lokale Tests klicken oder indem Sie auf die Schaltfläche Webvorschau klicken und Vorschau auf Port 8080 auswählen.

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

Beispiel-Prompts senden

Senden Sie einen Beispiel-Prompt an den Agenten:

What's running in my project?

Probieren Sie nun einen anderen Beispiel-Prompt aus. Sie erhalten dann mehr Text:

Does anything need my attention?

Die Unterhaltung sollte in etwa so aussehen:

ADK-Text-Agent

Die Antwort ist korrekt, aber es handelt sich um einen langen, monotonen Text.

5. A2UI-JSON generieren

Als Nächstes stellen Sie den Agenten von Nur-Text auf A2UI um.

Das A2UI Python SDK enthält einen Prompt-Generator, der Systemprompts für Sie schreibt. 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 google.adk.agents.callback_context import CallbackContext
from google.adk.models import Gemini
from google.adk.models.llm_response import LlmResponse
from google.genai import types
from a2ui.inference_formats.direct_json import DirectJsonFormat
from a2ui.basic_catalog.provider import BasicCatalog
from .resources import get_resources

a2ui_format = DirectJsonFormat(
    version="0.8",
    catalogs=[BasicCatalog.get_config("0.8")],
)

instruction = a2ui_format.prompt_generator.generate(
    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,
)


def show_raw_json(
    callback_context: CallbackContext,
    llm_response: LlmResponse,
) -> LlmResponse | None:
    """Show the A2UI JSON as text so you can read it, instead of rendering it."""
    if not llm_response.content or not llm_response.content.parts:
        return None
    for part in llm_response.content.parts:
        if part.text:
            part.text = (
                part.text
                .replace("<a2ui-json>", "```json\n")
                .replace("</a2ui-json>", "\n```")
            )
    return llm_response


root_agent = Agent(
    model=Gemini(
        model="gemini-3.8-flash",
        retry_options=types.HttpRetryOptions(attempts=5),
    ),
    name="cloud_dashboard",
    description="A cloud infrastructure assistant that renders rich A2UI interfaces.",
    instruction=instruction,
    tools=[get_resources],
    after_model_callback=show_raw_json,
)

show_raw_json zeigt das A2UI-JSON als Text an, damit Sie es lesen können. Sie entfernen sie später, um das Rendern der Benutzeroberfläche zu sehen.

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

In diesem Codelab wird A2UI-Version 0.8 (version="0.8") verwendet, die vom adk web A2UI-Renderer unterstützt wird.

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.

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 sehen Sie strukturierte Nachrichten wie beginRendering und surfaceUpdate (und manchmal dataModelUpdate) in einem JSON-Codeblock.

ADK A2UI JSON

Das JSON beschreibt eine umfangreiche Benutzeroberfläche mit Karten, Symbolen und Schaltflächen, aber show_raw_json stellt es als Text dar, damit Sie es lesen können. Als Nächstes sehen Sie sich an, wie dieses JSON strukturiert ist, und entfernen dann show_raw_json, um es als tatsächliche UI-Komponenten zu rendern.

7. A2UI verstehen

Sehen Sie sich den JSON-Code an, den Ihr Agent gerade generiert hat. A2UI bietet drei Arten von Nachrichten zum Erstellen einer Benutzeroberfläche. Es kann sein, dass Ihr KI-Agent nicht immer alle drei verwendet:

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 getrennt 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 Grundformen

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 aus diesen Komponenten verschiedene Layouts, z. B. eine Übersicht, ein Prioritäts-Dashboard oder ein Konfigurationsformular. Weitere Informationen zu den einzelnen Komponenten finden Sie in der Komponentenreferenz.

8. A2UI-Komponenten rendern

Das SDK umschließt A2UI mit Standard--Tags. adk web erkennt sie und rendert die Komponenten mit dem integrierten A2UI-Renderer. Wenn du sie sehen möchtest, entferne show_raw_json.

Agent aktualisieren

Ersetzen Sie den Inhalt von a2ui_agent/agent.py durch Folgendes. Die einzigen Änderungen gegenüber dem vorherigen Schritt bestehen darin, dass die Funktion show_raw_json, ihr Parameter after_model_callback und die beiden Importe, die sie verwendet hat, entfernt wurden:

from google.adk.agents import Agent
from google.adk.models import Gemini
from google.genai import types
from a2ui.inference_formats.direct_json import DirectJsonFormat
from a2ui.basic_catalog.provider import BasicCatalog
from .resources import get_resources

a2ui_format = DirectJsonFormat(
    version="0.8",
    catalogs=[BasicCatalog.get_config("0.8")],
)

instruction = a2ui_format.prompt_generator.generate(
    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(
        model="gemini-3.8-flash",
        retry_options=types.HttpRetryOptions(attempts=5),
    ),
    name="cloud_dashboard",
    description="A cloud infrastructure assistant that renders rich A2UI interfaces.",
    instruction=instruction,
    tools=[get_resources],
)

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.

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.

ADK A2UI-Agent

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

Does anything need my attention?

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

Alle drei Prompts verwenden denselben Agent, dasselbe Tool und dieselben Komponenten, aber jeder führt zu einer anderen Benutzeroberfläche, die zu Ihrer Anfrage passt.

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 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 <YOUR_PROJECT_ID>

11. Glückwunsch

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

Das haben Sie gelernt

  • A2UI ist ein Protokoll mit 18 deklarativen Primitiven und einigen einfachen Nachrichten, mit denen eine Benutzeroberfläche erstellt wird.
  • Das A2UI SDK generiert Systemprompts, mit denen das LLM den Komponenten-Katalog kennenlernt.
  • Derselbe Agent, dasselbe Tool und dieselben Primitiven bilden unterschiedliche Benutzeroberflächen 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

Weitere Informationen

Hier finden Sie Lernressourcen, mit denen Sie KI-Agenten für Unternehmen mit Gemini Enterprise Agent Ready (GEAR) entwickeln und bereitstellen können.