BigQuery Conversational Agent w Vertex AI z Google ADK: sześć pułapek
Stwórz agenta w języku naturalnym dla BigQuery przy użyciu Google ADK i Gemini, wdroż go w Vertex AI Agent Engine oraz uniknij pułapek związanych z Pythonem, zależnościami, rachunkowością i IAM.
Źródła: Building a BigQuery Conversational Agent on Vertex AI with ADK and the traps nobody warns you about
Problem: proste pytania utknięte w kolejce
Zespoły biznesowe stale potrzebują danych już dostępnych w magazynie danych. Ile zamówień zostało wysłanych w zeszłym miesiącu? Który produkt sprzedaje się najlepiej? Każde pytanie zamienia się w zgłoszenie, następnie wymaga ręcznego wydobycia informacji, a potem serii korespondencji, która może trwać godziny lub dni, mimo że odpowiedź znajduje się zaledwie w jednym zapytaniu w BigQuery.
Aльтernatywą jest agent konwersacyjny. Użytkownik wpisuje pytanie w zwykłej angielszczyźnie, agent sam tworzy zapytanie SQL, uruchamia je w BigQuery i zwraca wynik. Nie ma potrzeby tworzenia zgłoszeń, wydobycia danych ani umiejętności obsługi SQL. Uruchomienie tego na laptopie to najprostsza część. Prawdziwe problemy pojawiają się podczas prawidłowego wdrożenia na Google Cloud – w tym konflikty wersji Pythona, nierozdane zależności oraz problemy z IAM, które pojawiają się dopiero wtedy, gdy agent działa w chmurze.
Stack używany w tym budowaniu składa się z czterech elementów:
- Google ADK – framework Agent Development Kit, który zarządza agentem.
- Gemini 2.5 Flash on Vertex AI jako silnik rozumowania.
- zestaw narzędzi BigQuery dostarczany przez ADK do inspekcji schematów i wykonywania zapytań SQL.
- Vertex AI Agent Engine – zarządzany środowisko wykonawcze używane do wdrażania.
Ustawianie projektu
Podstawą jest nowy projekt w Pythonie z zainstalowanym ADK; teoretycznie wymaga to trzech poleceń: utworzenia środowiska wirtualnego, jego aktywacji oraz zainstalowania pakietu za pomocą pip.
python3 -m venv .venv
source .venv/bin/activate
pip install google-adk
Pułapka nr 1: wersja Pythona. ADK wymaga Pythona 3.10 lub nowszej. Mac z systemowym Pythonem 3.9 wydaje się działać poprawnie, dopóki nie uruchomi się agent – wtedy pojawia się mnóstwo komunikatów FutureWarning, a następnie poważny błąd informujący, że MCP wymaga Pythona 3.10 lub nowszej. W systemie macOS należy uniknąć konfliktów z interpreterem systemowym i zainstalować czystą wersję za pomocą Homebrew, jak opisano w następnym fragmencie.
brew install python@3.12
python3.12 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install google-adk
(.venv). Następnie utwórz szkielet agenta za pomocą linii poleceń ADK.adk create bq_agent_app
Pułapka 2: nazwy folderów. Folder agenta musi być ważnym identyfikatorem w Pythonie, co oznacza, że mogą w nim występować tylko litery, cyfry i podkreślniki. Nazwa z myślnicą, taka jak bq-agent-app, powoduje niepowodzenie deploju z błędem Invalid agent name. Forma z podkreślnikiem, bq_agent_app, działa poprawnie. To drobny szczegół, który może łatwo pochłonąć dziesięć minut.
Cały agent w jednym pliku
Tutaj ADK pokazuje swoją wartość. Logika, która w innych przypadkach wymagałaby setek linijek kodu orkiestracji, mieści się w jednym pliku deklaratywnym. Plik zaczyna się od importów niezbędnych do autoryzacji w Google, klasy Agent, zestawu narzędzi BigQuery oraz klas konfiguracji uprawnień i narzędzi.
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
Pozostała część ponownie wykorzystuje domyślne uprawnienia aplikacji, tworzy konfigurację uprawnień, konfiguruje zestaw narzędzi oraz definiuje sam agent, w tym jego model, filtry instrukcji i narzędzi.
# 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],
)
Trzy elementy w tym pliku stanowią istotę koncepcji agenta.
Najpierw myślenie i działanie są rozdzielone. Gemini zajmuje się rozumowaniem, ale samo w sobie nie posiada żadnej wiedzy o twoich danych ani drogi dostępu do BigQuery. BigQueryToolset dostarcza narzędzia, których model może zdecydować się użyć, takie jak sprawdzenie schematu lub wykonanie zapytania. Wszystko to działa w formie pętli: model rozważa pytanie i wybiera narzędzie, ADK je uruchamia, po czym powraca wynik, a model wybiera kolejny krok, aż uda mu się udzielić odpowiedzi. Ta pętla stanowi granicę między agentem a chatbotem – chatbot rozmawia, natomiast agent działa w twoich systemach w ramach kontrolowanego cyklu.
Po drugie, instrukcja jest głównym narzędziem sterującym. To zdanie, które każe agencie sprawdzić schemat przed napisaniem zapytania SQL, zapobiega tworzeniu przez niego arbitralnych nazw kolumn. Zachowanie agenta kształtuje się poprzez podawane instrukcje, a nie kod, i to ma większe znaczenie, niż się na pierwszy rzut oka wydaje.
Po trzecie, tool_filter stanowi mechanizm ograniczania uprawnień, udostępniając jedynie te narzędzia, których agent rzeczywiście potrzebuje. W przypadku pracy z danymi wrażliwymi należy go dostosować do trybu tylko odczytu, aby agent mógł wykonywać zapytania, ale nie mógł nic zmieniać.
Ruch lokalny
ADK oferuje dwa sposoby uruchamiania agenta. adk run bq_agent_app otwiera zwykłą rozmowę w terminalu, natomiast adk web uruchamia lokalną interfejs internetową z panelem rozmowy oraz panelem Zdarzeń pokazującym każde wezwanie narzędzia. Interfejs internetowy jest bardziej przyjazny, choć adk run jest lepszym wyborem do rozwiązywania problemów, ponieważ pokazuje błędy otwarcie, zamiast sprawiać, że proces zawodzi w tajemnicy.
Pułapka 3: zależności, których zestaw narzędzi nigdy nie deklaruje
W tym etapie rzeczywiście zdarzają się błędy, a ten konkretny wymaga najwięcej prób i korekt. Zestaw narzędzi BigQuery jest opisywany jako wbudowany w ADK, jednak w rzeczywistości polega na pakietach, których google-adk nie instaluje. Pierwsze uruchomienie kończy się błędem ModuleNotFoundError: No module named 'google.cloud'. Instalacja google-cloud-bigquery powoduje inny błąd – cannot import name 'dataplex_v1' – a następnie pojawia się wymóg zainstalowania db-dtypes. To trzy błędy z rzędu, każdy spowodowany pakietem, którego zestaw narzędzi zakłada, ale nigdy nie wymienia.
Rozwiązaniem jest zainstalowanie wszystkich trzech pakietów od razu i uniknięcie tego błędnego cyklu.
pip install google-cloud-bigquery google-cloud-dataplex db-dtypes
Następnie uruchom interfejs WWW.
adk web
Otwórz lokalną adres URL, wybierz agenta i zadaj proste pytanie w celu weryfikacji systemu kanalizacyjnego.
List the tables in bigquery-public-data.thelook_ecommerce
Dane testowe to thelook_ecommerce – syntetyczny zbiór danych e-commerce, który Google publikuje otwarcie. Klienci, produkty i zamówienia sprawiają, że nadaje się on dobrze do agenta odpowiadającego na pytania biznesowe, przy czym nie są używane żadne prawdziwe dane. Jeśli zostanie wyświetlona lista tabel, oznacza to, że konfiguracja działa poprawnie. Obserwuj panel Zdarzeń, w którym agent łączy funkcje get_table_info z execute_sql. Ten panel dostarcza najwyraźniejszego obrazu zachowania agenta i doskonale sprawdza się w demonstracjach.
Pułapka 4: projekt fakturowania
Gdy instalacja zostanie potwierdzona, spróbuj zadać prawdziwe pytanie.
What is the most sold product?
Agent uprzejmie odmawia. Informuje, że nie ma uprawnień do tworzenia zadań w projekcie bigquery-public-data, następnie pokazuje SQL, który miałby zostać wykonyany, i prosi o wskazanie projektu, w którym ma odpowiednie uprawnienia. Wygląda to na błąd konfiguracji, ale tak nie jest. To koncepcja BigQuery, która jest oczywista w perspektywie czasu, ale na początku sprawia trudności niemal wszystkim.
bigquery-public-data to projekt tylko do odczytu należący do Google. Można czytać jego tabele, ale nie można w nim wykonywać zapytań, ponieważ ich wykonanie tworzy zadanie, a zadania muszą być rozliczane w projekcie, w którym ma się uprawnienia. Google nie pozwala nikomu rozliczać kosztów obliczeń w swoim projekcie. Dlatego odczytywanie danych i wykonywanie zapytań to dwie oddzielne czynności związane z dwoma różnymi projektami: jeden przechowuje dane, a drugi opłaca obliczenia.
Rozwiązanie to poleca zestawowi narzędzi wykonywanie zadań w Twoim własnym projekcie, przy jednoczesnym czytaniu z publicznego zbioru danych. Ustawieniem jest compute_project_id, które znajduje się w obiekcie BigQueryToolConfig – ten musi zostać najpierw zaimportowany.
from google.adk.tools.bigquery.config import BigQueryToolConfig
Następnie zestaw narzędzi jest tworzony przy użyciu tej konfiguracji, z komentarzem wskazującym, które zadania są wykonywane i jak jest naliczana opłata w projekcie.
bigquery_toolset = BigQueryToolset(
credentials_config=credentials_config,
bigquery_tool_config=BigQueryToolConfig(
compute_project_id="your-project-id", # jobs run and bill here
),
tool_filter=[...],
)
Po ponownym rozruchu pojawia się drugi, bardziej interesujący mur. Agent wie teraz, jak naliczyć opłaty za twój projekt, ale dochodzi do wniosku, że w ogóle nie może odczytać publicznego zestawu danych, i ponownie odmawia. Tym razem się myli, ponieważ odczytywanie publicznego zestawu danych z własnego projektu fakturowania jest normalne i dozwolone. Agent był po prostu zbyt ostrożny.
Tutaj wraca koncepcja wykorzystania instrukcji jako narzędzia do rozwiązania problemu. Problem leży w instrukcjach, a nie w kodzie, ponieważ agent doszedł do wniosku na podstawie reguły, której w rzeczywistości nie istnieje. Jedno wyraźne zdanie w instrukcjach rozwiązuje ten problem. Zdanie to stanowi, że zlecenia zapytań są zawsze wykonywane w skonfigurowanym projekcie fakturowania, że dane z dowolnego dostępnego zestawu danych, w tym tych publicznych, mogą być odczytywane, oraz że odczytywanie publicznego zestawu danych z projektu fakturowania jest normalne i nigdy nie powinno być powodem do odmowy.
Po kolejnym przetestowaniu agent sprawdza schemat, tworzy zapytanie łączące dane, je uruchamia i zwraca najlepszy produkt wraz z użytym zapytaniem. Ten przykład pokazuje, że agent może mieć odpowiednie uprawnienia techniczne, a mimo to źle funkcjonować z powodu niejednoznacznych instrukcji. Precyzyjne sformułowanie poleceń jest elementem inżynierii w tym procesie, a nie dodatkową umiejętnością.
Rozwijanie w Agent Engine
Uruchamianie na laptopie to jedno, natomiast prawdziwą wartość ma agent uruchamiany bezpośrednio na infrastrukturze Google. Vertex AI Agent Engine to zarządzany środowisko wykonawcze stworzone specjalnie dla agentów ADK: przekazujesz tam agenta, a Google go uruchamia, skaluje i utrzymuje w działaniu, bez konieczności obsługi serwerów.
Rozwój rozpoczyna się od włączenia kilku interfejsów API oraz utworzenia kontenera tymczasowego, w którym ADK umieszcza spakowany kod.
gcloud services enable aiplatform.googleapis.com storage.googleapis.com
gcloud storage buckets create gs://your-project-id-adk-staging --location=us-central1
Następnie przychodzi polecenie deploy, które przyjmuje projekt, region oraz bucket testowy.
adk deploy agent_engine \
--project=your-project-id \
--region=us-central1 \
--staging_bucket=gs://your-project-id-adk-staging \
bq_agent_app
Trwa to kilka minut, ponieważ w tle tworzony jest kontener, a następna pułapka znajduje się wewnątrz tego kontenera.
Pułapka 5: kontener nic nie wie o twoim laptopie
Pierwsze uruchomienie Agent Engine kończy się awarią z dokładnie tym samym błędem cannot import name 'dataplex_v1', który wydawał się rozwiązany. System rozmieszczeń nie może zobaczyć, co jest zainstalowane na komputerze programisty. Zna jedynie pakiety wymienione w pliku requirements.txt umieszczonym w folderze agenta. Dlatego laptop miał zależności, a kontener ich nie miał. Ta lekcja dotyczy każdego celu w GCP – czy to Cloud Functions, Cloud Run, czy Agent Engine. Pomyślne działanie lokalnie i w produkcji to różne kwestie, a wyraźna lista zależności łączy je ze sobą.
Rozwiązaniem jest dokładne opisanie pakietów.
# requirements.txt
google-adk
google-cloud-bigquery
google-cloud-dataplex
db-dtypes
Ponownie uruchom proces, a kontener zainstaluje to, czego potrzebuje.
Pułapka 6: agent to już nie ty
Ostatnia pułapka uczy najwięcej na temat agentów w środowisku produkcyjnym. Deploy odbywa się pomyślnie, ale zapytanie wpisane w cloud Playground zostaje odrzucone przez BigQuery ze względu na brak uprawnień bigquery.jobs.create. To nie jest błąd – to IAM działa zgodnie z projektem.
Na laptopie agent działał jako ty, korzystając ze wszystkich twoich uprawnień. Po zainstalowaniu działa on pod nazwą konta usługowego, czyli w zasadzie tożsamości robota, która początkowo nie ma żadnych uprawnień do BigQuery. To właśnie taka konstrukcja sprawia, że agenci są bezpieczni w pobliżu danych wrażliwych. Agent nie może przekroczyć granic swoich uprawnień, nic nie jest ukrywane, a IAM ogranicza go tak samo jak każdą osobę.
Konto usługowe wymaga dwóch ról: jednej do wykonywania zapytań i drugiej do odczytu danych. Pierwszy blok przyznaje roles/bigquery.jobUser.
gcloud projects add-iam-policy-binding your-project-id \
--member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
--role="roles/bigquery.jobUser"
Druga przyznaje roles/bigquery.dataViewer.
gcloud projects add-iam-policy-binding your-project-id \
--member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
--role="roles/bigquery.dataViewer"
Poczekaj chwilę, aż zmiana się rozprzestrzeni, i spróbuj ponownie w środowisku Playground. Agent odpowiada następnie z chmury, działając w pełni na infrastrukturze Google, podczas gdy laptop pozostaje zamknięty.
Lekcje z procesu budowania
- Agent to nie chatbot. Różnica polega na pętli, w której model rozważa sytuację, wywołuje narzędzie, sprawdza wynik i powtarza proces, aż będzie mógł odpowiedzieć.
- Instrukcja wykonuje większość rzeczywistej pracy. Identyczny kod i dostęp prowadzą do zupełnie różnego zachowania w zależności od sformułowania instrukcji, a usunięcie wymyślonych nazw kolumn oraz niepotrzebnych odmów to czysta praca z promptem.
- Fakt, że coś jest wbudowane, nie gwarantuje, że jest zainstalowane. Zestaw narzędzi BigQuery przychodzi razem z ADK, ale wymaga bibliotek
google-cloud-bigquery,google-cloud-dataplexorazdb-dtypes, więc należy je zainstalować najpierw. - Lokalne środowisko a środowisko produkcyjne to dwa różne światy. W warunkach lokalnych agent działa pod twoją tożsamością wraz z twoimi pakietami. Po rozruchu w środowisku produkcyjnym działa jako konto usługowe, posiadające jedynie te uprawnienia, które wymienia plik
requirements.txt, przy czym obie te różnice są wyraźnie załatwiane. - IAM zapewnia bezpieczeństwo. Agent uruchomiony w środowisku produkcyjnym nie może przekroczyć uprawnień swojego konta usługowego, więc każdy dostęp jest wyraźny, śledzalny i możliwy do cofnięcia, tak jak w przypadku użytkownika ludzkiego. To właśnie daje pewność interesariuszom biznesowym przed udzieleniem agentowi dostępu do rzeczywistych danych.
Projekt, który zaczynał się jako pytanie o pozyskiwanie odpowiedzi w języku naturalnym z BigQuery, kończy się jako w pełni wdrożony agent Vertex AI, który odpowiada na pytania biznesowe bez użycia SQL i bez konieczności ręcznego wydobywania danych. Wszystko to jest częścią rozwiązania GCP, więc zespół już pracujący z BigQuery nie musi przyjmować nowego zestawu narzędzi – wystarczy dodać Gemini do tych, których już używa. W przewodnikach nie wspomina się o żadnych z tych pułapek: wersji języka Python, nierozdeklarowanych zależnościach, pomyłkach w konfiguracji projektu billingowego oraz kontach usługowych bez odpowiednich uprawnień. Znajomość potencjalnych problemów oszczędza godziny pracy, więc zacznij od małych kroków, sprawdzaj różne opcje i analizuj błędy.
Literatura pokrewna
- Bedrock Agents: Sumaryzacja pamięci, wersjonowane zasady bezpieczeństwa i baza wiedzy — Kontrola agentów Bedrock za pomocą Terraform: pamięć sesji z dostosowanym promptem do sumaryzacji, wersjonowane zasady bezpieczeństwa z mechanizmem wykrywania i blokowania, oraz system RAG oparty na S3.
- Praktyczne notatki: Google ADK wyjaśnione: budowanie systemów multi-agentowych z użyciem — Szczegółowy przewodnik po praktycznych notatkach: Google ADK wyjaśnione: budowanie systemów multi-agentowych z użyciem, obejmujący kontrakty, sprawdzania oraz gotowe elementy kodu dla zespołów wdrażających ten model.