Агент анализа данных с сохранением состояния в среде выполнения агента

1. Обзор

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Настройте свой проект

Откройте редактор Cloud Shell в созданном вами проекте GCP.

Затем создайте терминал > Новый терминал и выполните следующую команду, чтобы задать свой проект. Последующие команды будут считывать идентификатор проекта из этой настройки.

gcloud config set project <INSERT_YOUR_GCP_PROJECT_HERE>

Включить API

В терминале выполните следующую команду.

gcloud services enable \
  aiplatform.googleapis.com \
  bigquery.googleapis.com \
  telemetry.googleapis.com \
  --project=$(gcloud config get project)

• aiplatform.googleapis.com : размещает вашего агента на Agent Runtime, включая Gemini Enterprise Sessions и Memory Bank, и использует модель Gemini.
• API BigQuery ( bigquery.googleapis.com ): SQL-запросы к общедоступным и закрытым наборам данных.
• API телеметрии ( telemetry.googleapis.com ): трассировка OpenTelemetry для мониторинга агентов.

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

Установите ADK

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

mkdir -p ~/adk-deploy-scale
cd ~/adk-deploy-scale
uv init --bare
uv add google-adk google-auth google-cloud-bigquery "google-cloud-aiplatform[agent_engines]"

uv создает изолированную среду Python для этого практического занятия, поэтому вам не нужно ничего активировать. Добавляйте префикс uv run к командам Python.

Пакет google-adk включает в себя инструмент командной строки adk , который вы будете использовать для тестирования и развертывания агента. adk deploy использует google-cloud-aiplatform для создания вашего агента в Agent Runtime, а google-cloud-bigquery — это клиентская библиотека, лежащая в основе инструментов BigQuery в ADK.

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

В папке ~/adk-deploy-scale создайте каталог агента. Все последующие команды выполняйте из ~/adk-deploy-scale (родительской папки для data_science_agent/ ):

mkdir data_science_agent

Затем выполните следующую команду, чтобы создать файл data_science_agent/.env , содержащий ваш проект, регион, куда вы будете развертывать агента, и настройки для развернутого агента. adk deploy считывает этот файл, поэтому эти настройки будут работать и в новом окне терминала.

cat > ~/adk-deploy-scale/data_science_agent/.env <<EOF
GOOGLE_CLOUD_PROJECT=$(gcloud config get project)
GOOGLE_CLOUD_LOCATION=us-central1
GOOGLE_GENAI_USE_ENTERPRISE=True
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
EOF

• GOOGLE_CLOUD_PROJECT и GOOGLE_CLOUD_LOCATION : идентификатор вашего проекта (заполняется из gcloud ) и регион, в котором работает агент.
• GOOGLE_GENAI_USE_ENTERPRISE : использует ADK для вызова Gemini через ваш проект Google Cloud.
• OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT : регистрирует полные входные запросы и ответы агента, полезно для отладки.

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

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

adk-deploy-scale/
  data_science_agent/
    .env
    __init__.py
    agent.py
    requirements.txt    # created in the Deploy step

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

Создайте файл 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.

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

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.integrations.bigquery import BigQueryCredentialsConfig
from google.adk.integrations.bigquery import BigQueryToolset
from google.adk.models import Gemini
from google.adk.tools.preload_memory_tool import PreloadMemoryTool
from google.genai import types
import google.auth

PROJECT_ID = os.getenv("GOOGLE_CLOUD_PROJECT")
if not PROJECT_ID:
    raise ValueError(
        "GOOGLE_CLOUD_PROJECT environment variable is required. "
        "Add it to data_science_agent/.env: 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 Agent 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 Runtime, 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(
        model="gemini-3.8-flash",
        # gemini-3.8-flash is served from the global endpoint. The agent
        # itself runs in GOOGLE_CLOUD_LOCATION (us-central1).
        client_kwargs={"location": "global"},
        retry_options=types.HttpRetryOptions(attempts=5),
    ),
    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. Приложение инкапсулирует корневой агент в развертываемое приложение, которое может обслуживать среда выполнения агента. name должно совпадать с именем каталога ( data_science_agent ) — adk web использует это для поиска и загрузки агента.
