Cómo crear un agente de planificación de itinerarios con el ADK y la fundamentación de Google Maps

1. Introducción

En este codelab, compilarás un agente de planificación de viajes con el Kit de desarrollo de agentes (ADK) y lo fundamentarás con Google Maps. Le pedirás al agente que genere rutas panorámicas y recomendaciones de restaurantes, aprovechando los datos del mundo real de Google Maps.

Actividades

• Inicializa un proyecto de agente con el paquete de inicio de agente
• Configura el agente para que use la herramienta Google Maps Grounding
• Prueba el agente resultante de forma local con una interfaz web

Requisitos

• Un navegador web, como Chrome
• Un proyecto de Google Cloud con la facturación habilitada.

Este codelab está dirigido a desarrolladores intermedios que tienen cierta familiaridad con Python y Google Cloud, pero que no necesariamente son expertos.

2. Antes de comenzar

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.

Inicie Cloud Shell

1. Verifica la autenticación:

gcloud auth list

2. Confirma tu proyecto:

gcloud config get project

3. Establécela si es necesario:

export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID

Habilita las APIs

Ejecuta este comando para habilitar todas las APIs requeridas:

gcloud services enable \
  aiplatform.googleapis.com

3. Instala el paquete de inicio del agente

La forma más fácil de comenzar un proyecto del ADK es con el paquete de inicio de agente. El paquete de inicio de Google Cloud Agent es una herramienta de interfaz de línea de comandos (CLI) de código abierto diseñada para acelerar el desarrollo y la implementación de agentes de IA generativa listos para la producción en Google Cloud.

1. Asegúrate de que uv esté instalado y, luego, ejecuta el comando create para inicializar un proyecto de agente nuevo:

uvx agent-starter-pack create

Si no tienes instalado uv, puedes usar pip:

# Create and activate a Python virtual environment
python -m venv .venv && source .venv/bin/activate

# Install the agent starter pack
pip install --upgrade agent-starter-pack

# Create a new agent project
agent-starter-pack create

Consulta el repositorio de agent-starter-pack para obtener más detalles.

2. Cuando se te solicite, proporciona las siguientes opciones para configurar tu proyecto para el desarrollo local con un frontend de React:

• Agent Template: adk (Simple React Agent)
• Deployment: none (Cloud Deployment inhabilitado por el momento)
• Región: us-central1

Esto generará una estructura de directorio del proyecto que contendrá la lógica principal del agente, las pruebas y una guía de GEMINI.md. Navega a tu directorio nuevo:

cd my-agent

4. Configura la fundamentación

El paquete de inicio de agente genera un archivo GEMINI.md que les indica a las herramientas de codificación asistida por IA cómo administrar tu proyecto. Actualizaremos esta información para incluir la documentación de Grounding de Google Maps.

1. Abre GEMINI.md en tu editor.
2. Agrega el siguiente vínculo de referencia en la sección ## Reference Documentation:

- **Google Maps Grounding**: https://docs.cloud.google.com/vertex-ai/generative-ai/docs/grounding/grounding-with-google-maps

Este contexto ayudará a cualquier asistente de programación con IA a comprender la función de fundamentación.

5. Actualiza el agente

Ahora configuraremos el agente para que actúe como un planificador de itinerarios, con la herramienta de fundamentación de Google Maps.

1. Abre el archivo app/agent.py.
2. Reemplaza todo el contenido de app/agent.py por el siguiente código:

"""Agent application for the itinerary planner codelab."""

import os
import google.auth
from google.adk.agents import Agent
from google.adk.apps import App
from google.adk.models import Gemini
from google.adk.tools import google_maps_grounding
from google.genai import types

# Authenticate and set environment variables
_, project_id = google.auth.default()
os.environ["GOOGLE_CLOUD_PROJECT"] = project_id
os.environ["GOOGLE_CLOUD_LOCATION"] = "global"
os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "True"

# Define the root agent
root_agent = Agent(
    name="itinerary_planner_agent",
    model=Gemini(
        model="gemini-2.5-flash",
        retry_options=types.HttpRetryOptions(attempts=3),
    ),
    instruction=(
        "You are an itinerary planner agent. Help users plan their trips by"
        " recommending restaurants and scenic routes. Use the"
        " google_maps_grounding tool to get both restaurant recommendations and"
        " route recommendations based on user preferences. When calling for"
        " restaurant recommendation, prompt the tool to tell you about the vibe"
        " of the place. When calling for routes with multiple legs, describe"
        " each of those legs with a brief sentence. Always describe the key"
        " landmarks along the route in one brief sentence."
    ),
    # Add the Google Maps Grounding tool to the agent
    tools=[google_maps_grounding],
)

