1. Pengantar
Dalam codelab ini, Anda akan membuat agen perencanaan perjalanan menggunakan Agent Development Kit (ADK) dan memadukannya dengan Google Maps. Anda akan meminta agen untuk membuat rute indah dan rekomendasi restoran, dengan memanfaatkan data dunia nyata dari Google Maps.
Yang akan Anda lakukan
- Menginisialisasi project agen menggunakan Agent Starter Pack
- Mengonfigurasi agen untuk menggunakan alat Perujukan Google Maps
- Uji agen yang dihasilkan secara lokal dengan antarmuka web
Yang Anda butuhkan
- Browser web seperti Chrome
- Project Google Cloud yang mengaktifkan penagihan
Codelab ini ditujukan untuk developer tingkat menengah, yang sudah cukup familier dengan Python dan Google Cloud, tetapi tidak harus menjadi pakar.
2. Sebelum memulai
Buat Project Google Cloud
- Di Konsol Google Cloud, di halaman pemilih project, pilih atau buat project Google Cloud.
- Pastikan penagihan diaktifkan untuk project Cloud Anda. Pelajari cara memeriksa apakah penagihan telah diaktifkan pada suatu project.
Mulai Cloud Shell
- Verifikasi autentikasi:
gcloud auth list
- Konfirmasi project Anda:
gcloud config get project
- Tetapkan jika perlu:
export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID
Mengaktifkan API
Jalankan perintah ini untuk mengaktifkan semua API yang diperlukan:
gcloud services enable \
aiplatform.googleapis.com
3. Menginstal Agent Starter Pack
Cara termudah untuk memulai project ADK adalah dengan Referensi Dasar Agen. Google Cloud Agent Starter Pack adalah alat antarmuka command line (CLI) open source yang dirancang untuk mempercepat pengembangan dan deployment agen AI Generatif yang siap produksi di Google Cloud.
- Pastikan
uvsudah diinstal, lalu jalankan perintah create untuk melakukan inisialisasi project agen baru:
uvx agent-starter-pack create
- Jika diminta, berikan opsi berikut untuk mengonfigurasi project Anda untuk pengembangan lokal dengan frontend React:
- Template Agen:
adk(Agen React Sederhana) - Deployment:
none(Cloud Deployment dinonaktifkan untuk saat ini) - Region:
us-central1
Tindakan ini akan menghasilkan struktur direktori project yang berisi logika agen utama, pengujian, dan panduan GEMINI.md. Buka direktori baru Anda:
cd my-agent
4. Mengonfigurasi Perujukan
Paket Pemula Agen membuat file GEMINI.md yang menginstruksikan alat coding yang dibantu AI tentang cara mengelola project Anda. Kami akan memperbarui bagian ini untuk menyertakan dokumentasi Perujukan Google Maps.
- Buka
GEMINI.mddi editor Anda. - Tambahkan link referensi berikut di bagian
## Reference Documentation:
- **Google Maps Grounding**: https://docs.cloud.google.com/vertex-ai/generative-ai/docs/grounding/grounding-with-google-maps
Konteks ini akan membantu asisten coding AI memahami fitur perujukan.
5. Memperbarui Agen
Sekarang kita akan mengonfigurasi agen untuk bertindak sebagai perencana perjalanan, lengkap dengan alat Perujukan Google Maps.
- Buka file
app/agent.py. - Ganti seluruh konten
app/agent.pydengan kode berikut:
"""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",
)
Kode ini mengonfigurasi agen berbasis gemini-2.5-flash yang menggunakan alat google_maps_grounding untuk mengambil informasi terkini tentang tempat dan rute.
Untuk melihat semua model yang tersedia, lihat dokumentasi Vertex AI.
6. Menjalankan Agen
Setelah logika agen Anda diterapkan, coba uji di antarmuka web lokal Anda.
- Dari root direktori
my-agent, jalankan perintah berikut untuk memulai aplikasi web:
uv run adk web
atau, jika menggunakan lingkungan virtual:
adk web
- Buka URL yang diberikan di output terminal di browser Anda.
- Uji agen dengan mengajukan pertanyaan. Contoh:
- "Buat rencana perjalanan 1 hari di San Francisco, termasuk restoran Italia yang enak."
- "Saya akan mengunjungi Tokyo, bisakah Anda memberi saya itinerari yang mencakup bangunan bersejarah yang menarik dan tempat ramen yang sangat direkomendasikan dengan suasana yang nyaman?"
Anda akan melihat output yang mirip dengan rencana perjalanan mendetail yang dilengkapi dengan ulasan asli dan deskripsi rute yang diambil langsung dari Google Maps.
7. Memverifikasi Perujukan dalam Kode
Untuk mengonfirmasi secara terprogram bahwa agen Anda berhasil menggunakan perujukan Maps, Anda dapat memeriksa peristiwa respons untuk metadata khusus Maps.
Saat Anda menjalankan agen (misalnya, dalam skrip pengujian), agen akan menghasilkan peristiwa yang berisi grounding_metadata. Anda dapat melakukan iterasi pada grounding_chunks dalam metadata ini dan memeriksa atribut maps.
Berikut adalah contoh yang menunjukkan cara memeriksa atribut maps, mirip dengan yang mungkin Anda gunakan dalam pengujian otomatis:
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. Mengekstrak Polyline yang Dienkodekan
Selain memverifikasi bahwa perujukan terjadi, Anda mungkin ingin mengekstrak data tertentu seperti jalur rute. Saat alat perujukan Maps menampilkan informasi rute, alat ini sering kali menyertakan "Encoded Polyline" yang dapat digunakan untuk merender rute di frontend peta.
Anda dapat menemukan polyline ini dengan memeriksa teks dalam atribut maps dari grounding_chunks. Berikut adalah contoh cara mendeteksinya:
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. Pembersihan
Untuk menghindari biaya berkelanjutan pada akun Google Cloud Anda, hapus resource yang dibuat selama codelab ini.
- Jika Anda membuat project khusus untuk codelab ini, hapus project tersebut sepenuhnya:
gcloud projects delete $PROJECT_ID
Jika Anda menggunakan project yang ada dan ingin mempertahankannya, Anda tidak perlu menghapus resource tertentu, karena Agen berjalan secara lokal dan API yang digunakan bersifat serverless.
10. Selamat
Selamat! Anda telah berhasil membuat agen perencana itinerari dan mematangkannya menggunakan insight Google Maps.
Yang telah Anda pelajari
- Cara membuat kerangka agen baru menggunakan Agent Starter Pack
- Cara menambahkan alat perujukan ke definisi Agen ADK
- Cara menguji agen ADK menggunakan runner web bawaan
Langkah berikutnya
- Menjelajahi Alat ADK dan pola integrasi lainnya