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 Reiseplanungs-Agenten und fundieren ihn mit Google Maps. Sie fordern den Agenten auf, malerische Routen und Restaurantempfehlungen zu generieren, wobei er auf reale Daten aus Google Maps zurückgreift.

Aufgaben

  • Agentenprojekt mit dem Agent Starter Pack initialisieren
  • Agenten für die Verwendung des Tools Google Maps Grounding konfigurieren
  • Erstellten 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 keine Experten sein müssen.

2. Hinweis

Google Cloud-Projekt erstellen

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

Cloud Shell starten

  1. Authentifizierung überprüfen:
gcloud auth list
  1. Projekt bestätigen:
gcloud config get project
  1. Bei Bedarf festlegen:
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 Starter Pack installieren

Am einfachsten beginnen Sie ein ADK-Projekt mit dem Agent Starter Pack. Das Google Cloud Agent Starter Pack ist ein Open-Source-Befehlszeilentool (Command-Line Interface, CLI), mit dem die Entwicklung und Bereitstellung produktionsreifer generativer KI-Agenten in Google Cloud beschleunigt werden soll.

  1. Prüfen Sie, ob uv installiert ist, und führen Sie dann den Befehl „create“ aus, um ein neues Agentenprojekt zu initialisieren:
uvx agent-starter-pack create
  1. Geben Sie bei Aufforderung die folgenden Optionen an, um Ihr Projekt für die lokale Entwicklung mit einem React-Frontend zu konfigurieren:
  • Agent Template: adk (Simple React Agent)
  • Bereitstellung: none (Cloud-Bereitstellung ist vorerst deaktiviert)
  • Region: us-central1

Dadurch wird eine Projektverzeichnisstruktur mit der Hauptlogik des Agenten, Tests und einer GEMINI.md-Anleitung generiert. Wechseln Sie in das neue Verzeichnis:

cd my-agent

4. Fundierung konfigurieren

Das Agent Starter Pack generiert eine GEMINI.md-Datei, in der KI-gestützte Codierungstools angewiesen werden, wie sie Ihr Projekt verwalten sollen. Wir aktualisieren diese Datei, um die Dokumentation zur Google Maps-Fundierung einzufügen.

  1. Öffnen Sie GEMINI.md im 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 KI-Codierungsassistenten, die Fundierungsfunktion zu verstehen.

5. Agent aktualisieren

Jetzt konfigurieren wir den Agenten so, dass er als Reiseplaner fungiert, einschließlich des Tools „Google Maps Grounding“.

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

Dieser Code konfiguriert einen auf gemini-2.5-flash basierenden Agenten, der das Tool google_maps_grounding verwendet, um aktuelle Informationen zu Orten und Routen abzurufen.

Alle verfügbaren Modelle finden Sie in der Vertex AI-Dokumentation.

6. Agent ausführen

Nachdem Sie die Logik des Agenten eingerichtet haben, können Sie sie in der lokalen Weboberfläche testen.

  1. Führen Sie im Stammverzeichnis von my-agent den folgenden Befehl aus, um die Webanwendung zu starten:
uv run adk web

oder bei Verwendung einer virtuellen Umgebung:

adk web
  1. Öffnen Sie die in der Terminalausgabe angegebene URL in Ihrem Browser.
  2. Testen Sie den Agenten, indem Sie ihm eine Frage stellen. Beispiel:
  • „Plane eine eintägige Reise nach München mit einem guten italienischen Restaurant.“
  • „Ich besuche Tokio. Kannst du mir einen Reiseplan mit interessanten historischen Sehenswürdigkeiten und einem gut bewerteten Ramen-Lokal mit gemütlicher Atmosphäre erstellen?“

Sie sollten eine Ausgabe sehen, die einem detaillierten Reiseplan ähnelt, der mit echten Rezensionen und Routenbeschreibungen aus Google Maps angereichert ist.

Beispiel für die Ausgabe eines Agent-Reiseplans

7. Fundierung im Code überprüfen

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

Wenn Sie Ihren Agenten ausführen (z. B. in einer Testanleitung), 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, wie Sie nach dem Attribut maps suchen 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 prüfen, ob die Fundierung erfolgt ist, sondern auch bestimmte Daten wie Routenpfade extrahieren. Wenn das Tool „Maps Grounding“ Routeninformationen zurückgibt, enthält es oft eine „codierte Polylinie“, mit der die Route in einem Karten-Frontend gerendert werden kann.

Sie finden diese Polylinie, indem Sie den Text im Attribut maps der grounding_chunks prüfen. Hier ist ein Beispiel, wie Sie sie 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 Kosten für Ihr Google Cloud-Konto zu vermeiden.

  1. Wenn Sie für dieses Codelab ein eigenes Projekt erstellt haben, löschen Sie es vollständig:
gcloud projects delete $PROJECT_ID

Wenn Sie ein vorhandenes Projekt verwendet haben und es behalten 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

Das wars! Sie haben das Lab erfolgreich abgeschlossen. Sie haben einen Reiseplanungs-Agenten erstellt und ihn mit Google Maps-Informationen fundiert.

Was Sie gelernt haben

  • So erstellen Sie ein Gerüst für einen neuen Agenten mit dem Agent Starter Pack
  • So fügen Sie einer ADK-Agentendefinition Fundierungstools hinzu
  • So testen Sie einen ADK-Agenten mit dem integrierten Web-Runner

Nächste Schritte

  • Weitere ADK-Tools und Integrationsmuster kennenlernen

Referenzdokumente