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

1. Introduzione

Nota: questa funzionalità è soggetta ai "Termini delle Offerte pre-GA" nella sezione Termini di servizio generali dei Termini specifici dei servizi. Le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per ulteriori informazioni, consulta le descrizioni della fase di lancio

Panoramica

Obiettivi didattici

• Come eseguire il deployment di un modello Gemma 4 su una GPU Cloud Run RTX 6000 Pro con vLLM
• Come creare un agente AI utilizzando Agent Development Kit (ADK) e come utilizzare Gemma 4 con questo strumento.
• Come concedere agli agenti AI l'accesso ai dati strutturati in BigQuery utilizzando il server BigQuery MCP.

Gemma 4 è una famiglia di modelli open weight con licenza Apache 2 di Google DeepMind. I modelli sono multimodali, multilingue, offrono ragionamento e un'architettura efficiente.

Cloud Run è un ambiente serverless per i container con supporto per le GPU.

Agent Development Kit (ADK) è un framework di sviluppo di agenti open source che 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 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 consentono di utilizzare i relativi strumenti, risorse e prompt per eseguire azioni e ottenere dati aggiornati dal servizio di backend. BigQuery MCP Server offre agli 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.

Nota: questo codelab utilizza il modello Gemma 4 31B Instruction-Tuned. Il codelab mostra come utilizzare Run:ai Model Streamer e il traffico in uscita VPC diretto per ridurre al minimo il tempo necessario per caricare il modello da Cloud Storage durante l'avvio del container. Per ulteriori informazioni, consulta la guida alle best practice per le GPU.

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
REGION="CLOUD-RUN-REGION"; gcloud config set run/region $REGION && echo $REGION > lab2rgn.txt

Sostituisci CLOUD-RUN-REGION con una delle seguenti regioni Cloud:

• us-central1
• asia-southeast1

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.

# Model name on HuggingFace Hub
export MODEL_NAME="google/gemma-4-31B-it"

# Cloud Run Service name
export SERVICE_NAME="gemma4-rtx-vllm-codelab"

# Cloud Project and Region for Cloud Run
export GOOGLE_CLOUD_PROJECT=$(gcloud config get project -q)
export GOOGLE_CLOUD_REGION=$(cat lab2rgn.txt 2> /dev/null || gcloud config get run/region -q)

# Service account for Cloud Run service
export SERVICE_ACCOUNT="vllm-service-sa"
export SERVICE_ACCOUNT_EMAIL="${SERVICE_ACCOUNT}@${GOOGLE_CLOUD_PROJECT}.iam.gserviceaccount.com"

# GCS Bucket for the model cache.
export MODEL_CACHE_BUCKET="${GOOGLE_CLOUD_PROJECT}-${GOOGLE_CLOUD_REGION}-hf-model-cache"
# Model cache location in GSC bucket
export GCS_MODEL_LOCATION="gs://${MODEL_CACHE_BUCKET}/model-cache/${MODEL_NAME}"
# Uncomment next line if loading gemma-4-31B-it directly from the public cache bucket
# export GCS_MODEL_LOCATION="gs://vertex-model-garden-public-us/gemma4/gemma-4-31B-it"

# VPC Network for Direct VPC Egress
export VPC_NETWORK="vllm-${GOOGLE_CLOUD_REGION}-net"
export VPC_SUBNET="vllm-${GOOGLE_CLOUD_REGION}-subnet"
export SUBNET_RANGE="10.8.0.0/26"

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 di 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 \
    iam.googleapis.com \
    compute.googleapis.com \
    vpcaccess.googleapis.com \
    storage.googleapis.com \
    bigquery.googleapis.com \
    aiplatform.googleapis.com

3. Crea service account

Se non specifichi un service account quando viene creato il servizio o il job Cloud Run, Cloud Run utilizza il service account predefinito di Compute Engine. È consigliabile utilizzare un service account separato per il servizio Cloud Run per evitare di eseguire il servizio con autorizzazioni eccessive.

Crea service account per il servizio Cloud Run

gcloud iam service-accounts create ${SERVICE_ACCOUNT} \
  --project "${GOOGLE_CLOUD_PROJECT}" \
  --display-name "vLLM Service Account"

4. Configura Cloud Storage

Crea un bucket Cloud Storage per archiviare i pesi del modello. In questo modo, puoi utilizzare il traffico in uscita VPC diretto per scaricare più rapidamente i pesi del modello ogni volta che Cloud Run avvia un'istanza del servizio.

