Генеративный интерфейс пользователя от 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 о создании интерфейсов агентами в реальном времени.