Criar um agente analista do Google Trends com o MCP do BigQuery

1. Visão geral

Neste codelab, você vai criar um agente analista do Google Trends usando o ADK do Google. Esse agente usa o servidor MCP do BigQuery para descobrir e executar ferramentas que consultam o conjunto de dados públicos do Google Trends (bigquery-public-data.google_trends).

O que você vai aprender

• Como configurar um projeto para desenvolvimento com o ADK.
• Como ativar e usar servidores MCP gerenciados para o BigQuery.
• Como criar um agente que usa ferramentas do MCP.
• Como executar o agente localmente para testes.
• Como implantar o agente no Google Cloud Run.

O que é necessário

• Tenha um projeto do Google Cloud com o faturamento ativado.
• Um navegador da web, como o Chrome
• Python 3.11 ou mais recente

Este codelab é destinado a desenvolvedores intermediários que têm alguma familiaridade com Python e Google Cloud.

Este codelab leva aproximadamente de 15 a 20 minutos para ser concluído.

Os recursos criados neste codelab custam menos de US $5.

2. Configurar o ambiente

Criar um projeto do Google Cloud

1. No console do Google Cloud, na página do seletor de projetos, selecione ou crie um projeto na nuvem do Google Cloud.
2. Verifique se o faturamento está ativado para seu projeto do Cloud. Saiba como verificar se o faturamento está ativado em um projeto.

Recomendamos que você use o Google Cloud Shell para este codelab. Ele fornece um ambiente de terminal com Python e a CLI do Google Cloud já instalados.

Para ativar o Cloud Shell, clique no botão Ativar Cloud Shell na parte de cima do console do Google Cloud.

Definir variáveis de ambiente

Defina as seguintes variáveis de ambiente.

export GOOGLE_CLOUD_PROJECT=<INSERT_YOUR_GCP_PROJECT_HERE>
export GOOGLE_GENAI_USE_VERTEXAI=1

Observação: definir GOOGLE_GENAI_USE_VERTEXAI=1 direciona o ADK a usar a Vertex AI, aproveitando o Cloud IAM para autenticação em vez de um GEMINI_API_KEY.

Autenticar e configurar o gcloud

Faça login na sua Conta do Google, defina o projeto ativo e configure as Application Default Credentials.

Pule esta etapa se estiver usando o Cloud Shell.

gcloud auth login
gcloud auth application-default login

Observação: o gcloud auth login autentica os comandos da CLI gcloud, enquanto o gcloud auth application-default login autentica o código do aplicativo local.

Defina o projeto na nuvem do Google Cloud:

gcloud config set project ${GOOGLE_CLOUD_PROJECT}

Ativar as APIs necessárias

Ative as APIs do Cloud necessárias para o Cloud Run, o Artifact Registry, o BigQuery e a Vertex AI.

gcloud services enable run.googleapis.com \
                       cloudbuild.googleapis.com \
                       artifactregistry.googleapis.com \
                       bigquery.googleapis.com \
                       aiplatform.googleapis.com

Ativar a MCP para BigQuery

Os servidores MCP gerenciados precisam ser ativados explicitamente para o projeto.

gcloud beta services mcp enable bigquery.googleapis.com

Criar uma pasta para o projeto

Comece criando uma pasta raiz para seu agente e uma pasta interna para a implementação dele.

mkdir google-trends-agent
cd google-trends-agent
mkdir google_trends

3. Criar o código do agente

Crie um arquivo vazio chamado google_trends/__init__.py:

touch google_trends/__init__.py

Em seguida, crie um arquivo chamado google_trends/agent.py e cole o seguinte código:

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. Run the agent

Nesta etapa, você vai configurar um ambiente virtual Python local, instalar dependências e executar o agente para verificar o comportamento dele na sua máquina (ou no Google Cloud Shell).

• Navegue até o diretório raiz do aplicativo (google-trends-agent).
• Crie um ambiente virtual:

