Google Trends-Analysten-Agent mit BigQuery MCP erstellen

1. Übersicht

In diesem Codelab erstellen Sie mit dem Google ADK einen Google Trends-Analysten-Agenten. Dieser Agent nutzt den BigQuery MCP-Server , um Tools dynamisch zu ermitteln und auszuführen, die das öffentliche Google Trends-Dataset (bigquery-public-data.google_trends) abfragen.

Lerninhalte

• Ein Projekt für die ADK-Entwicklung einrichten
• Verwaltete MCP-Server für BigQuery aktivieren und verwenden
• Einen Agenten erstellen, der MCP-Tools verwendet
• Den Agenten lokal testen
• Den Agenten in Google Cloud Run bereitstellen

Voraussetzungen

• Ein Google Cloud-Projekt mit aktivierter Abrechnung
• Ein Webbrowser wie Chrome
• Python 3.11 oder höher

Dieses Codelab richtet sich an fortgeschrittene Entwickler, die mit Python und Google Cloud vertraut sind.

Die Bearbeitung dieses Codelabs dauert etwa 15 bis 20 Minuten.

Die in diesem Codelab erstellten Ressourcen sollten weniger als 5 $kosten.

2. Umgebung einrichten

Google Cloud-Projekt erstellen

1. Wählen Sie in der Google Cloud Console auf der Seite der Projektauswahl ein Google Cloud-Projekt aus oder erstellen Sie eines.
2. Die Abrechnung für das Cloud-Projekt muss aktiviert sein. Informationen zum Prüfen, ob die Abrechnung für ein Projekt aktiviert ist.

Wir empfehlen, für dieses Codelab Google Cloud Shell zu verwenden. Dort ist eine Terminalumgebung mit bereits installiertem Python und der Google Cloud CLI verfügbar.

Klicken Sie oben in der Google Cloud Console auf die Schaltfläche Cloud Shell aktivieren, um Cloud Shell zu aktivieren.

Umgebungsvariablen festlegen

Legen Sie die folgenden Umgebungsvariablen fest:

export GOOGLE_CLOUD_PROJECT=<INSERT_YOUR_GCP_PROJECT_HERE>
export GOOGLE_GENAI_USE_VERTEXAI=1

Hinweis: Wenn Sie GOOGLE_GENAI_USE_VERTEXAI=1 festlegen, wird das ADK angewiesen, Vertex AI zu verwenden. Für die Authentifizierung wird dann Cloud IAM anstelle eines GEMINI_API_KEY verwendet.

Authentifizieren und Konfigurieren von gcloud

Melden Sie sich in Ihrem Google-Konto an, legen Sie Ihr aktives Projekt fest und konfigurieren Sie die Standardanmeldedaten für Anwendungen.

Wenn Sie Cloud Shell verwenden, können Sie diesen Schritt überspringen.

gcloud auth login
gcloud auth application-default login

Hinweis: gcloud auth login authentifiziert die gcloud CLI-Befehle, während gcloud auth application-default login den lokalen Anwendungscode authentifiziert.

Legen Sie das Google Cloud-Projekt fest:

gcloud config set project ${GOOGLE_CLOUD_PROJECT}

Erforderliche APIs aktivieren

Aktivieren Sie die erforderlichen Google Cloud APIs für Cloud Run, Artifact Registry, BigQuery und Vertex AI.

gcloud services enable run.googleapis.com \
                       cloudbuild.googleapis.com \
                       artifactregistry.googleapis.com \
                       bigquery.googleapis.com \
                       aiplatform.googleapis.com

MCP für BigQuery aktivieren

Verwaltete MCP-Server müssen explizit für Ihr Projekt aktiviert werden.

gcloud beta services mcp enable bigquery.googleapis.com

Projektordner erstellen

Erstellen Sie zuerst einen Stammordner für Ihren Agenten und einen internen Ordner für die Agentenimplementierung.

mkdir google-trends-agent
cd google-trends-agent
mkdir google_trends

3. Agentencode erstellen

Erstellen Sie eine leere Datei mit dem Namen google_trends/__init__.py:

touch google_trends/__init__.py

Erstellen Sie dann eine Datei mit dem Namen google_trends/agent.py und fügen Sie den folgenden Code ein:

import os
import textwrap
import warnings
from datetime import date

import google.auth
from google.adk.agents import LlmAgent
from google.adk.apps import App
from google.adk.tools.mcp_tool import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams
from google.auth.transport.requests import Request

