1. Wprowadzenie
W tym ćwiczeniu dowiesz się, jak utworzyć agenta do planowania podróży za pomocą pakietu Agent Development Kit (ADK) i powiązać go z Mapami Google. Poprosisz agenta o wygenerowanie malowniczych tras i rekomendacji restauracji, wykorzystując dane z Map Google.
Jakie zadania wykonasz
- Inicjowanie projektu agenta za pomocą pakietu startowego agenta
- Skonfiguruj agenta tak, aby korzystał z narzędzia Grounding w Mapach Google.
- Testowanie utworzonego agenta lokalnie za pomocą interfejsu internetowego
Czego potrzebujesz
- przeglądarka, np. Chrome;
- projekt Google Cloud z włączonymi płatnościami;
To ćwiczenie jest przeznaczone dla średnio zaawansowanych programistów, którzy znają Pythona i Google Cloud, ale nie są ekspertami w tych dziedzinach.
2. Zanim zaczniesz
Tworzenie projektu Google Cloud
- W konsoli Google Cloud na stronie selektora projektu wybierz lub utwórz projekt w chmurze Google.
- Sprawdź, czy w projekcie Cloud włączone są płatności. Dowiedz się, jak sprawdzić, czy w projekcie są włączone płatności.
Uruchamianie Cloud Shell
- Potwierdź uwierzytelnianie:
gcloud auth list
- Potwierdź projekt:
gcloud config get project
- W razie potrzeby ustaw:
export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID
Włącz interfejsy API
Aby włączyć wszystkie wymagane interfejsy API, uruchom to polecenie:
gcloud services enable \
aiplatform.googleapis.com
3. Instalowanie pakietu startowego agenta
Najłatwiej rozpocząć projekt ADK od pakietu startowego agenta. Google Cloud Agent Starter Pack to narzędzie wiersza poleceń (CLI) o otwartym kodzie źródłowym, które zostało zaprojektowane, aby przyspieszyć tworzenie i wdrażanie w Google Cloud agentów generatywnej AI gotowych do użycia w środowisku produkcyjnym.
- Sprawdź, czy pakiet
uvjest zainstalowany, a potem uruchom polecenie create, aby zainicjować nowy projekt agenta:
uvx agent-starter-pack create
- Gdy pojawi się odpowiedni komunikat, podaj te opcje, aby skonfigurować projekt na potrzeby lokalnego tworzenia aplikacji z interfejsem React:
- Szablon agenta:
adk(Simple React Agent) - Wdrożenie:
none(wdrażanie w chmurze jest obecnie wyłączone) - Region:
us-central1
Spowoduje to wygenerowanie struktury katalogu projektu zawierającej główną logikę agenta, testy i GEMINI.md przewodnik. Przejdź do nowego katalogu:
cd my-agent
4. Konfigurowanie umocowania
Pakiet startowy agenta generuje plik GEMINI.md, który zawiera instrukcje dla narzędzi do kodowania wspomaganego przez AI dotyczące zarządzania projektem. Zaktualizujemy tę stronę, aby uwzględnić dokumentację dotyczącą ugruntowania w Mapach Google.
- Otwórz plik
GEMINI.mdw edytorze. - Dodaj ten link do sekcji
## Reference Documentation:
- **Google Maps Grounding**: https://docs.cloud.google.com/vertex-ai/generative-ai/docs/grounding/grounding-with-google-maps
Ten kontekst pomoże asystentom kodowania opartym na AI zrozumieć funkcję podstawową.
5. Aktualizowanie agenta
Teraz skonfigurujemy agenta, aby działał jako narzędzie do planowania podróży, wraz z narzędziem Grounding w Mapach Google.
- Otwórz plik
app/agent.py. - Zastąp całą zawartość pliku
app/agent.pytym kodem:
"""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",
)
Ten kod konfiguruje agenta opartego na gemini-2.5-flash, który używa narzędzia google_maps_grounding do pobierania aktualnych informacji o miejscach i trasach.
Aby wyświetlić wszystkie dostępne modele, zapoznaj się z dokumentacją Vertex AI.
6. Uruchamianie agenta
Po zaimplementowaniu logiki agenta przetestuj ją w lokalnym interfejsie internetowym.
- W katalogu głównym
my-agenturuchom to polecenie, aby uruchomić aplikację internetową:
uv run adk web
lub jeśli używasz środowiska wirtualnego:
adk web
- Otwórz w przeglądarce adres URL podany w danych wyjściowych terminala.
- Przetestuj agenta, zadając mu pytanie. Na przykład:
- Zaplanuj 1-dniowy plan podróży po San Francisco, uwzględniając dobrą włoską restaurację.
- Jadę do Tokio. Możesz mi podać plan podróży z ciekawymi zabytkami i dobrze ocenianą restauracją ramen o przytulnym klimacie?
Powinny się wyświetlić wyniki podobne do szczegółowego planu podróży wzbogaconego o prawdziwe opinie i opisy tras pobrane bezpośrednio z Map Google.
7. Weryfikowanie uzasadnienia w kodzie
Aby programowo potwierdzić, że Twój agent korzysta z informacji z Map, możesz sprawdzić zdarzenia odpowiedzi pod kątem metadanych specyficznych dla Map.
Gdy uruchamiasz agenta (np. w scenariuszu testowania), generuje on zdarzenia zawierające grounding_metadata. Możesz iterować po grounding_chunks w tych metadanych i sprawdzać atrybut maps.
Oto przykład sprawdzania atrybutu maps, podobny do tego, który możesz wykorzystać w automatycznym teście:
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. Wyodrębnianie zakodowanych linii łamanych
Oprócz sprawdzenia, czy nastąpiło ugruntowanie, możesz chcieć wyodrębnić konkretne dane, takie jak ścieżki tras. Gdy narzędzie do ugruntowania Map zwraca informacje o trasie, często zawiera „Zakodowaną linię łamaną”, której można użyć do wyrenderowania trasy w interfejsie mapy.
Tę linię łamaną znajdziesz, sprawdzając tekst w atrybucie maps elementu grounding_chunks. Oto przykład, jak możesz to wykryć:
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. Czyszczenie danych
Aby uniknąć obciążenia konta Google Cloud bieżącymi opłatami, usuń zasoby utworzone podczas tego ćwiczenia.
- Jeśli na potrzeby tego laboratorium został przez Ciebie utworzony osobny projekt, usuń go w całości:
gcloud projects delete $PROJECT_ID
Jeśli użyto istniejącego projektu i chcesz go zachować, nie musisz usuwać żadnych zasobów, ponieważ agent działał lokalnie, a używane interfejsy API są bezserwerowe.
10. Gratulacje
Gratulacje! Udało Ci się utworzyć agenta do planowania podróży i powiązać go ze źródłem informacji za pomocą statystyk z Map Google.
Czego się dowiedziałeś(-aś)
- Jak utworzyć szkielet nowego agenta za pomocą pakietu startowego agenta
- Jak dodać narzędzia do ugruntowania do definicji agenta ADK
- Testowanie agenta ADK za pomocą wbudowanego narzędzia do uruchamiania w internecie
Dalsze kroki
- Poznaj inne narzędzia ADK i wzorce integracji