Compila un agente del ADK de Inteligencia de ubicación con servidores de MCP para BigQuery y Google Maps

1. Introducción

En este codelab, compilarás un agente con el ADK potenciado por Gemini 3.0 Pro. El agente estará equipado con herramientas de dos servidores de MCP remotos (alojados en Google) para acceder de forma segura a BigQuery y obtener datos demográficos, de precios y de ventas, y a Google Maps para realizar análisis y validaciones de ubicaciones del mundo real.

El agente coordina las solicitudes entre el usuario y los servicios de Google Cloud para resolver problemas comerciales relacionados con el conjunto de datos de la panadería ficticia.

Actividades

Configura los datos: Crea el conjunto de datos fundamental de la panadería en BigQuery.
Desarrolla el agente: Crea un agente inteligente con el Kit de desarrollo de agentes (ADK).
Integrar herramientas: Equipa al agente con las funcionalidades de BigQuery y Maps a través del servidor de MCP.
Analiza el mercado: Interactúa con el agente para evaluar las tendencias y la saturación del mercado.

Requisitos

Un navegador web, como Chrome
Un proyecto de Google Cloud con la facturación habilitada o una cuenta de Gmail

Este codelab es para desarrolladores de todos los niveles, incluidos los principiantes. Usarás la interfaz de línea de comandos en Google Cloud Shell y código de Python para el desarrollo del ADK. No es necesario que seas un experto en Python, pero tener conocimientos básicos para leer código te ayudará a comprender los conceptos.

2. Antes de comenzar

Crea un proyecto de Google Cloud

En la página del selector de proyectos de la consola de Google Cloud, selecciona o crea un proyecto de Google Cloud.

Asegúrate de que la facturación esté habilitada para tu proyecto de Cloud. Obtén información sobre cómo verificar si la facturación está habilitada en un proyecto.

Inicia Cloud Shell

Cloud Shell es un entorno de línea de comandos que se ejecuta en Google Cloud y que viene precargado con las herramientas necesarias.

Haz clic en Activar Cloud Shell en la parte superior de la consola de Google Cloud:

Una vez que te conectes a Cloud Shell, ejecuta este comando para verificar tu autenticación en Cloud Shell:

gcloud auth list

Ejecuta el siguiente comando para confirmar que tu proyecto esté configurado para usar gcloud:

gcloud config get project

Confirma que el proyecto sea el esperado y, luego, ejecuta el siguiente comando para establecer el ID del proyecto:

export PROJECT_ID=$(gcloud config get project)

3. Obtener el código

Clona el repositorio

Clona el repositorio en tu entorno de Cloud Shell:

git clone https://github.com/google/mcp.git

Navega al directorio de la demostración:

cd mcp/examples/launchmybakery

Authenticate

Ejecuta el siguiente comando para autenticarte con tu cuenta de Google Cloud. Esto es necesario para que el ADK acceda a BigQuery.

gcloud auth application-default login

Sigue las instrucciones para completar el proceso de autenticación.

4. Configura el entorno y BigQuery

Ejecuta secuencias de comandos de configuración

Ejecuta la secuencia de comandos de configuración del entorno. Este script habilita las APIs de BigQuery y de Google Maps, y crea un archivo .env con tu ID del proyecto y la clave de la API de Maps.

chmod +x setup/setup_env.sh
./setup/setup_env.sh

Ejecuta la secuencia de comandos de configuración de BigQuery. Esta secuencia de comandos automatiza la creación del bucket de Cloud Storage, la carga de datos y el aprovisionamiento del conjunto de datos y las tablas de BigQuery.

chmod +x ./setup/setup_bigquery.sh
./setup/setup_bigquery.sh

Una vez que se complete la secuencia de comandos, se debería crear el conjunto de datos mcp_bakery y propagarse con las siguientes tablas:

Datos demográficos: Datos del censo y características de la población por código postal.
bakery_prices: Precios de la competencia y detalles de productos de varios productos horneados.
sales_history_weekly: Es el rendimiento de las ventas semanales (cantidad y revenue) por tienda y producto.
foot_traffic: Son las puntuaciones estimadas del tráfico presencial por código postal y hora del día.

Para verificar que se hayan creado el conjunto de datos y las tablas, visita la consola de BigQuery en tu proyecto de Google Cloud:

5. Instala el ADK.