# Suppress experimental ADK credential warnings
warnings.filterwarnings("ignore")

def get_agent_instruction(project_id: str) -> str:
    """Generates a clear and formatted prompt for the data analyst."""
    instruction = f"""
    # ROLE
    You are a Google Search Trends Analyst. Your mission is to provide clear answers using SQL data.

    # DATA CONSTRAINTS
    - BigQuery tool `execute_sql` requires explicit billing project mapping. Use: '{project_id}'.
    - Target dataset strictly: `bigquery-public-data.google_trends`

    # SCHEMA DISCOVERY (CRITICAL)
    1. DO NOT call `get_table_info` or `list_table_ids` (Triggers Permission Errors).
    2. Run `SELECT * FROM table LIMIT 0` via `execute_sql` for field definition mapping.

    # OUTPUT PRESENTATION
    - Render purely as a cleanly aligned Markdown table.
    - Use clear and descriptive headers for each column.
    - Remove conversational preambles. Output only the results.
    """
    return textwrap.dedent(instruction).strip()

def get_auth_headers() -> dict[str, str]:
    """Fetch auth headers for the project using Google Cloud Platform scopes."""
    credentials, _ = google.auth.default(
        scopes=["https://www.googleapis.com/auth/cloud-platform"]
    )
    request = Request()
    credentials.refresh(request)

    return {"Authorization": f"Bearer {credentials.token}"}

def get_todays_date() -> str:
    """Returns today's date in YYYY-MM-DD format."""
    return date.today().isoformat()

# --- Application Initialization ---
project_id = os.environ.get("GOOGLE_CLOUD_PROJECT")
if not project_id:
    raise ValueError("GOOGLE_CLOUD_PROJECT environment variable is not set")

mcp_headers = {
    "Content-Type": "application/json",
    "Accept": "application/json, text/event-stream",
} | get_auth_headers()

# Configure BigQuery Tools via MCP
bq_tools = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://bigquery.googleapis.com/mcp",
        headers=mcp_headers,
    )
)

# Initialize the LLM Agent
root_agent = LlmAgent(
    name="google_trends",
    model="gemini-3-flash-preview",
    tools=[get_todays_date, bq_tools],
    instruction=get_agent_instruction(project_id),
)

# Create the ADK App
app = App(name=root_agent.name, root_agent=root_agent)

4. Agent ausführen

In diesem Schritt richten Sie eine lokale virtuelle Python-Umgebung ein, installieren Abhängigkeiten und führen den Agenten aus, um sein Verhalten auf Ihrem Computer (oder in Google Cloud Shell) zu überprüfen.

• Rufen Sie das Stammverzeichnis der Anwendung (google-trends-agent) auf.
• Erstellen Sie eine virtuelle Umgebung:

python -m venv mcp_demo_env
source mcp_demo_env/bin/activate

• Installieren Sie die erforderlichen Python-Pakete:

pip install google-auth google-adk

Wir verwenden ADK Web, um unseren neuen Agenten zu testen.

Führen Sie für die lokale Entwicklung und Tests den folgenden Befehl aus:

adk web

Führen Sie für die Entwicklung und Tests in Google Cloud Shell den folgenden Befehl aus:

adk web --allow_origins="*"

