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

1. Visão geral

Neste codelab, você vai criar um agente de análise do Google Trends usando o ADK do Google. Esse agente aproveita o servidor MCP do BigQuery para descobrir e executar dinamicamente 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 do 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 na nuvem 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 o Python e o Google Cloud.

Este codelab leva aproximadamente 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 de seletor de projetos, selecione ou crie um projeto na nuvem.
2. Verifique se o faturamento está ativado para seu projeto na nuvem. Saiba como verificar se o faturamento está ativado em um projeto.

Recomendamos que você use o Google Cloud Shell para este codelab. Ele oferece um ambiente de terminal com o 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 para usar a Vertex AI, aproveitando o Cloud IAM para autenticação em vez de uma 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.

Você pode pular esta etapa se estiver usando o Cloud Shell.

gcloud auth login
gcloud auth application-default login

Observação: gcloud auth login autentica os comandos da CLI gcloud, enquanto 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 necessárias do Google Cloud 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 o MCP para o BigQuery

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

gcloud beta services mcp enable bigquery.googleapis.com

Criar uma pasta de projeto

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

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[mcp]

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. É possível 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.

Tente fazer estas perguntas ao agente:

• Mostre as principais tendências nos EUA
• Quais são as principais tendências em ascensão na França neste mês?
• Quais foram as três principais tendências na Califórnia na semana passada?
• Quais são as tabelas do BigQuery a que você tem acesso?
• Conte-me 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 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"]

Implantar o agente

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

Fique de olho na resposta ao comando. Quando a implantação terminar, ela vai fornecer um URL de serviço. Use 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 de 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.

Também é possível 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, exclua o projeto inteiro:

gcloud projects delete ${GOOGLE_CLOUD_PROJECT}

Também é possível 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 de análise do Google Trends.

O que você aprendeu

• Como usar o MCP para estender as capacidades do agente dinamicamente
• Como criar e disponibilizar agentes 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 MCP para expandir as capacidades do agente

Documentos de referência

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