Практычныя прыемкі: Протакол агента да UI (A2UI) з кітам для разработкі агентоў (ADK)
Практычныя нарады: Протакол агента і корпусу ўжывання (A2UI) з Кітам развіцця агента (ADK): контракты, перакрычанні та слоты для коду для команд, якія викорыстоўваюць гэты патерн.
Існавайце гэта як перапрацоўаны варыянт ідэй з документа “Agent to UI Protocol (A2UI) with Agent Development Kit (ADK)” для працавальнікаў: чыстыя этапы, арганізаваныя блакі для коду і прыметкі з восстанавлення, якія застаюцца пасля перадачы задання. Этап “Адгледжэнне” найкраща функцыонуе, калі яго розглядаць як меркаваную плошчу. Запісаце адна ідеальная транскрыпцыя, адзін прыклад неудачы і прыметкі з вярнення да пачатковага стану прычым расшырэнню масштаба. Разглядайце гэты этап як кантракт між вхіднымі даннымі і пераканаўанымі выходнымі рэзультатамі. Даўце назвы артыфактам, задаце критэрыя успеху і адмовіцеся ад тыхняга частковага завершэння без паведамлення.
Agent to UI Protocol (A2UI)
Для пераходу на стадію протакола UI для агента неабяжна практыка: перад змінайом код трэба адзначыць вхідныя данні, адпаведальнага за крок і критэрыі завершэння. Аперацыяныя працавнікі должны магчымае запускаць крок з вядомай точкі контролю, не падозрываючы прыхованы статус. Запісваць трэба час выканання, а таксу токенаў чы запытак праза функцыйнае рэзультат. Відкрытыя данні пра вартасцы запобегаюць неспакоўным рахункам, калі процес пераходзіць з дэмавай версіі ў спяльныя среды. Апраўленне людзьмі трэба тых крокоў, якія витрачаюць грошы чы зменяюць данні ў працэсе. Компіляцыйныя налашчэнні не ўзначаюць павнае адпрацоўванне бізнес-функцыйяў.
Тыпы і форматы паведамленняў
У стадії выбору типа і формата паведамлення неабяжна ўзначыць вхідныя даны, адпаведальнага за этап і крэтыры завершэння перад змянайом коду. Аперацыяныя працавнікі должны магчымае запускаць этап з вядомай точкі контролю, не падозрываючы прыхованы стан. Конфігурацыю трэба залічыць пазначкай ад коду прыемліка. Файлы сераўнавання, храненні секрэтных данных і флагі функцый належыць у аднам месца, якое працавнікі можуць пераглядаць, не чытаючы весь ланцуг задач. Прызначыць людскія празборы для рэшэнняў, якія выкарыстоўваюць грошы або зміняюць даны у працэсе виробніцтва. Падключэння пад час компілявання не ўзначае повнасці бізнес-процэсу.
{
"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" }
}
}
Компаненты
Для стадіі Компаненты неабяжна ўзначыць вхідныя даны, адпаведальнага за крок і крэтыяры завершэння пры зміне коду. Аперацыйныя працавнікі павінны магчымаецца перазапускаць крок з вядомага пункта контролю, не спрабоўваючы здагадвацца пра схованы стан. Неабяжна задокументаваць як шлях успеху, так і шлях вярнення да нормальнага стану. Перапрыбуткі, людзкія пераказы і обробка некоректных паведамленняў є часткай продукту, а не яго пазнейшай дапрацоўкі. Неабяжна застаўляць людзкую затверджэнняе для тых крокоў, якія выкалічваюць грошы або зменяюць даны ў працэсе виробніцтва. Працэсы, якія выкананы ў часе компіляцыі, не є падставай для стверджэнняе абоўсюднага завершэнняе задачы. Для стадіі Компаненты неабяжна ўзначыць вхідныя даны, адпаведальнага за крок і крэтыяры завершэння пры зміне коду. Аперацыйныя працавнікі павінны магчымаецца перазапускаць крок з вядомага пункта контролю, не спрабоўваючы здагадвацца пра схованы стан. Спрыяйце таму, каб гэтае стадіі выступала як контракт межа вхіднымі данымі і перакананымі выходнымі рэзультатамі. Даўце назвы всім элементам, узначыць крэтыяры успеху і не прабоўвацца прыймаць часткова завершаныя рэзультаты без падтверджэнняе.
Трактаванне паведамленняў
Калі працюеце над стадзіяй «Праймут кэу», спачатку запісайце умовы працы: неабяжлівыя данні, сігнал успеху і тое, што выходзіць у случае частковага нявыпання. Такі список контроля дапамагае заліцвачыць змяны ў кодзе правядама. Запісвайце час выканання і кост токена або запыту праза функцыйнальныя рэзултаты. Відразлівасць коста з самага пачатку запобегае неспакоўным рахункам, калі працэс пераходзіць з дэмаверыянту ў спакульнае сераўерное сэрвіса. Зрабіце контрольную пазнаку пасля дорогіх крокаў. Система не должна зноў нарахоўваць кост той самай вызову LLM, калі аператар прабуюць зноў выканаць пазнейшы элемент працэсу.
{
"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"
}
}
}
{
"version": "v0.9",
"action": {
"name": "confirm",
"surfaceId": "booking",
"context": {
"details": {
"datetime": "2025-12-16T19:00:00Z",
"guests": "3"
}
}
}
}
{
"version": "v0.9",
"deleteSurface": { "surfaceId": "booking" }
}
Варыянты транспортування
Калі працюеце над стадзіяй «Аптаркты транспортування», спачатку запісайце угоду: неабяжлівыя даны, сігнал успеху і тое, што выходзіць у разе частковага неяксамоства. Такі список пераконтролюе чыстасць пазнейшых змян у кодзе. Зберагайце настройкі параду ўнутры коду прыемліка. Файлы сераўнавання, хранальнікі секрэтных дадзеных і флагі функцый належыць у аднам месца, дзе аператары можаць аудытаваць іх без неабяжлівага чытання всей структуры. Ставьце контрольныя пункты пасля дорогіх крокаў. Функцыя вярнення роботы не должна зноў выклікаць той самы вызов LLM, калі аператар перапрыяўляе роботу да наступнага вузла.
Рэндэрары
Калі працуеце над стадзіяй Renderers, спачатку запісайце контракт: неабяжлівыя данні, сигнал успеху і тое, што выходзіць у разе частковага нявыпання. Такі список пераконвае ў тым, што пазнейшыя змены коду будуць чыстымі. Документавайце як шлях успеху, так і шлях вярнення. Перапрыбуткі, людзкі контроль і обработка некоректных паведамленняў ёсць частью продукту, а не пазнейшым дапрацоўкам. Стварайце контрольныя пункты пасля дорогіх крокаў. Система вярнення не должна зноў ставіць плату за той самы вызов LLM, калі аператар перапрыбуе пазнейшы вузел. Калі працуеце над стадзіяй Renderers, спачатку запісайце контракт: неабяжлівыя данні, сигнал успеху і тое, што выходзіць у разе частковага нявыпання. Такі список пераконвае ў тым, што пазнейшыя змены коду будуць чыстымі. Спрыймайце гэтую стадзію як контракт межа даннімі і перакананымі выходнымі даннымі. Даўце назвы артыфактам, задайце критэрыя успеху і адмовіцеся ад тыхнейкага частковага завершэння.
A2UI проты AG-UI
A2UI vs AG-UI этап работае наяўней, калі яго спрыяваць як мерыемую паверхню. Зафіксавайце адна ідеальная транскрыпцыя, адзін прыклад неудачы і запіс пра вярнэнне да поперадньага стану пры розшырэнні масштаба. Запісвайце часы выканання і кост токеноў або запытаў разам з функцыйнальнымі рэзультатамі. Відразлівае паказанне костаў з самага пачатку запобегае неспакойным рахункам, калі процес пераходзіць з дэмаверсіі ў спяльныя среды. Храніце стан графаў у простам і типаваным формате. Вкладзеныя блокі маскуюць інфармацыю пра тое, який вузел запісаў канкрэтны поле, і спакшваюць продажчыку роботу пасля перарываў.
A2UI з кітам развіцця агента (ADK)
A2UI з стадіяю развіцьба агента працуе найкраща, калі яго розглядаюць як вимерную паверхню. Зберагчы адны «золаты» транскрыпт, адны прыклад неудачы і запіс пра вярнэнне да пачатковага стану, перш чым расширваць сферу дзеяння. Храніце настройкі параду ад коду прыемлена. Файлы серавіса, хранальнікі секрэтных данных і флагі функцыйяў должны знаходзіцца ў аднам месцы, куды аператары можаць адбавляць аудыт без неабяжнага чытання всіх дадзеных. Храніце стан графа ў простам і типаваным формате. Вкладныя блокі маскуюць інфармацыю пра тое, калький вузел запісаў калькі поле, і спакоююць працэс пасля перарываў.
Перш чым пачнуць
Этап «Перш чым пачаткаць» працюе найэфектывней, калі яго спрыяваць як мерыемую паверхню. Зафіксавце адны ідеальны прыклад роботы, адну справу з бягам і прыметку па вярнэнню да пачатковага стану пры розшырэнні масштаба. Дакументавайце як шлях успеху, так і шлях вярнэння да нормальнага стану. Перапрыбуткі, людзкія контраліны і обработка некоректных паведамленняў є часткай продукту, а не элементамі пазнейшага дапрацоўкі. Храніце стан графа ў простам і типаваным формате. Вярнутыя структуры дакументаў маскуюць інфармацыю пра тое, який вузел запісаў кожны поле, і спакшуюць продовжэнне роботы пасля перарываў. Этап «Перш чым пачаткаць» працюе найэфектывней, калі яго спрыяваць як мерыемую паверхню. Зафіксавце адны ідеальны прыклад роботы, адну справу з бягам і прыметку па вярнэнню да пачатковага стану пры розшырэнні масштаба. Спрыявайце гэты этап як кантракт межа вхіднымі даннымі і перакананымі выходнымі рэзультатамі. Даўце назвы дакументам, задаце критэрыя успеху і не падтрымвайце беззвучнае частковае завершэння роботы.
git clone https://github.com/google/a2ui.git
cd a2ui
export GEMINI_API_KEY="your_gemini_api_key_here"
Аплікацыя для пошуку рестаранаў
Для стадії прыкладніка Restaurant Finder неабяжна прадзефінавацыя вхідных дадзеных, адпраўніка крока і крэтарыяў завершэння працы перад зменым коду. Аперацыйныя працавнікі павінны магчымае перзапускаць крок з вядомай точкі контролю, не падозрываючы схованы статус. Запісваць час выконання і кост токенаў або запытаў разам з функцыйнаімі рэзультатамі. Відразлівае прадставленне костоў запобегае неспакойным рахункам, калі працэс пераходзіць з дэмавай версіі ў спяльнаныя сераўеры. Пры кроках, якія витрачаюць грошы або зменяюць данні ў працэсе, неабходна людская апраўка. Кампіляцыйныя налашчэнні не ўзначаюць павнае адпраўлення прыкладніка.
npm run demo:restaurant
[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] },
...
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.
"""
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,
)
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],
)
# --- 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)
CopilotKit A2UI Starter і A2UI Composer
Для CopilotKit A2UI Starter і stage неабяжна практыка задаць вхідныя даны, адпаведнага власніка крока і крэтыяры выходу пры змены коду. Аператары должны магчымаць перзапуск крока з вядомай точкі контролю, не падозрываючы схованы стан. Конфігурацыю трэба захаваць пазначыльна коду прыкладнення. Файлы сераўнавання, хранільнікі секрэтных дадзеных і флагі функций должны знаходзіцца ў аднам месцы, якое аператары можаць пераглядаць без неабяжнай чытання ўсіх элементаў системы. Прызначыце людскую апрацоўку для рэшэнняяе крокав, якія выкарыстоўваюць грошы або зміняюць даны ў працэсе. Прыўязка на час компілявання не є гарантыяйю полнайасці бізнес-процэсаў.
Падсумак
У стадії падробнага аналізу неабяжна ўважна вызначыць інпуты, адпаведальнага за крок і крэтыры завершэння пры перадзеі коду. Аперацыйныя працавнікі павінны магчымае перадзеі крок з вядомай точкі контролю, не падозрываючы прыхованы стан. Неабяжна дакументаваць як шлях успеху, так і шлях вярнення да нормальнага стану. Перапрыбуткі, людзкія пераказы і обробка некоректных паведамленняў ёсць часткай продукту, а не пасляднім дапрацоўкам. Неабяжна застаўляць людзкую затверджэнняе для тых крокаў, якія выкарыстоўваюць грошы або зміняюць даны ў працэсе. Компіляцыйныя налашчэння не ўзначаюць повнасці бізнес-функцыяў. У стадії падробнага аналізу неабяжна ўважна вызначыць інпуты, адпаведальнага за крок і крэтыры завершэння пры перадзеі коду. Аперацыйныя працавнікі павінны магчымае перадзеі крок з вядомай точкі контролю, не падозрываючы прыхованы стан. Спрыяць гэтай стадіі як кантракту межа інпутамі і перакананымы выходнымі даннымі. Даць назвы элементам, вызначыць крэтыры успеху і не прабаваць прыймаць часткова завершаныя рэзультаты без падтверджэння.
Чек-ліст для аперацый
Калі працюеце над стадзіяй Кантрольнага списку, спачатку запісайце угоду: неабяжлівыя даны, сігнал успеху і тое, што выходзіць у разе частковага неяксамоства. Такі кантрольны список дапамагае заліцварыць пазнейшыя змены коду.
Валіце маленькія, тэставаныя елементы замест большых скрыптов. Калі якісь крок неяксамоства, гэтае неяксамоства павінны адначасова паказваць аднае абавеспакоўванне, а не заплутаны ланцужок задач.
Зробіце кантрольную паузу пасля дорогіх крокаў. Система адновлення не павінна зноў вырахоўваць кашты за той самы вызов LLM, калі аператар прабуе зноў выконаць пазнейшы вузел.
Фіксуйце версіі залежнасцей і запісвайце хэш адобраза, які выканаў дэманстрацыю. Возможнасць павтарнага стварэння результата лепшая за традыцыйныя знаёмства.
Спрыятліва ставіцеся да гэтай стадзіі як да угоды межа данымі і перакананымі рэзультатамі. Даўце назвы артыфактам, задаце критэрыя успеху і адмовіцеся ад тыхняга частковага завершэння без паведамлення.
Зробіце кантрольную паузу пасля дорогіх крокаў. Система адновлення не павінна зноў вырахоўваць кашты за той самы вызов LLM, калі аператар прабуе зноў выконаць пазнейшы вузел.
Перш чым запускать стак, заморозьце версіі, зафіксавце «золаты» транскрыпты для критычнага шляху і паказвце способы абяроны. У спільных средах неабходны ліміты частоты запытоў, пераканання ў належнасці тэнантам і чысткі власнік для ротацыі секрэтных даных. Валіце простую надзейнасць працоўнікам, а не крэатыўныя разовыя дэманстрацыі.
Прыметкі для de52e67f800d: не кладзіце ключы прадастальніка ў репазітарый, задаце верхнюю межу токена на кожную сесію і зберагачыце транскрыпты празаўсюды з фікстурамі eval, каб пазнейшыя замены модэляў заставаліся порównаннімі.