Dadurch wird der ADK-Webserver gestartet. Sie können über die lokale Weboberfläche mit dem Agenten interagieren (in der Regel unter http://localhost:8000).

Hinweis: Sie können den Agenten auch mit dem einfacheren adk run google_trends Befehl testen.

Stellen Sie Ihrem Agenten die folgenden Fragen:

• Zeig mir die Top-Trends in den USA
• Was sind die Top-Trends in Frankreich in diesem Monat?
• Was waren letzte Woche die drei wichtigsten Trends in Kalifornien?
• Auf welche BigQuery-Tabellen haben Sie Zugriff?
• Erzählen Sie mir alles, was Sie über die Tabelle „top_trends“ wissen

5. In Cloud Run bereitstellen

Führen Sie die folgenden Schritte aus, um den Agenten sicher in Google Cloud Run bereitzustellen.

Berechtigungen gewähren

Cloud Run benötigt die Berechtigung, auf Vertex AI zuzugreifen und BigQuery MCP-Tools zu verwenden.

# Get your project number automatically
PROJECT_NUMBER=$(gcloud projects describe $GOOGLE_CLOUD_PROJECT --format='value(projectNumber)')

# Vertex AI Access: To talk to the Gemini model
gcloud projects add-iam-policy-binding ${GOOGLE_CLOUD_PROJECT} \
  --member="serviceAccount:${PROJECT_NUMBER}[e-mail]" \
  --role="roles/aiplatform.user"

# MCP & BigQuery: To execute tools and run SQL jobs
gcloud projects add-iam-policy-binding ${GOOGLE_CLOUD_PROJECT} \
  --member="serviceAccount:${PROJECT_NUMBER}[e-mail]" \
  --role="roles/mcp.toolUser"

gcloud projects add-iam-policy-binding ${GOOGLE_CLOUD_PROJECT} \
  --member="serviceAccount:${PROJECT_NUMBER}[e-mail]" \
  --role="roles/bigquery.jobUser"

gcloud projects add-iam-policy-binding ${GOOGLE_CLOUD_PROJECT} \
  --member="serviceAccount:${PROJECT_NUMBER}[e-mail]" \
  --role="roles/bigquery.dataViewer"

Dockerfile erstellen

Erstellen Sie im Stammverzeichnis Ihres Projekts (google-trends-agent) eine Datei mit dem Namen Dockerfile und fügen Sie den folgenden Inhalt ein:

FROM python:3.11-slim
WORKDIR /app

# Create a non-root user
RUN adduser --disabled-password --gecos "" myuser
USER myuser
ENV PATH="/home/myuser/.local/bin:$PATH"

# Copy the agent folder into the container
COPY --chown=myuser:myuser google_trends/ /app/agents/google_trends/

# Install the python packages
RUN pip install google-auth google-adk

# Set environment variables
ENV GOOGLE_GENAI_USE_VERTEXAI=1

# Expose port
EXPOSE 8080

# Run ADK web server
CMD ["adk", "web", "--port=8080", "--host=0.0.0.0", "/app/agents"]

Agent bereitstellen

Führen Sie den folgenden Befehl im Stammverzeichnis aus. Dadurch wird Ihr Agent containerisiert und in Cloud Run bereitgestellt.

Behalten Sie die Befehlsausgabe im Blick. Sobald die Bereitstellung abgeschlossen ist, wird eine Dienst-URL angezeigt. Mit dieser URL interagieren Sie mit Ihrem Agenten.

gcloud run deploy google-trends-agent \
  --source . \
  --region us-west1 \
  --allow-unauthenticated \
  --set-env-vars="GOOGLE_CLOUD_PROJECT=${GOOGLE_CLOUD_PROJECT}"

Schnelltest

Sobald die Bereitstellung abgeschlossen ist, wird in der Konsole eine Dienst-URL ausgegeben. Öffnen Sie diese URL in Ihrem Browser. Dort sehen Sie dieselbe interaktive Benutzeroberfläche wie lokal, aber jetzt in der Cloud.

Sie können auch die Logs beobachten, um sicherzustellen, dass alles reibungslos funktioniert:

gcloud logging read "resource.type=cloud_run_revision AND resource.labels.service_name=google-trends-agent" --limit 10

6. Bereinigen

Löschen Sie die in diesem Codelab erstellten Ressourcen, um laufende Kosten zu vermeiden.

Löschen Sie den Cloud Run-Dienst:

gcloud run services delete google-trends-agent --region us-west1

Wenn Sie ein Projekt speziell für dieses Codelab erstellt haben, können Sie das gesamte Projekt löschen:

gcloud projects delete ${GOOGLE_CLOUD_PROJECT}

Sie können auch alle Dateien löschen, die mit diesem Codelab zusammenhängen:

deactivate
cd ..
rm -rf google-trends-agent

7. Glückwunsch

Glückwunsch! Sie haben einen Google Trends-Analysten-Agenten erstellt und bereitgestellt.

Lerninhalte

• MCP verwenden, um die Funktionen von Agenten dynamisch zu erweitern
• LLM-Agenten mit dem Google ADK erstellen und bereitstellen
• Agenten in Cloud Run bereitstellen und skalieren

Nächste Schritte

• Ändern Sie den Agenten so, dass er verschiedene BigQuery-Datasets abfragt.
• Fügen Sie weitere MCP-Tools hinzu, um die Funktionen des Agenten zu erweitern.

Referenzdokumente

• ADK-Dokumentation
• Anleitung zu MCP-Tools
• BigQuery MCP
• Cloud Run-Dokumentation