Crea un agente di pianificazione dell'itinerario con ADK e il grounding di Google Maps

1. Introduzione

In questo codelab, creerai un agente di pianificazione di viaggi utilizzando Agent Development Kit (ADK) e lo baserai su Google Maps. Chiederai all'agente di generare itinerari panoramici e consigli di ristoranti, sfruttando i dati reali di Google Maps.

In questo lab proverai a:

• Inizializza un progetto di agente utilizzando lo Starter pack dell'agente
• Configura l'agente per utilizzare lo strumento Grounding di Google Maps
• Testa l'agente risultante localmente con un'interfaccia web

Che cosa ti serve

• Un browser web come Chrome
• Un progetto cloud Google Cloud con la fatturazione abilitata

Questo codelab è destinato a sviluppatori di livello intermedio che hanno una certa familiarità con Python e Google Cloud, ma non sono necessariamente esperti.

2. Prima di iniziare

Crea un progetto Google Cloud

1. Nella console Google Cloud, nella pagina di selezione del progetto, seleziona o crea un progetto Google Cloud.
2. Verifica che la fatturazione sia attivata per il tuo progetto Cloud. Scopri come verificare se la fatturazione è abilitata per un progetto.

Avvia Cloud Shell

1. Verifica l'autenticazione:

gcloud auth list

2. Conferma il progetto:

gcloud config get project

3. Impostalo se necessario:

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

Abilita API

Esegui questo comando per abilitare tutte le API richieste:

gcloud services enable \
  aiplatform.googleapis.com

3. Installare lo starter pack dell'agente

Il modo più semplice per iniziare un progetto ADK è utilizzare lo starter pack dell'agente. Google Cloud Agent Starter Pack è uno strumento open source dell'interfaccia a riga di comando (CLI) progettato per accelerare lo sviluppo e il deployment di agenti di AI generativa pronti per la produzione su Google Cloud.

1. Assicurati che uv sia installato, quindi esegui il comando create per inizializzare un nuovo progetto di agente:

uvx agent-starter-pack create

Se non hai installato uv, puoi utilizzare 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

Per ulteriori dettagli, consulta il repository agent-starter-pack.

2. Quando ti viene richiesto, fornisci le seguenti opzioni per configurare il progetto per lo sviluppo locale con un frontend React:

• Modello di agente: adk (agente React semplice)
• Deployment: none (Cloud Deployment è disattivato per il momento)
• Regione: us-central1

Verrà generata una struttura di directory del progetto contenente la logica principale dell'agente, i test e una guida GEMINI.md. Vai alla nuova directory:

cd my-agent

4. Configurare il grounding

Lo starter pack dell'agente genera un file GEMINI.md che indica agli strumenti di programmazione assistita dall'AI come gestire il progetto. Aggiorneremo questa pagina per includere la documentazione relativa alla messa a terra di Google Maps.

1. Apri GEMINI.md nell'editor.
2. Aggiungi il seguente link di riferimento nella sezione ## Reference Documentation:

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

Questo contesto aiuterà gli assistenti di programmazione AI a comprendere la funzionalità di grounding.

5. Aggiorna l'agente

Ora configureremo l'agente in modo che funga da pianificatore di itinerari, completo dello strumento di grounding di Google Maps.

1. Apri il file app/agent.py.
2. Sostituisci l'intero contenuto di app/agent.py con il seguente codice:

"""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",
)

Questo codice configura un agente basato su gemini-2.5-flash che utilizza lo strumento google_maps_grounding per recuperare informazioni aggiornate su luoghi e percorsi.

Per visualizzare tutti i modelli disponibili, consulta la documentazione di Vertex AI.

6. Esegui l'agente

Con la logica dell'agente in posizione, prova a testarla nell'interfaccia web locale.

1. Dalla radice della directory my-agent, esegui questo comando per avviare l'app web:

uv run adk web

oppure, se utilizzi un ambiente virtuale:

adk web

2. Apri l'URL fornito nell'output del terminale nel browser.
3. Prova l'agente ponendogli una domanda. Ad esempio:

• "Pianifica un itinerario di un giorno a San Francisco che includa un buon ristorante italiano."
• "Visiterò Tokyo. Puoi darmi un itinerario con punti di riferimento storici interessanti e un locale di ramen molto apprezzato con un'atmosfera accogliente?"

Dovresti visualizzare un output simile a un itinerario dettagliato arricchito da recensioni reali e descrizioni del percorso estratte direttamente da Google Maps.

7. Verifica della fondatezza nel codice

Per verificare a livello di programmazione che l'agente stia utilizzando correttamente la base di Maps, puoi esaminare gli eventi di risposta per i metadati specifici di Maps.

Quando esegui l'agente (ad esempio in uno script per il test), l'agente genera eventi che contengono grounding_metadata. Puoi scorrere l'array grounding_chunks all'interno di questi metadati e verificare la presenza dell'attributo maps.

Ecco un esempio che mostra come verificare la presenza dell'attributo maps, simile a quello che potresti utilizzare in un test automatizzato:

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. Estrai polilinee codificate

Oltre a verificare che sia stato eseguito il grounding, potresti voler estrarre dati specifici come i percorsi. Quando lo strumento di grounding di Maps restituisce informazioni sul percorso, spesso include una "polilinea codificata" che può essere utilizzata per visualizzare il percorso in un frontend della mappa.

Puoi trovare questa polilinea controllando il testo all'interno dell'attributo maps di grounding_chunks. Ecco un esempio di come rilevarlo:

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. Esegui la pulizia

Per evitare addebiti continui al tuo account Google Cloud, elimina le risorse create durante questo codelab.

1. Se hai creato un progetto dedicato per questo codelab, eliminalo completamente:

gcloud projects delete $PROJECT_ID

Se hai utilizzato un progetto esistente e vuoi conservarlo, non hai risorse specifiche da eliminare, poiché l'agente è stato eseguito localmente e le API utilizzate sono serverless.

10. Complimenti

Complimenti! Hai creato correttamente un agente di pianificazione dell'itinerario e lo hai basato sugli approfondimenti di Google Maps.

Cosa hai imparato

• Come creare la struttura di un nuovo agente utilizzando lo starter pack dell'agente
• Come aggiungere strumenti di grounding a una definizione dell'agente ADK
• Come testare un agente ADK utilizzando il runner web integrato

Passaggi successivi

• Esplora altri strumenti ADK e pattern di integrazione

Documenti di riferimento

• Documentazione ADK
• Grounding di Google Maps