Генератыўны інтэрфейс ад агентаў ADK праз пратакол 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. Ён дазволяе AI-агентам ствараць насыценыя, інтэрактывныя інтэрфейсы, якія можна прадстаўіць на вебе, у мобільных прыстроях і на дэсктопе. Напрыклад, якшо корыстувач запытае: «Калія хорашыя рэстараны ў Нью-Йорку?», агент можа не толькі вернуць тэкстовы спіс, але і опіс інтэрфейса, а прыстрой на стороне кліента ператворыць гэты опіс у інтэрактыўную візуалізацыю рэстаранаў.
Основныя концэпцыі задокументаваны на 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"
}
}
}
}
Шостае, агент адказвае, або пачатковаючы зноў аднойчы UI, або закрываючы паверхню:
{
"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
Установіце кантэнт ключа Gemini API:
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 запоўняе каталогі компанентаў і стварае сістэмныя прапозыціі, якія напамінаюць модэлю пра правільны фармат A2UI JSON. Выкліканне 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 агентамі ў рэальны час.