app = App(
    root_agent=root_agent,
    name="app",
)

Este código configura un agente basado en gemini-2.5-flash que usa la herramienta google_maps_grounding para recuperar información actual sobre lugares y rutas.

Para ver todos los modelos disponibles, consulta la documentación de Vertex AI.

6. Ejecuta el agente

Con la lógica del agente implementada, intenta probarla en tu interfaz web local.

1. Desde la raíz de tu directorio my-agent, ejecuta el siguiente comando para iniciar la app web:

uv run adk web

O bien, si usas un entorno virtual:

adk web

2. Abre la URL que se proporciona en el resultado de la terminal en tu navegador.
3. Prueba el agente haciéndole una pregunta. Por ejemplo:

• "Planifica un itinerario de 1 día en San Francisco que incluya un buen restaurante italiano".
• "Voy a visitar Tokio. ¿Me puedes dar un itinerario con puntos de referencia históricos interesantes y un lugar de ramen muy bien calificado con un ambiente agradable?".

Deberías ver un resultado similar a un itinerario detallado enriquecido con opiniones reales y descripciones de rutas extraídas directamente de Google Maps.

7. Verifica la fundamentación en el código

Para confirmar de forma programática que tu agente usa correctamente la fundamentación de Maps, puedes inspeccionar los eventos de respuesta para ver los metadatos específicos de Maps.

Cuando ejecutas tu agente (por ejemplo, en una secuencia de comandos de prueba), este genera eventos que contienen grounding_metadata. Puedes iterar el grounding_chunks dentro de estos metadatos y verificar el atributo maps.

A continuación, se muestra un ejemplo que demuestra cómo verificar el atributo maps, similar a lo que podrías usar en una prueba automatizada:

async for event in runner.run_async(
    user_id="test_user",
    session_id=session.id,
    new_message=content,
):
    if event.grounding_metadata:
        if event.grounding_metadata.grounding_chunks:
            for chunk in event.grounding_metadata.grounding_chunks:
                # Check for the maps attribute to confirm maps grounding
                if hasattr(chunk, "maps") and chunk.maps:
                    print("SUCCESS: Maps grounding chunks detected in the response!")

8. Cómo extraer polilíneas codificadas

Además de verificar que se haya producido la fundamentación, es posible que desees extraer datos específicos, como las rutas. Cuando la herramienta de fundamentación de Maps devuelve información de la ruta, a menudo incluye una "polilínea codificada" que se puede usar para renderizar la ruta en el frontend de un mapa.

Puedes encontrar esta polilínea verificando el texto dentro del atributo maps del grounding_chunks. Este es un ejemplo de cómo puedes detectarlo:

async for event in runner.run_async(
    user_id="test_user",
    session_id=session.id,
    new_message=content,
):
    if event.grounding_metadata:
        if event.grounding_metadata.grounding_chunks:
            for chunk in event.grounding_metadata.grounding_chunks:
                # Extract the encoded polyline from the maps chunk text
                if (
                    hasattr(chunk, "maps")
                    and chunk.maps
                    and hasattr(chunk.maps, "text")
                    and chunk.maps.text
                    and "Encoded Polyline" in chunk.maps.text
                ):
                    print("SUCCESS: Encoded Polyline detected in the response!")

9. Limpia

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

1. Si creaste un proyecto dedicado para este codelab, bórralo por completo:

gcloud projects delete $PROJECT_ID

Si usaste un proyecto existente y quieres conservarlo, no tienes recursos específicos para borrar, ya que el agente se ejecutó de forma local y las APIs que se usaron no tienen servidor.

10. Felicitaciones

¡Felicitaciones! Creaste correctamente un agente de planificación de itinerarios y lo fundamentaste con estadísticas de Google Maps.

Qué aprendiste

• Cómo crear un nuevo agente con el paquete de inicio de agente
• Cómo agregar herramientas de fundamentación a la definición de un agente del ADK
• Cómo probar un agente del ADK con el ejecutor web integrado

Próximos pasos

• Explora otras herramientas del ADK y patrones de integración

Documentos de referencia

• Documentación del ADK
• Fundamentación de Google Maps