In combinazione con la funzionalità Run:ai Model Streamer in vLLM, riduce notevolmente il tempo di caricamento del modello.

Crea un bucket

Assicurati che sia un bucket a regione singola collocato nella stessa regione del servizio Cloud Run.

gcloud storage buckets create "gs://${MODEL_CACHE_BUCKET}" \
    --uniform-bucket-level-access --public-access-prevention \
    --project "${GOOGLE_CLOUD_PROJECT}" --location "${GOOGLE_CLOUD_REGION}"

5. Recupera e memorizza nella cache i pesi del modello

Poi scarica il modello Gemma 4 nel bucket Cloud Storage. I pesi dei modelli sono decine di gigabyte e il download sulla macchina locale o su Cloud Shell potrebbe non essere fattibile. Utilizza invece Cloud Build con spazio di archiviazione sufficiente per contenere i pesi del modello.

Copia i pesi del modello da un bucket Cloud Storage condiviso

Google Cloud ospita un bucket Cloud Storage accessibile pubblicamente con i pesi del modello Gemma 4.

Se utilizzi una delle regioni us-, anziché copiare i pesi del modello, puoi semplicemente modificare GCS_MODEL_LOCATION in modo che punti alla posizione della cache pubblica. Ad esempio, per il modello gemma-4-31B-it, imposta export GCS_MODEL_LOCATION="gs://vertex-model-garden-public-us/gemma4/gemma-4-31B-it" (se utilizzi un file di ambiente, ad esempio .env o env.sh, non dimenticare di modificarlo).

Per copiarli nel bucket di archiviazione, esegui il comando:

gcloud builds submit --project="${GOOGLE_CLOUD_PROJECT}" --region="${GOOGLE_CLOUD_REGION}" --no-source \
    --substitutions="_MODEL_NAME=${MODEL_NAME},_GCS_MODEL_LOCATION=${GCS_MODEL_LOCATION}" \
    --config=/dev/stdin <<'EOF'
steps:
- name: 'gcr.io/google.com/cloudsdktool/google-cloud-cli:slim'
  entrypoint: 'bash'
  args:
  - '-c'
  - |
    if [[ "$_GCS_MODEL_LOCATION" == *"vertex-model-garden-public-us"* ]]; then
      echo "Using the public cache bucket."
      exit 0
    fi
    gcloud config set storage/parallel_composite_upload_enabled True
    gcloud config set storage/parallel_composite_upload_threshold 150M
    gcloud config set storage/sliced_object_download_threshold 150M
    MODEL_NAME="$_MODEL_NAME"
    SHORT_NAME="$${MODEL_NAME#*/}"
    gcloud storage cp -r -D "gs://vertex-model-garden-public-us/gemma4/$${SHORT_NAME}" "$_GCS_MODEL_LOCATION"
EOF

Nota: questa operazione richiede un tempo significativo, da 10 a 30 minuti.

6. Configura la rete per il traffico in uscita VPC diretto

La configurazione del traffico in uscita VPC diretto richiede la creazione di una rete e di una subnet con l'accesso privato Google abilitato.

In questo modo, i servizi Cloud Run possono connettersi all'insieme di indirizzi IP esterni utilizzati dalle API di Google e dai servizi, incluso Cloud Storage.

Crea una rete

gcloud compute networks create "$VPC_NETWORK" \
        --subnet-mode=custom \
        --bgp-routing-mode=regional \
        --project "$GOOGLE_CLOUD_PROJECT"

Crea una subnet

gcloud compute networks subnets create "$VPC_SUBNET" \
        --network="$VPC_NETWORK" \
        --region="$GOOGLE_CLOUD_REGION" \
        --range="$SUBNET_RANGE" \
        --enable-private-ip-google-access \
        --project "$GOOGLE_CLOUD_PROJECT"

7. Configura il criterio di accesso del service account

Il service account Cloud Run deve disporre delle autorizzazioni per accedere ai pesi del modello nel bucket di archiviazione che hai creato.

gcloud storage buckets add-iam-policy-binding "gs://${MODEL_CACHE_BUCKET}" \
    --member "serviceAccount:${SERVICE_ACCOUNT_EMAIL}" \
    --role "roles/storage.admin" \
    --project "${GOOGLE_CLOUD_PROJECT}"

8. Inizializza le variabili di configurazione

Definisci le variabili sia per il motore di inferenza vLLM sia per il servizio Cloud Run.

