Как интегрировать Google ADK с кастомным интерфейсом: пошаговое руководство с примерами

Руководство по интеграции Google ADK в кастомный интерфейс: примеры кода, работа с сессиями, FastAPI, деплой на Vertex AI и структура агента.

Всем здравствуйте!

Меня зовут Mykhailo Kapustin, я разработчик с 10-летним опытом работы, соучредитель и технический директор в научно-исследовательском проекте Advanced Scientific Research Projects и Senior AI/ML-инженер в образовательной сфере в Кремниевой долине в компании Woolf.

Недавно передо мной встала задача — создать кастомного интерактивного агента с кастомным UI, который можно было бы встроить в существующую инфраструктуру проекта. Я начал ресерч, провел встречи с другими инженерами, включая Grigory Nosyrev (Senior Software Engineer, Workato), и понял: материалов по интеграции Google Agent Development Kit (ADK) в реальные интерфейсы почти нет.

Что такое Google ADK: краткое описание возможностей

Google Agent Development Kit (ADK) — это open-source-инструментарий от Google, представленный 9 апреля 2025 года. Он предназначен для создания LLM-агентов, способных вести диалог, вызывать внешние функции, работать с внутренним состоянием, подключать документы и выстраивать reasoning-процессы. ADK позволяет разрабатывать агентов локально или в облаке, с минимальным количеством кода и достаточно прозрачной архитектурой.

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

Простого агента на Google ADK создать несложно

Google ADK — удивительно аккуратная технология. Интерфейсы просты, документация лаконична, и для большинства базовых кейсов не нужно много кода. Даже если у вас не так много опыта в программировании, вы вполне сможете собрать своего первого агента.

Вот пример буквально минимального агента, используя официальный пакет adk-python:

from google.adk.agents import Agent 
from google.adk.tools import google_search

root_agent = Agent( 
   name="search_assistant", 
   model="gemini-2.0-flash", # Or your preferred Gemini model 
   instruction="You are a helpful assistant. Answer user questions using Google Search when needed.",    
   description="An assistant that can search the web.",
   tools=[google_search] 
)

Вы описываете инструкцию, подключаете инструмент (google_search), и на этом — всё. Агент готов общаться с вами и искать необходимую информацию в google search.

Если вы хотите начать с чего-то более развернутого, я рекомендую заглянуть в официальный репозиторий adk-samles, где вы найдёте рабочие шаблоны, включая агентов с функциями, цепочками reasoning, состоянием и встроенными тестами.

📎 Запустить агента можно командой: adk web

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

Рис. 1. Демонстрация работы агента в веб-интерфейсе Agent Development Kit. Видна инициализация сессии и первое сообщение от агента.

Всё запускается локально, без необходимости писать дополнительный код или настраивать инфраструктуру.

Архитектура агента Google ADK: сессии, reasoning, state

Когда вы отправляете первое сообщение через поле “Type a message…” в веб-интерфейсе adk web, Google ADK автоматически создаёт уникальную сессию для текущего диалога. С этого момента всё, что происходит между вами и LLM, — хранится в контексте этой сессии.

Рис. 2. Интерфейс Vertex AI Agent Development Kit: вкладка Sessions с активной сессией агента exam-builder. Сессии позволяют отслеживать ход взаимодействия, сохранять состояние и восстанавливать диалог по session_id.

Внутри каждой сессии агент ведёт собственное внутреннее состояние, в которое входит:

• история сообщений;

• размышления и промежуточные шаги reasoning-процесса;

• список вызванных функций и событий;

• артефакты, если они генерируются агентом.

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

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

Но что, если вам нужен собственный интерфейс для интерактивной работы с LLM — со своим дизайном, логикой, авторизацией и бизнес-интеграцией?

Подключение кастомного UI к Google ADK через FastAPI

После первых экспериментов с adk web у меня возник естественный вопрос:
если веб-интерфейс уже умеет общаться с агентом, значит под капотом у него есть API — а могу ли я использовать этот API для своего интерфейса?

Ответ — да. Google ADK разворачивает полноценный FastAPI-сервер, и adk web использует его напрямую. Это означает, что вы можете построить собственный UI — с авторизацией, кастомной логикой и пользовательским опытом — используя тот же набор методов.

📦 Чтобы запустить ADK API, достаточно команды:

adk api_server

После этого локально запускается FastAPI-интерфейс на порту 8000:

