Головна / Статті

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