Разработка пользовательского интерфейса с использованием ADK и A2UI

1. Обзор

Большинство агентов ИИ отвечают текстом. В этом практическом занятии вы будете использовать A2UI , чтобы ваш агент отвечал пользовательским интерфейсом. Агент описывает карточки, списки, кнопки и формы в формате JSON, используя каталог стандартных компонентов, а клиент отображает их с помощью собственных виджетов, поэтому для новых макетов не требуется новый код фронтенда.

Агент будет создан с помощью комплекта разработки агентов (ADK) .

Что вы построите

Имитация панели мониторинга облачной инфраструктуры в три этапа:

  1. Стандартный агент , возвращающий данные ресурсов в виде обычного текста.
  2. Агент A2UI , возвращающий те же данные, что и структурированный JSON-файл A2UI.
  3. Агент , отображающий JSON-данные A2UI в виде интерактивных компонентов пользовательского интерфейса в среде разработки ADK.

Агент ADK A2UI

Что вы узнаете

  • Принцип работы A2UI: 18 примитивов, сообщения, формирующие пользовательский интерфейс, и модель плоских компонентов.
  • Как использовать SDK A2UI для того, чтобы заставить агент ADK сгенерировать JSON-файл A2UI.
  • Как отображать компоненты A2UI в adk web

Что вам понадобится

  • Проект Google Cloud с включенной функцией выставления счетов.
  • Веб-браузер, например Chrome.
  • Python 3.12+ и uv , если вы запускаете код на своем компьютере, а не в Cloud Shell.

Этот практический урок предназначен для разработчиков среднего уровня, имеющих некоторое представление о Python и Google Cloud.

Выполнение этого практического задания займет приблизительно 20 минут.

Стоимость ресурсов, созданных в рамках этого практического занятия, должна составлять менее 5 долларов.

2. Настройте свою среду.

Создайте проект в Google Cloud.

  1. В консоли Google Cloud на странице выбора проекта выберите или создайте проект Google Cloud .
  2. Убедитесь, что для вашего облачного проекта включена функция выставления счетов. Узнайте, как проверить, включена ли функция выставления счетов для проекта .

Запустить редактор CloudShell

Чтобы запустить сеанс Cloud Shell из консоли Google Cloud, нажмите кнопку «Активировать Cloud Shell» в консоли Google Cloud.

Это запустит сессию в нижней панели вашей консоли Google Cloud.

Чтобы запустить редактор, нажмите кнопку «Открыть редактор» на панели инструментов окна Cloud Shell.

Включить API

На панели инструментов редактора Cloud Shell нажмите «Терминал» и «Новый терминал» , затем выполните следующую команду, чтобы включить необходимые API:

gcloud services enable aiplatform.googleapis.com

Установите зависимости

В терминале выполните следующие команды, чтобы создать папку для этого практического занятия, внутри которой будет папка a2ui_agent для вашего кода агента, а также установить Agent Development Kit (ADK) и A2UI SDK:

mkdir -p ~/adk-a2ui/a2ui_agent
cd ~/adk-a2ui
uv init --bare
uv add google-adk a2ui-agent-sdk

uv создает изолированную среду Python для этого практического занятия, поэтому вам не нужно ничего активировать. Добавляйте префикс uv run к командам Python.

3. Создайте агента.

Начните со стандартного агента ADK, который возвращает обычный текст. Именно так выглядит большинство современных приложений-агентов.

Настройте параметры проекта.

В терминале выполните следующую команду, чтобы создать файл a2ui_agent/.env с указанием вашего проекта и местоположения, а также чтобы ADK вызывал Gemini через ваш проект Google Cloud. ADK загружает этот файл автоматически, поэтому настройки будут работать и в новых терминалах.

cat > ~/adk-a2ui/a2ui_agent/.env <<EOF
GOOGLE_CLOUD_PROJECT=$(gcloud config get project)
GOOGLE_CLOUD_LOCATION=global
GOOGLE_GENAI_USE_ENTERPRISE=True
EOF

Определите инструмент и имитационные данные.

Создайте файл a2ui_agent/resources.py со следующим содержимым. Этот инструмент возвращает список облачных ресурсов с указанием их статуса.