INFO:     Started server process [18018]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

И вы можете открыть документацию Google ADK API по адресу: http://127.0.0.1:8000/docs

Рис. 3. OpenAPI-документация с полным списком доступных эндпоинтов FastAPI-сервера ADK, включая работу с сессиями, трассировкой, оценками и артефактами.

📎 Здесь будет доступна полная FastAPI-документация со всеми доступными маршрутами, включая:

• POST /run — для одиночных вызовов агента;

• GET /run_sse — для потоковых ответов (SSE);

• POST /sessions — для управления пользовательскими сессиями;

• POST /evals — для запуска встроенных процедур оценки;

• GET /artifacts — для работы с артефактами, созданными агентом.

Таким образом, вы можете буквально «повторить» функциональность adk web — но уже в собственном приложении.

Всё хорошо, пока вы работаете локально. Но стоит перейти к реальной интеграции — и сразу встаёт вопрос: модель нужно куда-то задеплоить, чтобы к ней можно было подключиться извне — надёжно, стабильно и без запуска с локальной машины.

Как задеплоить агента: Vertex AI, Cloud Run или Docker

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

• Vertex AI Agent Engine — полностью управляемое решение от Google Cloud;

• Cloud Run — простой способ запустить контейнер в облаке;

• Custom Infrastructure — самостоятельное управление через Docker, GKE или on-premise.

Рис. 4. Схема деплоя агента из Google ADK: сборка контейнера и запуск на Vertex AI Agent Engine, Cloud Run или собственной инфраструктуре через Docker/GKE.

Из этих трёх вариантов я выбрал Vertex AI Agent Engine — полностью управляемую платформу, разработанную специально для продакшн-деплоя LLM-агентов. Она позволяет сосредоточиться на логике, не отвлекаясь на настройку инфраструктуры, сетей, балансировки и авторизации.

Процесс деплоя здесь предельно лаконичный. После создания агента:

app = reasoning_engines.AdkApp(
    agent=root_agent,
    enable_tracing=True,
)

remote_app = agent_engines.create(
    agent_engine=app,
    requirements=["google-cloud-aiplatform[adk,agent_engines]"],
    extra_packages=["./path_to_folder_with_agent"],
)

По сравнению с Cloud Run и тем более Custom Infrastructure, Agent Engine минимизирует инженерные риски, ускоряет разработку и позволяет команде быстрее перейти к тестированию и итерациям. А в случае необходимости — его всегда можно дополнить своими слоями авторизации, логирования или аналитики.

📄 Документация по процессу деплоя: https://google.github.io/adk-docs/deploy.

После деплоя: знакомство с Agent Engine API

Когда вы задеплоили агента через Vertex AI Agent Engine, под капотом происходит важный переход: вы больше не взаимодействуете напрямую с Google ADK API. Вместо этого вы начинаете работать с отдельным API — Agent Engine API, который Google разработал поверх ADK.

Хотя оба API схожи концептуально, между ними есть различия в форматах, маршрутах и возможностях, которые стоит учитывать.

Вам будут доступны ключевые методы для управления сессиями и общения с моделью:

Методы работы с сессиями:

• create_session — создать новую сессию;

• get_session / async_get_session — получить информацию о сессии;

• list_sessions — получить список всех сессий пользователя;

• delete_session — удалить сессию.

Методы взаимодействия с агентом:

• stream_query — основной способ интерактивного общения с агентом (через SSE);

• async_stream_query — аналогичный метод с асинхронной поддержкой;

• streaming_agent_run_with_events — расширенный способ получения пошаговых событий (в т.ч. reasoning, вызовы функций и артефакты).

📌 Важно понимать: вся логика диалога теперь завязана на эти API, а значит, вы можете строить собственный UI, бекенд или микросервис, используя именно эти точки входа.

🔗 Официальная документация по Agent Engine API:
https://cloud.google.com/vertex-ai/generative-ai/docs/agent-engine/use/overview

Интеграция с продакшен-системой: как подключить модель к вашему продукту

Теперь главный вопрос — как встроить это в вашу архитектуру.

Я перебрал несколько архитектурных вариантов:

• Фронтенд напрямую обращается к LLM
  Просто и быстро, но небезопасно: придётся давать агенту доступ к базе и внутренним API, а значит — решать вопросы авторизации, защиты данных и контроля над моделью.

