Галоўная / Артыкулы

Генератыўны інтэрфейс ад агентаў ADK праз пратакол 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. Ён дазволяе 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 агентамі ў рэальны час.