Interfejs użytkownika generatywny z ADK Agents przy użyciu protokołu A2UI: wiadomości i przykłady
Dowiedz się, w jaki sposób A2UI umożliwia agentowi zwracanie interaktywnego interfejsu użytkownika w formacie JSON, w czym różni się od AG-UI oraz jak uruchomić lokalnie przykład narzędzia do wyszukiwania restauracji Google ADK.
Źródła: Agent to UI Protocol (A2UI) with Agent Development Kit (ADK)
Cztery protokoły są często wymieniane w kontekście agentów wykorzystywanych w rzeczywistych aplikacjach: MCP, A2A, A2UI oraz AG-UI. AG-UI łączy aplikację front-end z backendem agenta i dobrze współpracuje z narzędziem Google Agent Development Kit (ADK). Tym razem skupiamy się na A2UI – protokole o podobnej nazwie, która może wprowadzać w błąd – oraz na sposobie jego uruchamiania z agenta ADK.
Czym jest A2UI
A2UI to protokół generatywnego interfejsu użytkownika stworzony przez Google. Umożliwia agentom AI tworzenie bogatych, interaktywnych interfejsów, które mogą być wyświetlane w przeglądarce, na urządzeniach mobilnych i komputerach stacjonarnych. Załóżmy, że użytkownik pyta: „Jakie są dobre restauracje w Nowym Jorku?”. Agent może nie tylko zwrócić listę tekstową, ale także opis interfejsu, a narzędzie renderujące po stronie klienta przekształca ten opis w interaktywną prezentację restauracji.
Podstawowe koncepcje są opisane na stronie a2ui.org, a najważniejsze informacje mieszczą się w kilku akapitach.
Cztery typy wiadomości
Wszystko, co wysyła agent, ma format JSON, a istnieją tylko cztery rodzaje wiadomości:
createSurfacetworzy nową powierzchnię i określa katalog komponentów, który jest używany.updateComponentsdodaje lub zmienia komponenty interfejsu wewnątrz powierzchni.updateDataModelzmienia stan aplikacji.deleteSurfaceusuwa powierzchnię.
Razem opisują one zarówno interfejs, jak i dane za nim kryjące się:
{
"version": "v0.9",
"createSurface": {
"surfaceId": "main",
"catalogId": "https://a2ui.org/specification/v0_9/basic_catalog.json"
}
}
{
"version": "v0.9",
"updateComponents": {
"surfaceId": "main",
"components": [...]
}
}
{
"version": "v0.9",
"updateDataModel": {
"surfaceId": "main",
"path": "/user",
"value": { "name": "Alice" }
}
}
Katalog komponentów
A2UI dostarcza standardowy katalog, podzielony według przeznaczenia:
- Układ: Rząd, Kolumna i Lista, które służą do układania innych komponentów
- Wyświetlanie: Tekst, Obraz, Ikona, Wideo i Podziałnik, które prezentują informacje
- Interaktywne: Przycisk, Pole tekstowe, Pola wyboru, Pole daty i godziny oraz Suwak, które przyjmują dane
- Kontener: Karta, Karty i Okno modalne, które grupują treść
W referencie komponentów w dokumencacji znajduje się pełna galeria z przykładami.
Rozmowa rezerwacyjna, wiadomość po wiadomości
Przykład rezerwacji w restauracji z dokumentacji dobrze ilustruje cały cykl życia.
Najpierw agent tworzy powierzchnię do komunikacji:
{
"version": "v0.9",
"createSurface": {
"surfaceId": "booking",
"catalogId": "https://a2ui.org/specification/v0_9/basic_catalog.json"
}
}
Po drugie, określa strukturę interfejsu użytkownika:
{
"version": "v0.9",
"updateComponents": {
"surfaceId": "booking",
"components": [
{
"id": "root",
"component": "Column",
"children": ["header", "guests-field", "submit-btn"]
},
{
"id": "header",
"component": "Text",
"text": "Confirm Reservation",
"variant": "h1"
},
{
"id": "guests-field",
"component": "TextField",
"label": "Guests",
"value": { "path": "/reservation/guests" }
},
{
"id": "submit-btn",
"component": "Button",
"child": "submit-text",
"variant": "primary",
"action": {
"event": {
"name": "confirm",
"context": {
"details": { "path": "/reservation" }
}
}
}
}
]
}
}
Po trzecie, wypełnia dane:
{
"version": "v0.9",
"updateDataModel": {
"surfaceId": "booking",
"path": "/reservation",
"value": {
"datetime": "2025-12-16T19:00:00Z",
"guests": "2"
}
}
}
Czwartym krokiem jest zmiana przez użytkownika liczby gości na 3, po czym klient samodzielnie aktualizuje /reservation/guests. Piątym krokiem jest naciśnięcie przez użytkownika przycisku Potwierdź, a wtedy klient wysyła z powrotem informację o wykonanej akcji:
{
"version": "v0.9",
"action": {
"name": "confirm",
"surfaceId": "booking",
"context": {
"details": {
"datetime": "2025-12-16T19:00:00Z",
"guests": "3"
}
}
}
}
Szóste, agent reaguje albo poprzez ponowne aktualizowanie interfejsu użytkownika, albo poprzez zamknięcie powłoki:
{
"version": "v0.9",
"deleteSurface": { "surfaceId": "booking" }
}
Transport i renderowanie
A2UI nie przejmuje się tym, w jaki sposób przemieszczają się wiadomości, ponieważ wystarczy cokolwiek, co potrafi przekazywać dane w formacie JSON. Obecnie obsługiwane są transporty typu A2A i AG-UI, natomiast REST, WebSockets oraz SSE są planowane lub proponowane. Strona dokumentacji poświęcona transportom przedstawia aktualny stan rzeczy.
Gdy agent wygeneruje dane w formacie JSON, renderer przekształca je na komponenty natywne. W środowisku internetowym istnieją renderery typu Lit i Angular, natomiast SDK GenUI od Flutter obsługuje urządzenia mobilne, komputery stacjonarne oraz przeglądarki. Strona poświęcona rendererom zawiera aktualną listę dostępnych rozwiązań.
A2UI i AG-UI obok siebie
Nazwy są podobne, a zadania różne, ale uzupełniające się. AG-UI stanowi połączenie między aplikacją przeznaczoną dla użytkowników a backendem opartym na agentach. A2UI to specyfikacja deklaratywna, której agenty używają do włączania elementów interfejsu użytkownika do swoich odpowiedzi.
Próba użycia przykładów
Repozytorium A2UI zawiera przykłady agentów ADK, które można wygenerować i uruchomić lokalnie. Najpierw sklonuj je:
git clone https://github.com/google/a2ui.git
cd a2ui
Ustaw klucz API Gemini:
export GEMINI_API_KEY="your_gemini_api_key_here"
Każdy przykład składa się z części serwerowej (agenta) i części klienckiej (renderera), przy czym obie muszą być uruchomione. Przykłady agentów ADK znajdują się w folderze adk, w podfolderze samples/agent, natomiast renderery klienckie – w folderze samples/client.
Nawigator restauracji
Z folderu samples/client/lit pojedynczy polecenie uruchamia demonstrację:
npm run demo:restaurant
Otwórz http://localhost:5173/?app=restaurant i zacznij zadawać pytania, na przykład „5 najlepszych restauracji chińskich w Nowym Jorku”. Agent generuje interfejs użytkownika, który następnie jest renderowany przez klienta:
Logi pokazują surowy plik JSON A2UI wysłany przez agenta:
[REST] LiteLLM completion() model= gemini-2.5-flash; provider = gemini
[REST] INFO:agent:Event from runner: model_version='gemini-2.5-flash' content=Content(
[REST] parts=[
[REST] Part(
[REST] text="""<a2ui-json>
[REST] [
[REST] {
[REST] "beginRendering": {
[REST] "surfaceId": "default",
[REST] "root": "root-column",
[REST] "styles": {
[REST] "primaryColor": "#FF0000",
[REST] "font": "Roboto"
[REST] }
[REST] }
[REST] },
[REST] {
[REST] "surfaceUpdate": {
[REST] "surfaceId": "default",
[REST] "components": [
[REST] {
[REST] "id": "root-column",
[REST] "component": {
[REST] "Column": {
[REST] "children": {
[REST] "explicitList": [
[REST] "title-heading",
[REST] "item-list"
[REST] ]
[REST] }
[REST] }
[REST] }
[REST] },
...
Co dzieje się w środku
Kod agenta znajduje się w samples/agent/adk/restaurant_finder. Plik prompt_builder.py pokazuje, w jaki sposób budowany jest prompt, aby agent mógł odpowiadać w formacie A2UI. Opis roli zaczyna się od wyraźnej instrukcji, że ostateczny wynik musi być odpowiedzią w formacie JSON A2UI:
ROLE_DESCRIPTION = (
"You are a helpful restaurant finding assistant. Your final output MUST be a a2ui"
" UI JSON response."
)
UI_DESCRIPTION = """
- If the query is for a list of restaurants, use the restaurant data you have already received from the `get_restaurants` tool to populate the `dataModelUpdate.contents` array (e.g., as a `valueMap` for the "items" key).
- If the number of restaurants is 5 or fewer, you MUST use the `SINGLE_COLUMN_LIST_EXAMPLE` template.
- If the number of restaurants is more than 5, you MUST use the `TWO_COLUMN_LIST_EXAMPLE` template.
- If the query is to book a restaurant (e.g., "USER_WANTS_TO_BOOK..."), you MUST use the `BOOKING_FORM_EXAMPLE` template.
- If the query is a booking submission (e.g., "User submitted a booking..."), you MUST use the `CONFIRMATION_EXAMPLE` template.
"""
Klasa A2uiSchemaManager ładuje katalogi komponentów i tworzy instrukcje systemowe, które pomagają modelowi w prawidłowym formacie A2UI JSON. Wywołanie metody generate_system_prompt łączy opis roli agenta z schematem oraz kilkoma przykładami, dzięki czemu model otrzymuje dokładne wskazówki dotyczące formatowania:
version = VERSION_0_9
restaurant_prompt = A2uiSchemaManager(
version,
catalogs=[
BasicCatalog.get_config(
version=version,
examples_path=f"examples/{version}",
)
],
schema_modifiers=[remove_strict_validation],
).generate_system_prompt(
role_description=ROLE_DESCRIPTION,
ui_description=UI_DESCRIPTION,
include_schema=True,
include_examples=True,
validate_examples=True,
)
agent.py tworzy następnie agenta z tym promptem systemowym:
return LlmAgent(
model=LiteLlm(model=LITELLM_MODEL),
name="restaurant_agent",
description="An agent that finds restaurants and helps book tables.",
instruction=instruction,
tools=[get_restaurants],
)
Po wysłaniu JSON przez agenta, należy je zweryfikować pod kątem schematu A2UI przed przesłaniem do klienta:
# --- Validation Steps ---
# Check if it validates against the A2UI_SCHEMA
# This will raise jsonschema.exceptions.ValidationError if it fails
logger.info(
"--- RestaurantAgent.stream: Validating against A2UI_SCHEMA... ---"
)
selected_catalog.validator.validate(parsed_json_data)
Dokumentacja ADK zawiera stronę integracji z A2UI z bardziej szczegółowymi informacjami. Po stronie klienta plik renderers/lit zawiera implementację Lit, która bierze wygenerowany JSON i go renderuje.
Narzędzia do rozpoczęcia pracy
CopilotKit udostępnia szablon początkowy A2UI oraz narzędzie A2UI Composer do eksperymentowania z komponentami.
Korzystnymi źródłami dalszej lektury są dokumentacja i specyfikacja protokołu A2UI, repozytorium na GitHubie, post ogłoszeniowy Googlea na temat interfejsów sterowanych agentami, strona integracji ADK, narzędzie CopilotKit Composer oraz szablon początkowy, a także kilka filmów na YouTube o agentach tworzących interfejsy w czasie rzeczywistym.
Powiązane materiały
- Praktyczne notatki: Agencyjny SDLC: Jak AI przekształca rozwój oprogramowania — Szczegółowy przewodnik po Praktycznych notatkach: Agencyjny SDLC: Jak AI przekształca rozwój oprogramowania: umowy, sprawdzania oraz gotowe elementy kodu dostępne dla zespołów wdrażających ten model.
- Wybór partnera do rozwoju agentów AI: pytania wykraczające poza demonstrację — Jak ocenić dostawców agentów w 2026 roku: określenie zakresu pracy, integracje, uprawnienia, wiedza, testy awaryjne, widoczność wdrożenia, przegląd przez człowieka oraz odpowiedzialność po uruchomieniu.