RESOURCES = [
    {
        "name": "auth-service",
        "type": "Cloud Run",
        "region": "us-west1",
        "status": "healthy",
        "cpu": "2 vCPU",
        "memory": "1 GiB",
        "instances": 3,
        "url": "https://auth-service-abc123.run.app",
        "last_deployed": "2026-04-18T14:22:00Z",
    },
    {
        "name": "events-db",
        "type": "Cloud SQL",
        "region": "us-east1",
        "status": "warning",
        "tier": "db-custom-8-32768",
        "storage": "500 GB SSD",
        "connections": 195,
        "version": "PostgreSQL 16",
        "issue": "Storage usage at 92%",
    },
    {
        "name": "analytics-pipeline",
        "type": "Cloud Run",
        "region": "us-west1",
        "status": "error",
        "cpu": "2 vCPU",
        "memory": "4 GiB",
        "instances": 0,
        "url": "https://analytics-pipeline-ghi789.run.app",
        "last_deployed": "2026-04-10T16:45:00Z",
        "issue": "CrashLoopBackOff: OOM killed",
    },
]

def get_resources() -> list[dict]:
    """Get all cloud resources in the current project.
    Returns a list of cloud infrastructure resources including their
    name, type, region, status, and type-specific details.
    Status is one of: healthy, warning, error. Resources with
    warning or error status include an 'issue' field describing
    the problem.
    """
    return RESOURCES

Определите агента

Создайте a2ui_agent/agent.py со следующим содержимым:

from google.adk.agents import Agent
from google.adk.models import Gemini
from google.genai import types
from .resources import get_resources

root_agent = Agent(
    model=Gemini(
        model="gemini-3.8-flash",
        retry_options=types.HttpRetryOptions(attempts=5),
    ),
    name="cloud_dashboard",
    description="A cloud infrastructure assistant that reports on project resources.",
    instruction=(
        "You are a cloud infrastructure assistant. When users ask about their "
        "cloud resources, use the get_resources tool to fetch the current state. "
        "Summarize the results clearly in plain text."
    ),
    tools=[get_resources],
)

4. Проверьте агента.

ADK включает в себя пользовательский интерфейс для разработчиков, который можно использовать для взаимодействия с агентом и отправки ему запросов в браузере для тестирования.

Запуск пользовательского интерфейса разработчика ADK

В терминале Cloud Shell Editor выполните следующую команду, чтобы запустить пользовательский интерфейс разработчика ADK:

uv run adk web --port 8080 --allow_origins "*" --reload_agents

Вы должны увидеть сообщение, похожее на следующее:

+-----------------------------------------------------------------------------+
| ADK Web Server started                                                      |
|                                                                             |
| For local testing, access at http://127.0.0.1:8080.                         |
+-----------------------------------------------------------------------------+

Откройте пользовательский интерфейс разработчика ADK.

Вы можете открыть пользовательский интерфейс разработчика ADK в браузере, щелкнув по локальному тестовому URL-адресу с помощью клавиши Ctrl или Cmd , или нажав кнопку « Предварительный просмотр веб-страницы» и выбрав «Предварительный просмотр на порту 8080» .

После того, как вы откроете пользовательский интерфейс разработчика ADK, выберите a2ui_agent из выпадающего меню.

Пришлите примеры подсказок

Отправьте агенту пример голосового сообщения:

What's running in my project?

Теперь попробуйте другой пример запроса, и вы получите больше текстового вывода:

Does anything need my attention?

Ваш диалог должен выглядеть примерно так:

ADK Текстовый Агент

Ответ точный, но это сплошной текст.

5. Сгенерировать JSON-файл A2UI

Далее переключите агент с обычного текстового интерфейса на A2UI.

В состав A2UI Python SDK входит генератор подсказок, который автоматически формирует системные подсказки. Он обучает LLM работе с полным каталогом компонентов A2UI, правильным именам и типам свойств, а также структуре JSON.

Обновите агента

Замените содержимое файла a2ui_agent/agent.py следующим:

from google.adk.agents import Agent
from google.adk.agents.callback_context import CallbackContext
from google.adk.models import Gemini
from google.adk.models.llm_response import LlmResponse
from google.genai import types
from a2ui.inference_formats.direct_json import DirectJsonFormat
from a2ui.basic_catalog.provider import BasicCatalog
from .resources import get_resources

a2ui_format = DirectJsonFormat(
    version="0.8",
    catalogs=[BasicCatalog.get_config("0.8")],
)

instruction = a2ui_format.prompt_generator.generate(
    role_description=(
        "You are a cloud infrastructure assistant. When users ask about "
        "their cloud resources, use the get_resources tool to fetch the "
        "current state."
    ),
    workflow_description=(
        "Analyze the user's request and return structured UI when appropriate."
    ),
    ui_description=(
        "Use cards for resource summaries, rows and columns for comparisons, "
        "icons for status indicators, and buttons for drill-down actions. "
        "Do NOT use markdown formatting in text values. Use the usageHint "
        "property for heading levels instead. "
        "Respond ONLY with the A2UI JSON array. Do NOT include any text "
        "outside the JSON. Put all explanations into Text components."
    ),
    include_schema=True,
    include_examples=True,
)