• Прокси-бэкенд между фронтендом и LLM
  Даёт больше контроля: можно логировать сообщения, фильтровать ответы, реализовать авторизацию. Но тогда придётся проксировать стриминг (через WebSocket или SSE) и синхронизировать состояние между моделью и бэкендом.

• Общая база между LLM и прокси
  Упрощает доступ к состоянию, но создаёт риск гонок, консистентности данных и проблем с поддержкой.

Все эти подходы жизнеспособны, особенно если у вас есть опыт и ресурсы на продуманную архитектуру. В своём проекте я выбрал прокси-бэкенд, который:

• авторизует пользователей,

• фильтрует/обогащает ответы,

• логирует данные,

• и запрашивает состояние сессии у модели, чтобы понимать, что происходит внутри.

Пример работы:

1. Фронтенд отправляет сообщение на бэкенд.

2. Бэкенд делегирует его в LLM (query или stream_query).

3. LLM обрабатывает запрос и дополняет state сессии.

4. LLM возвращает сообщения от LLM.

5. Затем бэкенд запрашивает state по session_id.

6. Финальный результат уходит во фронт.

Рис. 5. Схема архитектуры взаимодействия в кастомном интерфейсе на базе Google ADK

Единственный нюанс — стриминг: нужно проксировать stream_query через WebSocket (или SSE), чтобы ответ приходил в реальном времени.

Теперь у нас есть всё, чтобы построить продакшен-интеграцию: агент задеплоен в Vertex AI Agent Engine, мы умеем отправлять запросы и получать ответы, можем заглянуть в state сессии и понять, что происходит внутри. Остался последний, но критически важный шаг — научиться наполнять state во время общения с моделью, чтобы сохранять важные данные, отслеживать прогресс и строить диалог с памятью.

Управление состоянием сессии: как обновлять state во время общения

Чтобы обновлять state в процессе общения, ADK предоставляет механизм коллбэков — функций, которые вызываются автоматически после генерации ответа или выполнения инструмента.

Документация по коллбэкам:
📚 https://google.github.io/adk-docs/callbacks/

Вот базовый пример: функция memorize_list добавляет значение в список под нужным ключом в state.

def memorize_list(key: str, value: str, tool_context: ToolContext) -> dict:
    mem_dict = tool_context.state
    if key not in mem_dict:
        mem_dict[key] = []
    if value not in mem_dict[key]:
        mem_dict[key].append(value)
    return {"status": f'Stored "{key}": "{value}"'}

Теперь подключим эту функцию к агенту через after_model_callback, чтобы сохранять данные после каждого ответа LLM:

def save_to_state(callback_context: CallbackContext, llm_response: LlmResponse) -> Optional[LlmResponse]:
    memorize_list("progress", llm_response.content.parts[0].text, callback_context)

Этот коллбэк будет автоматически вызываться после генерации ответа, и агент сможет обновлять своё состояние без участия фронтенда или бэкенда. Благодаря этому подходу агент становится «помнящим»: он знает, на каком этапе находится пользователь, какие шаги уже пройдены и что делать дальше.

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

Теперь у вас есть всё:
🔹 агент, задеплоенный в облаке,
🔹 API для общения,
🔹 прокси, обрабатывающий запросы,
🔹 и state, который можно изменять в процессе диалога.

Осталось только одно — решить, что именно вы хотите "помнить" и зачем.
И это уже не про код, а про бизнес-логику и цели продукта. На этом этапе LLM становится не просто моделью, а частью полноценного пользовательского опыта.

Вывод

Интеграция с Google ADK и Vertex AI Agent Engine — это не просто способ подключить LLM к продукту. Это возможность построить гибкую и масштабируемую архитектуру, в которой модель становится полноценным участником диалога, а не просто API-обёрткой над текстом.

С помощью state, callback'ов и продуманной архитектуры вы можете:

• управлять памятью и поведением агента,

• наблюдать и анализировать сессии,

• настраивать опыт общения под нужды конкретного продукта.

Самое важное — вы не ограничены.
Вы можете экспериментировать, подключать свою аналитику, менять модели, адаптировать ответы, развивать агента как полноценного участника бизнес-процесса.

Интерфейс с LLM — это не конечная точка. Это начало новой ветки архитектуры вашего продукта.

© Фото автора данной статьи — Mykhailo Mykhailovich Kapustin.