Агент Stateful Data Science на Agent Engine

1. Обзор

В этом практическом занятии вы создадите агента для анализа данных, который будет запрашивать реальные данные из общедоступных наборов данных BigQuery и запоминать ваши предпочтения между сессиями. Затем вы развернете его в Agent Engine, полностью управляемом сервисе Google Cloud, который занимается инфраструктурой, масштабированием и управлением сессиями.

Агент использует три основные возможности, которые активируются постепенно:

• Инструментарий BigQuery : Агент исследует схемы и выполняет SQL-запросы к реальным наборам данных BigQuery — это работает как локально, так и при развертывании.
• Банк памяти : После развертывания агент запоминает пользовательские предпочтения и контекст в условиях разъединенных сессий.
• Наблюдаемость : Cloud Trace фиксирует этапы обработки информации агентом, вызовы инструментов и задержки с помощью инструментов OpenTelemetry.

Что вы узнаете

• Как создать агент ADK с помощью BigQueryToolset для доступа к реальным данным
• Как настроить банк памяти для обеспечения сохранения данных между сессиями
• Как развернуть агент в Agent Engine с помощью adk deploy
• Как предоставить разрешения IAM для служебной учетной записи развернутого агента
• Как проверить устойчивость и наблюдаемость памяти

Что вам понадобится

• Проект Google Cloud с включенной функцией выставления счетов.
• Google Cloud SDK ( gcloud CLI)
• Веб-браузер, например Chrome.
• uv (менеджер пакетов Python)
• Python 3.12+ (устанавливается автоматически программой uv при необходимости)

ADK (Agent Development Kit) — это фреймворк от Google для создания агентов искусственного интеллекта. В этом практическом занятии используется ADK для создания агента и его развертывания в Agent Engine.

Этот практический урок предназначен для разработчиков среднего уровня, имеющих некоторое представление о Python и Google Cloud.

Выполнение этого практического задания займет приблизительно 30 минут (включая 5–10 минут на развертывание).

Стоимость ресурсов, созданных в рамках этого практического занятия, должна составлять менее 5 долларов.

2. Настройте свою среду.

Создайте проект в Google Cloud.

1. В консоли Google Cloud на странице выбора проекта выберите или создайте проект Google Cloud .
2. Убедитесь, что для вашего облачного проекта включена функция выставления счетов. Узнайте, как проверить, включена ли функция выставления счетов для проекта .

Установка переменных среды

export GOOGLE_CLOUD_PROJECT=<INSERT_YOUR_GCP_PROJECT_HERE>
export GOOGLE_CLOUD_LOCATION=us-central1
export GOOGLE_GENAI_USE_VERTEXAI=True

Включить API

gcloud services enable \
  aiplatform.googleapis.com \
  bigquery.googleapis.com \
  telemetry.googleapis.com \
  --project=$GOOGLE_CLOUD_PROJECT

• API платформы ИИ ( aiplatform.googleapis.com ) — хостинг Agent Engine
• API BigQuery ( bigquery.googleapis.com ) — SQL-запросы к общедоступным и закрытым наборам данных.
• API телеметрии ( telemetry.googleapis.com ) — трассировка OpenTelemetry для мониторинга агентов.

Включение API может занять до минуты. Если на последующих этапах вы видите ошибки "API не включен", подождите немного и повторите попытку.

Создайте виртуальную среду и установите ADK.

uv venv .venv --python 3.12
source .venv/bin/activate
uv pip install google-adk google-auth

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

3. Создайте агента.

Создайте новый каталог проекта агента. Все последующие команды следует запускать из этого рабочего каталога (родительского каталога data_science_agent/ ):

mkdir data_science_agent

Итоговая структура ваших каталогов будет выглядеть следующим образом:

./
  data_science_agent/
    __init__.py
    agent.py
    requirements.txt    # created in the Deploy step
    .env                # created in the Deploy step

Теперь создайте __init__.py и agent.py , а затем добавьте requirements.txt и .env на этапе развертывания.

Создайте файл data_science_agent/__init__.py — он необходим для того, чтобы ADK мог обнаружить и загрузить вашего агента:

from . import agent  # noqa: F401 — required by `adk eval` and `adk web`

Создайте файл data_science_agent/agent.py :

Этот агент подключается к BigQuery для извлечения данных и сохраняет сессии в Memory Bank.

Память активируется автоматически при развертывании — переменная среды GOOGLE_CLOUD_AGENT_ENGINE_ID устанавливается средой выполнения Agent Engine и отсутствует при локальном запуске.

from __future__ import annotations

import os

from google.adk.agents import LlmAgent
from google.adk.agents.callback_context import CallbackContext
from google.adk.apps import App
from google.adk.tools.bigquery import BigQueryCredentialsConfig
from google.adk.tools.bigquery import BigQueryToolset
from google.adk.tools.preload_memory_tool import PreloadMemoryTool
import google.auth

