Einen Reiseplanungs-Agenten mit ADK und Google Maps-Fundierung erstellen

1. Einführung

In diesem Codelab erstellen Sie mit dem Agent Development Kit (ADK) einen Agenten zur Reiseplanung, der auf Google Maps basiert. Sie fordern den Agenten auf, malerische Routen und Restaurantempfehlungen zu generieren, wobei er Realdaten aus Google Maps nutzt.

Aufgaben

• Agent-Projekt mit dem Agent Starter Pack initialisieren
• Agent für die Verwendung des Tools Google Maps Grounding konfigurieren
• Den resultierenden Agenten lokal mit einer Weboberfläche testen

Voraussetzungen

• Ein Webbrowser wie Chrome
• Ein Google Cloud-Projekt mit aktivierter Abrechnung

Dieses Codelab richtet sich an Entwickler mit mittleren Kenntnissen, die mit Python und Google Cloud vertraut sind, aber nicht unbedingt Experten sein müssen.

2. Hinweis

Google Cloud-Projekt erstellen

1. Wählen Sie in der Google Cloud Console auf der Seite zur Projektauswahl ein Google Cloud-Projekt aus oder erstellen Sie eines.
2. Die Abrechnung für das Cloud-Projekt muss aktiviert sein. So prüfen Sie, ob die Abrechnung für ein Projekt aktiviert ist.

Cloud Shell starten

1. Authentifizierung überprüfen:

gcloud auth list

2. Bestätigen Sie Ihr Projekt:

gcloud config get project

3. Legen Sie sie bei Bedarf fest:

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

APIs aktivieren

Führen Sie diesen Befehl aus, um alle erforderlichen APIs zu aktivieren:

gcloud services enable \
  aiplatform.googleapis.com

3. Agent-Starterpaket installieren

Am einfachsten beginnen Sie ein ADK-Projekt mit dem Agent Starter Pack. Das Google Cloud Agent Starter Pack ist ein Open-Source-Befehlszeilentool (CLI), das die Entwicklung und Bereitstellung von produktionsreifen generativen KI-Agents in Google Cloud beschleunigen soll.

1. Prüfen Sie, ob uv installiert ist, und führen Sie dann den Befehl „create“ aus, um ein neues Agent-Projekt zu initialisieren:

uvx agent-starter-pack create

Wenn Sie uv nicht installiert haben, können Sie pip verwenden:

# 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

Weitere Informationen finden Sie im Repository für das Agent-Starter-Pack.

2. Geben Sie bei Aufforderung die folgenden Optionen an, um Ihr Projekt für die lokale Entwicklung mit einem React-Frontend zu konfigurieren:

• Agent Template (Agent-Vorlage): adk (Simple React Agent)
• Bereitstellung: none (Cloud-Bereitstellung vorerst deaktiviert)
• Region: us-central1

Dadurch wird eine Projektverzeichnisstruktur mit der Haupt-Agent-Logik, Tests und einer GEMINI.md-Anleitung generiert. Wechseln Sie in das neue Verzeichnis:

cd my-agent

4. Fundierung konfigurieren

Mit dem Starterpaket für KI-Agenten wird eine GEMINI.md-Datei generiert, in der KI-gestützte Codierungstools angewiesen werden, wie sie Ihr Projekt verwalten sollen. Wir werden diese Seite aktualisieren, um die Dokumentation zur Fundierung von Google Maps aufzunehmen.

1. Öffnen Sie GEMINI.md in einem Editor.
2. Fügen Sie unter dem Abschnitt ## Reference Documentation den folgenden Referenzlink hinzu:

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

Dieser Kontext hilft allen KI-basierten Programmierassistenten, die Funktion zum Fundieren zu verstehen.

5. Agent aktualisieren

Jetzt konfigurieren wir den Agenten so, dass er als Reiseplaner fungiert, komplett mit dem Google Maps-Grounding-Tool.

