KI-Agenten mit Gemini und BigQuery MCP-Server in Cloud Run erstellen und bereitstellen

1. Einführung

Lerninhalte

• Sie erfahren, wie Sie mit dem Agent Development Kit (ADK) und Gemini in der Agent Platform einen KI-Agenten erstellen.
• Sie erfahren, wie Sie KI-Agenten mit dem BigQuery MCP-Server Zugriff auf strukturierte Daten in BigQuery gewähren.

Cloud Run ist eine vollständig verwaltete, serverlose Compute-Plattform, mit der Sie containerisierte Anwendungen und Dienste ausführen können, ohne die zugrunde liegende Infrastruktur verwalten zu müssen.

Das Agent Development Kit (ADK) ist ein Open-Source-Framework für die Entwicklung von Agenten, mit dem Sie zuverlässige KI-Agenten im Unternehmen erstellen, debuggen und bereitstellen können.

BigQuery ist ein vollständig verwaltetes, serverloses Data Warehouse für Unternehmen, in dem Sie große Datasets speichern, abfragen und analysieren können.

Das Model Context Protocol (MCP) standardisiert die Verbindung von Large Language Models (LLMs) und KI-Anwendungen oder -Agenten mit externen Datenquellen. Mit MCP-Servern können Sie deren Tools, Ressourcen und Prompts verwenden, um Aktionen auszuführen und aktualisierte Daten aus dem Backend-Dienst abzurufen. Der BigQuery MCP-Server bietet Ihren KI-Agenten eine direkte und sichere Möglichkeit, Daten in BigQuery zu analysieren. Dieser vollständig verwaltete MCP-Server reduziert den Verwaltungsaufwand, sodass Sie sich auf die Entwicklung intelligenter Agenten konzentrieren können.

2. Einrichtung und Anforderungen

Dieses gesamte Lab kann über die Befehlszeile ausgeführt werden. Sie können Cloud Shell verwenden (klicken Sie rechts oben in der Konsole auf das Eingabeaufforderungssymbol), um die Umgebung zu starten.

Legen Sie zuerst das Standardprojekt und die Cloud Run-Region fest:

# set the project
gcloud config set project YOUR_PROJECT_ID

Ersetzen Sie YOUR_PROJECT_ID durch Ihre Google Cloud-Projekt-ID.

# set Cloud Run region
gcloud config set run/region CLOUD-RUN-REGION

Ersetzen Sie CLOUD-RUN-REGION durch eine der von Cloud Run unterstützten Regionen.

Hier sind Umgebungsvariablen, die in diesem Codelab verwendet werden. Sie können diese in einer Umgebungsdatei speichern und „sourcen“. Achten Sie darauf, den Wert Ihrer Projekt-ID und optional der Region richtig festzulegen.

# Cloud Project Id and Cloud Run region
export GOOGLE_CLOUD_PROJECT="${GOOGLE_CLOUD_PROJECT:-$(gcloud config get-value project -q)}"
export GOOGLE_CLOUD_REGION="${GOOGLE_CLOUD_REGION:-$(CR_REGION=$(gcloud config get-value run/region -q 2>/dev/null); echo "${CR_REGION:-us-central1}")}"
# Gemini API in Agent Platform
export GOOGLE_GENAI_USE_ENTERPRISE="True" # Use Agent Platform
export GOOGLE_CLOUD_LOCATION="global" # Use global Gemini API endpoint

Hinweis:Es ist sinnvoll, dieses Snippet als Scriptdatei zu speichern und in Zukunft wiederzuverwenden, wenn die Cloud Shell-Sitzung zurückgesetzt wird. Speichern Sie es als env.sh und führen Sie source env.sh aus, um die Umgebungsvariablen festzulegen, wenn Sie die nachfolgenden Schritte ausführen. Übertragen Sie env.sh nicht in Versionsverwaltungssysteme.

Aktivieren Sie die für dieses Codelab erforderlichen APIs. Es kann 2 bis 3 Minuten dauern, bis die API-Änderungen wirksam werden.

gcloud services enable --project "${GOOGLE_CLOUD_PROJECT}" \
    run.googleapis.com \
    cloudbuild.googleapis.com \
    artifactregistry.googleapis.com \
    bigquery.googleapis.com \
    aiplatform.googleapis.com

3. Daten-Agent mit dem Agent Development Kit erstellen

Code des Agenten schreiben

Erstellen Sie im Cloud Shell-Terminal oder in Ihrem lokalen Terminal ein Stammverzeichnis für Ihre Agentenanwendung:

mkdir data_agent

Öffnen Sie den Cloud Shell-Editor oder einen anderen Texteditor und erstellen Sie agent.py im Verzeichnis data_agent:

data_agent/
    agent.py

agent.py

import os

from google.adk.agents import LlmAgent
from google.adk.tools.mcp_tool.mcp_toolset import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams

import google.auth
from google.auth.transport.requests import Request

# Fetch Application Default Credentials (ADC)
# to use as agent's own identity for accessing BigQuery MCP Server
_application_default_credentials, project_id = google.auth.default()
_request = Request()
_application_default_credentials.refresh(_request)

# Retrieve Google Cloud project to use.
project_id = os.getenv("GOOGLE_CLOUD_PROJECT", project_id)
if not project_id:
    raise ValueError("GOOGLE_CLOUD_PROJECT environment variable is not set.")

# Builds authentication headers for MCP Server requests,
# and refreshes credentials if needed.
def _adc_auth_header_provider(context = None) -> dict[str, str]:
    if not _application_default_credentials.valid:
        _application_default_credentials.refresh(_request)

    return {
        "Authorization": f"Bearer {_application_default_credentials.token}",
        "x-goog-user-project": project_id
    }

# Initialize the MCP Toolset with the connection parameters
bigquery_toolset = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://bigquery.googleapis.com/mcp",
        tool_filter=[
            'get_dataset_info',
            'list_table_ids',
            'get_table_info',
            # Using readonly is a security measure to prevent accidental data modification.
            'execute_sql_readonly',
        ]
    ),
    header_provider=_adc_auth_header_provider # Auth header provider function
)

# Configure the agent

system_instruction = f"""
You are a helpful assistant that can answer questions about data in BigQuery.
To answer the user's question, use data you have access to by using tools `list_table_ids` and `get_table_info`.
Your data is in `bigquery-public-data.new_york_citibike` dataset (Citi Bike trips and stations in the NYC area.)

Plan of action:
0. ALWAYS start by analyzing dataset.
1. Analyze your data, investigate schema and dimensions by querying distrinct values of columns using `execute_sql_readonly`.
   Output information about tables, columns, their data types and sets of values (for dimensions).
   Note which columns can be joined or used in aggregations/filters, and what type conversion may be needed for joining or aggregating.
   DO NOT MAKE ASSUMPTIONS ABOUT DATA (structure, type, values, relationships) BASED ON YOUR PRIOR KNOWLEDGE. ALWAYS VERIFY YOUR ASSUMPTIONS.
2. Understand and interpret the user's question.
3. Formulate a plan to answer the user's question.
4. Write a SQL query to retrieve relevant data in necessary form.
   This is where you must pay extra attention to column types and dimensions' sets of values.
5. Retrieve data by generating BigQuery SQL and using `execute_sql_readonly`.
   Always use Dry Run to verify SQL correctness.
   Use `{project_id}` to run BigQuery queries (`project_id` parameter of `execute_sql_readonly`).

Do not use LaTeX in your responses. When giving a final answer, use Markdown.
"""

root_agent = LlmAgent(
    model="gemini-3.6-flash",
    name="data_agent",
    instruction=system_instruction,
    description="A helpful assistant that can answer questions using NYC Citibike data.",
    tools=[bigquery_toolset]
)

Für die Bereitstellung sind für das ADK auch __init__.py und requirements.txt erforderlich:

• __init__.py muss einen Import für den Agenten enthalten.
• requirements.txt enthält eine Liste der Python-Abhängigkeiten: google-adk für das Agent Development Kit und mcp für den Model Context Protocol-Client.

Mit diesen Befehlen können Sie __init__.py und requirements.txt erstellen:

echo "from . import agent" > data_agent/__init__.py
echo -e "google-adk==2.4.*\nmcp==1.29.*" > data_agent/requirements.txt

Die endgültige Ordnerstruktur sollte so aussehen:

data_agent/
    __init__.py
    agent.py
    requirements.txt

Agent lokal testen

Das Agent Development Kit enthält das CLI-Tool adk, eine interaktive Terminaloberfläche zum Testen Ihrer Agenten. Dies ist nützlich für schnelle Tests, gescriptete Interaktionen und CI/CD-Pipelines. Eine der Funktionen ist adk web – die ADK-Weboberfläche, mit der Sie Ihre Agenten interaktiv entwickeln und debuggen können. ADK Web ist nicht für den Einsatz in Produktionsbereitstellungen vorgesehen, macht es aber sehr einfach, den Agenten auszuprobieren.

