BigQuery Канвэрсацыйянальны Агент на 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 на Vertex AI – двігун для выканання логічных расчынань.
- Набор засобаў BigQuery, які поставляецца разам з ADK для аналізу схем і выканання запытакаў SQL.
- Vertex AI Agent Engine – кераваны рантайм, які вікорыстоўваецца для развертвання.
Настройка праекта
Фундаментам являецца чысты Python-праект з установленым ADK; тэорэтычна для яго настройкі трэба тры каманды: стварыць вяртую срэду, актывараваць яе і выконаць pip-install пакета.
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
Рэштка павторыходзіць за зместамі Default Credentials прыкладнення, стварае канфігурацыю атрыбутаў, насталявае набор засобаў і візначае сам агента, укладаючы ў гэта йго мадэль, інструкціі і фільтры засобаў.
# 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
Потым выклікаецца каманда deploy, якая берае праект, рэгіон і кантэйнер для прыготавкі.
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: мэмарыя сесіі з адпаведным запросам на стыканне, версіяваныя правілы з методам detect-then-block, а таксама RAG, які базуецца на S3.
- Практычныя заўважэнні: Google ADK: стварэнне мнагаагентных сістэм — Паследоўны апіс практычных заўважэнняў: Google ADK: стварэнне мнагаагентных сістэм: контракты, перакананні і шаблоны коду для команд, якія вікорыстоўваюць гэты патэрн.