Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Crea un agente analista di Google Trends con BigQuery MCP

1. Panoramica

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

Obiettivi didattici

Come configurare un progetto per lo sviluppo dell'ADK.
Come abilitare e utilizzare i server MCP gestiti per BigQuery.
Come creare un agente che utilizza gli strumenti MCP.
Come eseguire l'agente localmente 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+

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

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

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 GOOGLE_GENAI_USE_VERTEXAI=1 indica all'ADK di utilizzare Vertex AI, sfruttando Cloud IAM per l'autenticazione anziché un GEMINI_API_KEY.

Autenticarsi e configurare gcloud

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

gcloud auth login
gcloud auth application-default login

Nota: gcloud auth login autentica i comandi dell'interfaccia a riga di comando gcloud, 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 Google 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

Creare 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 agente

Crea un file vuoto denominato google_trends/__init__.py:

touch google_trends/__init__.py

Poi, 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 in Google Cloud Shell).

Vai alla directory root 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[mcp]

Utilizzeremo ADK Web per testare il nostro nuovo agente.

Per lo sviluppo e i test locali, esegui questo comando:

adk web

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

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: per testare l'agente puoi anche utilizzare il comando adk run google_trends più semplice.

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 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}-compute@developer.gserviceaccount.com" \
  --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}-compute@developer.gserviceaccount.com" \
  --role="roles/mcp.toolUser"

gcloud projects add-iam-policy-binding ${GOOGLE_CLOUD_PROJECT} \
  --member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \
  --role="roles/bigquery.jobUser"

gcloud projects add-iam-policy-binding ${GOOGLE_CLOUD_PROJECT} \
  --member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \
  --role="roles/bigquery.dataViewer"

Crea il Dockerfile

Nella radice 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 questo comando dalla directory principale. In questo modo, l'agente verrà containerizzato ed eseguito il deployment su Cloud Run.

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 eliminarlo completamente:

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 analista di Google Trends.