1. Öffnen Sie die Datei app/agent.py.
2. Ersetzen Sie den gesamten Inhalt von app/agent.py durch den folgenden Code:

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

Mit diesem Code wird ein gemini-2.5-flash-basierter Agent konfiguriert, der das Tool google_maps_grounding verwendet, um aktuelle Informationen zu Orten und Routen abzurufen.

Eine Liste aller verfügbaren Modelle finden Sie in der Vertex AI-Dokumentation.

6. Agent ausführen

Nachdem Sie die Logik Ihres Agents implementiert haben, können Sie sie in Ihrer lokalen Weboberfläche testen.

1. Führen Sie im Stammverzeichnis Ihres my-agent-Verzeichnisses den folgenden Befehl aus, um die Web-App zu starten:

uv run adk web

oder, wenn Sie eine virtuelle Umgebung verwenden:

adk web

2. Öffnen Sie die in der Terminalausgabe angegebene URL in Ihrem Browser.
3. Testen Sie den KI-Agenten, indem Sie ihm eine Frage stellen. Beispiel:

• „Plane einen Tagesausflug nach San Francisco mit einem guten italienischen Restaurant.“
• „Ich besuche Tokio. Kannst du mir eine Reiseroute mit interessanten historischen Sehenswürdigkeiten und einem gut bewerteten Ramen-Restaurant mit gemütlicher Atmosphäre zusammenstellen?“

Sie sollten eine Ausgabe sehen, die einer detaillierten Reiseroute ähnelt, die mit echten Rezensionen und Routenbeschreibungen angereichert ist, die direkt aus Google Maps stammen.

7. Fundierung im Code überprüfen

Wenn Sie programmatisch bestätigen möchten, dass Ihr Agent Maps-Grounding erfolgreich verwendet, können Sie die Antwort-Ereignisse auf Maps-spezifische Metadaten prüfen.

Wenn Sie den Agent ausführen (z. B. in einem Testskript), gibt er Ereignisse mit grounding_metadata aus. Sie können die grounding_chunks in diesen Metadaten durchlaufen und nach dem Attribut maps suchen.

Hier ist ein Beispiel dafür, wie Sie das Attribut maps prüfen können, ähnlich wie in einem automatisierten Test:

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. Codierte Polylinien extrahieren

Sie können nicht nur überprüfen, ob die Fundierung stattgefunden hat, sondern auch bestimmte Daten wie Routenpfade extrahieren. Wenn das Tool zur Fundierung von Google Maps Routeninformationen zurückgibt, enthält es häufig eine „Encoded Polyline“, mit der die Route in einem Karten-Frontend gerendert werden kann.

Sie finden diese Polylinie, indem Sie den Text im Attribut maps des grounding_chunks-Elements prüfen. Hier ist ein Beispiel dafür, wie Sie das erkennen können:

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

Löschen Sie die in diesem Codelab erstellten Ressourcen, um laufende Gebühren für Ihr Google Cloud-Konto zu vermeiden.

1. Wenn Sie für dieses Codelab ein dediziertes Projekt erstellt haben, löschen Sie es vollständig:

gcloud projects delete $PROJECT_ID

Wenn Sie ein vorhandenes Projekt verwendet haben und es beibehalten möchten, müssen Sie keine bestimmten Ressourcen löschen, da der Agent lokal ausgeführt wurde und die verwendeten APIs serverlos sind.

10. Glückwunsch

Glückwunsch! Sie haben erfolgreich einen Agent für die Reiseplanung erstellt und ihn mit Google Maps-Informationen verknüpft.

Das haben Sie gelernt

• Neuen Agenten mit dem Agent Starter Pack erstellen
• ADK-Agentendefinitionen Grounding-Tools hinzufügen
• ADK-Agenten mit dem integrierten Web-Runner testen

Nächste Schritte

• Weitere ADK-Tools und Integrationsmuster

Referenzdokumente

• ADK-Dokumentation
• Google Maps-Fundierung