BigQuery Conversational Agent в Vertex AI с Google ADK: шесть ловушек
Создайте агента BigQuery на естественном языке с использованием Google ADK и Gemini, разверните его в Vertex AI Agent Engine и избегайте проблем, связанных с Python, зависимостями, оплатой и IAM.
Источники: Building a BigQuery Conversational Agent on Vertex AI with ADK and the traps nobody warns you about
Проблема: простые вопросы застревают в очереди
Команды бизнеса постоянно нуждаются в данных, уже хранящихся в хранилище данных. Сколько заказов было отправлено в прошлом месяце? Какой продукт продаётся лучше всего? Каждый вопрос превращается в заявку, затем следует ручной извлечение данных, после чего начинается цикл обмена сообщениями, который может занять часы или дни, хотя ответ находится всего в одном запросе в BigQuery.
Альтернативой является конверсационный агент. Пользователь вводит вопрос на простом английском языке, агент сам формирует SQL-запрос, выполняет его в BigQuery и возвращает результат. Не требуется никаких заявок, извлечения данных или знаний SQL. Реализовать это на ноутбуке — это простая часть. Настоящие проблемы возникают при правильной развертке в Google Cloud: конфликты версий Python, незаявленные зависимости и сюрпризы с IAM, которые проявляются только тогда, когда агент запускается в облаке.
Стек для этой сборки состоит из четырех компонентов:
- Google ADK — фреймворк для разработки агентов, отвечающий за их управление.
- Gemini 2.5 Flash on Vertex AI в качестве движка рассуждений.
- Набор инструментов BigQuery, поставляемый ADK для анализа схем и выполнения SQL-запросов.
- Vertex AI Agent Engine — управляемая среда выполнения, используемая для развертывания.
Настройка проекта
Основой служит новый Python-проект с установленным ADK; теоретически для его настройки требуется три команды: создание виртуальной среды, её активация и установка пакета с помощью pip.
python3 -m venv .venv
source .venv/bin/activate
pip install google-adk
Ловушка 1: версия Python. Для ADK требуется Python 3.10 или новее. Mac с системным Python 3.9 кажется работоспособным до запуска агента, но затем выводится множество сообщений FutureWarning, а после этого появляется серьезная ошибка с указанием на то, что MCP требует Python 3.10 или новее. На macOS следует избегать проблем с системным интерпретатором и установить чистую версию через Homebrew, как описано ниже.
brew install python@3.12
python3.12 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install google-adk
Проверьте версию с помощью команды python --version — она должна быть 3.12.x, — и убедитесь, что строка промпта терминала начинается с (.venv). После этого сгенерируйте структуру агента с помощью командной строки ADK.
adk create bq_agent_app
Ловушка 2: имена папок. Имя папки агента должно соответствовать правилам валидного идентификатора в Python, то есть в нем могут использоваться только буквы, цифры и подчеркивания. Имя с дефисами, такое как bq-agent-app, приводит к сбою при развертывании с ошибкой Invalid agent name. Формат с подчеркиваниями bq_agent_app работает корректно. Это незначительная деталь, но она может легко занять десять минут.
Весь агент в одном файле
Именно здесь проявляется преимущество ADK. Логика, которая в противном случае потребовала бы сотни строк кода для оркестрации, помещается в один декларативный файл. Файл начинается с импортов для аутентификации в Google, класса Agent, набора инструментов BigQuery, а также классов для настройки учетных данных и инструментов.
import google.auth
from google.adk.agents import Agent
from google.adk.tools.bigquery import BigQueryToolset, BigQueryCredentialsConfig
from google.adk.tools.bigquery.config import BigQueryToolConfig
Остальная часть повторно использует стандартные учетные данные приложения, формирует конфигурацию учетных данных, настраивает набор инструментов и определяет сам агент, включая его модель, фильтры инструкций и инструментов.
# Reuse your Application Default Credentials
application_default_credentials, project = google.auth.default()
credentials_config = BigQueryCredentialsConfig(
credentials=application_default_credentials
)# Google's first-party BigQuery toolset
bigquery_toolset = BigQueryToolset(
credentials_config=credentials_config,
bigquery_tool_config=BigQueryToolConfig(
compute_project_id="your-project-id", # bills the query jobs
),
tool_filter=[
"list_dataset_ids",
"get_dataset_info",
"list_table_ids",
"get_table_info",
"execute_sql",
],
)root_agent = Agent(
model="gemini-2.5-flash",
name="bq_data_assistant",
description="Answers natural-language questions over BigQuery data.",
instruction=(
"You are a data assistant for business teams. "
"When asked a question, first inspect the schema of the relevant "
"tables (get_table_info) BEFORE writing any SQL, so you use real "
"column names and never invent them. "
"You always run your query jobs in the configured billing project, "
"but you CAN read data from any accessible dataset, including public "
"ones. Reading a public dataset from your billing project is normal "
"and allowed, never refuse for that reason. "
"Write standard BigQuery SQL, execute it with execute_sql, then "
"return a clear answer with the number and, in one line, the query used. "
"If a question is ambiguous, ask for clarification before running."
),
tools=[bigquery_toolset],
)
Три ключевых аспекта в этом файле отражают истинную сущность агента.
Во-первых, процессы мышления и действия разделены. Gemini отвечает за логические рассуждения, но сам по себе не обладает информацией о ваших данных и не имеет доступа к BigQuery. BigQueryToolset предоставляет инструменты, с помощью которых модель может принимать решения, например проверять схему или выполнять запросы. Все это происходит в виде цикла: модель рассматривает вопрос, выбирает инструмент, ADK его запускает, поступает результат, и модель выбирает следующее действие до тех пор, пока не сможет дать ответ. Именно этот цикл является границей между агентом и чат-ботом. Чат-бот просто общается, тогда как агент действует в ваших системах в рамках контролируемого цикла.
Во-вторых, инструкции являются основным инструментом управления. Предложение, требующее от агента проверить схему перед написанием SQL-запроса, предотвращает самовольное создание им имен столбцов. Поведение агента формируется через инструкции, а не через код, и это имеет большее значение, чем кажется на первый взгляд.
В-третьих, tool_filter обеспечивает контроль с минимальными привилегиями, позволяя использовать только те инструменты, которые действительно необходимы агенту. Для работы с конфиденциальными данными в производственных условиях его следует настроить в режим только для чтения, чтобы агент мог выполнять запросы, но не мог ничего изменять.
Запуск локально
ADK предоставляет два способа запуска агента. adk run bq_agent_app открывает обычный терминал для общения, а adk web запускает локальный веб-интерфейс с панелью чата и панелью событий, отображающей каждый вызов инструмента. Веб-интерфейс более удобен, однако adk run предпочтительнее для устранения неполадок, поскольку он отображает ошибки открыто, а не приводит к их скрытому возникновению.
Ловушка 3: зависимости, которые никогда не указываются в наборе инструментов
На этом этапе возникают сбои, и именно они требуют наибольшего количества попыток их устранения. Набор инструментов BigQuery описывается как встроенный в ADK, однако на самом деле он тайно зависит от пакетов, которые google-adk не устанавливает. При первой попытке запуска возникает ошибка ModuleNotFoundError: No module named 'google.cloud'. Установка google-cloud-bigquery приводит к другой ошибке — cannot import name 'dataplex_v1', после чего появляется запрос на установку db-dtypes. Таким образом, происходят три ошибки подряд, каждая из которых вызвана пакетом, который набор инструментов предполагает наличие, но никогда не указывает.
Выход из ситуации — заранее установить все три пакета, чтобы избежать постоянных попыток их установки.
pip install google-cloud-bigquery google-cloud-dataplex db-dtypes
Затем запустите веб-интерфейс.
adk web
Откройте локальный URL, выберите агента и задайте простой вопрос для проверки работы системы водоснабжения.
List the tables in bigquery-public-data.thelook_ecommerce
Тестовые данные — это thelook_ecommerce, синтетический набор данных для электронной коммерции, который Google публикует открыто. Клиенты, товары и заказы делают его подходящим для агента, отвечающего на вопросы бизнеса, причем в нем не используются реальные данные. Если будет отображен список таблиц, значит настройка работает. Следите за панелью «События», где агент объединяет вызовы get_table_info и execute_sql. Эта панель позволяет наилучшим образом увидеть поведение агента и хорошо подходит для демонстраций.
Ловушка 4: проект с финансовым учетом
После проверки основных компонентов попробуйте задать реальный вопрос.
What is the most sold product?
Агент вежливо отказывается. Он сообщает, что у него нет разрешения на создание заданий в проекте bigquery-public-data, затем показывает SQL-запрос, который он хотел бы выполнить, и просит указать проект, в котором у него есть права. Кажется, что это ошибка конфигурации, но это не так. Это концепция BigQuery, которая становится очевидной со временем, но сначала сбивает с толку практически всех.
bigquery-public-data — это проект с ограниченным доступом, принадлежащий Google. Вы можете читать его таблицы, но не можете выполнять в нем запросы, поскольку выполнение запроса создаёт задание, а за задание необходимо взимать плату в проекте, в котором у вас есть права. Google не позволяет никому взимать плату за обработку данных в своём проекте. Следовательно, чтение данных и выполнение запроса — это два отдельных действия, связанные с двумя разными проектами: один хранит данные, а другой оплачивает обработку.
Это решение указывает набору инструментов на выполнение задач в вашем собственном проекте, при этом он продолжает читать данные из общедоступного набора данных. Параметр называется compute_project_id и находится в объекте BigQueryToolConfig, который сначала необходимо импортировать.
from google.adk.tools.bigquery.config import BigQueryToolConfig
Затем набор инструментов создается с использованием этой конфигурации, причем комментарий указывает на то, что задачи выполняются и учитываются в стоимости вашего проекта.
bigquery_toolset = BigQueryToolset(
credentials_config=credentials_config,
bigquery_tool_config=BigQueryToolConfig(
compute_project_id="your-project-id", # jobs run and bill here
),
tool_filter=[...],
)
После повторной развертки появляется вторая, более интересная проблема. Агент теперь знает, как взимать плату за ваш проект, но приходит к выводу, что совершенно не может читать публичный набор данных, и снова отказывается. На этот раз он ошибается, поскольку чтение публичного набора данных из собственного проекта биллинга является нормальным и разрешенным действием. Агент просто проявил чрезмерную осторожность.
Здесь снова пригодится принцип использования инструкций в качестве рычага для решения проблем. Проблема заключается в самом запросе, а не в коде, поскольку агент сам пришел к правилу, которого на самом деле не существует. Одно четкое предложение в инструкции решает эту проблему. В этом предложении говорится, что задания по запросу всегда выполняются в настроенном проекте биллинга, что данные из любого доступного набора данных, включая публичные, могут быть прочитаны, и что чтение публичного набора данных из проекта биллинга является нормальным действием и никогда не должно служить причиной для отказа.
После ещё одной переназначения агент проверяет схему, формирует запрос на объединение данных, выполняет его и возвращает наиболее подходящий продукт вместе с использованным запросом. Приведённый пример показывает, что у агента может быть всё необходимое техническое доступное оборудование, но он всё равно может плохо себя вести из-за неоднозначных инструкций. Точное формулирование запросов является частью инженерной работы, а не дополнительным навыком.
Развертывание в Agent Engine
Работа на ноутбуке — это одно, а работа на инфраструктуре Google — совсем другое; именно там агент становится действительно полезным инструментом. Vertex AI Agent Engine — это управляемая среда выполнения, созданная специально для агентов ADK: вы передаёте агента, а Google занимается его запуском, масштабированием и поддержанием в рабочем состоянии без необходимости управления серверами.
Развертывание начинается с включения нескольких API и создания временной папки, куда ADK помещает упакованный код.
gcloud services enable aiplatform.googleapis.com storage.googleapis.com
gcloud storage buckets create gs://your-project-id-adk-staging --location=us-central1
Затем следует команда развертывания, которая принимает проект, регион и бакет для предварительной обработки.
adk deploy agent_engine \
--project=your-project-id \
--region=us-central1 \
--staging_bucket=gs://your-project-id-adk-staging \
bq_agent_app
Это занимает несколько минут, поскольку в фоновом режиме создается контейнер, и следующая ловушка находится внутри этого контейнера.
Ловушка 5: контейнер ничего не знает о вашем ноутбуке
Первая попытка запуска Agent Engine заканчивается сбоем из-за той же ошибки cannot import name 'dataplex_v1', которая, казалось, была устранена. Система развертывания не может видеть, что установлено на машине разработчика; она знает только пакеты, указанные в файле requirements.txt, находящемся в папке агента. Следовательно, на ноутбуке были зависимости, а в контейнере их не было. Этот урок актуален для всех целей GCP — будь то Cloud Functions, Cloud Run или Agent Engine. Успешная работа в локальных условиях и в производственной среде — это разные вещи, и явный список зависимостей связывает их между собой.
Решение заключается в прямом указании всех пакетов.
# requirements.txt
google-adk
google-cloud-bigquery
google-cloud-dataplex
db-dtypes
После переразвертывания контейнер устанавливает необходимое оборудование.
Ловушка 6: агент больше не является вами
Последняя ловушка наилучшим образом иллюстрирует особенности работы агентов в производственной среде. Развертывание проходит успешно, но запрос, введённый в cloud Playground, отклоняется BigQuery из-за отсутствия разрешения bigquery.jobs.create. Это не ошибка — IAM работает согласно заложенной концепции.
На ноутбуке агент действовал от вашего имени, используя все ваши права. После развертывания он работает под управлением счёта службы, что по сути является идентичностью робота, и у такой идентичности изначально нет прав в BigQuery. Именно такая конструкция обеспечивает безопасность агентов при работе с конфиденциальными данными: агент не может выйти за рамки того, что разрешено его идентичности, ничего не скрыто, а IAM ограничивает его так же, как и любого человека.
Учетной записи сервиса требуются две роли: одна для выполнения запросов, а другая — для чтения данных. Первый блок предоставляет роль roles/bigquery.jobUser.
gcloud projects add-iam-policy-binding your-project-id \
--member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
--role="roles/bigquery.jobUser"
Второй предоставляет roles/bigquery.dataViewer.
gcloud projects add-iam-policy-binding your-project-id \
--member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
--role="roles/bigquery.dataViewer"
Подождите немного, пока изменения распространятся, затем снова попробуйте в Playground. Агент отвечает из облака, полностью работая на инфраструктуре Google, в то время как ноутбук остается закрытым.
Уроки, извлеченные в процессе разработки
- Агент — это не чат-бот. Разница заключается в цикле, в котором модель рассуждает, вызывает инструмент, смотрит результат и повторяет процесс до тех пор, пока не сможет дать ответ.
- Инструкция выполняет основную работу. Одинаковый код и права доступа могут приводить к совершенно разному поведению в зависимости от формулировки инструкции; кроме того, устранение выдуманных имен столбцов и ненужных отказов было чисто вопросом правильной формулировки запроса.
- Наличие компонента в составе не гарантирует его установку. Набор инструментов BigQuery поставляется вместе с ADK, но требует наличия библиотек
google-cloud-bigquery,google-cloud-dataplexиdb-dtypes; поэтому их следует установить первыми. - Локальная среда и производственная среда — это разные миры. В локальной среде агент работает от имени пользователя вместе с его пакетами. После развертывания он работает от имени учетной записи сервиса, имея доступ только к тем компонентам, которые указаны в файле
requirements.txt; обе ситуации регулируются явно. - Механизм IAM обеспечивает безопасность. Развернутый агент не может превысить полномочия своей учетной записи сервиса, поэтому каждый запрос на доступ является прозрачным, отслеживаемым и может быть отозван, так же как и у человека-пользователя. Именно это дает уверенность заинтересованным сторонам перед предоставлением агенту доступа к реальным данным.
Проект, который начинался с вопроса о получении ответов на естественном языке из BigQuery, завершился созданием полностью развернутого агента Vertex AI, способного отвечать на бизнес-вопросы без использования SQL и без ручной обработки данных. Всё это реализовано с использованием инструментов GCP, поэтому команда, уже работающая с BigQuery, не вынуждена переходить на новую технологическую платформу — она просто добавляет Gemini к уже существующим инструментам. В учебниках не упоминается ни одна из этих проблем: версия Python, незаявленные зависимости, путаница с проектами для оплаты и сервисные учётные записи без необходимых прав. Знание возможных ошибок экономит часы работы, поэтому начните с малого, создавайте ошибки и изучайте сообщения об ошибках.
Связанные материалы
- Агенты Bedrock: краткое изложение информации, версионированные ограничения и база знаний — Управление агентами Bedrock с использованием Terraform: память сессии с пользовательским запросом на краткое изложение, версионированные ограничения с механизмом обнаружения и блокировки, а также система RAG с хранением в S3.
- Практические рекомендации: разбор Google ADK: создание многоагентных систем с его использованием — Подробное руководство по практическим рекомендациям: разбор Google ADK: создание многоагентных систем с его использованием: контракты, проверки и готовые блоки кода для команд, внедряющих эту архитектуру.