# vLLM variables
export MAX_MODEL_LEN="32767"    # 32767 to improve concurrency. Keep it empty to use model's maximim context length (256K)
export QUANTIZATION_TYPE="fp8"  # Model quantization for faster performance and lower memory usage.
export KV_CACHE_DTYPE="fp8"     # KV-cache quantization to save GPU memory.
export GPU_MEM_UTIL="0.95"      # Fraction of GPU memory to be used by the vLLM engine.
export TENSOR_PARALLEL_SIZE="1" # Partitioning model across GPUs (1 here as we have only 1 GPU).
export MAX_NUM_SEQS="16"         # Max concurrent requests vLLM processes in one batch.

# Cloud Run variables
export CLOUD_RUN_CPU_NUM=20
export CLOUD_RUN_MEMORY_GB=80
export CLOUD_RUN_MAX_INSTANCES=1
export CLOUD_RUN_CONCURRENCY=16

Nota sulla regolazione per le prestazioni: la regolazione di queste variabili è un compromesso tra velocità effettiva e latenza:

• MAX_NUM_SEQS rispetto a CLOUD_RUN_CONCURRENCY: CLOUD_RUN_CONCURRENCY deve essere almeno uguale a MAX_NUM_SEQS. Per un utilizzo ottimale con picchi di traffico, impostalo leggermente più alto (ad es. 2 volte).
• Pressione della memoria: MAX_MODEL_LEN e MAX_NUM_SEQS utilizzano la memoria GPU per la cache KV. Se si verificano errori di memoria insufficiente (OOM) con lunghezze di contesto elevate, valuta la possibilità di ridurre MAX_NUM_SEQS.
• Latenza: una concorrenza più elevata (MAX_NUM_SEQS) aumenta la velocità effettiva totale, ma può aumentare la latenza delle singole richieste.
• Scalabilità: CLOUD_RUN_MAX_INSTANCES consente di scalare orizzontalmente. Se la latenza della singola istanza è accettabile, ma hai bisogno di una capacità totale maggiore, aumenta questo valore.

9. Esegui il deployment in Cloud Run

Prepara la riga di comando del container vLLM

vLLM richiede molti parametri per eseguire modelli di grandi dimensioni in modo rapido ed efficiente. Questi parametri verranno passati come argomenti al container di cui è stato eseguito il deployment in Cloud Run.

CONTAINER_ARGS=(
    "vllm"
    "serve"
    "${GCS_MODEL_LOCATION}"
    "--served-model-name" "${MODEL_NAME}"
    "--enable-log-requests"
    "--enable-chunked-prefill"
    "--enable-prefix-caching"
    "--generation-config" "auto"
    "--enable-auto-tool-choice"
    "--tool-call-parser" "gemma4"
    "--reasoning-parser" "gemma4"
    "--dtype" "bfloat16"
    "--quantization" "${QUANTIZATION_TYPE}"
    "--kv-cache-dtype" "${KV_CACHE_DTYPE}"
    "--max-num-seqs" "${MAX_NUM_SEQS}"
    "--gpu-memory-utilization" "${GPU_MEM_UTIL}"
    "--tensor-parallel-size" "${TENSOR_PARALLEL_SIZE}"
    "--load-format" "runai_streamer"
    "--port" "8080"
    "--host" "0.0.0.0"
)

if [[ "${MAX_MODEL_LEN}" != "" ]]; then
    CONTAINER_ARGS+=("--max-model-len" "${MAX_MODEL_LEN}")
fi

export CONTAINER_ARGS_STR="${CONTAINER_ARGS[*]}"

Esegui il deployment del servizio Cloud Run

Esegui il seguente comando per eseguire il deployment del servizio Cloud Run. Tieni presente il tipo di GPU (RTX 6000 Pro), l'immagine di base (pytorch-vllm-serve:gemma4) e la necessità di autenticarsi per richiamare il servizio (--no-allow-unauthenticated).

