Cómo crear un agente de analista de Google Trends con MCP de BigQuery

1. Descripción general

En este codelab, compilarás un agente analista de Google Trends con el ADK de Google. Este agente aprovecha el servidor de MCP de BigQuery para descubrir y ejecutar de forma dinámica herramientas que consultan el conjunto de datos públicos de Google Trends (bigquery-public-data.google_trends).

Qué aprenderás

• Cómo configurar un proyecto para el desarrollo del ADK
• Cómo habilitar y usar servidores de MCP administrados para BigQuery
• Cómo compilar un agente que usa herramientas de MCP
• Cómo ejecutar el agente de forma local para realizar pruebas
• Cómo implementar el agente en Google Cloud Run

Requisitos

• Un proyecto de Google Cloud con la facturación habilitada.
• Un navegador web, como Chrome
• Python 3.11 o versiones posteriores

Este codelab es para desarrolladores intermedios que tienen cierta familiaridad con Python y Google Cloud.

Este codelab tarda entre 15 y 20 minutos en completarse.

Los recursos creados en este codelab deberían costar menos de USD 5.

2. Configura tu entorno

Crea un proyecto de Google Cloud

1. En la página del selector de proyectos de la consola de Google Cloud, selecciona o crea un proyecto de Google Cloud.
2. Asegúrate de que la facturación esté habilitada para tu proyecto de Cloud. Obtén información para verificar si la facturación está habilitada en un proyecto.

Te recomendamos que uses Google Cloud Shell para este codelab. Proporciona un entorno de terminal con Python y Google Cloud CLI ya instalados.

Para activar Cloud Shell, haz clic en el botón Activar Cloud Shell en la parte superior de la consola de Google Cloud.

Configura variables de entorno

Configura las siguientes variables de entorno:

export GOOGLE_CLOUD_PROJECT=<INSERT_YOUR_GCP_PROJECT_HERE>
export GOOGLE_GENAI_USE_VERTEXAI=1

Nota: Establecer GOOGLE_GENAI_USE_VERTEXAI=1 dirige el ADK para que use Vertex AI, aprovechando Cloud IAM para la autenticación en lugar de un GEMINI_API_KEY.

Autentica y configura gcloud

Accede a tu Cuenta de Google, configura tu proyecto activo y configura las credenciales predeterminadas de la aplicación.

Puedes omitir este paso si usas Cloud Shell.

gcloud auth login
gcloud auth application-default login

Nota: gcloud auth login autentica los comandos de la CLI de gcloud, mientras que gcloud auth application-default login autentica el código de la aplicación local.

Configura el proyecto de Google Cloud:

gcloud config set project ${GOOGLE_CLOUD_PROJECT}

Habilita las APIs necesarias

Habilita las APIs de Google Cloud necesarias para Cloud Run, Artifact Registry, BigQuery y Vertex AI.

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

Habilita MCP para BigQuery

Los servidores MCP administrados deben habilitarse de forma explícita para tu proyecto.

gcloud beta services mcp enable bigquery.googleapis.com

Crea una carpeta de proyecto

Comienza por crear una carpeta raíz para tu agente y una carpeta interna para la implementación del agente.

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

3. Crea el código del agente

Crea un nuevo archivo llamado google_trends/__init__.py:

touch google_trends/__init__.py

Luego, crea un archivo llamado google_trends/agent.py y pega el siguiente 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. Ejecuta el agente

En este paso, configurarás un entorno virtual de Python local, instalarás dependencias y ejecutarás el agente para verificar su comportamiento en tu máquina (o en Google Cloud Shell).

• Navega al directorio raíz de la aplicación (google-trends-agent).
• Crea un entorno virtual:

python -m venv mcp_demo_env
source mcp_demo_env/bin/activate

• Instale los paquetes de Python necesarios:

pip install google-auth google-adk

Usaremos la Web del ADK para probar nuestro nuevo agente.

Para el desarrollo y las pruebas locales, ejecuta el siguiente comando:

adk web

Para el desarrollo y las pruebas en Google Cloud Shell, ejecuta el siguiente comando:

adk web --allow_origins="*"

Esto iniciará el servidor web del ADK. Puedes interactuar con el agente a través de la interfaz web local (por lo general, en http://localhost:8000).

Nota: También puedes usar el comando adk run google_trends más simple para probar el agente.

Prueba a hacerle estas preguntas a tu agente:

• Muéstrame las principales tendencias en EE.UU.
• ¿Cuáles son las principales tendencias en aumento en Francia este mes?
• ¿Cuáles fueron las 3 principales tendencias en California la semana pasada?
• ¿A qué tablas de BigQuery tienes acceso?
• Cuéntame todo lo que sabes sobre la tabla top_trends

5. Implementa en Cloud Run

Sigue estos pasos para implementar el agente de forma segura en Google Cloud Run.

Otorgar permisos

Cloud Run necesita permiso para acceder a Vertex AI y usar las herramientas del MCP de 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"

Crea el Dockerfile

En la raíz de tu proyecto (google-trends-agent), crea un archivo llamado Dockerfile y pega el siguiente contenido:

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

Implementa el agente

Ejecuta el siguiente comando desde el directorio raíz. Esto alojará tu agente en contenedores y lo implementará en Cloud Run.

Presta atención al resultado del comando. Una vez que finalice la implementación, se proporcionará una URL de servicio. Usarás esta URL para interactuar con tu agente.

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

Verificación rápida

Una vez que finalice la implementación, la consola mostrará una URL de servicio. Abre esta URL en tu navegador. Proporcionará la misma IU interactiva que viste de forma local, pero ahora se ejecuta en la nube.

También puedes supervisar los registros para asegurarte de que todo funcione sin problemas:

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

6. Limpieza

Para evitar cargos continuos, borra los recursos que creaste durante este codelab.

Borra el servicio de Cloud Run:

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

Si creaste un proyecto específicamente para este codelab, puedes borrarlo por completo:

gcloud projects delete ${GOOGLE_CLOUD_PROJECT}

También puedes borrar todos los archivos relacionados con este codelab:

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

7. Felicitaciones

¡Felicitaciones! Creaste e implementaste correctamente un agente de analista de Google Trends.

Qué aprendiste

• Cómo usar el MCP para extender las capacidades del agente de forma dinámica
• Cómo compilar y publicar agentes de LLM con el ADK de Google
• Cómo implementar y escalar agentes en Cloud Run

Próximos pasos

• Intenta modificar el agente para consultar diferentes conjuntos de datos de BigQuery
• Agrega más herramientas de MCP para expandir las capacidades del agente

Documentos de referencia

• Documentación del ADK
• Guía de herramientas del MCP
• BigQuery MCP
• Documentación de Cloud Run