Tworzenie agenta analityka Trendów Google za pomocą MCP BigQuery

1. Przegląd

W tym ćwiczeniu utworzysz agenta analityka Trendy Google za pomocą Google ADK. Ten agent korzysta z serwera BigQuery MCP do dynamicznego wykrywania i wykonywania narzędzi, które wysyłają zapytania do publicznego zbioru danych Trendy Google (bigquery-public-data.google_trends).

Czego się nauczysz

• Jak skonfigurować projekt na potrzeby tworzenia pakietu ADK.
• Jak włączyć i używać zarządzanych serwerów MCP w BigQuery.
• Jak utworzyć agenta, który korzysta z narzędzi MCP.
• Jak uruchomić agenta lokalnie na potrzeby testowania.
• Jak wdrożyć agenta w Google Cloud Run.

Czego potrzebujesz

• Projekt Google Cloud z włączonymi płatnościami.
• Przeglądarka internetowa, np. Chrome.
• Python 3.11 lub nowszy.

To ćwiczenie jest przeznaczone dla średnio zaawansowanych programistów, którzy znają Pythona i Google Cloud.

Ukończenie tego ćwiczenia zajmie około 15–20 minut.

Zasoby utworzone w tym ćwiczeniu powinny kosztować mniej niż 5 USD.

2. Konfigurowanie środowiska

Utwórz projekt Google Cloud

1. W konsoli Google Cloud na stronie wyboru projektu wybierz lub utwórz projekt w chmurze Google Cloud.
2. Sprawdź, czy w projekcie w chmurze włączone są płatności. Dowiedz się, jak sprawdzić, czy w projekcie są włączone płatności.

W tym ćwiczeniu zalecamy używanie Google Cloud Shell. Zapewnia ono środowisko terminala z już zainstalowanym Pythonem i interfejsem wiersza poleceń Google Cloud.

Aby aktywować Cloud Shell, kliknij przycisk Aktywuj Cloud Shell u góry konsoli Google Cloud.

Ustawianie zmiennych środowiskowych

Ustaw te zmienne środowiskowe.

export GOOGLE_CLOUD_PROJECT=<INSERT_YOUR_GCP_PROJECT_HERE>
export GOOGLE_GENAI_USE_VERTEXAI=1

Uwaga: ustawienie GOOGLE_GENAI_USE_VERTEXAI=1 powoduje, że pakiet ADK używa Vertex AI, wykorzystując Cloud IAM do uwierzytelniania zamiast GEMINI_API_KEY.

Uwierzytelnianie i konfigurowanie gcloud

Zaloguj się na swoje konto Google, ustaw aktywny projekt i skonfiguruj domyślne uwierzytelnianie aplikacji.

Jeśli używasz Cloud Shell, możesz pominąć ten krok.

gcloud auth login
gcloud auth application-default login

Uwaga: gcloud auth login uwierzytelnia polecenia interfejsu wiersza poleceń gcloud, a gcloud auth application-default login uwierzytelnia lokalny kod aplikacji.

Ustaw projekt Google Cloud:

gcloud config set project ${GOOGLE_CLOUD_PROJECT}

Włączanie niezbędnych interfejsów API

Włącz wymagane interfejsy Google Cloud API dla Cloud Run, Artifact Registry, BigQuery i Vertex AI.

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

Włączanie MCP w BigQuery

Zarządzane serwery MCP muszą być wyraźnie włączone w projekcie.

gcloud beta services mcp enable bigquery.googleapis.com

Tworzenie folderu projektu

Zacznij od utworzenia folderu głównego agenta i folderu wewnętrznego na potrzeby implementacji agenta.

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

3. Tworzenie kodu agenta

Utwórz pusty plik o nazwie google_trends/__init__.py:

touch google_trends/__init__.py

Następnie utwórz plik o nazwie google_trends/agent.py i wklej ten kod:

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. Uruchamianie agenta