gcloud beta run deploy "${SERVICE_NAME}" \
    --image="us-docker.pkg.dev/vertex-ai/vertex-vision-model-garden-dockers/pytorch-vllm-serve:gemma4" \
    --project "${GOOGLE_CLOUD_PROJECT}" \
    --region "${GOOGLE_CLOUD_REGION}" \
    --service-account "${SERVICE_ACCOUNT_EMAIL}" \
    --execution-environment gen2 \
    --no-allow-unauthenticated \
    --cpu="${CLOUD_RUN_CPU_NUM}" \
    --memory="${CLOUD_RUN_MEMORY_GB}Gi" \
    --gpu=1 \
    --gpu-type=nvidia-rtx-pro-6000 \
    --no-gpu-zonal-redundancy \
    --no-cpu-throttling \
    --max-instances ${CLOUD_RUN_MAX_INSTANCES} \
    --concurrency ${CLOUD_RUN_CONCURRENCY} \
    --network ${VPC_NETWORK} \
    --subnet ${VPC_SUBNET} \
    --vpc-egress all-traffic \
    --set-env-vars "MODEL_NAME=${MODEL_NAME}" \
    --set-env-vars "GOOGLE_CLOUD_PROJECT=${GOOGLE_CLOUD_PROJECT}" \
    --set-env-vars "GOOGLE_CLOUD_REGION=${GOOGLE_CLOUD_REGION}" \
    --port=8080 \
    --timeout=3600 \
    --cpu-boost \
    --startup-probe tcpSocket.port=8080,initialDelaySeconds=240,failureThreshold=40,timeoutSeconds=10,periodSeconds=15 \
    --command "bash" \
    --args="^;^-c;${CONTAINER_ARGS_STR}"

Il deployment richiede alcuni minuti. Al termine, avrai un ambiente basato su GPU che utilizza Gemma 4 utilizzando un'infrastruttura serverless con scalabilità automatica, inclusa la scalabilità a zero (nessun traffico, nessun costo).

Nota: se il deployment del servizio non riesce con riferimento alla disponibilità o alla quota della GPU, salta il test del servizio e continua con la sezione Crea un agente dati utilizzando Agent Development Kit. Se non è disponibile alcun servizio Gemma 4, l'agente può utilizzare Gemini 3.5 Flash Lite in Gemini Enterprise Agent Platform.

10. Prova il servizio

Una volta eseguito il deployment, puoi interagire con il modello Gemma 4 utilizzando l'API compatibile con vLLM OpenAI.

Ottieni l'URL del servizio

Recupera l'URL del servizio Cloud Run di cui hai eseguito il deployment.

SERVICE_URL=$(gcloud run services describe $SERVICE_NAME --project "${GOOGLE_CLOUD_PROJECT}" --region "${GOOGLE_CLOUD_REGION}" --format 'value(status.url)')
echo "Service URL: $SERVICE_URL"

Esegui l'inferenza

Invia un prompt al modello utilizzando curl.

curl -s "$SERVICE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $(gcloud auth print-identity-token)" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "'"${MODEL_NAME}"'",
  "messages": [
    {"role": "user", "content": "Why is the sky blue?"}
  ],
  "chat_template_kwargs": {
    "enable_thinking": true
  },
  "skip_special_tokens": false
}' | jq -r '.choices[0].message.content'

11. 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
import subprocess

from google.adk.agents import LlmAgent
from google.adk.models.lite_llm import LiteLlm
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
from google.oauth2 import id_token

# Fetch Application Default Credentials (ADC)
application_default_credentials, project_id = google.auth.default()
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.")

if os.getenv("GOOGLE_GENAI_USE_ENTERPRISE", "").lower() not in ["true", "1"]:
    # Using Cloud Run for hosting LLM with LiteLLM wrapper
    api_base = os.getenv(
        "API_BASE",
        os.environ.get("OPENAI_API_BASE", "")
    ).rstrip("/")
    if not api_base:
        raise ValueError("API_BASE environment variable is not set")
    if not api_base.endswith("/v1"):
        api_base += "/v1"

    model_name = os.getenv("MODEL_NAME")
    if not model_name:
        raise ValueError("MODEL_NAME environment variable is not set")
    # Format required by LiteLLM for OpenAI-compatible APIs
    model_name=f"openai/{model_name}"

    # To access the model's Cloud Run service,
    # we need an identity token.
    try:
        model_service_token_string = id_token.fetch_id_token(Request(), api_base)
    except Exception as e:
        # Fallback with using gcloud CLI to get the identity token
        model_service_token_string = subprocess.check_output(
            f"gcloud auth print-identity-token -q",
            shell=True
        ).decode().strip()

    # Gemma 4 in vLLM requires additional parameters in the request body.
    extra_body={
        "chat_template_kwargs": {
            "enable_thinking": True
        },
        "skip_special_tokens": False
    }
    # Configure the model with LiteLLM and an OpenAI-compatible endpoint
    custom_model = LiteLlm(
      model=model_name,
      base_url=api_base,
      api_key=model_service_token_string,
      extra_body=extra_body
    )
    model = custom_model
else:
    # Gemini API in Agent Platform fallback
    model = "gemini-3.5-flash-lite"

