Criar e implantar agentes de IA com o Gemma 4 e o servidor MCP do BigQuery no Cloud Run

1. Introdução

Observação:este recurso está sujeito aos Termos da solução pré-GA na seção Termos gerais de serviço dos Termos específicos de serviço. Os recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento

Visão geral

O que você vai aprender

• Como implantar um modelo Gemma 4 em uma GPU RTX 6000 Pro do Cloud Run com vLLM.
• Como criar um agente de IA usando o Kit de Desenvolvimento de Agente (ADK) e usar o Gemma 4 com ele.
• Como conceder aos agentes de IA acesso a dados estruturados no BigQuery usando o servidor MCP do BigQuery.

Gemma 4 é uma família de modelos de peso aberto licenciados pelo Apache 2 do Google DeepMind. Os modelos são multimodais, multilíngues, oferecem raciocínio e uma arquitetura eficiente.

O Cloud Run é um ambiente sem servidor para contêineres com suporte a GPUs.

O Kit de Desenvolvimento de Agente (ADK) é um framework de desenvolvimento de agentes de código aberto que permite criar, depurar e implantar agentes de IA confiáveis em escala empresarial.

O BigQuery é um data warehouse corporativo sem servidor totalmente gerenciado que permite armazenar, consultar e analisar conjuntos de dados grandes.

O Protocolo de Contexto de Modelo (MCP) padroniza como modelos de linguagem grandes (LLMs) e aplicativos ou agentes de IA se conectam a fontes de dados externas. Os servidores MCP permitem usar as ferramentas, os recursos e os comandos deles para realizar ações e receber dados atualizados do serviço de back-end. O servidor MCP do BigQuery oferece aos agentes de IA uma maneira direta e segura de analisar dados no BigQuery. Esse servidor MCP totalmente gerenciado remove a sobrecarga de gerenciamento, permitindo que você se concentre no desenvolvimento de agentes inteligentes.

Observação:este codelab usa o modelo Gemma 4 31B Instruction-Tuned. O codelab demonstra como usar o Run:ai Model Streamer e a saída VPC direta para minimizar o tempo que o modelo leva para carregar do Cloud Storage durante a inicialização do contêiner. Para mais informações, consulte o guia de práticas recomendadas para GPU.

2. Configuração e requisitos

Todo este laboratório pode ser executado na linha de comando. Você pode usar o Cloud Shell (clique no ícone de comando no canto superior direito do console) para iniciar o ambiente.

Comece definindo o projeto padrão e a região do Cloud Run:

# set the project
gcloud config set project YOUR_PROJECT_ID

Substitua YOUR_PROJECT_ID pelo ID do seu projeto do Google Cloud.

# set Cloud Run region
REGION="CLOUD-RUN-REGION"; gcloud config set run/region $REGION && echo $REGION > lab2rgn.txt

Substitua CLOUD-RUN-REGION por uma das seguintes regiões do Cloud:

• us-central1
• asia-southeast1

Confira as variáveis de ambiente que serão usadas neste codelab. É possível salvá-las em um arquivo de ambiente e "originar" esse arquivo. Defina corretamente o valor do ID do projeto e, opcionalmente, a região.

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

Observação:é útil salvar esse snippet como um arquivo de script e reutilizá-lo no futuro, em casos em que a sessão do Cloud Shell é redefinida. Salve-o como env.sh e execute source env.sh para definir as variáveis de ambiente ao executar as etapas subsequentes. Não confirme env.sh nos sistemas de controle de versões.

Ative as APIs necessárias para este codelab. As mudanças na API podem levar de 2 a 3 minutos para entrar em vigor.

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. Criar a conta de serviço

Se você não especificar uma conta de serviço quando o serviço ou job do Cloud Run for criado, o Cloud Run vai usar a conta de serviço padrão do Compute Engine. Recomendamos uma conta de serviço separada para o serviço do Cloud Run para evitar a execução do serviço com permissões excessivas.

Criar uma conta de serviço para o serviço do Cloud Run

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

4. Configurar o Cloud Storage

Crie um bucket do Cloud Storage para armazenar os pesos do modelo. Isso permitirá o uso da saída VPC direta para fazer o download dos pesos do modelo mais rapidamente sempre que o Cloud Run iniciar uma instância de serviço.

Combinado com o recurso Run:ai Model Streamer no vLLM, ele reduz significativamente o tempo de carregamento do modelo.

Criar um bucket

