bigquery vertex-ai google-adk gemini ai-agents google-cloud-platform

BigQuery Conversational Agent auf Vertex AI mit Google ADK: Sechs Fallstricke

Erstellen Sie einen BigQuery-Agenten für natürliche Sprache mit Google ADK und Gemini, deployen Sie ihn im Vertex AI Agent Engine und vermeiden Sie die Fallen bezüglich Python, Abhängigkeiten, Abrechnung und IAM.

Verlag: REACTAPP.TOPAuf dieser Website hinzugefügt 28. Okt. 202610 Min. Lesezeit2389 Wörter

Quellen: Building a BigQuery Conversational Agent on Vertex AI with ADK and the traps nobody warns you about

Das Problem: Einfache Fragen stecken in der Warteschlange

Unternehmensteams benötigen ständig Zahlen, die bereits im Data Warehouse vorhanden sind. Wie viele Bestellungen wurden letzten Monat versandt? Welches Produkt verkauft sich am besten? Jede Frage wird zu einem Ticket, anschließend zu einer manuellen Extraktion und dann zu einem Hin- und Herwechsel, der Stunden oder Tage in Anspruch nehmen kann – obwohl die Antwort nur durch eine einzige Abfrage in BigQuery zu erhalten ist.

Die Alternative ist ein konversationaler Agent. Der Benutzer gibt eine Frage in einfachem Englisch ein, der Agent erstellt selbst den SQL-Code, führt ihn in BigQuery aus und gibt das Ergebnis zurück. Kein Ticket, keine Extraktion, keine SQL-Kenntnisse erforderlich. Das Funktionieren davon auf einem Laptop ist der einfachere Teil. Die richtige Implementierung auf Google Cloud ist jedoch der Punkt, an dem versteckte Probleme auftauchen – darunter Versionskonflikte von Python, undeklarierte Abhängigkeiten sowie Überraschungen im IAM-System, die erst dann sichtbar werden, wenn der Agent in der Cloud läuft.

Der Stack für diese Konfiguration besteht aus vier Komponenten:

Google ADK, das Framework des Agentenentwicklungskits, das den Agenten steuert.
Gemini 2.5 Flash on Vertex AI als Reasoning-Engine.
Das BigQuery-Toolset, das von ADK mitgeliefert wird, um Schemata zu überprüfen und SQL-Anfragen auszuführen.
Vertex AI Agent Engine, die verwaltete Laufzeitumgebung, die für die Bereitstellung verwendet wird.

Projekt einrichten

Die Grundlage ist ein neues Python-Projekt mit installiertem ADK; theoretisch sind dafür drei Befehle nötig: ein virtuelles Umfeld erstellen, es aktivieren und das Paket mit pip installieren.

python3 -m venv .venv
source .venv/bin/activate
pip install google-adk

Falle 1: Die Python-Version. ADK benötigt Python 3.10 oder neuer. Ein Mac mit dem noch vorhandenen System-Python 3.9 scheint zunächst in Ordnung zu sein, bis der Agent gestartet wird – anschließend werden zahlreiche FutureWarning-Meldungen ausgegeben, gefolgt von einem schwerwiegenden Fehler, der besagt, dass MCP Python 3.10 oder neuer erfordert. Unter macOS sollte man jeden Konflikt mit dem System-Interpreter vermeiden und stattdessen über Homebrew eine saubere Version installieren, wie im nächsten Abschnitt beschrieben.

brew install python@3.12
python3.12 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install google-adk

Überprüfen Sie das Ergebnis mit python --version; dabei sollte die Version 3.12.x sein, und stellen Sie sicher, dass der Shell-Prompt mit (.venv) beginnt. Anschließend erstellen Sie das Agent-Skelett über die ADK-Befehlszeile.

adk create bq_agent_app

