1. บทนำ
ใน Codelab นี้ คุณจะได้สร้าง Marathon Planner Agent ที่ซับซ้อนโดยใช้ Agent Development Kit (ADK) คุณจะได้ตรวจสอบความสามารถของเอเจนต์อย่างค่อยเป็นค่อยไป ตั้งแต่พรอมต์ของระบบที่มีโครงสร้างดี ไปจนถึงการโหลดทักษะแบบไดนามิกและการแมปเครื่องมือ MCP สุดท้าย คุณจะทดสอบเอเจนต์ในเครื่องและติดตั้งใช้งานใน Agent Runtime (Agent Engine)
สิ่งที่คุณต้องดำเนินการ
- เริ่มต้นโปรเจ็กต์ ADK Agent ใหม่
- เขียนพรอมต์ของระบบที่มีประสิทธิภาพโดยใช้เครื่องมือสร้างที่มีโครงสร้าง
- เพิ่มเครื่องมือ MCP ของ Google Maps เพื่อบริบทตำแหน่งในโลกจริง
- โหลดทักษะลงในชุดเครื่องมือของเอเจนต์แบบไดนามิก
- ทดสอบการดำเนินการของเอเจนต์ในเครื่อง
- ติดตั้งใช้งาน Agent ใน Agent Engine (Cloud Run)
สิ่งที่คุณต้องมี
- เว็บเบราว์เซอร์ เช่น Chrome
- โปรเจ็กต์ Google Cloud ที่เปิดใช้การเรียกเก็บเงิน
- มีความคุ้นเคยกับ Python ในระดับพื้นฐาน
Codelab นี้เหมาะสำหรับนักพัฒนาแอประดับกลางที่ต้องการสร้างเอเจนต์ Generative AI เฉพาะทาง
ระยะเวลาโดยประมาณ: 45 นาที
ทรัพยากรที่สร้างใน Codelab นี้ควรมีค่าใช้จ่ายน้อยกว่า $2
2. ก่อนเริ่มต้น
สร้างโปรเจ็กต์ Google Cloud
- ในคอนโซล Google Cloud ในหน้าตัวเลือกโปรเจ็กต์ ให้เลือกหรือสร้างโปรเจ็กต์ Google Cloud
- ตรวจสอบว่าได้เปิดใช้การเรียกเก็บเงินสำหรับโปรเจ็กต์ที่อยู่ในระบบคลาวด์แล้ว ดูวิธีตรวจสอบว่าได้เปิดใช้การเรียกเก็บเงินในโปรเจ็กต์แล้วหรือไม่
เริ่มต้น Cloud Shell
Cloud Shell คือสภาพแวดล้อมบรรทัดคำสั่งที่ทำงานใน Google Cloud ซึ่งโหลดเครื่องมือที่จำเป็นไว้ล่วงหน้า
- คลิกเปิดใช้งาน Cloud Shell ที่ด้านบนของคอนโซล Google Cloud
- เมื่อเชื่อมต่อกับ Cloud Shell แล้ว ให้ยืนยันการตรวจสอบสิทธิ์โดยทำดังนี้
gcloud auth list - ตรวจสอบว่าได้กำหนดค่าโปรเจ็กต์แล้ว
gcloud config get project - หากไม่ได้ตั้งค่าโปรเจ็กต์ตามที่คาดไว้ ให้ตั้งค่าดังนี้
export PROJECT_ID=<YOUR_PROJECT_ID> gcloud config set project $PROJECT_ID
ยืนยันการตรวจสอบสิทธิ์
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 \ run.googleapis.com \ secretmanager.googleapis.com \ mapstools.googleapis.com \ storage.googleapis.com \ cloudresourcemanager.googleapis.com \ serviceusage.googleapis.com
สร้างคีย์ Google Maps API
หากต้องการใช้เครื่องมือ MCP ของ Google Maps คุณต้องสร้างคีย์ API ของ Maps
- ในคอนโซล Google Cloud ให้ใช้แถบค้นหาเพื่อไปที่ Google Maps Platform > ข้อมูลเข้าสู่ระบบ
- ยืนยันโปรเจ็กต์ Google Cloud หากได้รับข้อความแจ้ง
- คลิกสร้างข้อมูลเข้าสู่ระบบ แล้วเลือกคีย์ API
- คัดลอกคีย์ API ที่สร้างขึ้น ซึ่งจะต้องใช้ในขั้นตอนถัดไป
3. ตั้งค่าสภาพแวดล้อม
สำหรับ Codelab นี้ โค้ดจะโฮสต์อยู่ใน GitHub คุณจะโคลนที่เก็บซึ่งมีโครงสร้างไดเรกทอรีและคอมโพเนนต์ย่อยที่จำเป็น (เช่น ไดเรกทอรี skills/)
- โคลนที่เก็บและไปที่โฟลเดอร์โปรเจ็กต์
git clone https://github.com/GoogleCloudPlatform/next-26-keynotes cd next-26-keynotes/devkey/demo-1
- ตั้งค่าสภาพแวดล้อมเสมือนของ Python และติดตั้ง ADK โดยทำดังนี้
uv venv source .venv/bin/activate uv sync
- ตั้งค่าคีย์ Maps API แอปพลิเคชันจะอ่านจากตัวแปรสภาพแวดล้อม
export GOOGLE_MAPS_API_KEY="<YOUR_MAPS_API_KEY>"
กำหนดค่าตัวแปรสภาพแวดล้อม
เอเจนต์จำลองใช้ไฟล์ .env สำหรับการกำหนดค่า คัดลอกไฟล์ตัวอย่างและอัปเดตด้วยรหัสโปรเจ็กต์
- คัดลอกไฟล์สภาพแวดล้อมตัวอย่าง
cp planner_agent/sample.env planner_agent/.env
- เปิด
planner_agent/.envและอัปเดตฟิลด์GOOGLE_CLOUD_PROJECTด้วยรหัสโปรเจ็กต์ Google Cloud จริงของคุณ แล้วอัปเดตฟิลด์GOOGLE_MAPS_API_KEYด้วยคีย์ API ของ Google Maps ที่คุณสร้างขึ้น
ไฟล์ควรมีลักษณะคล้ายกับตัวอย่างต่อไปนี้
GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=<YOUR_PROJECT_ID>
GOOGLE_CLOUD_LOCATION=us-west1
GOOGLE_MAPS_API_KEY=<YOUR_MAPS_API_KEY>
GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY=true
OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS=true
4. สร้างเอเจนต์ ADK ใหม่
ดูไฟล์หลักที่กำหนด Agent: planner_agent/agent.py
ในที่เก็บ build-agents-with-skills ระบบจะเริ่มต้นตัวแทนโดยใช้คลาส Agent ของ ADK โดยจะระบุโมเดลพื้นฐาน ชื่อประจำตัว และดึงคำสั่งและเครื่องมือที่กำหนดไว้ในโมดูลอื่นๆ
เปิด planner_agent/agent.py เพื่อตรวจสอบโค้ดการเริ่มต้น
instruction="Answer user questions to the best of your knowledge"
description="A helpful assistant for user questions."
tools=[]
# ...
root_agent = Agent(
model='gemini-3-flash-preview',
name='planner_agent',
description=description,
instruction=instruction,
tools=tools
)
คลาส Agent จะแยกประวัติข้อความ การประสานงานเครื่องมือ และการสื่อสาร LLM ออกจากกันเพื่อให้คุณมุ่งเน้นไปที่ลักษณะการทำงานของเอเจนต์
ตอนนี้เอเจนต์ยังเป็นแบบทั่วไป คุณโต้ตอบกับ Gemini ได้เหมือนกับ LLM อื่นๆ
uv run adk run planner_agent
คำสั่งนี้จะเริ่มแชทกับตัวแทน โดยใช้ gemini-3-flash-preview เป็นโมเดลและสามารถตอบคำถามพื้นฐานได้
Running agent planner_agent, type exit to exit.
[user]: What is the length of a Marathon
[planner_agent]: The official length of a marathon is **26.2 miles**, which is
equivalent to **42.195 kilometers**.
ตัวแทนทราบข้อเท็จจริงบางอย่างเกี่ยวกับมาราธอนอยู่แล้ว แต่ก็ยังไม่เพียงพอที่จะวางแผนการวิ่งมาราธอนที่เหมาะสมพร้อมกฎและการวางแผนเส้นทาง
5. สร้างพรอมต์ของระบบ
พรอมต์ของระบบ (วิธีการ) จะกำหนดลักษณะการทำงานของเอเจนต์ โปรเจ็กต์นี้ใช้ PromptBuilder (planner_agent/utils.py) เพื่อเขียนคำสั่งแบบไดนามิกแทนที่จะใช้สตริงขนาดยักษ์เพียงรายการเดียว
เปิด planner_agent/prompts.py เพื่อดูโครงสร้างของพรอมต์ในส่วนต่างๆ ตามตรรกะ
from collections import OrderedDict
from .utils import PromptBuilder
ROLE = """\
...
"""
RULES = """\
...
"""
WORKFLOW = """\
...
"""
###
# Planner instructions with no tools mentioned
PLANNER_INSTRUCTION_NO_TOOLS = PromptBuilder(
OrderedDict(
role=ROLE,
rules=RULES,
tools=TOOLS_PROMPT_ONLY,
workflow=WORKFLOW_PROMPT_ONLY,
)
).build()
# Planner instruction with skills and tools defined
PLANNER_INSTRUCTION = PromptBuilder(
OrderedDict(
role=ROLE,
rules=RULES,
skills=SKILLS,
tools=TOOLS,
workflow=WORKFLOW,
)
).build()
ใน planner_agent/agent.py ระบบได้นำเข้าข้อมูลนี้แล้ว
ค้นหาส่วนที่มี TODO: Replace Instruction and Description และยกเลิกการแสดงความคิดเห็นของการกำหนดตัวแปร instruction และ description ใหม่
โค้ดในส่วนนั้นควรมีลักษณะดังนี้
instruction=PLANNER_INSTRUCTION_NO_TOOLS
description="Expert GIS analyst for marathon route and event planning."
คุณกำลังนำเข้าเวอร์ชันของพรอมต์สำหรับเอเจนต์ที่ไม่ได้อ้างอิงเครื่องมือใดๆ คุณจะเพิ่มเครื่องมือได้ในขั้นตอนถัดไป
คุณทดสอบตัวแทนเวอร์ชันนี้ได้โดยทำดังนี้
uv run adk run planner_agent
ในหน้าต่างแชท ให้ส่งพรอมต์ต่อไปนี้
Plan a marathon for 10000 participants in Las Vegas on April 24, 2027 in the
evening timeframe
หลังจากนั้นไม่นาน คุณควรได้รับการตอบกลับที่คล้ายกับข้อความต่อไปนี้
Running agent planner_agent, type exit to exit.
[user]: Plan a marathon for 10000 participants in Las Vegas on April 24, 2027 in the evening timeframe
[planner_agent]: Here is the comprehensive marathon plan for Las Vegas.
As requested, I have designed this event for an evening start on April 24, 2027. Because certain parameters (theme and budget) were not specified, I have applied pragmatic defaults: this will be a "Neon Nights" scenic theme to capitalize on the evening Strip, operating on a moderate-to-high budget given the infrastructure needed to secure major Las Vegas corridors.
### 1. Intent Alignment
* **City & Theme:** Las Vegas, Nevada. Theme: "Neon Nights" an evening race maximizing the visual impact of the illuminated city.
* **Date & Time:** Saturday, April 24, 2027. Late April evenings in Las Vegas offer optimal running weather (temperatures dropping from ~70°F at sunset to ~60°F). Race start is 6:30 PM (sunset is approx. 7:20 PM).
...
...
เมื่อใช้พรอมต์ที่กำหนดไว้อย่างดี ผลลัพธ์จะใกล้เคียงกับผลลัพธ์ที่คาดไว้มากขึ้น ในขั้นตอนถัดไป คุณจะเพิ่มเครื่องมือเพื่อยกระดับเอเจนต์ไปอีกขั้น
6. เพิ่มทักษะและเครื่องมือ
หากต้องการเปิดใช้ทักษะและเครื่องมือใน planner_agent/agent.py ให้ค้นหาส่วนที่มี TODO: Replaces Tools แล้วยกเลิกการแสดงความคิดเห็นใน 2 บรรทัดถัดไป โค้ดควรมีลักษณะดังนี้
instruction=PLANNER_INSTRUCTION
tools=get_tools()
นี่คือการเปลี่ยนแปลงโค้ดเพียงอย่างเดียวที่จำเป็นในขั้นตอนนี้ ส่วนที่เหลือของส่วนนี้จะอธิบายแนวคิดเบื้องหลังทักษะและเครื่องมือ
ทักษะ
ทักษะของเอเจนต์คือหน่วยฟังก์ชันการทำงานแบบสแตนด์อโลนที่เอเจนต์ ADK ใช้เพื่อทำงานที่เฉพาะเจาะจงได้ ทักษะของเอเจนต์จะรวบรวมคำสั่ง ทรัพยากร และเครื่องมือที่จำเป็นสำหรับงาน โดยอิงตามข้อกำหนดของทักษะของเอเจนต์ โครงสร้างของทักษะช่วยให้โหลดทักษะได้ทีละรายการเพื่อลดผลกระทบต่อหน้าต่างบริบทการทำงานของเอเจนต์
สำหรับเอเจนต์วางแผนการวิ่งมาราธอน จะมีทักษะที่กำหนดไว้ 3 อย่าง ได้แก่
- gis-spatial-engineering - มีหน้าที่ประมวลผลข้อมูล GeoJSON เพื่อสร้างเส้นทางมาราธอน
- การทำแผนที่ - ใช้เครื่องมือ Google Maps เพื่อค้นหาสถานที่และข้อมูลสภาพอากาศ
- race-director - ตรวจสอบว่าเส้นทางมาราธอนเป็นไปตามหลักเกณฑ์การวางแผน
ทักษะจะมีสคริปต์ เนื้อหาเพิ่มเติม และข้อมูลอ้างอิงได้
แอปพลิเคชันจะโหลดทักษะทั้งหมดและแสดงเป็นเครื่องมือใน planner_agent/tools.py โปรดสังเกตวิธีดำเนินการนี้ในฟังก์ชัน get_tools()
def get_tools() -> list:
"""Build the planner's tool list with lazy-loaded skills."""
from google.adk.code_executors.unsafe_local_code_executor import UnsafeLocalCodeExecutor
skills_dir = pathlib.Path(__file__).parent / "skills"
skills = []
if skills_dir.exists():
skills = [
load_skill_from_dir(d)
for d in sorted(skills_dir.iterdir())
if d.is_dir() and not d.name.startswith("_") and (d / "SKILL.md").exists()
]
additional_tools = _load_additional_tools(skills_dir)
skill_toolset = SkillToolset(
skills=skills,
code_executor=UnsafeLocalCodeExecutor(),
additional_tools=additional_tools,
)
tools = [
skill_toolset,
PreloadMemoryTool(),
]
tools.extend(get_maps_tools())
return tools
ส่วนที่น่าสนใจที่สุดคือload_skill_from_dirจาก ADK นอกจากนี้ ยังมีอีกวิธีในการสร้างทักษะใน ADK ซึ่งก็คือการสร้างทักษะแบบอินไลน์ แม้ว่าจะไม่ได้ใช้ใน Codelab นี้ แต่จะมีลักษณะดังนี้
from google.adk.skills import models
greeting_skill = models.Skill(
frontmatter=models.Frontmatter(
name="greeting-skill",
description=(
"A friendly greeting skill that can say hello to a specific person."
),
),
instructions=(
"Step 1: Read the 'references/hello_world.txt' file to understand how"
" to greet the user. Step 2: Return a greeting based on the reference."
),
resources=models.Resources(
references={
"hello_world.txt": "Hello! So glad to have you here!",
"example.md": "This is an example reference.",
},
),
)
เพิ่มเครื่องมือการแมป
เครื่องมือวางแผนการวิ่งมาราธอนต้องมีบริบทเชิงพื้นที่เพื่อสร้างเส้นทาง คุณระบุข้อมูลนี้ได้โดยการผสานรวมเซิร์ฟเวอร์ MCP (Model Context Protocol) ของ Google Maps
ใน planner_agent/tools.py โปรดสังเกตวิธีลงทะเบียนเซิร์ฟเวอร์ MCP ด้วยเครื่องมือ ApiRegistry
from google.adk.integrations.api_registry import ApiRegistry
class MapsApiRegistry(ApiRegistry):
"""ApiRegistry subclass that strips ADC headers to force API key auth."""
def get_toolset(self, *args, **kwargs): # noqa: ANN002, ANN003
toolset = super().get_toolset(*args, **kwargs)
conn = getattr(toolset, "_connection_params", None)
headers = getattr(conn, "headers", None) if conn else None
if headers:
headers.pop("Authorization", None) # type: ignore[union-attr]
headers.pop("x-goog-user-project", None) # type: ignore[union-attr]
return toolset
def get_maps_tools() -> list:
"""Return Maps MCP toolset if configured."""
project_id = os.getenv("GOOGLE_CLOUD_PROJECT", "").strip()
maps_key = _resolve_maps_key()
if not project_id or not maps_key:
return []
# Map the MCP server location on Google Cloud
mcp_server_name = f"projects/{project_id}/locations/global/mcpServers/google-mapstools.googleapis.com-mcp"
# Initialize the custom API registry that supports header injection
api_registry = MapsApiRegistry(
api_registry_project_id=project_id,
header_provider=header_provider,
)
return [api_registry.get_toolset(mcp_server_name=mcp_server_name)]
เมื่อเพิ่มชุดเครื่องมือ MCP แล้ว Agent จะมีความสามารถในการค้นหา Google Maps เพื่อดูรายละเอียดการกำหนดเส้นทาง ระดับความสูง และตำแหน่งโดยอัตโนมัติ
7. เรียกใช้ Agent ในเครื่อง
เมื่อเชื่อมต่อเอเจนต์ พรอมต์ และเครื่องมือเข้าด้วยกันแล้ว ให้เรียกใช้เอเจนต์ในเครื่อง คราวนี้คุณจะใช้ adk web เพื่อให้เห็นเหตุการณ์การโหลดทักษะและการเรียกใช้เครื่องมือ
uv run adk web
คุณควรเห็นข้อความที่คล้ายกัน
INFO: Started server process [99665]
INFO: Waiting for application startup.
+-----------------------------------------------------------------------------+
| ADK Web Server started |
| |
| For local testing, access at http://127.0.0.1:8000. |
+-----------------------------------------------------------------------------+
INFO: Application startup complete.
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
- เปิดเบราว์เซอร์ แล้วไปที่ URL ที่แสดงในเทอร์มินัล (โดยปกติคือ
http://localhost:8000) - เลือก
planner_agentในเมนูแบบเลื่อนลงด้านซ้ายบน - ในหน้าต่างแชท ให้ส่งพรอมต์ต่อไปนี้
Plan a marathon for 10000 participants in Las Vegas on April 24, 2027 in the
evening timeframe
คุณควรเห็นว่าระบบกำลังโหลดทักษะและเรียกใช้เครื่องมือ หลังจากนั้นไม่นาน เอเจนต์จะสร้างแผนการวิ่งมาราธอน
UI ควรมีลักษณะคล้ายกับภาพต่อไปนี้

8. ติดตั้งใช้งาน Agent
เมื่อพอใจกับประสิทธิภาพของเอเจนต์ในเครื่องแล้ว คุณสามารถทำให้เอเจนต์ใช้งานได้ใน Agent Engine ซึ่งจะโฮสต์เอเจนต์ใน Cloud Run อย่างปลอดภัย
หากต้องการติดตั้งใช้งาน Agent ให้ใช้คำสั่งการติดตั้งใช้งาน ADK CLI ดังนี้
uv run adk deploy agent_engine \ --env_file planner_agent/.env \ planner_agent
เมื่อการทำให้ใช้งานได้เสร็จสมบูรณ์แล้ว CLI จะแสดงเอาต์พุตปลายทางที่โฮสต์อย่างปลอดภัยสำหรับ Agent ของคุณ ตอนนี้คุณสามารถผสานรวมปลายทางนี้เข้ากับแอปพลิเคชันส่วนหน้า แชทบ็อต หรือระบบแบ็กเอนด์อื่นๆ ได้แล้ว นอกจากนี้ คุณยังใช้ Agent Runtime Playground เพื่อทดสอบเอเจนต์ได้ด้วย
เอาต์พุตจะมีลักษณะดังนี้
Files and dependencies resolved Deploying to agent engine... ✅ Created agent engine: projects/<PROJECT_ID>/locations/us-west1/reasoningEngines/<AGENT_ID>
คุณใช้สคริปต์ Python ที่ให้ไว้เพื่อสื่อสารกับตัวแทนได้
- คัดลอกไฟล์สภาพแวดล้อมตัวอย่าง
cp sample.env .env
- เปิด
.envและอัปเดตฟิลด์GOOGLE_CLOUD_PROJECTด้วยรหัสโปรเจ็กต์ Google Cloud จริงของคุณ
ไฟล์ควรมีลักษณะดังนี้
GOOGLE_CLOUD_PROJECT=<YOUR_PROJECT_ID>
GOOGLE_CLOUD_LOCATION=us-west1
- คุณแสดงรายการเอเจนต์ในโปรเจ็กต์ได้
python main.py list
คุณควรเห็นข้อความที่คล้ายกัน
Listing deployed agents... ID: <AGENT_ID> | Display Name: planner_agent
เมื่อได้รหัสตัวแทนที่ติดตั้งใช้งานแล้ว คุณจะส่งพรอมต์ได้โดยทำดังนี้
export AGENT_ID=<AGENT_ID>
python main.py prompt --agent-id ${AGENT_ID} --message "Plan a marathon for
10000 participants in Las Vegas on April 24, 2027 in the evening timeframe"
คุณจะได้รับเอาต์พุตที่มีลักษณะดังนี้
Streaming response from agent <AGENT_ID>:
{'model_version': 'gemini-3-flash-preview', 'content': {'parts': [{'text': 'Here is a comprehensive
...
...
...
9. ล้างข้อมูล
โปรดลบทรัพยากรที่สร้างขึ้นระหว่างการทำ Codelab นี้เพื่อหลีกเลี่ยงการเรียกเก็บเงินอย่างต่อเนื่องในบัญชี Google Cloud
ลบบริการ Cloud Run ที่สร้างขึ้นโดยการติดตั้งใช้งาน
python main.py delete --agent-id ${AGENT_ID}
หากจัดเก็บคีย์ Maps API ไว้ใน Secret Manager ให้ลบข้อมูลลับโดยทำดังนี้
gcloud secrets delete maps-api-key --project=$PROJECT_ID
หากสร้างโปรเจ็กต์ที่อยู่ในระบบคลาวด์ Google Cloud ใหม่สำหรับ Codelab นี้ คุณสามารถลบทั้งโปรเจ็กต์เพื่อนำทรัพยากรและ API ทั้งหมดที่เชื่อมโยงออกได้โดยทำดังนี้
gcloud projects delete $PROJECT_ID
10. ขอแสดงความยินดี
ยินดีด้วย คุณได้สร้าง Agent วางแผนการวิ่งมาราธอนที่ซับซ้อนโดยใช้ ADK
สิ่งที่คุณได้เรียนรู้
- การเริ่มต้นโปรเจ็กต์ Agent Development Kit (ADK)
- การใช้
PromptBuilderสำหรับพรอมต์ของระบบแบบแยกส่วน - การผสานรวมความสามารถในการแมปโดยใช้เครื่องมือ MCP และ
ApiRegistry - การโหลดทักษะแบบมีเงื่อนไขโดยใช้
SkillToolset - การทดสอบในเครื่องและการติดตั้งใช้งานใน Agent Engine