1. Обзор
Большинство агентов ИИ отвечают текстом. В этом практическом занятии вы будете использовать A2UI , чтобы ваш агент отвечал пользовательским интерфейсом. Агент описывает карточки, списки, кнопки и формы в формате JSON, используя каталог стандартных компонентов, а клиент отображает их с помощью собственных виджетов, поэтому для новых макетов не требуется новый код фронтенда.
Агент будет создан с помощью комплекта разработки агентов (ADK) .
Что вы построите
Имитация панели мониторинга облачной инфраструктуры в три этапа:
- Стандартный агент , возвращающий данные ресурсов в виде обычного текста.
- Агент A2UI , возвращающий те же данные, что и структурированный JSON-файл A2UI.
- Агент , отображающий JSON-данные A2UI в виде интерактивных компонентов пользовательского интерфейса в среде разработки ADK.

Что вы узнаете
- Принцип работы 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.
- В консоли Google Cloud на странице выбора проекта выберите или создайте проект Google Cloud .
- Убедитесь, что для вашего облачного проекта включена функция выставления счетов. Узнайте, как проверить, включена ли функция выставления счетов для проекта .
Запустить редактор 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?
Ваш диалог должен выглядеть примерно так:

Ответ точный, но это сплошной текст.
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-кода.

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 как реальный пользовательский интерфейс: карточки с индикаторами состояния, подробной информацией о ресурсах и кнопками действий.

Попробуйте другой вариант командной строки, чтобы увидеть, как агент создаст другой пользовательский интерфейс из того же набора примитивов:
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) | | |
Веб (литература) | | |
Веб (Angular) | | |
Мобильные/настольные устройства | Flutter GenUI SDK |
Справочная документация
- Спецификация и документация A2UI
- Репозиторий A2UI на GitHub
- Рендереры A2UI
- Документация ADK
- Интеграция ADK A2UI
Что дальше?
Изучите учебные материалы по созданию и развертыванию корпоративных агентов с помощью Gemini Enterprise Agent Ready (GEAR) .