PROJECT_ID = os.getenv("GOOGLE_CLOUD_PROJECT")
if not PROJECT_ID:
    raise ValueError(
        "GOOGLE_CLOUD_PROJECT environment variable is required. "
        "Set it with: export GOOGLE_CLOUD_PROJECT=<your-project-id>"
    )

credentials, _ = google.auth.default()
bq_toolset = BigQueryToolset(credentials_config=BigQueryCredentialsConfig(credentials=credentials))

# GOOGLE_CLOUD_AGENT_ENGINE_ID is set automatically by the Agent Engine runtime.
agent_engine_id = os.getenv("GOOGLE_CLOUD_AGENT_ENGINE_ID")


async def _save_memory(callback_context: CallbackContext) -> None:
    """Persist the session to Memory Bank after each agent run.

    Only activates on Agent Engine where Memory Bank is available.
    """
    if agent_engine_id:
        await callback_context.add_session_to_memory()


root_agent = LlmAgent(
    name="data_science_agent",
    model="gemini-2.5-pro",
    instruction=(
        "You are an expert Data Science Agent. "
        "Your goal is to query enterprise BigQuery datasets, analyze the data, "
        "and summarize your findings. "
        f"When executing SQL queries, use project_id `{PROJECT_ID}` as the "
        "billing project unless the user specifies a different one. "
        "Present results clearly with formatted numbers. "
        "Remember user preferences like preferred regions, date ranges, "
        "or analysis formats across conversations."
    ),
    tools=[bq_toolset, PreloadMemoryTool()],
    after_agent_callback=_save_memory,
)

app = App(
    name="data_science_agent",
    root_agent=root_agent,
)

Давайте разберем, что делает этот код:

1. BigQueryToolset предоставляет агенту такие инструменты, как execute_sql , list_table_ids и get_table_info — он может исследовать схемы и запрашивать любой набор данных, к которому имеет доступ вызывающая сторона.
2. PreloadMemoryTool автоматически извлекает соответствующие данные из памяти перед каждым вызовом LLM, выполняя поиск в банке памяти контента, связанного с сообщением пользователя. Функция обратного вызова _save_memory сохраняет сессию в банке памяти после каждого запуска агента, чтобы агент мог восстанавливать контекст в будущих сессиях.
3. Приложение инкапсулирует корневой агент в развертываемое приложение, которое может обслуживать Agent Engine. name должно совпадать с именем каталога ( data_science_agent ) — adk web использует это для поиска и загрузки агента.
4. Инструкция предписывает агенту использовать проект выставления счетов для SQL-запросов и запоминать пользовательские настройки.

4. Развертывание в Agent Engine

Создайте файл requirements.txt в каталоге data_science_agent :

google-adk>=1.26.0
google-genai>=1.27.0
google-auth>=2.0.0
python-dotenv>=1.1.0
opentelemetry-instrumentation-fastapi
opentelemetry-instrumentation-google-genai
opentelemetry-instrumentation-httpx
opentelemetry-instrumentation-grpc

• google-adk и google-genai — фреймворк ADK и клиент Gemini
• google-auth — аутентификация Google Cloud
• python-dotenv — загружает файл .env при запуске.
• Четыре пакета opentelemetry-instrumentation-* обеспечивают функции мониторинга, которые вы изучите позже. Они инструментируют HTTP-запросы FastAPI, вызовы модели Gemini и внутреннюю связь gRPC/HTTP, так что трассировки отображаются на вкладке «Трассировки Agent Engine».

Не добавляйте google-cloud-aiplatform[agent-engines] в ваш requirements.txt . CLI развертывания ADK автоматически добавляет эту зависимость во время развертывания. Повторное указание другой версии может вызвать конфликты версий пакетов OpenTelemetry, которые незаметно нарушат работу инструментария, из-за чего трассировки не будут отображаться на вкладке «Трассировки».

Создайте файл .env в каталоге data_science_agent , чтобы включить телеметрию на развернутом агенте:

GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY=true
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true

• GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY — активирует конвейер OpenTelemetry в среде выполнения Agent Engine.
• OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT — регистрирует полные входные сигналы командной строки и ответы агентов, что полезно для отладки.

Параметр OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT записывает в Cloud Logging полное содержимое запросов пользователей и ответов агентов. Это полезно для отладки, но может привести к сбору конфиденциальных данных или личной информации. В производственной среде установите для этого параметра значение false или убедитесь, что у вас действуют соответствующие политики обработки данных.

Разверните агента. Последний аргумент data_science_agent — это каталог, содержащий код вашего агента:

adk deploy agent_engine \
  --project=$GOOGLE_CLOUD_PROJECT \
  --region=$GOOGLE_CLOUD_LOCATION \
  --display_name="Data Science Agent" \
  --trace_to_cloud \
  --otel_to_cloud \
  data_science_agent

Флаг	Цель
--project / --region	Целевой проект и регион Google Cloud
--display_name	Удобочитаемое имя, отображаемое в консоли Cloud Console.
--trace_to_cloud	Включает экспорт трассировки Cloud Trace для трассировок агентов.
--otel_to_cloud	Включает конвейер обработки данных OpenTelemetry.

Развертывание обычно занимает 5–10 минут . После завершения вы увидите: Created agent engine: projects/.../reasoningEngines/

Пока ждёте, ознакомьтесь с документацией по банку памяти, чтобы узнать больше о том, как работает межсессионная память.

URL-адрес, отображаемый командой adk deploy может быть неверным. Если ссылка не работает, перейдите на страницу Agent Engine в Cloud Console и щелкните по своему агенту.

При развертывании в Agent Engine автоматически активируются две возможности:

• Банк памяти : PreloadMemoryTool подключается к банку памяти Agent Engine, а _save_memory автоматически сохраняет сессии.
• Наблюдаемость : Cloud Trace фиксирует этапы обработки информации агентом, вызовы инструментов и задержки.

5. Предоставьте BigQuery разрешения.

Необходимо предоставить BigQuery доступ к учетной записи службы Agent Engine. После развертывания агент работает от имени учетной записи службы, управляемой Google (а не от вашего личного имени), поэтому ему требуются явные разрешения для выполнения SQL-запросов.

PROJECT_NUMBER=$(gcloud projects describe $GOOGLE_CLOUD_PROJECT \
  --format='value(projectNumber)')

SA="service-${PROJECT_NUMBER}@gcp-sa-aiplatform-re.iam.gserviceaccount.com"

# Required to execute SQL queries
gcloud projects add-iam-policy-binding $GOOGLE_CLOUD_PROJECT \
  --member="serviceAccount:${SA}" \
  --role="roles/bigquery.jobUser"

# Required to read table metadata and data
gcloud projects add-iam-policy-binding $GOOGLE_CLOUD_PROJECT \
  --member="serviceAccount:${SA}" \
  --role="roles/bigquery.dataViewer"

Каждая команда при успешном выполнении выводит на экран Updated IAM policy for project [...] .

Если вы пропустите этот шаг, развернутый агент будет возвращать ошибки 403 при выполнении SQL-запросов. Роль bigquery.jobUser необходима для проекта выставления счетов (вашего проекта), а не для проекта данных.

Примечание: bigquery.dataViewer предоставляет доступ на чтение ко всем наборам данных в вашем проекте. Для использования в производственной среде рекомендуется предоставлять эту роль на уровне набора данных.

6. Проверьте развернутого агента.

Откройте страницу Agent Engine в консоли Google Cloud. Щелкните по развернутому агенту, чтобы открыть среду разработки Agent Engine Playground .

Выполнение каждого запроса может занять от 10 до 30 секунд, поскольку оператор обрабатывает запрос, задействует необходимые инструменты и возвращает результаты.

Проверьте возможности BigQuery:

1. "Перечислите таблицы в bigquery-public-data.hacker_news"
   • Ожидается : Агент вызывает list_table_ids и возвращает имена таблиц, включая full .
2. "Найдите количество сообщений в год в bigquery-public-data.hacker_news.full"
   • Ожидаемый результат : Агент вызывает execute_sql с SQL-запросом и возвращает таблицу с годами и количеством публикаций.
3. «Каково процентное изменение количества публикаций по сравнению с прошлым годом?»
   • Ожидаемый результат : Агент вызывает execute_sql с SQL-запросом, который вычисляет процентное изменение и возвращает результаты.

7. Проверка устойчивости памяти

Оставаясь на игровой площадке, научите агента одному из предпочтений:

1. «Помните, что мой любимый набор данных — это bigquery-public-data.hacker_news»
2. Какие столы в нём есть?

Подождите несколько секунд, пока память сохранится (функция обратного вызова _save_memory выполняется после того, как агент ответит).

Теперь начните новую сессию , нажав кнопку «+ Новая сессия» на боковой панели игровой площадки, а затем задайте следующий вопрос:

3. «Какой мой любимый набор данных?»

Агент должен вспомнить ссылку bigquery-public-data.hacker_news , даже если это совершенно новая сессия без истории переписки. Это работает, потому что:

• _save_memory сохраняет данные каждой сессии в банк памяти через callback_context.add_session_to_memory()
• PreloadMemoryTool извлекает соответствующие данные из памяти перед каждым вызовом LLM.
• Memory Bank сопоставляет контент семантически, а не только по ключевым словам.

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

