1. Przegląd
Większość agentów AI odpowiada tekstowo. W tym ćwiczeniu z programowania użyjesz A2UI, aby umożliwić agentowi odpowiadanie za pomocą interfejsu. Agent opisuje karty, listy, przyciski i formularze w formacie JSON, korzystając z katalogu standardowych komponentów, a klient renderuje je za pomocą własnych natywnych widżetów, więc nowe układy nie wymagają nowego kodu interfejsu.
Agenta utworzysz za pomocą pakietu Agent Development Kit (ADK).
Co utworzysz
Przykładowy panel infrastruktury w chmurze w 3 etapach:
- Standardowy agent, który zwraca dane zasobów w formie zwykłego tekstu.
- Agent A2UI, który zwraca te same dane co uporządkowany plik JSON A2UI
- Wyrenderowany agent, który wyświetla kod JSON A2UI jako interaktywne komponenty interfejsu w interfejsie deweloperskim ADK.
Czego się nauczysz
- Jak działa A2UI: 18 elementów podstawowych, wiadomości tworzące interfejs i płaski model komponentów
- Jak używać pakietu A2UI SDK, aby poprosić agenta ADK o wygenerowanie kodu JSON A2UI
- Jak renderować komponenty A2UI w
adk web
Czego potrzebujesz
- Projekt Google Cloud z włączonymi płatnościami
- przeglądarka, np. Chrome;
- Python 3.12+ i uv, jeśli uruchamiasz kod na własnym komputerze zamiast w Cloud Shell
To ćwiczenie jest przeznaczone dla średnio zaawansowanych programistów, którzy znają już Pythona i Google Cloud.
Wykonanie tego laboratorium zajmie około 20 minut.
Zasoby utworzone w tym module powinny kosztować mniej niż 5 USD.
2. Konfigurowanie środowiska
Tworzenie projektu Google Cloud
- W konsoli Google Cloud na stronie wyboru projektu wybierz lub utwórz projekt w chmurze Google Cloud.
- Sprawdź, czy w projekcie Cloud włączone są płatności. Dowiedz się, jak sprawdzić, czy w projekcie są włączone płatności.
Uruchamianie edytora Cloud Shell
Aby uruchomić sesję Cloud Shell w konsoli Google Cloud, kliknij Aktywuj Cloud Shell.
Spowoduje to uruchomienie sesji w dolnym panelu konsoli Google Cloud.
Aby uruchomić edytor, na pasku narzędzi w oknie Cloud Shell kliknij Otwórz edytor.
Włącz interfejsy API
Na pasku narzędzi edytora Cloud Shell kliknij Terminal i Nowy terminal, a następnie uruchom to polecenie, aby włączyć wymagane interfejsy API:
gcloud services enable aiplatform.googleapis.com
Instalowanie zależności
Aby utworzyć folder na potrzeby tego ćwiczenia, a w nim folder a2ui_agent na kod agenta, i zainstalować pakiet Agent Development Kit (ADK) oraz pakiet A2UI SDK, uruchom w terminalu te polecenia:
mkdir -p ~/adk-a2ui/a2ui_agent cd ~/adk-a2ui uv init --bare uv add google-adk a2ui-agent-sdk
uv tworzy izolowane środowisko Pythona na potrzeby tego ćwiczenia, więc nie musisz niczego aktywować. Polecenia Pythona poprzedzaj znakiem uv run.
3. Tworzenie agenta
Zacznij od standardowego agenta ADK, który zwraca zwykły tekst. Tak obecnie wygląda większość aplikacji agentów.
Konfigurowanie ustawień projektu
W terminalu uruchom to polecenie, aby utworzyć a2ui_agent/.env z użyciem projektu i lokalizacji oraz aby pakiet ADK wywoływał Gemini za pomocą Twojego projektu w chmurze Google. ADK automatycznie wczytuje ten plik, więc ustawienia działają też na nowych terminalach.
cat > ~/adk-a2ui/a2ui_agent/.env <<EOF GOOGLE_CLOUD_PROJECT=$(gcloud config get project) GOOGLE_CLOUD_LOCATION=global GOOGLE_GENAI_USE_ENTERPRISE=True EOF
Zdefiniuj narzędzie i dane próbne
Utwórz plik a2ui_agent/resources.py z tą zawartością. To narzędzie zwraca listę zasobów w chmurze wraz z ich stanem.
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
Zdefiniuj agenta
Utwórz plik a2ui_agent/agent.py z tą zawartością:
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. Testowanie agenta
ADK zawiera interfejs programisty, którego możesz używać do interakcji z agentem i wysyłania do niego promptów w przeglądarce na potrzeby testowania.
Uruchamianie interfejsu programistycznego pakietu ADK
W terminalu edytora Cloud Shell uruchom to polecenie, aby otworzyć interfejs programisty ADK:
uv run adk web --port 8080 --allow_origins "*" --reload_agents
Wyświetli się komunikat podobny do tego:
+-----------------------------------------------------------------------------+ | ADK Web Server started | | | | For local testing, access at http://127.0.0.1:8080. | +-----------------------------------------------------------------------------+
Otwórz interfejs programisty pakietu ADK
Interfejs programisty ADK możesz otworzyć w przeglądarce, klikając adres URL testowania lokalnego z naciśniętym klawiszem Ctrl lub Cmd albo klikając przycisk Podgląd w przeglądarce i wybierając Podejrzyj na porcie 8080.
Gdy wyświetli się interfejs programisty ADK, w menu kliknij a2ui_agent.
Wysyłanie przykładowych promptów
Wyślij do agenta przykładowy prompt:
What's running in my project?
Teraz wypróbuj inny prompt, aby uzyskać więcej tekstu:
Does anything need my attention?
Twoja rozmowa powinna wyglądać podobnie do tej poniżej:
Odpowiedź jest dokładna, ale to ściana tekstu.
5. Generowanie kodu JSON A2UI
Następnie przełącz agenta z trybu zwykłego tekstu na A2UI.
Pakiet SDK A2UI dla Pythona zawiera generator promptów, który tworzy prompty systemowe. Uczy ona LLM pełnego katalogu komponentów A2UI, prawidłowych nazw i typów właściwości oraz struktury JSON.
Aktualizowanie agenta
Zamień zawartość pliku a2ui_agent/agent.py na taką:
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 wyświetla kod JSON interfejsu A2UI w postaci tekstu, dzięki czemu możesz go odczytać. Później usuniesz go, aby zobaczyć renderowanie interfejsu.
Metoda prompt_generator.generate() łączy opis roli z pełnym schematem JSON interfejsu A2UI i przykładami few-shot, dzięki czemu LLM dokładnie wie, jak sformatować dane wyjściowe. Nie musisz ręcznie tworzyć katalogu komponentów.
W tym ćwiczeniu używana jest wersja 0.8 protokołu A2UI (version="0.8"), która jest obsługiwana przez moduł renderujący A2UI adk web.
6. Testowanie danych wyjściowych JSON
Jeśli interfejs deweloperski ADK jest nadal uruchomiony, powinien automatycznie ponownie wczytać zmiany wprowadzone w agencie.
Kliknij a2ui_agent, rozpocznij nową sesję, klikając + Nowa sesja w prawym górnym rogu interfejsu programisty ADK, a następnie wyślij ten sam prompt co wcześniej:
What's running in my project?
Tym razem agent odpowiada w formacie JSON A2UI zamiast w formie zwykłego tekstu. W wyniku czatu zobaczysz uporządkowane wiadomości, takie jak beginRendering i surfaceUpdate (a czasami dataModelUpdate), w bloku kodu JSON.
Plik JSON opisuje rozbudowany interfejs z kartami, ikonami i przyciskami, ale show_raw_json zachowuje go w formie tekstu, aby można było go odczytać. Następnie zobaczysz, jak jest zbudowany ten kod JSON, a potem usuniesz show_raw_json, aby wyrenderować go jako rzeczywiste komponenty interfejsu.
7. Informacje o A2UI
Sprawdź plik JSON wygenerowany przez agenta. A2UI ma 3 typy wiadomości do tworzenia interfejsu. Dane wyjściowe agenta nie muszą zawsze korzystać z tych 3 elementów:
1. beginRendering
Tworzy powierzchnię renderowania i nadaje nazwę komponentowi głównemu:
{"beginRendering": {"surfaceId": "default", "root": "main-column"}}
2. surfaceUpdate
Wysyła drzewo komponentów jako płaską listę z odwołaniami do identyfikatorów (nie zagnieżdżoną):
{"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
Wysyła dane oddzielnie od struktury:
{"dataModelUpdate": {"surfaceId": "default", "contents": [
{"key": "service_name", "valueString": "auth-service"},
{"key": "status", "valueString": "healthy"}
]}}
Komponenty są powiązane z danymi za pomocą {"path": "key"}. Możesz aktualizować dane bez ponownego wysyłania drzewa komponentów.
18 podstawowych kształtów
Kategoria | Komponenty |
Układ | Karta, Kolumna, Wiersz, Lista, Karty, Linia podziału, Okno modalne |
Wyświetlacz | Tekst, obraz, ikona, film, odtwarzacz audio |
Wejście | TextField, DateTimeInput, MultipleChoice, CheckBox, Slider |
Działanie | Przycisk |
Agent tworzy różne układy, takie jak widok przeglądania, panel priorytetowy lub formularz konfiguracji, z tych samych komponentów. Szczegółowe informacje o każdym z nich znajdziesz w dokumentacji komponentów.
8. Renderowanie komponentów A2UI
Pakiet SDK umieszcza A2UI w standardowych tagach adk web rozpoznaje je i renderuje komponenty za pomocą wbudowanego renderera A2UI. Aby go zobaczyć, usuń show_raw_json.
Aktualizowanie agenta
Zastąp zawartość pliku a2ui_agent/agent.py tym kodem: Jedyną zmianą w stosunku do poprzedniego kroku jest brak funkcji show_raw_json, jej parametru after_model_callback i 2 importów, z których korzystała:
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. Testowanie renderowanego interfejsu
Jeśli interfejs deweloperski ADK jest nadal uruchomiony, powinien automatycznie ponownie wczytać zmiany wprowadzone w agencie.
Odśwież kartę przeglądarki, wybierz a2ui_agent, a potem rozpocznij nową sesję, klikając + Nowa sesja w prawym górnym rogu interfejsu programisty ADK. Wyślij ten sam prompt co wcześniej:
What's running in my project?
Tym razem adk web renderuje komponenty A2UI jako rzeczywisty interfejs: karty ze wskaźnikami stanu, szczegółami zasobów i przyciskami działań.
Wypróbuj inny prompt, aby zobaczyć, jak agent tworzy inny interfejs z tego samego zestawu elementów podstawowych:
Does anything need my attention?
Na koniec spróbuj użyć innego prompta, aby wygenerować inny interfejs do wdrożenia nowej usługi:
I need to deploy a new service
Wszystkie 3 prompty korzystają z tego samego agenta, narzędzia i komponentów, ale każdy z nich generuje inny interfejs, który odpowiada Twojemu zapytaniu.
10. Czyszczenie
Aby uniknąć pozostawienia uruchomionych serwerów lokalnych, zwolnij miejsce na zasoby:
- W terminalu, w którym działa
adk web, naciśnij Ctrl+C, aby zatrzymać serwer agenta.
Jeśli Twój projekt został utworzony specjalnie na potrzeby tego ćwiczenia, możesz go usunąć w całości:
gcloud projects delete <YOUR_PROJECT_ID>
11. Gratulacje
Masz agenta ADK, który generuje bogaty, interaktywny interfejs użytkownika za pomocą protokołu A2UI.
Czego się dowiedzieliśmy
- A2UI to protokół z 18 deklaratywnymi elementami i kilkoma prostymi komunikatami, które tworzą interfejs.
- Pakiet SDK A2UI generuje prompty systemowe, które uczą LLM katalogu komponentów.
- Ten sam agent, narzędzie i elementy pierwotne tworzą różne interfejsy użytkownika dla różnych zamiarów.
- Komponenty A2UI można renderować bezpośrednio w
adk webpodczas programowania.
Tworzenie frontendu produkcyjnego
W tym ćwiczeniu renderujesz A2UI w adk web na potrzeby programowania i testowania.
W przypadku środowiska produkcyjnego możesz utworzyć interfejs za pomocą jednego z oficjalnych modułów renderujących A2UI:
Platforma | Mechanizm renderowania | Zainstaluj |
Internet (React) |
|
|
Web (Lit) |
|
|
Web (Angular) |
|
|
Urządzenia mobilne/komputery | Flutter GenUI SDK |
Dokumentacja
- Specyfikacja i dokumentacja A2UI
- Repozytorium A2UI w GitHubie
- Mechanizmy renderowania A2UI
- Dokumentacja pakietu ADK
- Integracja ADK A2UI
Co dalej?
Zapoznaj się z materiałami edukacyjnymi, aby tworzyć i wdrażać agenty klasy korporacyjnej za pomocą Gemini Enterprise Agent Ready (GEAR).