Verifique se é um bucket de região única localizado junto com o serviço do 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. Recuperar e armazenar em cache os pesos do modelo

Em seguida, faça o download do modelo Gemma 4 para o bucket do Cloud Storage. Os pesos dos modelos são dezenas de gigabytes, e fazer o download deles para sua máquina local ou Cloud Shell pode ser inviável. Em vez disso, use o Cloud Build com armazenamento suficiente para armazenar os pesos do modelo.

Copiar pesos do modelo de um bucket compartilhado do Cloud Storage

O Google Cloud hospeda um bucket do Cloud Storage acessível publicamente com pesos do modelo Gemma 4.

Se você usar uma das regiões us-, em vez de copiar os pesos do modelo, basta modificar GCS_MODEL_LOCATION para apontar para o local do cache público. Por exemplo, para o modelo gemma-4-31B-it, defina export GCS_MODEL_LOCATION="gs://vertex-model-garden-public-us/gemma4/gemma-4-31B-it" (se você usar um arquivo de ambiente, como .env ou env.sh, não se esqueça de modificá-lo).

Para copiá-los para o bucket de armazenamento, execute o 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

Observação:essa operação leva um tempo significativo, de 10 a 30 minutos.

6. Configurar a rede para saída VPC direta

A configuração de saída VPC direta exige a criação de uma rede e uma sub-rede com o Acesso privado do Google ativado.

Isso permite que os serviços do Cloud Run se conectem ao conjunto de endereços IP externos usados pelas APIs e serviços do Google, incluindo o Cloud Storage.

Criar uma rede

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

Criar uma sub-rede

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. Configurar a política de acesso da conta de serviço

A conta de serviço do Cloud Run precisa de permissões para acessar os pesos do modelo no bucket de armazenamento que você criou.

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. Inicializar variáveis de configuração

Defina as variáveis para o mecanismo de inferência vLLM e o serviço do 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

Observação sobre a otimização de desempenho:a otimização dessas variáveis é um equilíbrio entre capacidade e latência:

• MAX_NUM_SEQS vs CLOUD_RUN_CONCURRENCY: CLOUD_RUN_CONCURRENCY precisa ser pelo menos tão grande quanto MAX_NUM_SEQS. Para uma utilização ideal com picos de tráfego, defina um valor um pouco maior (por exemplo, 2x).
• Pressão de memória: MAX_MODEL_LEN e MAX_NUM_SEQS consomem memória da GPU para o cache KV. Se você encontrar erros de memória insuficiente (OOM) com tamanhos de contexto grandes, considere reduzir MAX_NUM_SEQS.
• Latência: uma simultaneidade maior (MAX_NUM_SEQS) aumenta a capacidade de processamento total, mas pode aumentar a latência de solicitações individuais.
• Escalonamento: CLOUD_RUN_MAX_INSTANCES permite escalonar horizontalmente. Se a latência de instância única for aceitável, mas você precisar de mais capacidade total, aumente esse valor.

9. Implantar no Cloud Run

Preparar a linha de comando do contêiner vLLM

O vLLM exige muitos parâmetros para executar modelos grandes de forma rápida e eficiente. Esses parâmetros serão transmitidos como argumentos para o contêiner implantado no 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[*]}"

Implantar o serviço do Cloud Run

Execute o comando a seguir para implantar o serviço do Cloud Run. Observe o tipo de GPU (RTX 6000 Pro), a imagem de base (pytorch-vllm-serve:gemma4) e a necessidade de autenticação para invocar o serviço (--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}"

Isso levará alguns minutos para ser implantado. Quando terminar, você terá um ambiente com tecnologia de GPU que serve o Gemma 4 usando uma infraestrutura sem servidor com escalonamento automático, incluindo o escalonamento para zero (sem tráfego, sem custo).

Observação:se a implantação do serviço falhar com referência à disponibilidade ou cota da GPU, pule o teste do serviço e continue com a seção Criar um agente de dados usando o Kit de Desenvolvimento de Agente. O agente pode usar o Gemini 3.5 Flash Lite na Gemini Enterprise Agent Platform se não houver um serviço Gemma 4 para usar.

10. Testar o serviço

Depois de implantado, você pode interagir com o modelo Gemma 4 usando a API compatível com vLLM OpenAI.

Receber o URL do serviço

Recupere o URL do serviço do Cloud Run implantado.

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"

Executar inferência

Envie um comando para o modelo usando 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. Criar um agente de dados usando o Kit de Desenvolvimento de Agente