Ahora que la infraestructura está lista, creemos un entorno virtual de Python y, luego, instalemos los paquetes necesarios para el ADK.

Crea un entorno virtual:

python3 -m venv .venv

Activa el entorno virtual:

source .venv/bin/activate

Instala el ADK:

pip install google-adk

Navega al directorio del agente:

cd adk_agent/

6. Inspecciona la aplicación del ADK

Haz clic en el botón Abrir editor en Cloud Shell para abrir el editor de Cloud Shell y ver el repositorio clonado en el directorio mcp/examples/launchmybakery.

El código del agente ya se proporciona en el directorio adk_agent/. Exploremos la estructura de la solución:

launchmybakery/
├── data/                        # Pre-generated CSV files for BigQuery
├── adk_agent/                   # AI Agent Application (ADK)
│   └── mcp_bakery_app/          # App directory
│       ├── agent.py             # Agent definition
│       ├── tools.py             # Custom tools for the agent
│       └── .env                 # Project configuration (created by setup script)
├── setup/                       # Infrastructure setup scripts
└── cleanup/                     # Infrastructure cleanup scripts

Archivos clave en mcp_bakery_app:

agent.py: Es la lógica principal que define el agente, sus herramientas y el modelo (versión preliminar de Gemini 3.0 Pro).
tools.py: Contiene cualquier definición de herramienta personalizada.
.env: Contiene la configuración y los secretos de tu proyecto (como las claves de API) creados por la secuencia de comandos de configuración.

1. Inicialización del conjunto de herramientas de MCP:

Ahora, abre adk_agent/mcp_bakery_app/tools.py en el Editor para comprender cómo se inicializan los conjuntos de herramientas de MCP.

Para permitir que nuestro agente se comunique con BigQuery y Google Maps, debemos configurar los clientes del Protocolo de contexto del modelo (MCP).

El código establece conexiones seguras con los servidores de MCP remotos de Google a través de StreamableHTTPConnectionParams.

def get_maps_mcp_toolset():
    dotenv.load_dotenv()
    maps_api_key = os.getenv('MAPS_API_KEY', 'no_api_found')
    
    tools = MCPToolset(
        connection_params=StreamableHTTPConnectionParams(
            url=MAPS_MCP_URL,
            headers={    
                "X-Goog-Api-Key": maps_api_key
            }
        )
    )
    print("MCP Toolset configured for Streamable HTTP connection.")
    return tools


def get_bigquery_mcp_toolset():   
        
    credentials, project_id = google.auth.default(
            scopes=["https://www.googleapis.com/auth/bigquery"]
    )

    credentials.refresh(google.auth.transport.requests.Request())
    oauth_token = credentials.token
        
    HEADERS_WITH_OAUTH = {
        "Authorization": f"Bearer {oauth_token}",
        "x-goog-user-project": project_id
    }

    tools = MCPToolset(
        connection_params=StreamableHTTPConnectionParams(
            url=BIGQUERY_MCP_URL,
            headers=HEADERS_WITH_OAUTH
        )
    )
    print("MCP Toolset configured for Streamable HTTP connection.")
    return tools

Maps Toolset: Configura la conexión al servidor de MCP de Maps con tu clave de API.
BigQuery Toolset: Esta función configura la conexión al servidor de MCP de BigQuery. Usa google.auth para recuperar automáticamente tus credenciales de Cloud, generar un token de portador de OAuth y, luego, insertarlo en el encabezado de autorización.

2. Definición del agente:

Ahora, abre adk_agent/mcp_bakery_app/agent.py en el Editor para ver cómo se define el agente.

El LlmAgent se inicializa con el modelo gemini-3-pro-preview.

maps_toolset = tools.get_maps_mcp_toolset()
bigquery_toolset = tools.get_bigquery_mcp_toolset()

root_agent = LlmAgent(
    model='gemini-3-pro-preview',
    name='root_agent',
    instruction=f"""
                Help the user answer questions by strategically combining insights from two sources:
                
                1.  **BigQuery toolset:** Access demographic (inc. foot traffic index), product pricing, and historical sales data in the  mcp_bakery dataset. Do not use any other dataset.
                Run all query jobs from project id: {project_id}. 

                2.  **Maps Toolset:** Use this for real-world location analysis, finding competition/places and calculating necessary travel routes.
                    Include a hyperlink to an interactive map in your response where appropriate.
            """,
    tools=[maps_toolset, bigquery_toolset]
)

