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:
- Ein Standard-Agent, der Ressourcendaten als Klartext zurückgibt
- Ein A2UI-Agent, der dieselben Daten wie strukturierte A2UI-JSON zurückgibt
- Ein gerenderter KI-Agent, der das A2UI-JSON als interaktive UI-Komponenten in der ADK-Entwicklungsoberfläche anzeigt

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 webrendern
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
- Wählen Sie in der Google Cloud Console auf der Seite zur Projektauswahl ein Google Cloud-Projekt aus oder erstellen Sie eines.
- 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:

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.

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.

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 webausgefü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 webgerendert 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) |
|
|
Web (Lit) |
|
|
Web (Angular) |
|
|
Mobilgerät/Computer | Flutter GenUI SDK |
Referenzdokumente
- A2UI-Spezifikation und -Dokumentation
- A2UI-GitHub-Repository
- A2UI-Renderer
- ADK-Dokumentation
- ADK-A2UI-Integration
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.