Crea e implementa agentes de IA con el servidor de MCP de Gemini y BigQuery en Cloud Run

1. Introducción

Qué aprenderás

• Cómo crear un agente de IA con el Kit de desarrollo de agentes (ADK) con Gemini en Agent Platform.
• Cómo otorgarles a los agentes de IA acceso a datos estructurados en BigQuery con el servidor de MCP de BigQuery

Cloud Run es una plataforma de procesamiento sin servidores completamente administrada que te permite ejecutar aplicaciones y servicios alojados en contenedores sin administrar ninguna infraestructura subyacente.

El Kit de desarrollo de agentes (ADK) es un framework de desarrollo de agentes de código abierto que te permite compilar, depurar e implementar agentes de IA confiables a escala empresarial.

BigQuery es un almacén de datos empresarial completamente administrado y sin servidores que te permite almacenar, consultar y analizar conjuntos de datos masivos.

El Protocolo de contexto del modelo (MCP) estandariza la forma en que los modelos de lenguaje grandes (LLM) y las aplicaciones o agentes de IA se conectan a fuentes de datos externas. Los servidores de MCP te permiten usar sus herramientas, recursos y mensajes para realizar acciones y obtener datos actualizados de su servicio de backend. El servidor de MCP de BigQuery les brinda a tus agentes de IA una forma directa y segura de analizar datos en BigQuery. Este servidor de MCP completamente administrado elimina la sobrecarga de administración, lo que te permite enfocarte en desarrollar agentes inteligentes.

2. Configuración y requisitos

Todo este lab se puede ejecutar en la línea de comandos. Puedes usar Cloud Shell (haz clic en el ícono de la línea de comandos en la esquina superior derecha de la consola) para iniciar el entorno.

Comienza por configurar el proyecto predeterminado y la región de Cloud Run:

# set the project
gcloud config set project YOUR_PROJECT_ID

Reemplaza YOUR_PROJECT_ID por el ID de tu proyecto de Google Cloud.

# set Cloud Run region
gcloud config set run/region CLOUD-RUN-REGION

Reemplaza CLOUD-RUN-REGION por una de las regiones compatibles con Cloud Run.

Estas son las variables de entorno que se usarán en este codelab. Puedes guardarlas en un archivo de entorno y “obtener su código fuente”. Asegúrate de configurar correctamente el valor del ID del proyecto y, de manera opcional, la región.

# 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

Nota: Es útil guardar este fragmento como un archivo de secuencia de comandos y volver a usarlo en el futuro, en los casos en que se restablece la sesión de Cloud Shell. Guárdalo como env.sh y ejecuta source env.sh para configurar las variables de entorno cuando ejecutes los pasos posteriores. No confirmes env.sh en los sistemas de control de versiones.

Habilita las APIs necesarias para este codelab. Los cambios en la API pueden tardar entre 2 y 3 minutos en aplicarse.

gcloud services enable --project "${GOOGLE_CLOUD_PROJECT}" \
    run.googleapis.com \
    cloudbuild.googleapis.com \
    artifactregistry.googleapis.com \
    bigquery.googleapis.com \
    aiplatform.googleapis.com

3. Crea un agente de datos con el Kit de desarrollo de agentes

Escribe el código del agente

Desde la terminal de Cloud Shell o tu terminal local, crea un directorio raíz para tu app de agente:

mkdir data_agent

Abre el Editor de Cloud Shell o cualquier otro editor de texto y crea agent.py en el directorio 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]
)

El ADK también requiere __init__.py y requirements.txt para la implementación:

• __init__.py debe tener una importación para el agente.
• requirements.txt enumera las dependencias de Python: google-adk para el Kit de desarrollo de agentes y mcp para el cliente del Protocolo de contexto del modelo.

Estos comandos te ayudan a crear __init__.py y requirements.txt:

echo "from . import agent" > data_agent/__init__.py
echo -e "google-adk==2.4.*\nmcp==1.29.*" > data_agent/requirements.txt

La estructura de carpetas final debería verse así:

data_agent/
    __init__.py
    agent.py
    requirements.txt

Prueba el agente de forma local

El Kit de desarrollo de agentes incluye la herramienta de CLI adk, una interfaz de terminal interactiva para probar tus agentes. Esto es útil para pruebas rápidas, interacciones con secuencias de comandos y canalizaciones de CI/CD. Una de las funciones que proporciona es adk web (interfaz web del ADK), una forma sencilla de desarrollar y depurar tus agentes de forma interactiva. La Web del ADK no está diseñada para usarse en implementaciones de producción, pero facilita la prueba del agente.

Nota: Antes de ejecutar este comando, asegúrate de que tu directorio actual tenga el directorio data_agent (con el comando ls).

Este comando inicia adk web, que inicia un servidor web local en el puerto 8080.

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

Una vez que se inicia el servicio, abre la página web local del ADK: http://localhost:8080/.

Si usas Google Cloud Shell, haz clic en el botón Vista previa en la Web y selecciona el elemento de menú “Vista previa en el puerto 8080”.

En la IU web del ADK, pregúntale al agente sobre los datos a los que tiene acceso:

What data do you have?

El agente usará las herramientas de MCP de BigQuery para explorar el conjunto de datos de citibike. Te dará una descripción general de las tablas y los campos disponibles en el conjunto de datos de Citibike.

4. Implementa el agente en Cloud Run

Este comando implementará el agente en Cloud Run con la CLI del 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}"

Prueba el agente

Usamos la opción --with_ui para la implementación de nuestro agente. Implementó el agente con la interfaz web del ADK.

1. Abre la URL del agente en el navegador web. El comando adk deploy la mostró, y también puedes recuperarla ejecutando el comando gcloud run services:

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

2. Pídele al agente que razone sobre los datos de Citibike disponibles:

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

El agente debe explorar el conjunto de datos de Citibike con el servidor de MCP de BigQuery, ejecutar algunas consultas de SQL y mostrar una lista de 3 estaciones de citibike.

5. ¡Felicitaciones!

Felicitaciones por completar el codelab.

Te recomendamos que revises la documentación de Cloud Run.

Temas abordados

• Cómo crear un agente de IA con el Kit de desarrollo de agentes y Gemini
• Cómo conectar el agente al servidor de MCP de BigQuery
• Cómo implementar el agente en Cloud Run

6. Limpia

Para evitar que se apliquen cargos a tu cuenta de Google Cloud por los recursos usados en este instructivo, borra el proyecto que contiene los recursos o borra los recursos individuales.

Opción 1: Borra el servicio

Borra el servicio de Cloud Run

gcloud run services delete bq-data-agent \
      --project "${GOOGLE_CLOUD_PROJECT}" \
      --region "${GOOGLE_CLOUD_REGION}" \
      --quiet

Opción 2: Borra el proyecto

Para borrar todo el proyecto, ve a Administrar recursos, selecciona el proyecto que creaste en el paso 2 y elige Borrar. Si borras el proyecto, deberás cambiar los proyectos en tu SDK de Cloud. Puedes ver la lista de todos los proyectos disponibles ejecutando gcloud projects list. Si deseas usar la línea de comandos, también puedes usar este comando:

gcloud projects delete ${GOOGLE_CLOUD_PROJECT}