4. Инструкция предписывает агенту использовать проект выставления счетов для SQL-запросов и запоминать пользовательские настройки.
5. Gemini с client_kwargs={"location": "global"} отправляет вызовы модели на глобальную конечную точку, где доступен gemini-3.8-flash . Сам агент работает в us-central1 : adk deploy устанавливает GOOGLE_CLOUD_LOCATION на развернутом агенте в регион, в который вы развертываете, поэтому местоположение модели задается в коде.

4. Развертывание в среде выполнения агента.

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

google-adk
google-genai
google-auth
google-cloud-bigquery
python-dotenv
opentelemetry-instrumentation-google-genai
opentelemetry-instrumentation-httpx
opentelemetry-instrumentation-grpc

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

Не добавляйте google-cloud-aiplatform в requirements.txt , даже если вы установили его локально. adk deploy добавит его за вас (вместе с версией ADK, которую вы используете для развертывания), но только если он еще не указан в вашем requirements.txt . Самостоятельное указание может вызвать конфликты версий пакетов OpenTelemetry, которые незаметно нарушат работу инструментария, из-за чего трассировки не будут отображаться на вкладке «Трассировки».

adk deploy также считывает созданный вами ранее файл data_science_agent/.env и устанавливает его параметры для развернутого агента.

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

uv run adk deploy agent_engine \
  --project=$(gcloud config get project) \
  --region=us-central1 \
  --display_name="Data Science Agent" \
  --otel_to_cloud \
  data_science_agent

В начале вывода отображаются две желтые строки: « Ignoring GOOGLE_CLOUD_PROJECT in .env ... и Ignoring GOOGLE_CLOUD_LOCATION in .env ... . Это ожидаемо: флаги --project и --region имеют приоритет над одинаковыми значениями в .env .

Флаг	Цель
--project / --region	Целевой проект и регион Google Cloud
--display_name	Удобочитаемое имя, отображаемое в консоли Cloud Console.
--otel_to_cloud	Экспортирует трассировки и журналы OpenTelemetry в Google Cloud и включает телеметрию ( GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY=true ) на развернутом агенте.

Развертывание обычно занимает 5–10 минут . После завершения в выходных данных отображается имя ресурса вашего агента ( projects/.../reasoningEngines/ ) и ссылку для просмотра в облачной консоли.

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

Если ссылка, отображаемая командой adk deploy не работает, откройте страницу «Развертывания» в консоли Cloud Console и щелкните по своему агенту.

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

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

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

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

PROJECT_NUMBER=$(gcloud projects describe $(gcloud config get 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 $(gcloud config get project) \
  --member="serviceAccount:${SA}" \
  --role="roles/bigquery.jobUser"

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

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

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

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

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

Откройте страницу «Развертывания» в консоли Google Cloud. Щелкните по развернутому агенту, затем перейдите на вкладку «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 минуты после завершения запроса. Если вы пока не видите никаких трассировок, подождите немного и обновите страницу.

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

При развертывании с --otel_to_cloud adk deploy создает контейнер, в котором запускается сервер API ADK с включенной функцией OpenTelemetry. В среде выполнения агента сервер инициализирует конвейер OpenTelemetry, который:

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

Развернутый контейнер включает ADK, SDK OpenTelemetry и экспортер, но не включает пакеты инструментов . Именно поэтому в вашем requirements.txt указаны все три. Без них сервер API ADK выдает предупреждение и пропускает эти сегменты.

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

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

1. Убедитесь, что API телеметрии включен : вы включили его на этапе настройки. Проверьте это с помощью команды: gcloud services list --enabled --project=$(gcloud config get project) | grep telemetry
2. Проверьте Cloud Logging на наличие предупреждений : перейдите в Logging > Logs Explorer и найдите "proceeding without" или "GoogleGenAiSdkInstrumentor" . Предупреждение, указывающее на инструментарий (GenAI, HTTPX или gRPC), означает, что соответствующий пакет opentelemetry-instrumentation-* отсутствует в вашем requirements.txt .
3. Не добавляйте google-cloud-aiplatform в ваш requirements.txt . adk deploy добавляет его автоматически; самостоятельное указание этого параметра может привести к конфликтам пакетов OpenTelemetry и незаметно нарушить работу инструментария.

9. Уборка

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

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

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

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

gcloud projects delete <YOUR_PROJECT_ID>

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

cd ~
rm -rf ~/adk-deploy-scale

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

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

Что вы узнали

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

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

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

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

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