W tym kroku skonfigurujesz lokalne środowisko wirtualne Pythona, zainstalujesz zależności i uruchomisz agenta, aby sprawdzić jego działanie na swoim komputerze (lub w Google Cloud Shell).

• Przejdź do katalogu głównego aplikacji (google-trends-agent).
• Utwórz środowisko wirtualne:

python -m venv mcp_demo_env
source mcp_demo_env/bin/activate

• Zainstaluj wymagane pakiety Pythona:

pip install google-auth google-adk

Do testowania nowego agenta użyjemy ADK Web.

Aby przeprowadzić lokalne testowanie i programowanie, uruchom to polecenie:

adk web

Aby programować i testować w Google Cloud Shell, uruchom to polecenie:

adk web --allow_origins="*"

Spowoduje to uruchomienie serwera WWW ADK. Możesz wchodzić w interakcje z agentem za pomocą lokalnego interfejsu internetowego (zwykle pod adresem http://localhost:8000).

Uwaga: do testowania agenta możesz też użyć prostszego adk run google_trends polecenia.

Spróbuj zadać agentowi te pytania:

• Pokaż mi najpopularniejsze trendy w Stanach Zjednoczonych
• Jakie są najpopularniejsze trendy we Francji w tym miesiącu?
• Jakie były 3 najpopularniejsze trendy w Kalifornii w zeszłym tygodniu?
• Do jakich tabel BigQuery masz dostęp?
• Powiedz mi wszystko, co wiesz o tabeli top_trends

5. Wdrożenie w Cloud Run

Aby bezpiecznie wdrożyć agenta w Google Cloud Run, wykonaj te czynności.

Przyznaj uprawnienia

Cloud Run potrzebuje uprawnień dostępu do Vertex AI i korzystania z narzędzi BigQuery MCP.

# 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"

Tworzenie Dockerfile

W katalogu głównym projektu (google-trends-agent) utwórz plik o nazwie Dockerfile i wklej tę zawartość:

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"]

Wdrażanie agenta

Uruchom to polecenie z katalogu głównego. Spowoduje to skonteneryzowanie i wdrożenie agenta w Cloud Run.

Obserwuj dane wyjściowe polecenia. Po zakończeniu wdrażania pojawi się adres URL usługi. Użyjesz tego adresu URL do interakcji z agentem.

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

Szybka weryfikacja

Po zakończeniu wdrażania w konsoli pojawi się adres URL usługi. Otwórz ten adres URL w przeglądarce. Zobaczysz ten sam interaktywny interfejs, który był widoczny lokalnie, ale teraz działa w chmurze.

Możesz też monitorować logi, aby upewnić się, że wszystko działa prawidłowo:

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

6. Czyszczenie

Aby uniknąć dalszych opłat, usuń zasoby utworzone podczas tego ćwiczenia.

Usuń usługę Cloud Run:

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

Jeśli masz projekt utworzony specjalnie na potrzeby tego ćwiczenia, możesz usunąć cały projekt:

gcloud projects delete ${GOOGLE_CLOUD_PROJECT}

Możesz też usunąć wszystkie pliki związane z tym ćwiczeniem:

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

7. Gratulacje

Gratulacje! Udało Ci się utworzyć i wdrożyć agenta analityka Trendy Google.

Czego się nauczysz

• Jak używać MCP do dynamicznego rozszerzania możliwości agenta.
• Jak tworzyć i udostępniać agentów LLM za pomocą Google ADK.
• Jak wdrażać i skalować agentów w Cloud Run.

Dalsze kroki

• Spróbuj zmodyfikować agenta, aby wysyłał zapytania do różnych zbiorów danych BigQuery.
• Dodaj więcej narzędzi MCP, aby rozszerzyć możliwości agenta.

Dokumentacja źródłowa

• Dokumentacja pakietu ADK
• Przewodnik po narzędziach MCP
• BigQuery MCP
• Dokumentacja Cloud Run