Instrucciones del sistema: Se le dan instrucciones específicas al agente para que combine estadísticas de BigQuery (para los datos) y de Maps (para el análisis de ubicación).
Herramientas: Se asignan maps_toolset y bigquery_toolset al agente, lo que le da acceso a las capacidades de ambos servicios.

El agente cumple con las instrucciones y las herramientas definidas en el repo. Si quieres, puedes cambiar las instrucciones para ver cómo afectan el comportamiento del agente.

7. Chatea con tu agente.

Vuelve a la terminal de Cloud Shell y ejecuta este comando para navegar al directorio adk_agent:

cd adk_agent

Ejecuta el siguiente comando para iniciar la interfaz web del ADK. Este comando activa un servidor web liviano para alojar la aplicación de chat:

adk web

Una vez que se inicie el servidor, podrás chatear con tu agente haciendo clic en la URL proporcionada para iniciar la interfaz web del ADK.

Interactúa con el agente haciéndole las siguientes preguntas. Deberías ver que se llaman las herramientas pertinentes.

Encuentra el vecindario (macro): "Quiero abrir una panadería en Los Ángeles. Encuentra el código postal con la mayor puntuación de tráfico peatonal matutino".

El agente debe usar herramientas como get_table_info y execute_sql para consultar la tabla foot_traffic en BigQuery.

Valida la ubicación (micro): "¿Puedes buscar ‘Panaderías’ en ese código postal para ver si está saturado?".

El agente debe usar las herramientas search places del conjunto de herramientas de Maps para responder esta pregunta.

¡Pruébalo! Consulta estas preguntas de ejemplo para ver tu agente del ADK en acción:

"Quiero abrir mi cuarta panadería en Los Ángeles. Necesito un vecindario con actividad temprana. Encuentra el código postal con la puntuación más alta de tráfico peatonal matutino".
"¿Puedes buscar "Panaderías" en ese código postal para ver si está saturado? Si hay demasiadas, busca cafeterías especializadas para poder ubicarme cerca de ellas y captar el tráfico de peatones".
"De acuerdo, y quiero posicionarla como una marca premium. ¿Cuál es el precio máximo que se cobra por una hogaza de masa madre en el área metropolitana de Los Ángeles?"
"Ahora quiero una proyección de ingresos para diciembre de 2025. Consultar mi historial de ventas y tomar los datos de mi tienda con mejor rendimiento para el "pan de masa madre". Ejecuta una previsión para diciembre de 2025 y estima la cantidad que venderé. Luego, calcula los ingresos totales proyectados con un precio ligeramente inferior al precio premium que encontramos (usemos USD 18)."
"Con eso podré pagar el alquiler. Por último, verifiquemos la logística. Busca el "Restaurant Depot" más cercano al área propuesta y asegúrate de que el tiempo de viaje sea inferior a 30 minutos para el reabastecimiento diario".

8. Limpieza

Para evitar que se apliquen cargos a tu cuenta de Google Cloud, borra los recursos que creaste durante este codelab.

Ejecuta la secuencia de comandos de limpieza. Esta secuencia de comandos borrará el conjunto de datos de BigQuery, el bucket de Cloud Storage y las claves de API que se crearon durante la configuración.

chmod +x ../cleanup/cleanup_env.sh
./../cleanup/cleanup_env.sh

9. Felicitaciones

¡Misión cumplida! Creaste correctamente un agente de inteligencia de ubicación con el Kit de desarrollo de agentes (ADK).

Al cerrar la brecha entre los datos de tu "empresa" en BigQuery y el contexto de ubicación del mundo real de Google Maps, creaste una herramienta potente capaz de realizar razonamientos comerciales complejos, todo con la tecnología del Protocolo de contexto del modelo (MCP) y Gemini.

Qué lograste:

Infraestructura como código: Aprovisionaste una pila de datos con las herramientas de Google Cloud CLI.
Integración de MCP: Conectaste un agente de IA a dos servidores MCP remotos distintos (BigQuery y Maps) sin escribir wrappers de API complejos.
Razonamiento unificado: Creaste un solo agente capaz de combinar estratégicamente estadísticas de dos dominios diferentes para resolver un problema comercial.