Fallstrick 2: Ordnernamen. Der Ordner des Agents muss ein gültiger Python-Identifikator sein, das bedeutet, er darf nur Buchstaben, Ziffern und Unterstriche enthalten. Ein mit Bindestrichen versehener Name wie bq-agent-app führt zum Deploy-Fehler mit der Meldung Invalid agent name. Die Form mit Unterstrichen bq_agent_app funktioniert. Es handelt sich um ein winziges Detail, das leicht zehn Minuten Zeit kosten kann.

Der gesamte Agent in einer Datei

Hier zeigt sich der Vorteil von ADK. Logik, die sonst Hunderte von Zeilen an Orchestrierungskodierung erfordern würde, passt in eine einzige deklarative Datei. Die Datei beginnt mit Importen für die Google-Authentifizierung, die Agent-Klasse, das BigQuery-Toolset sowie deren Klassen für Anmeldeinformationen und Tool-Konfigurationen.

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

Der Rest wiederverwendet die Standardanmeldeinformationen der Anwendung, erstellt die Konfiguration für die Anmeldeinformationen, konfiguriert das Werkzeugset und definiert den Agenten selbst, einschließlich seines Modells, der Anweisungen sowie des Toolsfilters.

# 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],
)

Drei Aspekte in dieser Datei veranschaulichen die eigentliche Idee eines Agenten.

Zunächst sind Denken und Handeln getrennt. Gemini übernimmt das Schlussfolgern, besitzt aber allein keinerlei Kenntnis über Ihre Daten und keinen Zugang zu BigQuery. Das BigQueryToolset stellt die „Hände“ bereit, also Tools, die das Modell nutzen kann – beispielsweise zur Überprüfung eines Schemas oder zum Ausführen einer Abfrage. Alles läuft in einem Schleifenprozess ab: Das Modell betrachtet die Frage und wählt ein Tool aus, ADK führt es aus, die Ausgabe kehrt zurück, und das Modell entscheidet sich für den nächsten Schritt, bis es eine Antwort geben kann. Diese Schleife bildet die Trennlinie zwischen einem Agenten und einem Chatbot. Ein Chatbot spricht, während ein Agent innerhalb eines kontrollierten Zyklus in Ihren Systemen handelt.

Zweitens ist die Anweisung das wichtigste Mittel. Der Befehl, der dem Agenten mitteilt, das Schema vor dem Schreiben von SQL zu überprüfen, verhindert, dass er sich eigene Spaltennamen ausdenkt. Das Verhalten wird durch die Anweisungen und nicht durch Code geprägt, und das ist wichtiger, als es auf den ersten Blick erscheint.

Drittens dient tool_filter zur Kontrolle der Berechtigungen – es stellt nur die Tools bereit, die der Agent tatsächlich benötigt. Für den Einsatz mit sensiblen Daten in der Produktion sollte dieser Filter auf Lesezugriff beschränkt werden, damit der Agent Abfragen ausführen kann, aber nichts ändern darf.

Lokaler Betrieb

ADK bietet zwei Möglichkeiten, einen Agenten auszuführen. adk run bq_agent_app öffnet ein einfaches Terminal-Chat-Fenster, während adk web eine lokale Web-Oberfläche mit einem Chat-Fenster sowie einem Events-Fenster startet, in dem jeder Toolaufruf aufgelistet wird. Die Web-Oberfläche ist zwar ansprechender, doch adk run eignet sich besser zum Fehlersuchen, da Fehler offen angezeigt werden anstatt stillschweigend fehlschlagen zu lassen.

Falle 3: Abhängigkeiten, die das Toolset nie deklariert

Auf dieser Stufe gehen Dinge kaputt, und das führt zu den meisten Rückfragen. Das BigQuery-Toolset wird als in ADK integriert beschrieben, verlässt sich jedoch heimlich auf Pakete, die google-adk nicht installiert. Der erste Start scheitert mit ModuleNotFoundError: No module named 'google.cloud'. Die Installation von google-cloud-bigquery führt zu einem anderen Fehler, cannot import name 'dataplex_v1', gefolgt von einer Anfrage nach db-dtypes. Das sind drei Fehler in Folge, jeweils verursacht durch ein Paket, das das Toolset voraussetzt, aber nie auflistet.