def show_raw_json(
    callback_context: CallbackContext,
    llm_response: LlmResponse,
) -> LlmResponse | None:
    """Show the A2UI JSON as text so you can read it, instead of rendering it."""
    if not llm_response.content or not llm_response.content.parts:
        return None
    for part in llm_response.content.parts:
        if part.text:
            part.text = (
                part.text
                .replace("<a2ui-json>", "```json\n")
                .replace("</a2ui-json>", "\n```")
            )
    return llm_response


root_agent = Agent(
    model=Gemini(
        model="gemini-3.8-flash",
        retry_options=types.HttpRetryOptions(attempts=5),
    ),
    name="cloud_dashboard",
    description="A cloud infrastructure assistant that renders rich A2UI interfaces.",
    instruction=instruction,
    tools=[get_resources],
    after_model_callback=show_raw_json,
)

show_raw_json отображает JSON-данные A2UI в текстовом виде, чтобы вы могли их прочитать. Позже вы удалите её, чтобы увидеть отрисовку пользовательского интерфейса.

Метод prompt_generator.generate() объединяет описание вашей роли с полной JSON-схемой A2UI и несколькими примерами, поэтому LLM точно знает, как форматировать свой вывод. Вам не нужно писать каталог компонентов вручную.

В этом практическом занятии используется версия A2UI 0.8 ( version="0.8" ), которая является версией, поддерживаемой adk web .

6. Проверьте вывод в формате JSON.

Если у вас всё ещё запущен пользовательский интерфейс разработчика ADK, созданный ранее, он должен автоматически перезагрузить изменения, внесённые вами в агент.

Выберите a2ui_agent , начните новую сессию, нажав кнопку «+Новая сессия» в правом верхнем углу пользовательского интерфейса разработчика ADK, затем отправьте тот же запрос, что и раньше:

What's running in my project?

На этот раз агент отвечает JSON-данными A2UI вместо обычного текста. В выводе чата вы увидите структурированные сообщения, такие как beginRendering и surfaceUpdate (а иногда dataModelUpdate ), в виде блока JSON-кода.

ADK A2UI JSON

JSON-объект описывает многофункциональный пользовательский интерфейс с карточками, иконками и кнопками, но show_raw_json сохраняет его в текстовом виде, чтобы вы могли его прочитать. Далее вы посмотрите, как структурирован этот JSON, а затем удалите show_raw_json , чтобы отобразить его в виде реальных компонентов пользовательского интерфейса.

7. Разберитесь в A2UI

Посмотрите на JSON-файл, который только что сгенерировал ваш агент. A2UI использует три типа сообщений для построения пользовательского интерфейса. В выводе вашего агента могут использоваться не все три типа сообщений каждый раз:

1. beginRendering

Создаёт поверхность для отрисовки и присваивает имя корневому компоненту:

{"beginRendering": {"surfaceId": "default", "root": "main-column"}}

2. surfaceUpdate

Отправляет дерево компонентов в виде плоского списка с идентификаторами (не вложенными):

{"surfaceUpdate": {"surfaceId": "default", "components": [
  {"id": "main-column", "component": {"Column": {"children": {"explicitList": ["title", "card1"]}}}},
  {"id": "title", "component": {"Text": {"text": {"literalString": "My Resources"}, "usageHint": "h1"}}},
  {"id": "card1", "component": {"Card": {"child": "card1-content"}}},
  {"id": "card1-content", "component": {"Text": {"text": {"path": "service_name"}}}}
]}}

3. Обновление модели данных

Отправляет данные отдельно от структуры:

{"dataModelUpdate": {"surfaceId": "default", "contents": [
  {"key": "service_name", "valueString": "auth-service"},
  {"key": "status", "valueString": "healthy"}
]}}

Компоненты привязываются к данным с помощью {"path": "key"} . Вы можете обновлять данные, не отправляя повторно дерево компонентов.

18 примитивов

Категория

Компоненты

Макет

Карточка, Столбец, Строка, Список, Вкладки, Разделитель, Модальное окно

Отображать

Текст, Изображение, Значок, Видео, Аудиоплеер

Вход

Текстовое поле, поле ввода даты и времени, поле выбора нескольких вариантов, флажок, ползунок.

Действие

Кнопка

Агент создает различные макеты, такие как окно просмотра, панель приоритетов или форма конфигурации, на основе этих же компонентов. Подробную информацию о каждом из них см. в справочнике компонентов .

8. Отображение компонентов A2UI

