Генеративний інтерфейс користувача від ADK Agents за допомогою протоколу A2UI: повідомлення та зразки
Дізнайтеся, як A2UI дозволяє агенту повертати інтерактивний інтерфейс користувача у форматі JSON, чим він відрізняється від AG-UI, та як запустити приклад пошуку ресторанів Google ADK локально.
Джерела: Agent to UI Protocol (A2UI) with Agent Development Kit (ADK)
Чотири протоколи часто згадуються, коли агенти використовуються у реальних додатках: MCP, A2A, A2UI та AG-UI. AG-UI з’єднує фронтенд-додаток із бекендом агента та добре поєднується з набором для розробки агентів від Google (ADK). Увага тут приділяється A2UI – протоколу з схожою назвою, яка може вводити в оману, та способам його використання з агента ADK.
Що таке A2UI
A2UI – це протокол генеративного інтерфейсу від Google. Він дозволяє штучним інтелектуальним агентам створювати насичені, інтерактивні інтерфейси, які можуть відображатися у веб-браузерах, мобільних пристроях та на десктопах. Наприклад, якщо користувач запитає: «Які є хороші ресторани в Нью-Йорку?», агент може не лише надати текстовий список, а й опис інтерфейсу; потім движок на клієнтській стороні перетворює цей опис на інтерактивне відображення ресторанів.
Основні концепції описані на сайті a2ui.org, і всі ключові моменти можна охарактеризувати за кілька абзаців.
Чотири типи повідомлень
Усе, що надсилає агент, — це JSON, і існує лише чотири види повідомлень:
createSurfaceстворює нову поверхню та вказує, який каталог компонентів вона використовує.updateComponentsдодає або змінює компоненти інтерфейсу всередині поверхні.updateDataModelзмінює стан додатку.deleteSurfaceвидаляє поверхню.
Разом вони описують як інтерфейс, так і дані, що стоять за ним:
{
"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" }
}
}
Каталог компонентів
A2UI постачає стандартний каталог, розділений за призначенням:
- Макетування: Рядок, Колонка та Список – для організації інших компонентів
- Відображення: Текст, Зображення, Іконка, Відео та Розділювач – для представлення інформації
- Інтерактивність: Кнопка, Поле введення тексту, Поле для позначки галочкою, Введення дати та Шкала – для отримання вхідних даних
- Контейнери: Картка, Вкладки та Модальне вікно – для групування контенту
У документації є повна галерея компонентів із прикладами.
Розмова про бронювання, повідомлення за повідомленням
Приклад бронювання в ресторані з документації чудово ілюструє цикл життя.
Спочатку агент створює поверхню:
{
"version": "v0.9",
"createSurface": {
"surfaceId": "booking",
"catalogId": "https://a2ui.org/specification/v0_9/basic_catalog.json"
}
}
По-друге, він визначає структуру інтерфейсу користувача:
{
"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" }
}
}
}
}
]
}
}
По-третє, воно заповнює дані:
{
"version": "v0.9",
"updateDataModel": {
"surfaceId": "booking",
"path": "/reservation",
"value": {
"datetime": "2025-12-16T19:00:00Z",
"guests": "2"
}
}
}
Четверте, користувач змінює кількість гостей на 3, і клієнт самостійно оновлює /reservation/guests. П’яте, користувач натискає «Підтвердити», і клієнт надсилає повідомлення про виконану дію:
{
"version": "v0.9",
"action": {
"name": "confirm",
"surfaceId": "booking",
"context": {
"details": {
"datetime": "2025-12-16T19:00:00Z",
"guests": "3"
}
}
}
}
Шосте, агент реагує або шляхом знову оновлення інтерфейсу, або шляхом закриття вікна:
{
"version": "v0.9",
"deleteSurface": { "surfaceId": "booking" }
}
Транспортування та відображення
A2UI не цікавить те, як передаються повідомлення, адже підходить будь-що, що може передавати JSON. Наразі підтримуються транспорти A2A та AG-UI, тоді як REST, WebSockets та SSE знаходяться у планах або пропонуються. На сторінці з транспортами в документації перелічено поточні варіанти.
Як тільки агент створює JSON, рендерер перетворює його на нативні компоненти. Для вебу існують рендерери Lit та Angular, а SDK GenUI від Flutter підтримує мобільні пристрої, десктоп та веб. На сторінці з рендерерами наведений актуальний перелік.
A2UI та AG-UI поруч
Назви схожі, а завдання різні, але взаємодоповнюючі. AG-UI є зв’язком між додатком, орієнтованим на користувача, та бекендом агентів. A2UI — це декларативна специфікація, яку агенти використовують для повернення UI-віджетів у своїх відповідях.
Спроба зразків
Репозиторій A2UI містить зразки агентів ADK, які можна створити та відтворити локально. Спочатку клонуйте його:
git clone https://github.com/google/a2ui.git
cd a2ui
Встановіть ключ API Gemini:
export GEMINI_API_KEY="your_gemini_api_key_here"
Кожен зразок має серверну частину (агента) та клієнтську частину (рендерера), і обидві мають працювати. Зразки агентів ADK знаходяться у папці adk внутрішньо папки samples/agent, а клієнтські рендерери — у папці samples/client.
Знахідник ресторанів
З папки samples/client/lit один командний запит запускає демо:
npm run demo:restaurant
Відкрийте http://localhost:5173/?app=restaurant та почніть ставити запитання, наприклад „Топ-5 китайських ресторанів у Нью-Йорку“. Агент генерує інтерфейс, а клієнт його відображає:
У журналах записується необроблений JSON формату A2UI, який надіслав агент:
[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] },
...
Що відбувається всередині
Код агента знаходиться у samples/agent/adk/restaurant_finder. Файл prompt_builder.py демонструє, як створюється запит, щоб агент відповідав у форматі A2UI. Опис ролі починається з чіткого завдання — кінцевий результат має бути 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.
"""
Клас A2uiSchemaManager завантажує каталоги компонентів та створює системні запитання, які допомагають моделі розуміти правильний формат JSON A2UI. Виклик функції generate_system_prompt поєднує опис ролі агента зі схемою та кількома прикладами, що забезпечує моделі чіткі вказівки щодо форматування:
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 створює агента з цим системним запитом:
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],
)
Після того, як агент генерує JSON, його слід перевірити за схемою A2UI перед трансляцією клієнту:
# --- 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)
У документації ADK є сторінка інтеграції з A2UI з більш детальною інформацією. З боку клієнта renderers/lit містить реалізацію Lit, яка бере генерований JSON та відображає його.
Інструменти для початку роботи
CopilotKit публікує шаблон-стартер для A2UI, а також A2UI Composer для експериментування з компонентами.
Корисними джерелами для подальшого читання є документація та специфікація протоколу A2UI, репозиторій на GitHub, пост Google про інтерфейси, керовані агентами, сторінка інтеграції ADK, CopilotKit Composer та стартер, а також кілька відео на YouTube про створення UI агентами в реальному часі.