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

Привет всем!
Меня зовут Михайло Капустин Я разработчик с 10-летним опытом, соучредитель и технический директор исследовательского проекта Расширенные научные исследовательские проекты.

Недавно мне была поставлена задача создать пользовательского интерактивного агента с пользовательским интерфейсом который можно было бы интегрировать в существующую инфраструктуру нашего проекта Я начал исследовать, обсуждал с другими инженерами — включая Григория Носырева (старший инженер-программист в Workato) — и осознал нечто важное: существует очень мало документации или публичных рекомендаций о том, как интегрировать Набор инструментов для разработки агентов Google (ADK) в реальные интерфейсы.

Что такое Google ADK: Краткий Обзор

Набор инструментов для разработки агентов Google (ADK) это набор инструментов с открытым исходным кодом, представленный Google 9 апреля 2025 года. Он предназначен для создания агентов LLM, способных вести беседы, вызывать внешние функции, управлять внутренним состоянием, подключаться к документам и выполнять сложные процессы рассуждения. ADK позволяет разработчикам создавать агентов локально или в облаке с минимальным количеством кода и довольно прозрачной архитектурой. Несмотря на то, что он относительно новый и имеет некоторые технические ограничения, ADK быстро развивается. Команда Google активно работает над улучшениями, и каждое обновление отражает четкое намерение сделать архитектуру на основе агентов более предсказуемой, прозрачной и управляемой.

Создание простого агента с Google ADK Легко

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

Вот пример минимального агента, использующего официальный

adk-python пакет: из

google. adk. .агенты импорт Агент 
из google.adk.инструменты импорт google_search

root_agent = Agent( 
   name="search_assistant", 
   model="gemini-2.0-flash", # Или ваша предпочтительная модель Gemini 
   instruction="Вы полезный помощник. Отвечайте на вопросы пользователей, используя Google Search, когда это необходимо.",    
   description="Помощник, который может искать в интернете.",
   tools=[google_search] 
)

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

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

📎 Чтобы запустить агента, просто выполните команду: adk web

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

Все работает локально — не требуется дополнительный код или настройка инфраструктуры.

Архитектура агента Google ADK: Сессии, Рассуждения и Состояние

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

В каждой сессии агент поддерживает свое собственное внутреннее состояние, которое включает:

историю сообщений,
шаги рассуждений и промежуточные мысли,
список вызванных функций и событий,
артефакты (если они были сгенерированы агентом).

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

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

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

Подключение пользовательского интерфейса к Google ADK через FastAPI

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

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

📦 Чтобы запустить ADK API, просто выполните следующую команду:

adk api_server

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

INFO:     Запущен процесс сервера [18018]
INFO:     Ожидание запуска приложения.
INFO:     Запуск приложения завершен.
INFO:     Uvicorn работает на http://127.0.0.1:8000 (Нажмите CTRL+C для выхода)

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

📎 Здесь вы найдете полную документацию 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 — легкий способ запускать контейнеры в облаке;
Пользовательская инфраструктура — самостоятельное развертывание с использованием Docker, GKE или локальных решений.

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

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

app = reasoning_engines.AdkApp(
    агент= 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"],
)

И это всё. Agent Engine автоматически создает контейнер, запускает сервер и предоставляет конечную точку, к которой вы можете подключиться с вашего фронтенда или получить доступ через REST API.

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

📄 Документация по развертыванию: https://google.github.io/adk-docs/deploy.

После развертывания: Знакомство с API Agent Engine API

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

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

У вас будет доступ к основным методам для управления сессиями и взаимодействия с вашей моделью:

Методы управления сессиями:

создать_сессию — создает новую сессию
получить_сессию / асинхронно_получить_сессию — извлекает информацию о сессии
список_сессий — перечисляет все пользовательские сессии
удалить_сессию — удаляет сессию

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

потоковый_запрос — основной метод для интерактивного общения с агентом (через SSE)
асинхронный_потоковый_запрос — аналогичный метод с поддержкой асинхронности
потоковый_агент_запуск_с_событиями — расширенная конечная точка, которая возвращает пошаговые события (например, рассуждения, вызовы функций и артефакты)

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

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

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

Теперь возникает ключевой вопрос — как вы интегрируете это в свою архитектуру?

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

Фронтенд → LLM напрямую
Просто и быстро, но небезопасно: вам придется предоставить агенту доступ к вашей базе данных и внутренним API — что означает необходимость решения вопросов аутентификации, защиты данных и контроля модели.
Прокси-сервер между фронтендом и LLM
Предоставляет больше контроля: вы можете регистрировать сообщения, фильтровать ответы и реализовывать авторизацию. Однако вам нужно будет проксировать потоковую передачу (через WebSocket или SSE) и синхронизировать состояние сессии между моделью и бэкендом.
Общая база данных между LLM и прокси
Упрощает доступ к состоянию, но вводит риски, связанные с условиями гонки, согласованностью данных и долгосрочной поддержкой.

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

аутентифицирует пользователей,
фильтрует/обогащает ответы,
регистрирует данные и
запрашивает состояние сессии у модели, чтобы понять, что происходит внутри.

Пример рабочего процесса:

Фронтенд отправляет сообщение на бэкенд.
Бэкенд пересылает его в LLM (запрос или потоковый_запрос).
LLM обрабатывает запрос и обновляет состояние сессии.
LLM возвращает свой ответ.
Бэкенд получает состояние сессии, используя session_id.
Окончательный результат отправляется на фронтенд.

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

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

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

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

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

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

def memorize_list(key: str, value: str, tool_context: ToolContext) -> словарь:
    mem_dict = tool_context.state
    если ключ не в mem_dict:
        mem_dict[key] = []
    если значение не в mem_dict[key]:
        mem_dict[key].добавить(значение)
    вернуть {"статус": f'Сохранено "{key}": "{value}"'}

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

def сохранить_в_состоянии(callback_context: CallbackContext, llm_response: LlmResponse) -> Optional[LlmResponse]:
    запомнить_список("прогресс", llm_response.content.parts[0].text, callback_context)

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

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

Теперь у вас есть все, что вам нужно:
🔹 Агент, развернутый в облаке,
🔹 API для связи,
🔹 Прокси, обрабатывающее запросы,
🔹 И состояние сессии, которое может развиваться в ходе разговора.

Единственный оставшийся вопрос: что именно вы хотите, чтобы ваш агент «запомнил» — и почему?

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

Прямой интеграции с развернутым агентом

Как только ваш агент развернут через Vertex AI Agent Engine, он становится доступным через REST-эндпоинт:

https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID:MODE

API предоставляет два режима взаимодействия: запрос и streamQuery.
Мы будем использовать запрос режим для инициализации сессии с предопределённым состоянием:

Пример запроса:

{
  "classMethod": "create_session",
  "input": {
    "user_id": "user_id",
    "state": {
       "user": {
            "gender": "man",
            "city": "Berlin"
        }
      /* структура состояния здесь */
    }
  }
}

Пример ответа:

{
  "output": {
    "state": {
       "user": {
            "gender": "man",
            "city": "Berlin"
        }
    },
    "lastUpdateTime": 1753711142.2750449,
    "userId": "user_id",
    "appName": "app_name",
    "id": "2971967285494808576",
    "events": []
  }
}

Здесь id поле представляет идентификатор сессии.
После создания сессии мы можем отправить сообщение, используя streamQuery режим.

Пример запроса:

{
  "user_id": "user_id",
  "session_id": "sessionId",
  "message": "Какова погода в Берлине сегодня?"
}

Пример ответа:

{
  "content": {
    "parts": [
      {
        "text": "{LLM ответ на ваше сообщение}"
      }
    ],
    "роль": "модель"
  },
  "метаданные_использования": {
    "количество_токенов_кандидатов": 74,
    "количество_токенов_подсказки": 2990,
    "общее_количество_токенов": 3064
  },
  "идентификатор_вызова": "e-d4bf65a1-b728-4c4d-9ead-bd1358e29275",
  "автор": "ваше_имя_llm",
  "действия": {
    "изменение_состояния": {},
    "изменение_артефакта": {},
    "запрашиваемые_конфигурации_аутентификации": {}
  },
  "ид": "78b41809-90ad-427b-a8df-bc9ce8167c6a",
  "временная_метка": 1753711240.486078
}

После этого взаимодействия вы можете снова запросить состояние сессии, используя query режим, чтобы проверить, что происходит внутри LLM и как оно развивается со временем.

Пример запроса:

{
    "classMethod": "get_session",
    "input": {
      "session_id": "{sessionId}",
      "user_id": "{userId}",
    }
}

Пример ответа:

{
  "events": [
    {
      "content": [
        {
            "parts": [
              {
                "text": "{LLM response to your message}"
              }
            ],
            "role": "model"
        }    
      ],
      "groundingMetadata": null,
      "errorCode": null,
      "invocationId": 'e-eb9b81ac-d901-4117-a79e-4766e7eb955a',
      "timestamp": 1753708785.467739,
      "errorMessage": ноль,
      "longRunningToolIds": ноль,
      "branch": ноль,
      "author": "user",
      "interrupted": ноль,
      "turnComplete": ноль,
      "usageMetadata": ноль,
      "customMetadata": ноль,
      "actions": [Object],
      "partial": ноль,
      "id": "2337804162965700608"
    }
  ],
  "appName": "app_name",
  "userId": 'bec12377-b51e-4172-b7f3-d287012490f6',
  "id": '8160114056225619968',
  "состояние": {
     "пользователь": {
            "пол": "мужчина",
            "город": "Берлин"
      },
      "текущий_вопрос": "Какова погода в Берлине сегодня?"
  },
  "времяПоследнегоОбновления": 1753711273.97866
}

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

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

Заключение

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

С помощью состояния, обратных вызовов и продуманной структуры бэкенда вы можете:

управлять памятью и поведением агента,
мониторить и анализировать сессии,
настраивать взаимодействие в соответствии с потребностями вашего продукта.

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

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

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

Authors

Что такое Google ADK: Краткий Обзор

Архитектура агента Google ADK: Сессии, Рассуждения и Состояние

Подключение пользовательского интерфейса к Google ADK через FastAPI

Как развернуть вашего агента: Vertex AI, Cloud Run или Docker

После развертывания: Знакомство с API Agent Engine API

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

Прямой интеграции с развернутым агентом

Пример запроса:

Пример ответа:

Пример ответа:

Заключение

Вам также может понравиться

Хотите разобраться глубже?

ИИ-агенты — от теории к живым системам