Crea un agente analista di Google Trends con BigQuery MCP

1. Panoramica

In questo codelab, creerai un agente di analisi di Google Trends utilizzando Google ADK. Questo agente sfrutta il server MCP BigQuery per scoprire ed eseguire dinamicamente gli strumenti che eseguono query sul set di dati pubblici di Google Trends (bigquery-public-data.google_trends).

Obiettivi didattici

• Come configurare un progetto per lo sviluppo di ADK.
• Come abilitare e utilizzare i server MCP gestiti per BigQuery.
• Come creare un agente che utilizza gli strumenti MCP.
• Come eseguire l'agente in locale per i test.
• Come eseguire il deployment dell'agente in Google Cloud Run.

Che cosa ti serve

• Un progetto cloud Google Cloud con la fatturazione abilitata
• Un browser web come Chrome
• Python 3.11 o versioni successive

Questo codelab è destinato a sviluppatori di livello intermedio che hanno una certa familiarità con Python e Google Cloud.

Il completamento di questo codelab richiede circa 15-20 minuti.

Le risorse create in questo codelab dovrebbero costare meno di 5 $.

2. Configura l'ambiente

Crea un progetto Google Cloud

1. Nella console Google Cloud, nella pagina di selezione del progetto, seleziona o crea un progetto Google Cloud.
2. Verifica che la fatturazione sia attivata per il tuo progetto Cloud. Scopri come verificare se la fatturazione è abilitata in un progetto.

Ti consigliamo di utilizzare Google Cloud Shell per questo codelab. Fornisce un ambiente terminale con Python e Google Cloud CLI già installati.

Per attivare Cloud Shell, fai clic sul pulsante Attiva Cloud Shell nella parte superiore della console Google Cloud.

Imposta le variabili di ambiente

Imposta le seguenti variabili di ambiente.

export GOOGLE_CLOUD_PROJECT=<INSERT_YOUR_GCP_PROJECT_HERE>
export GOOGLE_GENAI_USE_VERTEXAI=1

Nota: l'impostazione di GOOGLE_GENAI_USE_VERTEXAI=1 indica ad ADK di utilizzare Vertex AI, sfruttando Cloud IAM per l'autenticazione anziché una GEMINI_API_KEY.

Autentica e configura gcloud

Accedi al tuo Account Google, imposta il progetto attivo e configura le credenziali predefinite dell'applicazione.

Puoi saltare questo passaggio se utilizzi Cloud Shell.

gcloud auth login
gcloud auth application-default login

Nota: gcloud auth login autentica i comandi gcloud CLI, mentre gcloud auth application-default login autentica il codice dell'applicazione locale.

Imposta il progetto Google Cloud:

gcloud config set project ${GOOGLE_CLOUD_PROJECT}

Abilita le API necessarie

Abilita le API Cloud richieste per Cloud Run, Artifact Registry, BigQuery e Vertex AI.

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

Abilita MCP per BigQuery

I server MCP gestiti devono essere abilitati esplicitamente per il tuo progetto.

gcloud beta services mcp enable bigquery.googleapis.com

Crea una cartella di progetto

Inizia creando una cartella principale per l'agente e una cartella interna per l'implementazione dell'agente.

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

3. Crea il codice dell'agente

Crea un file vuoto denominato google_trends/__init__.py:

touch google_trends/__init__.py

Quindi, crea un file denominato google_trends/agent.py e incolla il seguente codice:

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. Esegui l'agente

In questo passaggio, configurerai un ambiente virtuale Python locale, installerai le dipendenze ed eseguirai l'agente per verificarne il comportamento sulla tua macchina (o Google Cloud Shell).

• Vai alla directory principale dell'applicazione (google-trends-agent).
• Crea un ambiente virtuale:

python -m venv mcp_demo_env
source mcp_demo_env/bin/activate

• Installa i pacchetti Python richiesti:

pip install google-auth google-adk

Utilizzeremo ADK Web per testare il nostro nuovo agente.

Per lo sviluppo e i test locali, esegui il comando seguente:

adk web

Per lo sviluppo e i test in Google Cloud Shell, esegui il comando seguente:

adk web --allow_origins="*"

Verrà avviato il server web ADK. Puoi interagire con l'agente utilizzando l'interfaccia web locale (di solito all'indirizzo http://localhost:8000).

Nota: puoi anche utilizzare il comando più semplice adk run google_trends per testare l'agente.

Prova a chiedere all'agente questi prompt:

• Mostrami le principali tendenze negli Stati Uniti
• Quali sono le principali tendenze in aumento in Francia questo mese?
• Quali sono state le 3 principali tendenze in California la settimana scorsa?
• A quali tabelle BigQuery hai accesso?
• Dimmi tutto quello che sai sulla tabella top_trends

5. Esegui il deployment in Cloud Run

Segui questi passaggi per eseguire il deployment dell'agente in modo sicuro in Google Cloud Run.

Concedi autorizzazioni

Cloud Run ha bisogno dell'autorizzazione per accedere a Vertex AI e utilizzare gli strumenti MCP BigQuery.

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

Crea il Dockerfile

Nella directory principale del progetto (google-trends-agent), crea un file denominato Dockerfile e incolla i seguenti contenuti:

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

Esegui il deployment dell'agente

Esegui il comando seguente dalla directory principale. In questo modo, l'agente verrà containerizzato e verrà eseguito il deployment in Cloud Run.

Tieni d'occhio l'output del comando. Al termine del deployment, verrà fornito un URL del servizio. Utilizzerai questo URL per interagire con l'agente.

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

Verifica rapida

Al termine del deployment, la console restituirà un URL del servizio. Apri questo URL nel browser; verrà visualizzata la stessa UI interattiva che hai visto in locale, ma ora in esecuzione nel cloud.

Puoi anche monitorare i log per assicurarti che tutto funzioni correttamente:

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

6. Elimina

Per evitare addebiti continui, elimina le risorse create durante questo codelab.

Elimina il servizio Cloud Run:

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

Se hai creato un progetto specifico per questo codelab, puoi eliminare l'intero progetto:

gcloud projects delete ${GOOGLE_CLOUD_PROJECT}

Puoi anche eliminare tutti i file correlati a questo codelab:

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

7. Complimenti

Complimenti! Hai creato ed eseguito correttamente il deployment di un agente di analisi di Google Trends.

Obiettivi didattici

• Come utilizzare MCP per estendere dinamicamente le funzionalità dell'agente
• Come creare e pubblicare agenti LLM con Google ADK
• Come eseguire il deployment e scalare gli agenti su Cloud Run

Passaggi successivi

• Prova a modificare l'agente per eseguire query su diversi set di dati BigQuery
• Aggiungi altri strumenti MCP per espandere le funzionalità dell'agente

Documenti di riferimento

• Documentazione di ADK
• Guida agli strumenti MCP
• MCP BigQuery
• Documentazione di Cloud Run