1. Pengantar
Dalam codelab ini, Anda akan membuat agen perencanaan perjalanan menggunakan Agent Development Kit (ADK) dan membumikannya dengan Google Maps. Anda akan meminta agen untuk membuat rekomendasi rute indah dan restoran, dengan memanfaatkan data dunia nyata dari Google Maps.
Yang akan Anda lakukan
- Menginisialisasi project agen menggunakan Paket Pemula Agen
- Mengonfigurasi agen untuk menggunakan alat Grounding Google Maps
- Menguji agen yang dihasilkan secara lokal dengan antarmuka web
Yang akan Anda butuhkan
- Browser web seperti Chrome
- Project Google Cloud yang mengaktifkan penagihan
Codelab ini ditujukan untuk developer tingkat menengah, yang memiliki pengetahuan tentang Python dan Google Cloud, tetapi tidak harus ahli.
2. Sebelum memulai
Membuat 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 diaktifkan di 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 Paket Pemula Agen
Cara termudah untuk memulai project ADK adalah dengan Paket Pemula Agen. Paket Pemula Agen Google Cloud adalah alat antarmuka command line (CLI) open source yang dirancang untuk mempercepat pengembangan dan deployment agen AI Generatif siap produksi di Google Cloud.
- Pastikan
uvterinstal, lalu jalankan perintah buat untuk menginisialisasi project agen baru:
uvx agent-starter-pack create
- Saat diminta, berikan opsi berikut untuk mengonfigurasi project Anda untuk pengembangan lokal dengan frontend React:
- Template Agen:
adk(Agen React Sederhana) - Deployment:
none(Deployment Cloud 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 Grounding
Paket Pemula Agen menghasilkan file GEMINI.md yang menginstruksikan alat coding yang dibantu AI tentang cara mengelola project Anda. Kami akan memperbarui file ini untuk menyertakan dokumentasi Grounding 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 grounding.
5. Memperbarui Agen
Sekarang kita akan mengonfigurasi agen untuk bertindak sebagai perencana perjalanan, lengkap dengan alat Grounding 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 terbaru tentang tempat dan rute.
Untuk melihat semua model yang tersedia, lihat dokumentasi Vertex AI.
6. Menjalankan Agen
Dengan logika agen Anda, 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 disediakan di output terminal di browser Anda.
- Uji agen dengan mengajukan pertanyaan. Contoh:
- "Buat rencana perjalanan 1 hari di San Francisco yang mencakup restoran Italia yang bagus."
- "Saya akan mengunjungi Tokyo, dapatkah Anda memberi saya rencana perjalanan dengan landmark bersejarah yang menarik dan tempat ramen dengan rating tinggi dan suasana yang nyaman?"
Anda akan melihat output yang mirip dengan rencana perjalanan mendetail yang diperkaya dengan ulasan dan deskripsi rute sebenarnya yang diambil langsung dari Google Maps.
7. Memverifikasi Grounding dalam Kode
Untuk mengonfirmasi secara terprogram bahwa agen Anda berhasil menggunakan grounding 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 melalui 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 grounding terjadi, Anda mungkin ingin mengekstrak data tertentu seperti jalur rute. Saat alat grounding Maps menampilkan informasi rute, alat ini sering kali menyertakan "Polyline yang Dienkodekan" 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 ke akun Google Cloud Anda, hapus resource yang dibuat selama codelab ini.
- Jika Anda membuat project khusus untuk codelab ini, hapus sepenuhnya:
gcloud projects delete $PROJECT_ID
Jika Anda menggunakan project yang ada dan ingin mempertahankannya, Anda tidak memiliki resource tertentu untuk dihapus, karena Agen berjalan secara lokal dan API yang digunakan bersifat tanpa server.
10. Selamat
Selamat! Anda telah berhasil membuat agen perencana perjalanan dan membumikannya menggunakan insight Google Maps.
Yang telah Anda pelajari
- Cara membuat kerangka agen baru menggunakan Paket Pemula Agen
- Cara menambahkan alat grounding ke definisi Agen ADK
- Cara menguji agen ADK menggunakan runner web bawaan
Langkah berikutnya
- Pelajari Alat ADK dan pola integrasi lainnya