SDK представляет собой обертку для A2UI в стандартный интерфейс. теги. adk web распознает их и отображает компоненты с помощью встроенного рендерера A2UI. Чтобы увидеть его, удалите show_raw_json .

Обновите агента

Замените содержимое файла a2ui_agent/agent.py следующим содержимым. Единственные изменения по сравнению с предыдущим шагом заключаются в удалении функции show_raw_json , её параметра after_model_callback и двух используемых ею импортов:

from google.adk.agents import Agent
from google.adk.models import Gemini
from google.genai import types
from a2ui.inference_formats.direct_json import DirectJsonFormat
from a2ui.basic_catalog.provider import BasicCatalog
from .resources import get_resources

a2ui_format = DirectJsonFormat(
    version="0.8",
    catalogs=[BasicCatalog.get_config("0.8")],
)

instruction = a2ui_format.prompt_generator.generate(
    role_description=(
        "You are a cloud infrastructure assistant. When users ask about "
        "their cloud resources, use the get_resources tool to fetch the "
        "current state."
    ),
    workflow_description=(
        "Analyze the user's request and return structured UI when appropriate."
    ),
    ui_description=(
        "Use cards for resource summaries, rows and columns for comparisons, "
        "icons for status indicators, and buttons for drill-down actions. "
        "Do NOT use markdown formatting in text values. Use the usageHint "
        "property for heading levels instead. "
        "Respond ONLY with the A2UI JSON array. Do NOT include any text "
        "outside the JSON. Put all explanations into Text components."
    ),
    include_schema=True,
    include_examples=True,
)

root_agent = Agent(
    model=Gemini(
        model="gemini-3.8-flash",
        retry_options=types.HttpRetryOptions(attempts=5),
    ),
    name="cloud_dashboard",
    description="A cloud infrastructure assistant that renders rich A2UI interfaces.",
    instruction=instruction,
    tools=[get_resources],
)

9. Проверьте отрисованный пользовательский интерфейс.

Если у вас всё ещё запущен пользовательский интерфейс разработчика ADK, созданный ранее, он должен автоматически перезагрузить изменения, внесённые вами в агент.

Обновите вкладку браузера, выберите a2ui_agent , затем начните новую сессию, нажав кнопку «+Новая сессия» в правом верхнем углу пользовательского интерфейса разработчика ADK, и отправьте тот же запрос, что и раньше:

What's running in my project?

На этот раз adk web отображает компоненты A2UI как реальный пользовательский интерфейс: карточки с индикаторами состояния, подробной информацией о ресурсах и кнопками действий.

Агент ADK A2UI

Попробуйте другой вариант командной строки, чтобы увидеть, как агент создаст другой пользовательский интерфейс из того же набора примитивов:

Does anything need my attention?

Наконец, попробуйте другой вариант ввода, чтобы сгенерировать другой пользовательский интерфейс для развертывания новой службы:

I need to deploy a new service

Все три варианта запроса используют один и тот же агент, инструмент и компоненты, но каждый из них создает разный пользовательский интерфейс, соответствующий вашему запросу.

10. Уборка

Чтобы избежать работы локальных серверов, очистите ресурсы:

  • В терминале, где запущена adk web , нажмите Ctrl+C , чтобы остановить сервер-агент.

Если вы создали проект специально для этого практического занятия, вы можете удалить весь проект:

gcloud projects delete <YOUR_PROJECT_ID>

11. Поздравляем!

Вы создали агент ADK, который генерирует насыщенный интерактивный пользовательский интерфейс с помощью A2UI.

Что вы узнали

  • A2UI — это протокол, содержащий 18 декларативных примитивов и несколько простых сообщений, которые формируют пользовательский интерфейс.
  • SDK A2UI генерирует системные подсказки, которые обучают LLM каталогу компонентов.
  • Один и тот же агент, инструмент и примитивы позволяют создавать различные пользовательские интерфейсы для разных целей.
  • Компоненты A2UI могут отображаться непосредственно в adk web во время разработки.

Создайте производственный интерфейс пользователя.

В этом практическом задании вы отобразили A2UI внутри adk web для разработки и тестирования.

Для использования в продакшене вам потребуется создать фронтенд, используя один из официальных рендереров A2UI:

Платформа

Рендерер

Установить

Веб (React)

@a2ui/react

npm install @a2ui/react

Веб (литература)

@a2ui/lit

npm install @a2ui/lit

Веб (Angular)

@a2ui/angular

npm install @a2ui/angular

Мобильные/настольные устройства

Flutter GenUI SDK

Начиная

Справочная документация

Что дальше?

Изучите учебные материалы по созданию и развертыванию корпоративных агентов с помощью Gemini Enterprise Agent Ready (GEAR) .