Главная / Статьи

Генеративный интерфейс пользователя от ADK Agents с протоколом A2UI: сообщения и примеры

Узнайте, как A2UI позволяет агенту возвращать интерактивный интерфейс в формате JSON, в чём его отличие от AG-UI, и как запустить пример поиска ресторанов Google ADK локально.

Издатель: REACTAPP.TOP6 мин чтения1361 слов

Источники: 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 о создании интерфейсов агентами в реальном времени.