Escrever o código do agente

No terminal do Cloud Shell ou no terminal local, crie um diretório raiz para o app do agente:

mkdir data_agent

Abra o Editor do Cloud Shell ou outro editor de texto e crie agent.py no diretório 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]
)

O ADK também exige __init__.py e requirements.txt para implantação:

• __init__.py precisa ter uma importação para o agente.
• requirements.txt lista as dependências do Python: google-adk para o Kit de Desenvolvimento de Agente, litellm para a biblioteca LiteLLM que o ADK aproveita para usar modelos não Gemini e mcp para o cliente do Protocolo de Contexto de Modelo.

Esses comandos ajudam a criar __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

A estrutura final da pasta precisa ser semelhante a esta:

data_agent/
    __init__.py
    agent.py
    requirements.txt

Testar o agente localmente

O Kit de Desenvolvimento de Agente vem com a ferramenta de CLI adk, uma interface de terminal interativa para testar seus agentes. Isso é útil para testes rápidos, interações com script e pipelines de CI/CD. Um dos recursos que ele oferece é adk web – a interface da Web do ADk – uma maneira simples de desenvolver e depurar seus agentes de forma interativa. O ADK Web não foi criado para uso em implantações de produção, mas facilita muito o teste do agente.

Observação:antes de executar esse comando, verifique se o diretório atual tem o diretório data_agent (com o comando ls).

Esse comando inicia adk web, que inicia um servidor da Web local na 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 .

Quando o serviço for iniciado, abra a página da Web do ADK local: http://localhost:8080/.

Se você estiver usando o Google Cloud Shell, clique no botão Visualização da Web .

Na interface da Web do ADK, pergunte ao agente sobre os dados a que ele tem acesso:

What data do you have?

Observação:a primeira solicitação ao agente pode levar alguns minutos se o serviço Gemma 4 implantado anteriormente for reduzido a zero pelo Cloud Run. Leva cerca de 3 a 4 minutos para iniciar e carregar o modelo.

O código do agente vai usar o modelo Gemma 4 implantado no Cloud Run. O modelo vai usar as ferramentas MCP do BigQuery para analisar o conjunto de dados do citibike. Ele vai oferecer uma visão geral das tabelas e campos disponíveis no conjunto de dados do Citibike.

12. Implantar o agente no Cloud Run

Se o comando anterior ainda estiver executando o servidor da Web do ADK, interrompa-o com a combinação Ctrl + C.

Esse comando vai implantar o agente no Cloud Run usando a CLI do ADK.

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

Testar o agente

Usamos a opção --with_ui para a implantação do agente. Ele implantou o agente com a interface da Web do ADK.

1. Abra o URL do agente no navegador da Web. O comando adk deploy o retornou, e você também pode recuperar o URL executando o comando gcloud run services:

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

2. Peça ao agente para raciocinar sobre os dados disponíveis do Citibike:

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

O agente precisa analisar o conjunto de dados do Citibike usando o servidor MCP do BigQuery, executar algumas consultas SQL e retornar uma lista de três estações de citibike.

13. Parabéns!

Parabéns por concluir o codelab.

Recomendamos revisar a documentação do Cloud Run.

O que aprendemos

• Como implantar o modelo Gemma 4 em uma GPU RTX 6000 Pro do Cloud Run.
• Como configurar a saída VPC direta e o streaming de modelos vLLM com o Cloud Storage para uma inicialização mais rápida do serviço.
• Como criar e implantar um agente de IA com o Kit de Desenvolvimento de Agente que usa o LLM Gemma 4 e o servidor MCP do BigQuery.

14. Limpar

Para evitar cobranças na sua conta do Google Cloud pelos recursos usados neste tutorial, exclua o projeto que os contém ou mantenha o projeto e exclua os recursos individuais.

Opção 1: excluir recursos

Excluir os serviços do 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

Excluir a conta de serviço

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

Excluir o bucket do Cloud Storage

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

Excluir a sub-rede e a rede VPC

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

Opção 2: excluir o projeto

Para excluir todo o projeto, acesse Gerenciar recursos, selecione o projeto criado na etapa 2 e escolha Excluir. Se você excluir o projeto, será necessário mudar os projetos no SDK Cloud. Para conferir a lista de todos os projetos disponíveis, execute gcloud projects list. Se você quiser usar a linha de comando, também poderá usar este comando:

gcloud projects delete ${GOOGLE_CLOUD_PROJECT}