Die Lösung besteht darin, alle drei im Voraus zu installieren und den endlosen Kreislauf zu umgehen.

pip install google-cloud-bigquery google-cloud-dataplex db-dtypes

Dann starten Sie die Web-Oberfläche.

adk web

Öffnen Sie die lokale URL, wählen Sie den Agenten aus und stellen Sie eine einfache Frage, um die Funktionalität zu überprüfen.

List the tables in bigquery-public-data.thelook_ecommerce

Die Testdaten sind thelook_ecommerce, ein synthetisches E-Commerce-Datensatz, den Google öffentlich veröffentlicht. Kunden, Produkte und Bestellungen machen ihn geeignet für einen Agenten zur Beantwortung geschäftlicher Fragen, wobei keine echten Daten verwendet werden. Wenn die Tabellenliste angezeigt wird, funktioniert die Einrichtung. Achten Sie auf das Events-Panel, in dem gezeigt wird, wie der Agent get_table_info mit execute_sql verknüpft. Dieses Panel bietet den klarensten Überblick über das Verhalten des Agents und eignet sich gut für Demonstrationen.

Falle 4: das Abrechnungsprojekt

Sobald die Grundfunktionen funktionieren, versuchen Sie es mit einer echten Frage.

What is the most sold product?

Der Agent lehnt höflich ab. Er gibt an, keine Berechtigung zu haben, Aufgaben im Projekt bigquery-public-data zu erstellen, zeigt anschließend den SQL-Code an, den er ursprünglich ausgeführt hätte, und bittet darum, auf ein Projekt verwiesen zu werden, für das er Berechtigungen hat. Es sieht wie eine Fehlkonfiguration aus, ist es aber nicht. Dies ist ein Konzept von BigQuery, das im Nachhinein offensichtlich ist, aber bei fast allen Anfängern zu Problemen führt.

bigquery-public-data ist ein ausschließlich zum Lesen bestimmtes Projekt, das Google gehört. Sie können seine Tabellen lesen, aber keine Abfragen darin ausführen, da die Ausführung einer Abfrage eine Aufgabe erstellt und eine solche Aufgabe einem Projekt in Rechnung gestellt werden muss, für das Sie Berechtigungen haben. Google erlaubt es niemandem, Rechenleistung für sein Projekt in Rechnung zu stellen. Das Lesen von Daten und die Ausführung einer Abfrage sind daher zwei getrennte Vorgänge, die mit zwei verschiedenen Projekten verbunden sind: Eines enthält die Daten und das andere bezahlt für die Rechenleistung.

Die Korrektur weist das Toolset an, Aufgaben in Ihrem eigenen Projekt auszuführen, während es weiterhin aus dem öffentlichen Datensatz liest. Die Einstellung lautet compute_project_id und befindet sich in BigQueryToolConfig, das zuerst importiert werden muss.

from google.adk.tools.bigquery.config import BigQueryToolConfig

Dann wird das Toolset mit dieser Konfiguration erstellt, wobei ein Kommentar angezeigt, welche Aufgaben in Ihrem Projekt ausgeführt und abgerechnet werden.

bigquery_toolset = BigQueryToolset(
    credentials_config=credentials_config,
    bigquery_tool_config=BigQueryToolConfig(
        compute_project_id="your-project-id",  # jobs run and bill here
    ),
    tool_filter=[...],
)

Nach der erneuten Bereitstellung erscheint eine zweite, interessantere Wand. Der Agent weiß nun, dass er Ihr Projekt abrechnen soll, kommt aber zu dem Schluss, dass er das öffentliche Datenset überhaupt nicht lesen kann, und weigert sich erneut. Diesmal liegt er falsch, denn das Lesen eines öffentlichen Datensets aus dem eigenen Abrechnungsprojekt ist normal und erlaubt. Der Agent war einfach übervorsichtig.