python -m venv mcp_demo_env
source mcp_demo_env/bin/activate

• Instale os pacotes Python necessários:

pip install google-auth google-adk

Vamos usar o ADK Web para testar nosso novo agente.

Para desenvolvimento e testes locais, execute o seguinte comando:

adk web

Para desenvolvimento e testes no Google Cloud Shell, execute o seguinte comando:

adk web --allow_origins="*"

Isso vai iniciar o servidor da Web do ADK. Você pode interagir com o agente usando a interface da Web local (geralmente em http://localhost:8000).

Observação: também é possível usar o comando adk run google_trends mais simples para testar o agente.

Pergunte ao agente:

• Mostre as principais tendências nos EUA
• Quais são as principais tendências em alta na França neste mês?
• Quais foram as 3 principais tendências na Califórnia na semana passada?
• Quais tabelas do BigQuery você pode acessar?
• Me conte tudo o que você sabe sobre a tabela top_trends

5. Implantar no Cloud Run

Siga estas etapas para implantar o agente com segurança no Google Cloud Run.

Conceder permissões

O Cloud Run precisa de permissão para acessar a Vertex AI e usar as ferramentas da MCP do BigQuery.

# 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}[e-mail]" \
  --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}[e-mail]" \
  --role="roles/mcp.toolUser"

gcloud projects add-iam-policy-binding ${GOOGLE_CLOUD_PROJECT} \
  --member="serviceAccount:${PROJECT_NUMBER}[e-mail]" \
  --role="roles/bigquery.jobUser"

gcloud projects add-iam-policy-binding ${GOOGLE_CLOUD_PROJECT} \
  --member="serviceAccount:${PROJECT_NUMBER}[e-mail]" \
  --role="roles/bigquery.dataViewer"

Criar o Dockerfile

Na raiz do projeto (google-trends-agent), crie um arquivo chamado Dockerfile e cole o seguinte conteúdo:

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

Implante o agente

Execute o seguinte comando no diretório raiz. Isso vai conteinerizar e implantar seu agente no Cloud Run.

Fique de olho na resposta ao comando. Quando a implantação terminar, um URL do serviço será fornecido. Você vai usar esse URL para interagir com o agente.

gcloud run deploy google-trends-agent \
  --source . \
  --region us-west1 \
  --allow-unauthenticated \
  --set-env-vars="GOOGLE_CLOUD_PROJECT=${GOOGLE_CLOUD_PROJECT}"

Verificação rápida

Quando a implantação terminar, o console vai gerar um URL do serviço. Abra esse URL no navegador. Ele vai fornecer a mesma interface interativa que você viu localmente, mas agora em execução na nuvem.

Você também pode monitorar os registros para garantir que tudo esteja funcionando corretamente:

gcloud logging read "resource.type=cloud_run_revision AND resource.labels.service_name=google-trends-agent" --limit 10

6. Limpeza

Para evitar cobranças contínuas, exclua os recursos criados durante este codelab.

Exclua o serviço do Cloud Run:

gcloud run services delete google-trends-agent --region us-west1

Se você criou um projeto especificamente para este codelab, é possível excluir todo o projeto:

gcloud projects delete ${GOOGLE_CLOUD_PROJECT}

Você também pode excluir todos os arquivos relacionados a este codelab:

deactivate
cd ..
rm -rf google-trends-agent

7. Parabéns

Parabéns! Você criou e implantou um agente analista do Google Trends.

O que você aprendeu

• Como usar o MCP para ampliar as habilidades do agente de forma dinâmica
• Como criar e disponibilizar agentes de LLM com o ADK do Google
• Como implantar e escalonar agentes no Cloud Run

Próximas etapas

• Tente modificar o agente para consultar diferentes conjuntos de dados do BigQuery
• Adicione mais ferramentas do MCP para ampliar as capacidades do agente

Documentos de referência

• Documentação do ADK
• Guia das ferramentas do MCP
• BigQuery MCP
• Documentação do Cloud Run