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

1. Introdução

O que você vai aprender

• Como criar um agente de IA usando o Kit de Desenvolvimento de Agentes (ADK) com o Gemini na Plataforma de Agentes.
• Como conceder aos agentes de IA acesso a dados estruturados no BigQuery usando o servidor MCP do BigQuery.

O Cloud Run é uma plataforma de computação sem servidor totalmente gerenciada que permite executar aplicativos e serviços conteinerizados sem gerenciar nenhuma infraestrutura.

O Kit de Desenvolvimento de Agentes (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 a maneira como os modelos de linguagem grandes (LLMs) e os 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.

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
gcloud config set run/region CLOUD-RUN-REGION

Substitua CLOUD-RUN-REGION por uma das regiões com suporte do Cloud Run.

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

# 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

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 \
    bigquery.googleapis.com \
    aiplatform.googleapis.com

3. Criar um agente de dados usando o Kit de Desenvolvimento de Agentes

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

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

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 Agentes 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.*\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 Agentes 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.

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

Depois que 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 e selecione o item de menu "Visualizar na porta 8080".

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

What data do you have?

O agente 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 dos campos disponíveis no conjunto de dados do Citibike.

4. Implantar o agente no Cloud Run

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

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

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 bq-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 do Citibike.

5. Parabéns!

Parabéns por concluir o codelab.

Recomendamos revisar a documentação do Cloud Run.

O que aprendemos

• Como criar um agente de IA com o Kit de Desenvolvimento de Agentes e o Gemini
• Como conectar o agente ao servidor MCP do BigQuery.
• Como implantar o agente no Cloud Run.

6. 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 o serviço

Excluir o serviço do Cloud Run

gcloud run services delete bq-data-agent \
      --project "${GOOGLE_CLOUD_PROJECT}" \
      --region "${GOOGLE_CLOUD_REGION}" \
      --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}