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, creará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

  • Inicializar un proyecto de agente con el paquete de inicio de agente
  • Configurar el agente para que use la herramienta Fundamentación con Google Maps
  • Probar 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á destinado a desarrolladores de nivel intermedio que tengan cierta familiaridad con Python y Google Cloud, pero que no sean necesariamente expertos.

2. Antes de comenzar

Cómo crear un proyecto de Google Cloud

  1. En la consola de Google Cloud, en la página del selector de proyectos, 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. Verificar la autenticación
gcloud auth list
  1. Confirma tu proyecto:
gcloud config get project
  1. Configúralo 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 de agente

La forma más fácil de comenzar un proyecto de ADK es con el paquete de inicio de agente. El paquete de inicio de agente de Google Cloud 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 nuevo proyecto de agente:
uvx agent-starter-pack create
  1. Cuando se te solicite, proporciona las siguientes opciones para configurar tu proyecto para el desarrollo local con un frontend de React:
  • Plantilla de agente: adk (agente simple de React)
  • Implementación: none (implementación en la nube inhabilitada por el momento)
  • Región: us-central1

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

cd my-agent

4. Configura la fundamentación

El paquete de inicio de agente genera un archivo GEMINI.md que indica a las herramientas de codificación asistida por IA cómo administrar tu proyecto. Actualizaremos este archivo para incluir la documentación de Fundamentación con 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 codificación de 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 Fundamentación con Google Maps.

  1. Abre el archivo app/agent.py.
  2. Reemplaza todo el contenido de app/agent.py con 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 en su lugar, intenta probarla en tu interfaz web local.

  1. Desde la raíz del 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
  1. Abre la URL que se proporciona en el resultado de la terminal en tu navegador.
  2. Prueba el agente haciéndole una pregunta. Por ejemplo:
  • "Planifica un itinerario de un día en San Francisco que incluya un buen restaurante italiano".
  • "Voy a visitar Tokio. ¿Puedes darme un itinerario con lugares históricos interesantes y un lugar de ramen muy bien calificado con un ambiente acogedor?".

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

Ejemplo de salida del itinerario del agente

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

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

Cuando ejecutas tu agente (por ejemplo, en una secuencia de comandos de prueba), el agente genera eventos que contienen grounding_metadata. Puedes iterar a través de los 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. Extrae polilíneas codificadas

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

Puedes encontrar esta polilínea verificando el texto dentro del atributo maps de grounding_chunks. A continuación, se muestra un ejemplo de cómo puedes detectarla:

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 cargos continuos en tu cuenta de Google Cloud, borra los recursos creados 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 servidores.

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 una definición de agente de ADK
  • Cómo probar un agente de ADK con el ejecutor web integrado

Próximos pasos

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

Documentos de referencia