Hier kommt wieder der Punkt ins Spiel, bei dem Anweisungen als Hebel dienen. Das Problem liegt in der Anfrage, nicht im Code, denn der Agent hatte sich auf eine nicht existierende Regel berufen. Ein einziger expliziter Satz in den Anweisungen löst das Problem. In diesem Satz steht, dass Abfragen immer im konfigurierten Abrechnungsprojekt ausgeführt werden, dass Daten aus jedem zugänglichen Datenset, einschließlich öffentlicher, gelesen werden können und dass das Lesen eines öffentlichen Datensets aus dem Abrechnungsprojekt normal ist und niemals ein Grund zur Ablehnung sein sollte.

Nach einer weiteren Neuverteilung inspiziert der Agent das Schema, erstellt die Vernetzung, führt sie aus und gibt das beste Produkt zusammen mit der verwendeten Abfrage zurück. Die Beispiele zeigen, dass ein Agent über die richtigen technischen Zugriffsrechte verfügen kann und dennoch aufgrund unklarer Anweisungen falsch handelt. Eine präzise Formulierung der Anweisungen ist hier Teil der Ingenieurarbeit, keine zusätzliche Fähigkeit.

Veröffentlichung im Agent Engine

Auf einem Laptop auszuführen ist eine Sache. Erst auf Googles eigener Infrastruktur wird der Agent wirklich nützlich. Vertex AI Agent Engine ist die verwaltete Laufzeitumgebung, die speziell für ADK-Agenten entwickelt wurde: Man übergeben den Agenten an Google, der ihn dann ausführt, skaliert und am Laufen hält – ohne dass man Server verwalten muss.

Die Veröffentlichung beginnt mit der Aktivierung einiger APIs sowie der Erstellung eines Staging-Buckets, in den ADK den verpackten Code platziert.

gcloud services enable aiplatform.googleapis.com storage.googleapis.com
gcloud storage buckets create gs://your-project-id-adk-staging --location=us-central1

Dann kommt der Deploy-Befehl, der das Projekt, die Region sowie den Staging-Bucket verwendet.

adk deploy agent_engine \
  --project=your-project-id \
  --region=us-central1 \
  --staging_bucket=gs://your-project-id-adk-staging \
  bq_agent_app

Das dauert ein paar Minuten, weil im Hintergrund ein Container erstellt wird, und die nächste Falle befindet sich innerhalb dieses Containers.

Falle 5: Der Container weiß nichts über Ihren Laptop

Der erste Ausführungsversuch von Agent Engine endet mit einem Absturz aufgrund derselben Fehlermeldung cannot import name 'dataplex_v1', von der angenommen wurde, sie sei gelöst. Eine Bereitstellung kann nicht erkennen, was auf dem Rechner eines Entwicklers installiert ist. Sie kennt nur die in einer requirements.txt-Datei aufgeführten Pakete, die sich im Agent-Ordner befinden. Der Laptop enthielt also die Abhängigkeiten, während der Container sie nicht hatte. Diese Lektion gilt für alle GCP-Ziele – egal ob Cloud Functions, Cloud Run oder Agent Engine. Lokale Tests und Produktionstests sind unterschiedliche Anforderungen, und eine explizite Abhängigkeitsliste verbindet die beiden miteinander.

Die Lösung besteht darin, die Pakete ausdrücklich aufzulisten.

# requirements.txt
google-adk
google-cloud-bigquery
google-cloud-dataplex
db-dtypes

Durch das Neuverlegen installiert der Container, was er benötigt.

Falle 6: Der Agent ist nicht mehr Sie

Die letzte Falle lehrt am meisten über Agenten in der Produktion. Die Bereitstellung ist erfolgreich, doch eine im Cloud Playground eingegebene Anfrage wird von BigQuery abgelehnt, weil die Berechtigung bigquery.jobs.create fehlt. Das ist kein Fehler – IAM funktioniert genau so, wie es konzipiert wurde.