8. Изучите возможности наблюдения.

В консоли Cloud перейдите к развернутому агенту и нажмите вкладку «Трассировки» .

Вы должны увидеть таблицу «Сессии» , содержащую список сессий из тестовых запросов, выполненных на предыдущих шагах. В таблице отображаются сводные метрики для каждой сессии — средняя продолжительность, вызовы модели, вызовы инструментов, использование токенов и любые ошибки.

Щёлкните по сессии , чтобы просмотреть подробные сведения о её трассировке, включая:

• Направленный ациклический граф (DAG) его сегментов — показывающий пошаговое описание рассуждений агента, вызовов инструментов (запросов BigQuery) и задержек.
• Входы и выходы для каждого участка (включаются с помощью переменной окружения OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT в файле .env )
• Метаданные, такие как идентификаторы сегментов, идентификаторы трассировки и временные параметры.

Вы также можете переключиться в режим просмотра отдельных фрагментов (переключатель вверху), чтобы увидеть отдельные фрагменты по всем сессиям.

Отображение трассировки может занять 1–2 минуты после завершения запроса. Если вы пока не видите никаких трассировок, подождите немного и обновите страницу.

Как работает отслеживание

При развертывании с --trace_to_cloud и --otel_to_cloud среда выполнения Agent Engine инициализирует конвейер OpenTelemetry, который:

1. Создает объект TracerProvider с экспортером OTLP, который отправляет данные трассировки на telemetry.googleapis.com
2. Использует четыре пакета инструментирования из вашего requirements.txt для захвата данных из ключевых библиотек (FastAPI, Gemini, httpx, gRPC) — google-genai явно инструментируется средой выполнения, в то время как остальные вносят свой вклад через автоматическое обнаружение OpenTelemetry.
3. Пакетная обработка и экспорт данных осуществляется через API телеметрии, где вкладка «Трассировки» считывает их.

Базовый образ Agent Engine предоставляет SDK и экспортер OpenTelemetry, но не включает пакеты инструментов . Именно поэтому в вашем requirements.txt должны быть указаны все четыре пакета — без них не будут созданы трассировки и не будут отображаться данные трассировки.

Поиск неисправностей

Если через несколько минут следы не появятся:

1. Убедитесь, что API телеметрии включен — вы включили его на этапе настройки. Проверьте это с помощью команды: gcloud services list --enabled --project=$GOOGLE_CLOUD_PROJECT | grep telemetry
2. Проверьте Cloud Logging на наличие предупреждений — перейдите в Logging > Logs Explorer и найдите "telemetry enabled but proceeding without" . Если вы видите предупреждение об инструментировании GenAI, значит, opentelemetry-instrumentation-google-genai отсутствует в вашем requirements.txt .
3. Не добавляйте google-cloud-aiplatform[agent-engines] в ваш requirements.txt . CLI развертывания ADK добавляет его автоматически; повторное объявление с другой версией может вызвать конфликты пакетов OpenTelemetry и незаметно нарушить работу инструментария.

9. Уборка

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

Удалите развернутый агент со страницы Agent Engine в Cloud Console. Выберите свой агент и нажмите «Удалить» .

В этом практическом занятии использовались запросы BigQuery к общедоступным наборам данных, хранение которых не влечет за собой никаких расходов. Предоставленные вами роли IAM остаются в проекте, но не влияют на стоимость.

Если вы создали проект специально для этого практического занятия, вы можете удалить весь проект целиком:

gcloud projects delete ${GOOGLE_CLOUD_PROJECT}

При желании, вы можете очистить окружающую среду в вашем регионе:

deactivate
rm -rf .venv data_science_agent

10. Поздравляем!

Вы создали агент для анализа данных с сохранением состояния и развернули его в Agent Engine!

Что вы узнали

• Как создать агент ADK с помощью BigQueryToolset для доступа к реальным данным
• Как включить постоянную память с помощью Memory Bank, используя PreloadMemoryTool и after_agent_callback
• Как предоставить разрешения IAM для служебной учетной записи развернутого агента
• Как развернуть приложение в Agent Engine и включить мониторинг с помощью Cloud Trace

Следующие шаги

• Выполняйте запросы к собственным частным наборам данных BigQuery, предоставив учетной записи службы Agent Engine доступ к вашим данным.
• Добавьте функцию выполнения кода для запуска анализа на Python в защищенной песочнице.
• Настройте панели мониторинга Cloud Trace для отслеживания работы вашего агента в производственной среде.
• Опубликуйте результаты в Google Workspace с помощью инструментов MCP.

Справочная документация

• Документация ADK
• Документация по агентскому движку
• Документация банка памяти
• Руководство по развертыванию Agent Engine