# Initialize the MCP Toolset with the connection parameters
bigquery_toolset = MCPToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://bigquery.googleapis.com/mcp",
        headers={
            "Authorization": f"Bearer {application_default_credentials.token}",
            "x-goog-user-project": project_id, # This is used for billing
        },
        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',
        ]
    )
)

# 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.
    It includes trip records starting from September 2013 and is updated daily.)

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=model,
    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, litellm per la libreria LiteLLM che ADK utilizza per l'utilizzo di modelli non Gemini 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.*\nlitellm\nmcp==1.29.*" > data_agent/requirements.txt

La struttura finale delle cartelle 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 offre è 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.

export API_BASE=$(gcloud run services describe $SERVICE_NAME \
  --project $GOOGLE_CLOUD_PROJECT \
  --region $GOOGLE_CLOUD_REGION \
  --format 'value(status.url)')

# If Gemma 4 deployment failed, use Gemini fallback
if [[ "${API_BASE}" == "" ]]; then
  export GOOGLE_GENAI_USE_ENTERPRISE=true
else
  export GOOGLE_GENAI_USE_ENTERPRISE=false
fi

uv tool run --with litellm,"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 .

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

What data do you have?

Nota: la prima richiesta all'agente potrebbe richiedere alcuni minuti se il servizio Gemma 4 di cui è stato eseguito il deployment in precedenza viene ridotto a zero da Cloud Run. L'avvio e il caricamento del modello richiedono circa 3-4 minuti.

Il codice dell'agente utilizzerà il modello Gemma 4 di cui è stato eseguito il deployment in Cloud Run. Il modello 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.

12. Esegui il deployment dell'agente in Cloud Run

Se il comando precedente è ancora in esecuzione sul server web ADK, arrestalo con la combinazione Ctrl + C.

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

export API_BASE=$(gcloud run services describe $SERVICE_NAME \
  --project $GOOGLE_CLOUD_PROJECT \
  --region $GOOGLE_CLOUD_REGION \
  --format 'value(status.url)')

# If Gemma 4 deployment failed, use Gemini fallback
if [[ "${API_BASE}" == "" ]]; then
  export GOOGLE_GENAI_USE_ENTERPRISE=true
else
  export GOOGLE_GENAI_USE_ENTERPRISE=false
fi

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 gemma4-data-agent \
      --app_name data_agent \
      data_agent \
      -- \
      --allow-unauthenticated \
      --max-instances 1 \
      --set-env-vars GOOGLE_GENAI_USE_ENTERPRISE=${GOOGLE_GENAI_USE_ENTERPRISE},MODEL_NAME="${MODEL_NAME}",API_BASE="${API_BASE}",GOOGLE_CLOUD_PROJECT="${GOOGLE_CLOUD_PROJECT}"

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 anche recuperare l'URL eseguendo il comando gcloud run services:

gcloud run services describe gemma4-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 deve esplorare il set di dati Citibike utilizzando il server BigQuery MCP, eseguire alcune query SQL e restituire un elenco di 3 stazioni citibike.

13. Complimenti!

Complimenti per aver completato il codelab.

Ti consigliamo di consultare la documentazione di Cloud Run.

Argomenti trattati

• Come eseguire il deployment del modello Gemma 4 su una GPU Cloud Run RTX 6000 Pro
• Come configurare il traffico in uscita VPC diretto e lo streaming del modello vLLM con Cloud Storage per un avvio più rapido del servizio.
• Come creare ed eseguire il deployment di un agente AI con Agent Development Kit che utilizza il modello linguistico di grandi dimensioni Gemma 4 e il server MCP BigQuery.

14. 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 le risorse

Elimina i servizi Cloud Run

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

Elimina il service account

gcloud iam service-accounts delete \
      ${SERVICE_ACCOUNT_EMAIL} \
      --project "${GOOGLE_CLOUD_PROJECT}" \
      --quiet

Elimina il bucket Cloud Storage

gcloud storage rm --recursive gs://$MODEL_CACHE_BUCKET

Elimina la rete VPC e la subnet

gcloud compute networks subnets delete $VPC_SUBNET \
    --region "${GOOGLE_CLOUD_REGION}" \
    --project "${GOOGLE_CLOUD_PROJECT}" \
    --quiet

gcloud compute networks delete $VPC_NETWORK \
    --project "${GOOGLE_CLOUD_PROJECT}" \
    --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 anche utilizzare questo comando:

gcloud projects delete ${GOOGLE_CLOUD_PROJECT}