Auf einem Laptop handelte der Agent als Sie und nutzte alle Ihre Berechtigungen. Nach der Bereitstellung läuft er unter einem Service-Konto, im Grunde einer Roboteridentität, und diese Identität verfügt zunächst über keine Rechte in BigQuery. Genau dieses Design sorgt dafür, dass Agenten in der Nähe sensibler Daten sicher sind. Ein Agent kann nicht über das hinausgehen, was seine Identität zulässt – nichts bleibt verborgen, und IAM beschränkt ihn genauso wie jede Person.

Das Servicekonto benötigt zwei Rollen, eine zum Ausführen von Abfragen und eine zum Lesen von Daten. Der erste Block gewährt roles/bigquery.jobUser.

gcloud projects add-iam-policy-binding your-project-id \
  --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
  --role="roles/bigquery.jobUser"

Die zweite gewährt roles/bigquery.dataViewer.

gcloud projects add-iam-policy-binding your-project-id \
  --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
  --role="roles/bigquery.dataViewer"

Warten Sie einen Moment, bis sich die Änderung durchgesetzt hat, und fragen Sie erneut im Playground. Der Agent antwortet anschließend aus der Cloud – vollständig auf Googles Infrastruktur laufend – während das Laptop geschlossen bleibt.

Lektionen aus dem Aufbau

Ein Agent ist kein Chatbot. Der Unterschied liegt im Zyklus, in dem das Modell nachdenkt, ein Tool aufruft, das Ergebnis prüft und dies wiederholt, bis es antworten kann.
Die Anweisung erledigt den größten Teil der Arbeit. Derselbe Code und dieselben Zugriffsrechte führen je nach Formulierung der Anweisung zu sehr unterschiedlichem Verhalten; das Weglassen erfundener Spaltennamen sowie unnötiger Ablehnungen war reine Prompt-Optimierung.
Beschafft zu haben garantiert noch keine Installation. Das BigQuery-Toolset kommt zwar mit ADK, erfordert aber google-cloud-bigquery, google-cloud-dataplex und db-dtypes; installieren Sie diese daher zuerst.
Lokal und in der Produktion sind unterschiedliche Welten. Lokal läuft der Agent unter Ihrer Identität zusammen mit Ihren Paketen. Nach dem Bereitstellen läuft er als Servicekonto mit nur den Elementen, die in requirements.txt aufgeführt sind, wobei beide Unterschiede ausdrücklich geschlossen werden.
IAM sorgt für Sicherheit. Ein bereitgestellter Agent kann die Rechte seines Servicekontos nicht überschreiten, sodass jeder Zugriff ausdrücklich erfolgt, nachvollziehbar ist und widerrufbar – genauso wie bei einem menschlichen Benutzer. Das ist die Sicherheit, die Geschäftspartner vor dem Zugriff eines Agents auf echte Daten benötigen.

Ein Projekt, das mit der Frage nach der Extraktion von Antworten in natürlicher Sprache aus BigQuery beginnt, endet als vollständig implementierter Vertex AI-Agent, der Geschäftsfragen ohne SQL und ohne manuelle Extraktion beantwortet. Alles davon ist native GCP-Lösung – somit muss ein Team, das bereits BigQuery nutzt, keinen neuen Technologiestack übernehmen, sondern fügt lediglich Gemini zu den bereits vorhandenen Tools hinzu. In den Tutorials werden keine dieser Fallstricke erwähnt: die Python-Version, die undeklarierten Abhängigkeiten, das Verwechslungsrisiko bei den Billing-Projekten sowie der Service-Account ohne Berechtigungen. Wenn man die Schwachstellen kennt, spart das Stunden – beginnen Sie daher klein, testen Sie verschiedene Ansätze und lesen Sie die Fehlermeldungen.