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, crearás un agente con el ADK potenciado por Gemini 3.1 Pro. El agente estará equipado con herramientas de dos servidores MCP remotos (alojados por Google) para acceder de forma segura a BigQuery para obtener datos demográficos, de precios y de ventas, y a Google Maps para el análisis y la validación de ubicaciones del mundo real.

El agente organiza las solicitudes entre el usuario y los servicios de Google Cloud para resolver problemas empresariales relacionados con el conjunto de datos ficticio de panadería.

Actividades

• Configura los datos: Crea el conjunto de datos de panadería fundamental en BigQuery.
• Desarrolla el agente: Crea un agente inteligente con el Kit de desarrollo de agentes (ADK).
• Integra herramientas: Equipa al agente con las funcionalidades de BigQuery y Maps a través del servidor 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 está dirigido a desarrolladores de todos los niveles, incluidos principiantes. Usarás la interfaz de línea de comandos en Google Cloud Shell y el código de Python para el desarrollo del ADK. No es necesario que seas un experto en Python, pero tener conocimientos básicos sobre cómo leer código te ayudará a comprender los conceptos.

2. Antes de comenzar

Cómo crear 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 sobre cómo verificar si la facturación está habilitada en un proyecto.

Iniciar 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.

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

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

gcloud auth list

3. Ejecuta el siguiente comando para confirmar que tu proyecto esté configurado para usarse con gcloud:

gcloud config get project

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

export PROJECT_ID=$(gcloud config get project)

3. Obtener el código

Clonar el repositorio

1. Clona el repositorio en tu entorno de Cloud Shell:

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

2. Navega al directorio de demostración:

cd mcp/examples/launchmybakery

Autenticar

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 indicaciones para completar el proceso de autenticación.

Nota: El ADK no actualiza automáticamente tu token de OAuth 2.0. Si tu sesión de chat dura más de 60 minutos, es posible que debas volver a autenticarte con el comando anterior.

4. Configura el entorno y BigQuery

Ejecuta secuencias de comandos de configuración

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

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

2. 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 debe crear el conjunto de datos mcp_bakery y se debe propagar con las siguientes tablas:

• demographics: datos del censo y características de la población por código postal
• bakery_prices : precios de la competencia y detalles de los productos de varios productos horneados
• sales_history_weekly : rendimiento de ventas semanales (cantidad y ingresos) por tienda y producto
• foot_traffic : puntuaciones estimadas de tráfico peatonal por código postal y hora del día

3. 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.

1. Crea un entorno virtual:

python3 -m venv .venv

2. Activa el entorno virtual:

source .venv/bin/activate

3. Instala el ADK:

pip install google-adk==1.28.0

4. 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: La lógica central que define el agente, sus herramientas y el modelo (versión preliminar de Gemini 3.1 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 a los servidores MCP remotos de Google con 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

• Conjunto de herramientas de Maps: Configura la conexión al servidor MCP de Maps con tu clave de API.
• Conjunto de herramientas de BigQuery: Esta función configura la conexión al servidor MCP de BigQuery. Usa google.auth para recuperar automáticamente tus credenciales de Cloud, genera un token de portador de OAuth y lo inserta 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.1-pro-preview.

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

root_agent = LlmAgent(
    model='gemini-3.1-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 combinar estadísticas de BigQuery (para datos) y Maps (para análisis de ubicación).
• Herramientas: Tanto maps_toolset como bigquery_toolset se asignan 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 repositorio. No dudes en realizar cambios en las instrucciones para ver cómo afecta el comportamiento del agente.

7. Chatea con tu agente

Vuelve a la terminal en Cloud Shell y ejecuta este comando para navegar al directorio adk_agent (si aún no lo hiciste):

cd adk_agent/

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

adk web --allow_origins 'regex:https://.*\.cloudshell\.dev'

Una vez que se inicie el servidor, verás lo siguiente en Cloud Shell:

+-----------------------------------------------------------------------------+
| ADK Web Server started                                                      |
|                                                                             |
| For local testing, access at http://127.0.0.1:8000.                         |
+-----------------------------------------------------------------------------+

INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

Tienes dos opciones para acceder a la IU del ADK:

Opción 1: Haz clic en el vínculo local Haz clic en el vínculo http://127.0.0.1:8000 que aparece en tu terminal de Cloud Shell.

Opción 2: Usa la vista previa en la Web

1. Haz clic en el botón Vista previa en la Web en la esquina superior derecha de Cloud Shell.
2. Selecciona Cambiar puerto.
3. Ingresa 8000 como número de puerto y haz clic en Cambiar y obtener vista previa.

Interactúa con el agente haciendo las siguientes preguntas en la IU web. Deberías ver que se llaman las herramientas pertinentes.

1. Encuentra el vecindario (macro): "Quiero abrir una panadería en Los Ángeles. Encuentra el código postal con la puntuación más alta 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.

2. 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 en el conjunto de herramientas de Maps para responder esta pregunta.

¡Inténtalo! Consulta estas preguntas de muestra 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 tiendas de 'Café de especialidad' para poder posicionarme cerca de ellas y captar tráfico peatonal".
• "Bien, quiero posicionar esto como una marca premium. ¿Cuál es el precio máximo que se cobra por un 'Pan de masa madre' en el área metropolitana de Los Ángeles?".
• "Ahora quiero una proyección de ingresos para diciembre de 2025. Consulta mi historial de ventas y toma datos de mi tienda con mejor rendimiento para el 'Pan de masa madre'. Ejecuta una previsión para diciembre de 2025 para estimar la cantidad que venderé. Luego, calcula los ingresos totales proyectados con un precio premium inferior al que encontramos (usemos USD 18)".
• "Eso cubrirá mi alquiler. Por último, verifiquemos la logística. Encuentra 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".

Cuando termines de probar tu agente, puedes finalizar la interfaz web del ADK presionando Ctrl+C en tu terminal de Cloud Shell.

8. Limpieza

Para evitar cargos continuos en tu cuenta de Google Cloud, borra los recursos creados 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 creadas 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 tus datos "empresariales" en BigQuery y el contexto de ubicación del mundo real de Google Maps, creaste una herramienta potente capaz de realizar razonamientos empresariales 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 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 empresarial.

Documentos de referencia

• Usa el servidor MCP de BigQuery
• Usa el servidor MCP de Maps Groundling Lite
• Autentica el MCP