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 — це фреймворк Agent Development Kit, який керує агентом.
- 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 пояснено: створення багатоагентних систем, що включає контракти, перевірки та готові фрагменти коду для команд, які використовують цю модель.