1. บทนำ
ใน Codelab นี้ คุณจะได้สร้างเอเจนต์วางแผนการเดินทางโดยใช้ Agent Development Kit (ADK) และเชื่อมโยงกับ Google Maps คุณจะแจ้งให้เอเจนต์สร้างเส้นทางที่สวยงามและแนะนำร้านอาหาร โดยใช้ประโยชน์จากข้อมูลในโลกแห่งความเป็นจริงจาก Google Maps
สิ่งที่คุณต้องดำเนินการ
- เริ่มต้นโปรเจ็กต์เอเจนต์โดยใช้ Agent Starter Pack
- กำหนดค่า Agent ให้ใช้เครื่องมือการเชื่อมต่อแหล่งข้อมูลของ Google Maps
- ทดสอบเอเจนต์ที่ได้ในเครื่องด้วยอินเทอร์เฟซเว็บ
สิ่งที่คุณต้องมี
- เว็บเบราว์เซอร์ เช่น Chrome
- โปรเจ็กต์ Google Cloud ที่เปิดใช้การเรียกเก็บเงิน
Codelab นี้เหมาะสำหรับนักพัฒนาซอฟต์แวร์ระดับกลางที่มีความคุ้นเคยกับ Python และ Google Cloud บ้าง แต่ไม่จำเป็นต้องเป็นผู้เชี่ยวชาญ
2. ก่อนเริ่มต้น
สร้างโปรเจ็กต์ Google Cloud
- ในคอนโซล Google Cloud ในหน้าตัวเลือกโปรเจ็กต์ ให้เลือกหรือสร้างโปรเจ็กต์ Google Cloud
- ตรวจสอบว่าได้เปิดใช้การเรียกเก็บเงินสำหรับโปรเจ็กต์ที่อยู่ในระบบคลาวด์แล้ว ดูวิธีตรวจสอบว่าได้เปิดใช้การเรียกเก็บเงินในโปรเจ็กต์แล้วหรือไม่
เริ่มต้น Cloud Shell
- ยืนยันการตรวจสอบสิทธิ์
gcloud auth list
- ยืนยันโปรเจ็กต์
gcloud config get project
- ตั้งค่าหากจำเป็น
export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID
เปิดใช้ API
เรียกใช้คำสั่งนี้เพื่อเปิดใช้ API ที่จำเป็นทั้งหมด
gcloud services enable \
aiplatform.googleapis.com
3. ติดตั้ง Agent Starter Pack
วิธีที่ง่ายที่สุดในการเริ่มโปรเจ็กต์ ADK คือการใช้ Agent Starter Pack Google Cloud Agent Starter Pack เป็นเครื่องมืออินเทอร์เฟซบรรทัดคำสั่ง (CLI) แบบโอเพนซอร์สที่ออกแบบมาเพื่อเร่งการพัฒนาและการติดตั้งใช้งานเอเจนต์ Generative AI ที่พร้อมใช้งานจริงใน Google Cloud
- ตรวจสอบว่าได้ติดตั้ง
uvแล้ว จากนั้นเรียกใช้คำสั่งสร้างเพื่อเริ่มต้นโปรเจ็กต์ Agent ใหม่
uvx agent-starter-pack create
- เมื่อได้รับแจ้ง ให้ระบุตัวเลือกต่อไปนี้เพื่อกำหนดค่าโปรเจ็กต์สำหรับการพัฒนาในเครื่องด้วยฟรอนท์เอนด์ของ React
- เทมเพลต Agent:
adk(Simple React Agent) - การติดตั้งใช้งาน:
none(ปิดใช้การติดตั้งใช้งานในระบบคลาวด์ชั่วคราว) - ภูมิภาค:
us-central1
ซึ่งจะสร้างโครงสร้างไดเรกทอรีโปรเจ็กต์ที่มีตรรกะของเอเจนต์หลัก การทดสอบ และGEMINI.mdคำแนะนำ ไปที่ไดเรกทอรีใหม่โดยใช้คำสั่งต่อไปนี้
cd my-agent
4. กำหนดค่าการเชื่อมต่อแหล่งข้อมูล
Agent Starter Pack จะสร้างไฟล์ GEMINI.md ที่สั่งให้เครื่องมือเขียนโค้ดที่ทำงานด้วยระบบ AI ทราบวิธีจัดการโปรเจ็กต์ เราจะอัปเดตหน้านี้ให้มีเอกสารประกอบเกี่ยวกับ Grounding ของ Google Maps
- เปิด
GEMINI.mdในเครื่องมือแก้ไข - เพิ่มลิงก์อ้างอิงต่อไปนี้ในส่วน
## Reference Documentation
- **Google Maps Grounding**: https://docs.cloud.google.com/vertex-ai/generative-ai/docs/grounding/grounding-with-google-maps
บริบทนี้จะช่วยให้ผู้ช่วยการเขียนโค้ด AI เข้าใจฟีเจอร์การเชื่อมต่อแหล่งข้อมูล
5. อัปเดต Agent
ตอนนี้เราจะกำหนดค่าเอเจนต์ให้ทำหน้าที่เป็นเครื่องมือวางแผนการเดินทาง พร้อมด้วยเครื่องมือ Grounding ของ Google Maps
- เปิดไฟล์
app/agent.py - แทนที่เนื้อหาทั้งหมดของ
app/agent.pyด้วยโค้ดต่อไปนี้
"""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",
)
โค้ดนี้กำหนดค่า Agent ที่อิงตาม gemini-2.5-flash ซึ่งใช้เครื่องมือ google_maps_grounding เพื่อดึงข้อมูลปัจจุบันเกี่ยวกับ Places และ Routes
หากต้องการดูโมเดลทั้งหมดที่พร้อมใช้งาน โปรดดูเอกสารประกอบของ Vertex AI
6. เรียกใช้ Agent
เมื่อมีตรรกะของเอเจนต์แล้ว ให้ลองทดสอบในอินเทอร์เฟซเว็บในเครื่อง
- จากรูทของไดเรกทอรี
my-agentให้เรียกใช้คำสั่งต่อไปนี้เพื่อเริ่มเว็บแอป
uv run adk web
หรือหากใช้สภาพแวดล้อมเสมือน ให้ทำดังนี้
adk web
- เปิด URL ที่ระบุในเอาต์พุตของเทอร์มินัลในเบราว์เซอร์
- ทดสอบเอเจนต์โดยการถามคำถาม เช่น
- "วางแผนการเดินทาง 1 วันในซานฟรานซิสโกโดยมีร้านอาหารอิตาลีดีๆ ด้วย"
- ฉันจะไปเที่ยวโตเกียว คุณช่วยบอกแผนการเดินทางที่มีสถานที่สำคัญทางประวัติศาสตร์ที่น่าสนใจและร้านราเม็งที่ได้รับคะแนนสูงพร้อมบรรยากาศอบอุ่นหน่อยได้ไหม
คุณควรเห็นเอาต์พุตที่คล้ายกับแผนการเดินทางแบบละเอียดซึ่งเสริมด้วยรีวิวจริงและคำอธิบายเส้นทางที่ดึงมาจาก Google Maps โดยตรง
7. ยืนยันการเชื่อมต่อแหล่งข้อมูลในโค้ด
หากต้องการยืนยันแบบเป็นโปรแกรมว่า Agent ใช้การเชื่อมต่อแหล่งข้อมูลของ Maps ได้สำเร็จหรือไม่ คุณสามารถตรวจสอบเหตุการณ์การตอบกลับเพื่อดูข้อมูลเมตาที่เฉพาะเจาะจงของ Maps ได้
เมื่อเรียกใช้ Agent (เช่น ในสคริปต์การทดสอบ) Agent จะสร้างเหตุการณ์ที่มี grounding_metadata คุณสามารถวนซ้ำใน grounding_chunks ภายในข้อมูลเมตานี้และตรวจสอบแอตทริบิวต์ maps ได้
ตัวอย่างต่อไปนี้แสดงวิธีตรวจสอบแอตทริบิวต์ maps ซึ่งคล้ายกับสิ่งที่คุณอาจใช้ในการทดสอบอัตโนมัติ
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. ดึงข้อมูลโพลีไลน์ที่เข้ารหัส
นอกเหนือจากการยืนยันว่าเกิดการเชื่อมต่อแหล่งข้อมูลแล้ว คุณอาจต้องการดึงข้อมูลที่เฉพาะเจาะจง เช่น เส้นทาง เมื่อเครื่องมือการเชื่อมต่อแหล่งข้อมูลของ Maps แสดงข้อมูลเส้นทาง มักจะมี "Polyline ที่เข้ารหัส" ซึ่งใช้ในการแสดงเส้นทางในส่วนหน้าของแผนที่ได้
คุณดูเส้นหลายเหลี่ยมนี้ได้โดยตรวจสอบข้อความภายในแอตทริบิวต์ maps ของ grounding_chunks ตัวอย่างวิธีตรวจหาการโจมตีมีดังนี้
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. ล้างข้อมูล
โปรดลบทรัพยากรที่สร้างขึ้นระหว่างการทำ Codelab นี้เพื่อหลีกเลี่ยงการเรียกเก็บเงินอย่างต่อเนื่องในบัญชี Google Cloud
- หากคุณสร้างโปรเจ็กต์เฉพาะสำหรับ Codelab นี้ ให้ลบโปรเจ็กต์ดังกล่าวทั้งหมดโดยทำดังนี้
gcloud projects delete $PROJECT_ID
หากใช้โปรเจ็กต์ที่มีอยู่และต้องการเก็บไว้ คุณก็ไม่ต้องลบทรัพยากรใดๆ เนื่องจาก Agent ทำงานในเครื่องและ API ที่ใช้เป็นแบบ Serverless
10. ขอแสดงความยินดี
ยินดีด้วย คุณสร้างเอเจนต์วางแผนการเดินทางและอิงตามข้อมูลเชิงลึกของ Google Maps ได้สำเร็จแล้ว
สิ่งที่คุณได้เรียนรู้
- วิธีสร้างโครงร่างเอเจนต์ใหม่โดยใช้ Agent Starter Pack
- วิธีเพิ่มเครื่องมือการเชื่อมต่อแหล่งข้อมูลลงในการกำหนด Agent ของ ADK
- วิธีทดสอบเอเจนต์ ADK โดยใช้โปรแกรมเรียกใช้เว็บในตัว
ขั้นตอนถัดไป
- ดูเครื่องมือ ADK และรูปแบบการผสานรวมอื่นๆ