Crea ed esegui il deployment di agenti AI con Gemini e il server MCP BigQuery in Cloud Run

1. Introduzione

Obiettivi didattici

• Come creare un agente AI utilizzando Agent Development Kit (ADK) con Gemini in Agent Platform.
• Come concedere agli agenti AI l'accesso ai dati strutturati in BigQuery utilizzando il server BigQuery MCP.

Cloud Run è una piattaforma di computing serverless completamente gestita che ti consente di eseguire applicazioni e servizi containerizzati senza gestire alcuna infrastruttura sottostante.

Agent Development Kit (ADK) è un framework di sviluppo di agenti open source che ti consente di creare, eseguire il debug e il deployment di agenti AI affidabili su scala aziendale.

BigQuery è un data warehouse aziendale serverless completamente gestito che ti consente di archiviare, eseguire query e analizzare set di dati di grandi dimensioni.

Model Context Protocol (MCP) standardizza il modo in cui i modelli linguistici di grandi dimensioni (LLM) e le applicazioni o gli agenti AI si connettono a origini dati esterne. I server MCP ti consentono di utilizzare i loro strumenti, risorse e prompt per eseguire azioni e ottenere dati aggiornati dal loro servizio di backend. BigQuery MCP Server offre ai tuoi agenti AI un modo diretto e sicuro per analizzare i dati in BigQuery. Questo server MCP completamente gestito elimina l'overhead di gestione, consentendoti di concentrarti sullo sviluppo di agenti intelligenti.

2. Configurazione e requisiti

L'intero lab può essere eseguito dalla riga di comando. Puoi utilizzare Cloud Shell (fai clic sull'icona del prompt in alto a destra nella console) per avviare l'ambiente.

Inizia impostando il progetto predefinito e la regione Cloud Run:

# set the project
gcloud config set project YOUR_PROJECT_ID

Sostituisci YOUR_PROJECT_ID con l'ID progetto Google Cloud.

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

Sostituisci CLOUD-RUN-REGION con una delle regioni supportate da Cloud Run.

Di seguito sono riportate le variabili di ambiente che verranno utilizzate in questo codelab. Puoi salvarle in un file di ambiente e "originarlo". Assicurati di impostare correttamente il valore dell'ID progetto e, facoltativamente, della regione.

# 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

Nota: è utile salvare questo snippet come file di script e riutilizzarlo in futuro, nei casi in cui la sessione di Cloud Shell viene reimpostata. Salvalo come env.sh ed esegui source env.sh per impostare le variabili di ambiente quando esegui i passaggi successivi. Non eseguire il commit env.sh nei sistemi di controllo della versione.

Abilita le API necessarie per questo codelab. L'applicazione delle modifiche alle API potrebbe richiedere 2-3 minuti.

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

3. Crea un agente dati utilizzando Agent Development Kit

Scrivi il codice dell'agente

Dal terminale di Cloud Shell o dal terminale locale, crea una directory principale per l'app agentica:

mkdir data_agent

Apri l'editor di Cloud Shell o un altro editor di testo e crea agent.py nella directory 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]
)

ADK richiede anche __init__.py e requirements.txt per il deployment:

• __init__.py deve avere un'importazione per l'agente.
• requirements.txt elenca le dipendenze Python: google-adk per Agent Development Kit e mcp per il client Model Context Protocol.

Questi comandi ti aiutano a creare __init__.py e requirements.txt:

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

La struttura di cartelle finale dovrebbe essere simile alla seguente:

data_agent/
    __init__.py
    agent.py
    requirements.txt

Prova l'agente localmente

Agent Development Kit include lo strumento CLI adk, un'interfaccia terminale interattiva per testare gli agenti. È utile per test rapidi, interazioni con script e pipeline CI/CD. Una delle funzionalità che fornisce è adk web - l'interfaccia web ADK - un modo semplice per sviluppare ed eseguire il debug degli agenti in modo interattivo. ADK Web non è progettato per l'utilizzo nei deployment di produzione, ma semplifica notevolmente la prova dell'agente.

Nota: prima di eseguire questo comando, assicurati che la directory corrente contenga la directory data_agent (con il comando ls).

Questo comando avvia adk web, che avvia un server web locale sulla porta 8080.

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

Una volta avviato il servizio, apri la pagina web ADK locale: http://localhost:8080/.

Se utilizzi Google Cloud Shell, fai clic sul pulsante Anteprima web e seleziona la voce di menu "Anteprima sulla porta 8080".

Nell'interfaccia utente web ADK, chiedi all'agente i dati a cui ha accesso:

What data do you have?

L'agente utilizzerà gli strumenti BigQuery MCP per esplorare il set di dati citibike. Ti fornirà una panoramica delle tabelle e dei campi disponibili nel set di dati Citibike.

4. Esegui il deployment dell'agente in Cloud Run

Questo comando eseguirà il deployment dell'agente in Cloud Run utilizzando ADK CLI.

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

Prova l'agente

Abbiamo utilizzato l'opzione --with_ui per il deployment dell'agente. Ha eseguito il deployment dell'agente con l'interfaccia web ADK.

1. Apri l'URL dell'agente nel browser web. Il comando adk deploy lo ha restituito e puoi recuperare l'URL anche eseguendo il comando gcloud run services:

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

2. Chiedi all'agente di ragionare sui dati Citibike disponibili:

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

L'agente dovrebbe esplorare il set di dati Citibike utilizzando il server BigQuery MCP, eseguire alcune query SQL e restituire un elenco di 3 stazioni citibike.

5. Complimenti!

Complimenti per aver completato il codelab.

Ti consigliamo di consultare la documentazione di Cloud Run.

Argomenti trattati

• Come creare un agente AI con Agent Development Kit e Gemini
• Come connettere l'agente al server BigQuery MCP.
• Come eseguire il deployment dell'agente in Cloud Run.

6. Libera spazio

Per evitare che al tuo account Google Cloud vengano addebitati costi relativi alle risorse utilizzate in questo tutorial, puoi eliminare il progetto o le singole risorse.

Opzione 1: elimina il servizio

Elimina il servizio Cloud Run

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

Opzione 2: elimina il progetto

Per eliminare l'intero progetto, vai a Gestisci risorse, seleziona il progetto che hai creato nel passaggio 2 e scegli Elimina. Se elimini il progetto, dovrai cambiare progetto in Cloud SDK. Puoi visualizzare l'elenco di tutti i progetti disponibili eseguendo gcloud projects list. Se preferisci utilizzare la riga di comando, puoi utilizzare anche questo comando:

gcloud projects delete ${GOOGLE_CLOUD_PROJECT}