Hinweis:Bevor Sie diesen Befehl ausführen, prüfen Sie mit dem Befehl ls, ob sich das Verzeichnis data_agent im aktuellen Verzeichnis befindet.

Mit diesem Befehl wird adk web gestartet, das einen lokalen Webserver auf Port 8080 startet.

uv tool run --with "mcp==1.29.*" --from "google-adk[mcp]==2.4.*" adk web --allow_origins="*" --port 8080 .

Öffnen Sie nach dem Start des Dienstes die lokale ADK-Webseite: http://localhost:8080/.

Wenn Sie Google Cloud Shell verwenden, klicken Sie auf die Schaltfläche „Webvorschau“ und wählen Sie den Menüpunkt „Vorschau auf Port 8080“ aus.

Fragen Sie den Agenten in der ADK-Weboberfläche nach den Daten, auf die er Zugriff hat:

What data do you have?

Der Agent verwendet BigQuery MCP-Tools, um das Citibike-Dataset zu untersuchen. Sie erhalten eine Übersicht über die verfügbaren Tabellen und Felder im Citibike-Dataset.

4. Agent in Cloud Run bereitstellen

Mit diesem Befehl wird der Agent mit der ADK-CLI in Cloud Run bereitgestellt.

uv tool run --from google-adk==2.4.0 \
  adk deploy cloud_run \
      --with_ui \
      --project $GOOGLE_CLOUD_PROJECT \
      --region $GOOGLE_CLOUD_REGION \
      --service_name bq-data-agent \
      --app_name data_agent \
      data_agent \
      -- \
      --allow-unauthenticated \
      --max-instances 1 \
      --set-env-vars GOOGLE_GENAI_USE_ENTERPRISE=True,GOOGLE_CLOUD_PROJECT="${GOOGLE_CLOUD_PROJECT},GOOGLE_CLOUD_LOCATION=${GOOGLE_CLOUD_LOCATION}"

Agent ausprobieren

Wir haben die Option --with_ui für die Bereitstellung unseres Agenten verwendet. Dadurch wurde der Agent mit der ADK-Weboberfläche bereitgestellt.

1. Öffnen Sie die Agenten-URL im Webbrowser. Der Befehl adk deploy hat sie zurückgegeben. Sie können die URL auch mit dem Befehl gcloud run services abrufen:

gcloud run services describe bq-data-agent \
  --project $GOOGLE_CLOUD_PROJECT \
  --region $GOOGLE_CLOUD_REGION \
  --format 'value(status.url)'

2. Bitten Sie den Agenten, die verfügbaren Citibike-Daten zu analysieren:

We have budget for 3 coffee trucks.
We want to find the best city bike stations to place our coffee trucks.

Der Agent sollte das Citibike-Dataset mit dem BigQuery MCP-Server untersuchen, einige SQL-Abfragen ausführen und eine Liste mit drei Citibike-Stationen zurückgeben.

5. Glückwunsch!

Sie haben das Codelab abgeschlossen.

Wir empfehlen Ihnen, die Cloud Run-Dokumentation zu lesen.

Behandelte Themen

• KI-Agent mit dem Agent Development Kit und Gemini erstellen
• Agent mit dem BigQuery MCP-Server verbinden
• Agent in Cloud Run bereitstellen

6. Bereinigen

Damit Ihrem Google Cloud-Konto die in dieser Anleitung verwendeten Ressourcen nicht in Rechnung gestellt werden, können Sie entweder das Projekt löschen oder die einzelnen Ressourcen entfernen.

Option 1: Dienst löschen

Cloud Run-Dienst löschen

gcloud run services delete bq-data-agent \
      --project "${GOOGLE_CLOUD_PROJECT}" \
      --region "${GOOGLE_CLOUD_REGION}" \
      --quiet

Option 2: Projekt löschen

Wenn Sie das gesamte Projekt löschen möchten, rufen Sie „Ressourcen verwalten“ auf, wählen Sie das in Schritt 2 erstellte Projekt aus und klicken Sie auf „Löschen“. Wenn Sie das Projekt löschen, müssen Sie die Projekte in Ihrem Cloud SDK ändern. Sie können die Liste aller verfügbaren Projekte mit dem Befehl gcloud projects list aufrufen. Wenn Sie die Befehlszeile verwenden möchten, können Sie auch diesen Befehl verwenden:

gcloud projects delete ${GOOGLE_CLOUD_PROJECT}