1. บทนำ
บทแนะนำนี้จะแนะนำวิธีติดตั้งใช้งาน จัดการ และตรวจสอบเอเจนต์ที่มีประสิทธิภาพซึ่งสร้างด้วย Agent Development Kit (ADK) ใน Google Cloud Run ADK ช่วยให้คุณสร้างเอเจนต์ที่สามารถจัดการเวิร์กโฟลว์ที่ซับซ้อนแบบหลายเอเจนต์ได้ การใช้ประโยชน์จาก Cloud Run ซึ่งเป็นแพลตฟอร์มแบบ Serverless ที่มีการจัดการครบวงจรจะช่วยให้คุณสามารถติดตั้งใช้งาน Agent เป็นแอปพลิเคชันที่ปรับขนาดได้และอยู่ในคอนเทนเนอร์โดยไม่ต้องกังวลเกี่ยวกับโครงสร้างพื้นฐาน การผสานรวมที่มีประสิทธิภาพนี้ช่วยให้คุณมุ่งเน้นที่ตรรกะหลักของเอเจนต์ได้ในขณะที่ได้รับประโยชน์จากสภาพแวดล้อมที่แข็งแกร่งและปรับขนาดได้ของ Google Cloud
ตลอดบทแนะนำนี้ เราจะดูการผสานรวม ADK กับ Cloud Run อย่างราบรื่น คุณจะได้เรียนรู้วิธีติดตั้งใช้งานเอเจนต์ จากนั้นจะเจาะลึกด้านการปฏิบัติจริงในการจัดการแอปพลิเคชันในสภาพแวดล้อมที่คล้ายกับการใช้งานจริง เราจะอธิบายวิธีเปิดตัวเอเจนต์เวอร์ชันใหม่อย่างปลอดภัยด้วยการจัดการการเข้าชม ซึ่งจะช่วยให้คุณทดสอบฟีเจอร์ใหม่ๆ กับผู้ใช้บางกลุ่มก่อนที่จะเปิดตัวอย่างเต็มรูปแบบได้
นอกจากนี้ คุณจะได้รับประสบการณ์จริงในการตรวจสอบประสิทธิภาพของเอเจนต์ เราจะจำลองสถานการณ์จริงโดยทำการทดสอบโหลดเพื่อสังเกตความสามารถในการปรับขนาดอัตโนมัติของ Cloud Run ในการทำงาน เราจะเปิดใช้การติดตามด้วย Cloud Trace เพื่อให้คุณได้รับข้อมูลเชิงลึกที่ละเอียดยิ่งขึ้นเกี่ยวกับพฤติกรรมและประสิทธิภาพของตัวแทน ซึ่งจะแสดงมุมมองแบบละเอียดตั้งแต่ต้นจนจบของคำขอขณะที่คำขอผ่านเอเจนต์ของคุณ ทำให้คุณระบุและแก้ไขปัญหาคอขวดด้านประสิทธิภาพได้ เมื่อจบบทแนะนำนี้ คุณจะมีความเข้าใจอย่างครอบคลุมเกี่ยวกับวิธีติดตั้งใช้งาน จัดการ และตรวจสอบเอเจนต์ที่ขับเคลื่อนด้วย ADK ใน Cloud Run อย่างมีประสิทธิภาพ
ใน Codelab นี้ คุณจะได้ใช้แนวทางแบบทีละขั้นตอนดังนี้
- สร้างฐานข้อมูล PostgreSQL ใน CloudSQL เพื่อใช้กับบริการเซสชันฐานข้อมูลของตัวแทน ADK
- ตั้งค่าเอเจนต์ ADK พื้นฐาน
- ตั้งค่าบริการเซสชันฐานข้อมูลเพื่อให้ ADK Runner ใช้
- ทำให้ Agent ใช้งานได้กับ Cloud Run เป็นครั้งแรก
- การทดสอบโหลดและการตรวจสอบการปรับขนาดอัตโนมัติของ Cloud Run
- ทำให้การแก้ไขเอเจนต์ใหม่ใช้งานได้และค่อยๆ เพิ่มการเข้าชมไปยังการแก้ไขใหม่
- ตั้งค่าการติดตามระบบคลาวด์และตรวจสอบการติดตามการเรียกใช้ Agent
ภาพรวมสถาปัตยกรรม
ข้อกำหนดเบื้องต้น
- คุ้นเคยกับการทำงานด้วย Python
- ความเข้าใจเกี่ยวกับสถาปัตยกรรม Full-Stack พื้นฐานโดยใช้บริการ HTTP
สิ่งที่คุณจะได้เรียนรู้
- โครงสร้าง ADK และยูทิลิตีในเครื่อง
- ตั้งค่าเอเจนต์ ADK ด้วยบริการเซสชันฐานข้อมูล
- ตั้งค่า PostgreSQL ใน CloudSQL เพื่อให้บริการเซสชันฐานข้อมูลใช้งานได้
- ติดตั้งใช้งานแอปพลิเคชันใน Cloud Run โดยใช้ Dockerfile และตั้งค่าตัวแปรสภาพแวดล้อมเริ่มต้น
- กำหนดค่าและทดสอบการปรับขนาดอัตโนมัติของ Cloud Run ด้วยการทดสอบโหลด
- กลยุทธ์ในการเผยแพร่แบบค่อยเป็นค่อยไปด้วย Cloud Run
- ตั้งค่าการติดตาม Agent ของ ADK ไปยัง Cloud Trace
สิ่งที่คุณต้องมี
- เว็บเบราว์เซอร์ Chrome
- บัญชี Gmail
- โปรเจ็กต์ Cloud ที่เปิดใช้การเรียกเก็บเงิน
Codelab นี้ออกแบบมาสำหรับนักพัฒนาซอฟต์แวร์ทุกระดับ (รวมถึงผู้เริ่มต้น) โดยใช้ Python ในแอปพลิเคชันตัวอย่าง อย่างไรก็ตาม คุณไม่จำเป็นต้องมีความรู้เกี่ยวกับ Python เพื่อทำความเข้าใจแนวคิดที่นำเสนอ
2. ก่อนเริ่มต้น
เลือกโปรเจ็กต์ที่ใช้งานอยู่ใน Cloud Console
Codelab นี้ถือว่าคุณมีโปรเจ็กต์ Google Cloud ที่เปิดใช้การเรียกเก็บเงินอยู่แล้ว หากยังไม่มี ให้ทำตามวิธีการด้านล่างเพื่อเริ่มต้นใช้งาน
- ใน Google Cloud Console ให้เลือกหรือสร้างโปรเจ็กต์ Google Cloud ในหน้าตัวเลือกโปรเจ็กต์
- ตรวจสอบว่าได้เปิดใช้การเรียกเก็บเงินสำหรับโปรเจ็กต์ Cloud แล้ว ดูวิธีตรวจสอบว่าได้เปิดใช้การเรียกเก็บเงินในโปรเจ็กต์แล้วหรือไม่
เตรียมฐานข้อมูล Cloud SQL
เราจะต้องมีฐานข้อมูลที่ตัวแทน ADK จะใช้ในภายหลัง มาสร้างฐานข้อมูล PostgreSQL ใน Cloud SQL กัน ก่อนอื่น ให้ไปที่แถบค้นหาในส่วนบนของคอนโซลระบบคลาวด์ แล้วพิมพ์ "Cloud SQL" จากนั้นคลิกผลิตภัณฑ์ Cloud SQL
หลังจากนั้น เราจะต้องสร้างอินสแตนซ์ฐานข้อมูลใหม่ คลิกสร้างอินสแตนซ์ แล้วเลือก PostgreSQL
นอกจากนี้ คุณอาจต้องเปิดใช้ Compute Engine API หากเริ่มต้นด้วยโปรเจ็กต์ใหม่ เพียงคลิกเปิดใช้ API หากข้อความนี้ปรากฏขึ้น
จากนั้นเราจะเลือกข้อกำหนดของฐานข้อมูล เลือกฉบับ Enterprise ที่ตั้งค่าล่วงหน้าเป็นฉบับ Sandbox
หลังจากนั้น ให้ตั้งชื่ออินสแตนซ์และรหัสผ่านเริ่มต้นสำหรับผู้ใช้ postgres ที่นี่ คุณสามารถตั้งค่านี้ด้วยข้อมูลเข้าสู่ระบบที่ต้องการ แต่เพื่อประโยชน์ของบทแนะนำนี้ เราจะใช้ "adk-deployment" ทั้งชื่ออินสแตนซ์และรหัสผ่านที่นี่
มาใช้ us-central1 กับโซนเดียวสำหรับบทแนะนำนี้กัน เราจะสร้างฐานข้อมูลให้เสร็จสมบูรณ์ได้ จากนั้นปล่อยให้ระบบตั้งค่าที่จำเป็นทั้งหมดให้เสร็จโดยคลิกปุ่มสร้างอินสแตนซ์
ในระหว่างที่รอให้การดำเนินการนี้เสร็จสิ้น เราสามารถไปยังส่วนถัดไปได้
ตั้งค่าโปรเจ็กต์ Cloud ในเทอร์มินัล Cloud Shell
- คุณจะใช้ Cloud Shell ซึ่งเป็นสภาพแวดล้อมบรรทัดคำสั่งที่ทำงานใน Google Cloud คลิกเปิดใช้งาน Cloud Shell ที่ด้านบนของคอนโซล Google Cloud
- เมื่อเชื่อมต่อกับ Cloud Shell แล้ว ให้ตรวจสอบว่าคุณได้รับการตรวจสอบสิทธิ์แล้วและตั้งค่าโปรเจ็กต์เป็นรหัสโปรเจ็กต์โดยใช้คำสั่งต่อไปนี้
gcloud auth list
- เรียกใช้คำสั่งต่อไปนี้ใน Cloud Shell เพื่อยืนยันว่าคำสั่ง gcloud รู้จักโปรเจ็กต์ของคุณ
gcloud config list project
- หากไม่ได้ตั้งค่าโปรเจ็กต์ ให้ใช้คำสั่งต่อไปนี้เพื่อตั้งค่า
gcloud config set project <YOUR_PROJECT_ID>
หรือคุณจะดู PROJECT_ID id ในคอนโซลก็ได้
คลิก แล้วคุณจะเห็นโปรเจ็กต์ทั้งหมดและรหัสโปรเจ็กต์ทางด้านขวา
- เปิดใช้ API ที่จำเป็นผ่านคำสั่งที่แสดงด้านล่าง การดำเนินการนี้อาจใช้เวลาสักครู่ โปรดอดทนรอ
gcloud services enable aiplatform.googleapis.com \
run.googleapis.com \
cloudbuild.googleapis.com \
cloudresourcemanager.googleapis.com \
sqladmin.googleapis.com
เมื่อเรียกใช้คำสั่งสำเร็จ คุณควรเห็นข้อความที่คล้ายกับข้อความที่แสดงด้านล่าง
Operation "operations/..." finished successfully.
คุณสามารถใช้คอนโซลแทนคำสั่ง gcloud ได้โดยค้นหาแต่ละผลิตภัณฑ์หรือใช้ลิงก์นี้
หากพลาด API ใดไป คุณก็เปิดใช้ได้เสมอในระหว่างการติดตั้งใช้งาน
โปรดดูคำสั่งและการใช้งาน gcloud ในเอกสารประกอบ
ไปที่ Cloud Shell Editor และตั้งค่าไดเรกทอรีการทำงานของแอปพลิเคชัน
ตอนนี้เราสามารถตั้งค่าโปรแกรมแก้ไขโค้ดเพื่อเขียนโค้ดได้แล้ว เราจะใช้ Cloud Shell Editor สำหรับการดำเนินการนี้
- คลิกปุ่ม "เปิดเครื่องมือแก้ไข" ซึ่งจะเปิด Cloud Shell Editor และเราจะเขียนโค้ดที่นี่ได้
- ตรวจสอบว่าได้ตั้งค่าโปรเจ็กต์ Cloud Code ไว้ที่มุมล่างซ้าย (แถบสถานะ) ของโปรแกรมแก้ไข Cloud Shell ตามที่ไฮไลต์ไว้ในรูปภาพด้านล่าง และตั้งค่าเป็นโปรเจ็กต์ Google Cloud ที่ใช้งานอยู่ซึ่งคุณเปิดใช้การเรียกเก็บเงินไว้ ให้สิทธิ์หากได้รับข้อความแจ้ง หากคุณทำตามคำสั่งก่อนหน้านี้แล้ว ปุ่มอาจชี้ไปยังโปรเจ็กต์ที่เปิดใช้งานโดยตรงแทนปุ่มลงชื่อเข้าใช้
- จากนั้นมาโคลนไดเรกทอรีการทำงานของเทมเพลตสำหรับโค้ดแล็บนี้จาก Github โดยเรียกใช้คำสั่งต่อไปนี้ ซึ่งจะสร้างไดเรกทอรีการทำงานในไดเรกทอรี deploy_and_manage_adk
git clone https://github.com/alphinside/deploy-and-manage-adk-service.git deploy_and_manage_adk
- หลังจากนั้น ให้ไปที่ส่วนบนของ Cloud Shell Editor แล้วคลิกไฟล์->เปิดโฟลเดอร์ ค้นหาไดเรกทอรี username แล้วค้นหาไดเรกทอรี deploy_and_manage_adk จากนั้นคลิกปุ่ม OK ซึ่งจะทำให้ไดเรกทอรีที่เลือกเป็นไดเรกทอรีการทำงานหลัก ในตัวอย่างนี้ ชื่อผู้ใช้คือ alvinprayuda ดังนั้นเส้นทางไดเรกทอรีจึงแสดงอยู่ด้านล่าง
ตอนนี้ Cloud Shell Editor ควรมีลักษณะดังนี้
จากนั้นเราจะกำหนดค่าการตั้งค่าสภาพแวดล้อม Python ได้
การตั้งค่าสภาพแวดล้อม
เตรียมสภาพแวดล้อมเสมือนของ Python
ขั้นตอนถัดไปคือการเตรียมสภาพแวดล้อมในการพัฒนา ไดเรกทอรีที่ใช้งานอยู่ในเทอร์มินัลที่ใช้งานอยู่ในปัจจุบันควรอยู่ภายในไดเรกทอรีที่ใช้งาน deploy_and_manage_adk เราจะใช้ Python 3.12 ใน Codelab นี้ และจะใช้ตัวจัดการโปรเจ็กต์ Python ของ uv เพื่อลดความซับซ้อนในการสร้างและจัดการเวอร์ชัน Python และสภาพแวดล้อมเสมือน
- หากยังไม่ได้เปิดเทอร์มินัล ให้เปิดโดยคลิกเทอร์มินัล -> เทอร์มินัลใหม่ หรือใช้ Ctrl + Shift + C ซึ่งจะเปิดหน้าต่างเทอร์มินัลที่ส่วนล่างของเบราว์เซอร์
- ดาวน์โหลด
uvและติดตั้ง Python 3.12 ด้วยคำสั่งต่อไปนี้
curl -LsSf https://astral.sh/uv/0.6.16/install.sh | sh && \
source $HOME/.local/bin/env && \
uv python install 3.12
- ตอนนี้มาเริ่มต้นสภาพแวดล้อมเสมือนโดยใช้
uvกัน เรียกใช้คำสั่งนี้
uv sync --frozen
การดำเนินการนี้จะสร้างไดเรกทอรี .venv และติดตั้งทรัพยากร Dependency การดูpyproject.toml อย่างรวดเร็วจะให้ข้อมูลเกี่ยวกับทรัพยากร Dependency ที่แสดงดังนี้
dependencies = [
"google-adk==1.3.0",
"locust==2.37.10",
"pg8000==1.31.2",
"python-dotenv==1.1.0",
]
- หากต้องการทดสอบสภาพแวดล้อมเสมือน ให้สร้างไฟล์ใหม่ชื่อ main.py แล้วคัดลอกโค้ดต่อไปนี้
def main():
print("Hello from deploy_and_manage_adk!")
if __name__ == "__main__":
main()
- จากนั้นเรียกใช้คำสั่งต่อไปนี้
uv run main.py
คุณจะได้รับเอาต์พุตดังที่แสดงด้านล่าง
Using CPython 3.12 Creating virtual environment at: .venv Hello from deploy_and_manage_adk!
ซึ่งแสดงว่าระบบกำลังตั้งค่าโปรเจ็กต์ Python อย่างถูกต้อง
ตั้งค่าไฟล์การกำหนดค่า
ตอนนี้เราจะต้องตั้งค่าไฟล์การกำหนดค่าสำหรับโปรเจ็กต์นี้
เปลี่ยนชื่อไฟล์ .env.example เป็น .env แล้วระบบจะแสดงค่าด้านล่าง อัปเดตค่า GOOGLE_CLOUD_PROJECT เป็น project-id
# Google Cloud and Vertex AI configuration GOOGLE_CLOUD_PROJECT=your-project-id GOOGLE_CLOUD_LOCATION=global GOOGLE_GENAI_USE_VERTEXAI=True # Database connection for session service # SESSION_SERVICE_URI=postgresql+pg8000://<username>:<password>@/<database>?unix_sock=/cloudsql/<instance_connection_name>/.s.PGSQL.5432
สำหรับโค้ดแล็บนี้ เราจะใช้ค่าที่กำหนดค่าไว้ล่วงหน้าสำหรับ GOOGLE_CLOUD_LOCATION และ GOOGLE_GENAI_USE_VERTEXAI. ส่วน SESSION_SERVICE_URI เราจะใส่เครื่องหมายความคิดเห็นไว้ก่อน
ตอนนี้เราสามารถไปยังขั้นตอนถัดไป ตรวจสอบตรรกะของเอเจนต์ และติดตั้งใช้งานได้แล้ว
3. สร้างเอเจนต์สภาพอากาศด้วย ADK และ Gemini 2.5
ข้อมูลเบื้องต้นเกี่ยวกับโครงสร้างไดเรกทอรี ADK
มาเริ่มสำรวจสิ่งที่ ADK มีให้และวิธีสร้าง Agent กัน ดูเอกสารประกอบทั้งหมดของ ADK ได้ในURL นี้ ADK มีเครื่องมือมากมายให้เราใช้ในการดำเนินการคำสั่ง CLI ตัวอย่างเช่น
- ตั้งค่าโครงสร้างไดเรกทอรีของเอเจนต์
- ลองโต้ตอบอย่างรวดเร็วผ่านอินพุตเอาต์พุต CLI
- ตั้งค่าอินเทอร์เฟซเว็บ UI การพัฒนาในเครื่องอย่างรวดเร็ว
ตอนนี้เรามาตรวจสอบโครงสร้างของ Agent ในไดเรกทอรี weather_agent กัน
weather_agent/ ├── __init__.py ├── agent.py
และหากตรวจสอบ init.py และ agent.py คุณจะเห็นโค้ดนี้
# __init__.py
from weather_agent.agent import root_agent
__all__ = ["root_agent"]
# agent.py
import os
from pathlib import Path
import google.auth
from dotenv import load_dotenv
from google.adk.agents import Agent
from google.cloud import logging as google_cloud_logging
# Load environment variables from .env file in root directory
root_dir = Path(__file__).parent.parent
dotenv_path = root_dir / ".env"
load_dotenv(dotenv_path=dotenv_path)
# Use default project from credentials if not in .env
_, project_id = google.auth.default()
os.environ.setdefault("GOOGLE_CLOUD_PROJECT", project_id)
os.environ.setdefault("GOOGLE_CLOUD_LOCATION", "global")
os.environ.setdefault("GOOGLE_GENAI_USE_VERTEXAI", "True")
logging_client = google_cloud_logging.Client()
logger = logging_client.logger("weather-agent")
def get_weather(city: str) -> dict:
"""Retrieves the current weather report for a specified city.
Args:
city (str): The name of the city (e.g., "New York", "London", "Tokyo").
Returns:
dict: A dictionary containing the weather information.
Includes a 'status' key ('success' or 'error').
If 'success', includes a 'report' key with weather details.
If 'error', includes an 'error_message' key.
"""
logger.log_text(
f"--- Tool: get_weather called for city: {city} ---", severity="INFO"
) # Log tool execution
city_normalized = city.lower().replace(" ", "") # Basic normalization
# Mock weather data
mock_weather_db = {
"newyork": {
"status": "success",
"report": "The weather in New York is sunny with a temperature of 25°C.",
},
"london": {
"status": "success",
"report": "It's cloudy in London with a temperature of 15°C.",
},
"tokyo": {
"status": "success",
"report": "Tokyo is experiencing light rain and a temperature of 18°C.",
},
}
if city_normalized in mock_weather_db:
return mock_weather_db[city_normalized]
else:
return {
"status": "error",
"error_message": f"Sorry, I don't have weather information for '{city}'.",
}
root_agent = Agent(
name="weather_agent",
model="gemini-2.5-flash",
instruction="You are a helpful AI assistant designed to provide accurate and useful information.",
tools=[get_weather],
)
คำอธิบายโค้ดของ ADK
สคริปต์นี้ประกอบด้วยการเริ่มต้นตัวแทนของเรา ซึ่งเราจะเริ่มต้นสิ่งต่อไปนี้
- ตั้งค่าโมเดลที่จะใช้เป็น
gemini-2.5-flash - จัดเตรียมเครื่องมือ
get_weatherเพื่อรองรับฟังก์ชันการทำงานของเอเจนต์ในฐานะเอเจนต์สภาพอากาศ
เรียกใช้ UI บนเว็บ
ตอนนี้เราสามารถโต้ตอบกับเอเจนต์และตรวจสอบลักษณะการทำงานของเอเจนต์ในเครื่องได้แล้ว ADK ช่วยให้เรามีเว็บ UI สำหรับการพัฒนาเพื่อโต้ตอบและตรวจสอบสิ่งที่เกิดขึ้นระหว่างการโต้ตอบ เรียกใช้คำสั่งต่อไปนี้เพื่อเริ่มเซิร์ฟเวอร์ UI สำหรับการพัฒนาในเครื่อง
uv run adk web --port 8080
ซึ่งจะสร้างเอาต์พุตคล้ายกับตัวอย่างต่อไปนี้ ซึ่งหมายความว่าเราเข้าถึงอินเทอร์เฟซเว็บได้แล้ว
INFO: Started server process [xxxx] INFO: Waiting for application startup. +-----------------------------------------------------------------------------+ | ADK Web Server started | | | | For local testing, access at http://localhost:8080. | +-----------------------------------------------------------------------------+ INFO: Application startup complete. INFO: Uvicorn running on http://0.0.0.0:8080 (Press CTRL+C to quit)
ตอนนี้หากต้องการตรวจสอบ ให้คลิกปุ่มตัวอย่างเว็บที่ด้านบนของ Cloud Shell Editor แล้วเลือกแสดงตัวอย่างบนพอร์ต 8080
คุณจะเห็นหน้าเว็บต่อไปนี้ ซึ่งคุณสามารถเลือกเอเจนต์ที่พร้อมให้บริการได้ที่ปุ่มเมนูแบบเลื่อนลงด้านซ้ายบน ( ในกรณีของเราควรเป็น weather_agent) และโต้ตอบกับบ็อต คุณจะเห็นข้อมูลมากมายเกี่ยวกับรายละเอียดบันทึกในระหว่างรันไทม์ของเอเจนต์ในหน้าต่างด้านซ้าย
ตอนนี้ลองโต้ตอบกับวิดีโอนี้ ในแถบด้านซ้าย เราสามารถตรวจสอบการติดตามสำหรับอินพุตแต่ละรายการ เพื่อให้เข้าใจระยะเวลาที่ใช้สำหรับแต่ละการดำเนินการที่เอเจนต์ทำก่อนที่จะสร้างคำตอบสุดท้าย
นี่เป็นหนึ่งในฟีเจอร์การสังเกตการณ์ที่สร้างขึ้นใน ADK และปัจจุบันเราตรวจสอบในเครื่อง ในภายหลังเราจะมาดูวิธีผสานรวมกับ Cloud Tracing เพื่อให้เรามีการติดตามคำขอทั้งหมดแบบรวมศูนย์
4. สคริปต์เซิร์ฟเวอร์แบ็กเอนด์
เราจะห่อหุ้มเอเจนต์ไว้ภายในแอป FastAPI เพื่อให้เข้าถึงเอเจนต์ในรูปแบบบริการได้ เราสามารถกำหนดค่าบริการที่จำเป็นเพื่อรองรับเอเจนต์ได้ที่นี่ เช่น การเตรียมบริการ Session, Memory หรือ Artifact เพื่อวัตถุประสงค์ในการผลิตที่นี่ นี่คือโค้ดของ server.py ที่จะใช้
import os
from dotenv import load_dotenv
from fastapi import FastAPI
from google.adk.cli.fast_api import get_fast_api_app
from pydantic import BaseModel
from typing import Literal
from google.cloud import logging as google_cloud_logging
from tracing import CloudTraceLoggingSpanExporter
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider, export
# Load environment variables from .env file
load_dotenv()
logging_client = google_cloud_logging.Client()
logger = logging_client.logger(__name__)
AGENT_DIR = os.path.dirname(os.path.abspath(__file__))
# Get session service URI from environment variables
session_uri = os.getenv("SESSION_SERVICE_URI", None)
# Prepare arguments for get_fast_api_app
app_args = {"agents_dir": AGENT_DIR, "web": True}
# Only include session_service_uri if it's provided
if session_uri:
app_args["session_service_uri"] = session_uri
else:
logger.log_text(
"SESSION_SERVICE_URI not provided. Using in-memory session service instead. "
"All sessions will be lost when the server restarts.",
severity="WARNING",
)
provider = TracerProvider()
processor = export.BatchSpanProcessor(CloudTraceLoggingSpanExporter())
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)
# Create FastAPI app with appropriate arguments
app: FastAPI = get_fast_api_app(**app_args)
app.title = "weather-agent"
app.description = "API for interacting with the Agent weather-agent"
class Feedback(BaseModel):
"""Represents feedback for a conversation."""
score: int | float
text: str | None = ""
invocation_id: str
log_type: Literal["feedback"] = "feedback"
service_name: Literal["weather-agent"] = "weather-agent"
user_id: str = ""
@app.post("/feedback")
def collect_feedback(feedback: Feedback) -> dict[str, str]:
"""Collect and log feedback.
Args:
feedback: The feedback data to log
Returns:
Success message
"""
logger.log_struct(feedback.model_dump(), severity="INFO")
return {"status": "success"}
# Main execution
if __name__ == "__main__":
import uvicorn
uvicorn.run(app, host="0.0.0.0", port=8080)
คำอธิบายโค้ดฝั่งเซิร์ฟเวอร์
ต่อไปนี้คือสิ่งที่กำหนดไว้ในสคริปต์ server.py
- แปลงเอเจนต์ของเราให้เป็นแอป FastAPI โดยใช้เมธอด
get_fast_api_appด้วยวิธีนี้ เราจะรับช่วงคำจำกัดความเส้นทางเดียวกันกับที่ใช้สำหรับ UI การพัฒนาเว็บ - กำหนดค่าบริการเซสชัน หน่วยความจำ หรืออาร์ติแฟกต์ที่จำเป็นโดยการเพิ่มอาร์กิวเมนต์คีย์เวิร์ดลงในเมธอด
get_fast_api_appในบทแนะนำนี้ หากเรากำหนดค่าตัวแปรสภาพแวดล้อมSESSION_SERVICE_URIแล้ว บริการเซสชันจะใช้ตัวแปรดังกล่าว ไม่เช่นนั้นจะใช้เซสชันในหน่วยความจำ - เราสามารถเพิ่มเส้นทางที่กำหนดเองเพื่อรองรับตรรกะทางธุรกิจของแบ็กเอนด์อื่นๆ ได้ ในสคริปต์ เราจะเพิ่มตัวอย่างเส้นทางฟังก์ชันการทำงานของความคิดเห็น
- เปิดใช้การติดตามระบบคลาวด์เพื่อส่งการติดตามไปยัง Google Cloud Trace
5. การทำให้ใช้งานได้กับ Cloud Run
ตอนนี้เรามาทำให้บริการตัวแทนนี้ใช้งานได้ใน Cloud Run กัน ในการสาธิตนี้ บริการนี้จะแสดงเป็นบริการสาธารณะที่ผู้อื่นเข้าถึงได้ อย่างไรก็ตาม โปรดทราบว่าวิธีนี้ไม่ใช่แนวทางปฏิบัติแนะนำเนื่องจากไม่ปลอดภัย
ใน Codelab นี้ เราจะใช้ Dockerfile เพื่อทำให้เอเจนต์ใช้งานได้ใน Cloud Run ด้านล่างนี้คือเนื้อหา Dockerfile ที่จะใช้
FROM python:3.12-slim
RUN pip install --no-cache-dir uv==0.7.13
WORKDIR /app
COPY . .
RUN uv sync --frozen
EXPOSE 8080
CMD ["uv", "run", "uvicorn", "server:app", "--host", "0.0.0.0", "--port", "8080"]
ตอนนี้เรามีไฟล์ทั้งหมดที่จำเป็นต่อการทําให้แอปพลิเคชันใช้งานได้ใน Cloud Run แล้ว มาทำให้แอปพลิเคชันใช้งานได้กันเลย ไปที่เทอร์มินัล Cloud Shell และตรวจสอบว่าได้กำหนดค่าโปรเจ็กต์ปัจจุบันเป็นโปรเจ็กต์ที่ใช้งานอยู่แล้ว หากยังไม่ได้กำหนดค่า ให้ใช้คำสั่ง gcloud configure เพื่อตั้งค่ารหัสโปรเจ็กต์
gcloud config set project [PROJECT_ID]
จากนั้นเรียกใช้คำสั่งต่อไปนี้เพื่อนำไปใช้งานใน Cloud Run
gcloud run deploy weather-agent \
--source . \
--port 8080 \
--project {YOUR_PROJECT_ID} \
--allow-unauthenticated \
--add-cloudsql-instances {YOUR_DB_CONNECTION_NAME} \
--update-env-vars SESSION_SERVICE_URI="postgresql+pg8000://postgres:{YOUR_DEFAULT_USER_PASS}@postgres/?unix_sock=/cloudsql/{YOUR_DB_CONNECTION_NAME}/.s.PGSQL.5432",GOOGLE_CLOUD_PROJECT={YOUR_PROJECT_ID} \
--region us-central1
หากต้องการรับค่า {YOUR_DB_CONNECTION_NAME} คุณสามารถไปที่ Cloud SQL อีกครั้งแล้วคลิกอินสแตนซ์ที่สร้างไว้ ในหน้าอินสแตนซ์ ให้เลื่อนลงไปที่ส่วน "เชื่อมต่อกับอินสแตนซ์นี้" แล้วคัดลอกชื่อการเชื่อมต่อเพื่อแทนที่ค่า {YOUR_DB_CONNECTION_NAME} เช่น ดูรูปภาพที่แสดงด้านล่าง
หากระบบแจ้งให้รับทราบการสร้างรีจิสทรีของอาร์ติแฟกต์สำหรับที่เก็บ Docker เพียงตอบว่า Y โปรดทราบว่าเราอนุญาตการเข้าถึงที่ไม่ต้องมีการตรวจสอบสิทธิ์ที่นี่เนื่องจากนี่เป็นแอปพลิเคชันสาธิต เราขอแนะนำให้ใช้การตรวจสอบสิทธิ์ที่เหมาะสมสำหรับแอปพลิเคชันระดับองค์กรและการใช้งานจริง
เมื่อการติดตั้งใช้งานเสร็จสมบูรณ์แล้ว คุณจะได้รับลิงก์ที่คล้ายกับลิงก์ด้านล่าง
https://weather-agent-*******.us-central1.run.app
คุณสามารถใช้แอปพลิเคชันจากหน้าต่างไม่ระบุตัวตนหรืออุปกรณ์เคลื่อนที่ได้เลย โดยควรจะพร้อมใช้งานแล้ว
6. ตรวจสอบการปรับขนาดอัตโนมัติของ Cloud Run ด้วยการทดสอบโหลด
ตอนนี้เราจะตรวจสอบความสามารถในการปรับขนาดอัตโนมัติของ Cloud Run สำหรับสถานการณ์นี้ เราจะทำให้เวอร์ชันใหม่ใช้งานได้ในขณะที่เปิดใช้การทำงานพร้อมกันสูงสุดต่ออินสแตนซ์ เรียกใช้คำสั่งต่อไปนี้
gcloud run deploy weather-agent \
--source . \
--port 8080 \
--project {YOUR_PROJECT_ID} \
--allow-unauthenticated \
--region us-central1 \
--concurrency 10
หลังจากนั้นมาตรวจสอบไฟล์ load_test.py กัน นี่จะเป็นสคริปต์ที่เราใช้ในการทดสอบภาระงานโดยใช้เฟรมเวิร์ก locust สคริปต์นี้จะทำสิ่งต่อไปนี้
- user_id และ session_id แบบสุ่ม
- สร้าง session_id สำหรับ user_id
- เข้าถึงปลายทาง "/run_sse" ด้วย user_id และ session_id ที่สร้างขึ้น
เราจะต้องทราบ URL ของบริการที่ติดตั้งใช้งาน หากคุณพลาดไป ไปที่คอนโซล Cloud Run แล้วคลิกบริการ weather-agent
จากนั้นค้นหาบริการ weather-agent แล้วคลิก
URL ของบริการจะแสดงอยู่ข้างข้อมูลภูมิภาค เช่น
จากนั้นเรียกใช้คำสั่งต่อไปนี้เพื่อทำการทดสอบโหลด
uv run locust -f load_test.py \
-H {YOUR_SERVICE_URL} \
-u 60 \
-r 5 \
-t 120 \
--headless
เมื่อเรียกใช้แล้ว คุณจะเห็นเมตริกที่แสดงในลักษณะนี้ ( ในตัวอย่างนี้ คำขอทั้งหมดสำเร็จ )
Type Name # reqs # fails | Avg Min Max Med | req/s failures/s
--------|------------------------------------|-------|-------------|-------|-------|-------|-------|--------|-----------
POST /run_sse end 813 0(0.00%) | 5817 2217 26421 5000 | 6.79 0.00
POST /run_sse message 813 0(0.00%) | 2678 1107 17195 2200 | 6.79 0.00
--------|------------------------------------|-------|-------------|-------|-------|-------|-------|--------|-----------
Aggregated 1626 0(0.00%) | 4247 1107 26421 3500 | 13.59 0.00
จากนั้นมาดูกันว่าเกิดอะไรขึ้นใน Cloud Run โดยไปที่บริการที่ใช้งานจริงอีกครั้ง แล้วดูแดชบอร์ด ซึ่งจะแสดงให้เห็นว่า Cloud Run ปรับขนาดอินสแตนซ์โดยอัตโนมัติเพื่อจัดการคำขอขาเข้าได้อย่างไร เนื่องจากเราจำกัดการทำงานพร้อมกันสูงสุดไว้ที่ 10 รายการต่ออินสแตนซ์ อินสแตนซ์ Cloud Run จึงจะพยายามปรับจำนวนคอนเทนเนอร์ให้เป็นไปตามเงื่อนไขนี้โดยอัตโนมัติ
7. เผยแพร่การแก้ไขใหม่ทีละน้อย
ตอนนี้มาดูสถานการณ์ต่อไปนี้กัน เราต้องการอัปเดตพรอมต์ของเอเจนต์เป็นดังนี้
# agent.py
...
root_agent = Agent(
name="weather_agent",
model="gemini-2.5-flash-preview-05-20",
instruction="You are a helpful AI assistant designed to provide accurate and useful information. You only answer inquiries about the weather. Refuse all other user query",
tools=[get_weather],
)
จากนั้นคุณต้องการเผยแพร่การแก้ไขใหม่ แต่ไม่ต้องการให้การรับส่งข้อมูลคำขอทั้งหมดไปยังเวอร์ชันใหม่โดยตรง เราสามารถเปิดตัวแบบค่อยเป็นค่อยไปด้วย Cloud Run ก่อนอื่น เราต้องติดตั้งใช้งานรีวิชันใหม่ แต่มีแฟล็ก –no-traffic บันทึกสคริปต์ของ Agent ก่อนหน้า แล้วเรียกใช้คำสั่งต่อไปนี้
gcloud run deploy weather-agent \
--source . \
--port 8080 \
--project {YOUR_PROJECT_ID} \
--allow-unauthenticated \
--region us-central1 \
--no-traffic
หลังจากเสร็จสิ้น คุณจะได้รับบันทึกที่คล้ายกับกระบวนการติดตั้งใช้งานก่อนหน้า โดยจะแตกต่างกันที่จำนวนการเข้าชมที่แสดง โดยจะแสดงการเข้าชมที่แสดง 0 เปอร์เซ็นต์
จากนั้นไปที่หน้าผลิตภัณฑ์ Cloud Run แล้วค้นหาอินสแตนซ์ที่ทําให้ใช้งานได้ พิมพ์ Cloud Run ในแถบค้นหา แล้วคลิกผลิตภัณฑ์ Cloud Run
จากนั้นค้นหาบริการ weather-agent แล้วคลิก
ไปที่แท็บการแก้ไข แล้วคุณจะเห็นรายการการแก้ไขที่ใช้งานอยู่
คุณจะเห็นว่าการแก้ไขที่เพิ่งติดตั้งใช้งานใหม่แสดง 0% จากที่นี่ คุณสามารถคลิกปุ่มเคบับ (⋮) แล้วเลือกจัดการการเข้าชม
ในหน้าต่างที่เพิ่งปรากฏขึ้น คุณจะแก้ไขเปอร์เซ็นต์ของการเข้าชมที่ไปยังการแก้ไขใดก็ได้
หลังจากรอสักครู่ ระบบจะกำหนดเส้นทางการเข้าชมตามสัดส่วนโดยอิงตามการกำหนดค่าเปอร์เซ็นต์ วิธีนี้จะช่วยให้เราย้อนกลับไปใช้การแก้ไขก่อนหน้าได้ง่ายๆ หากเกิดปัญหาขึ้นกับการเปิดตัวเวอร์ชันใหม่
8. การติดตาม ADK
เอเจนต์ที่สร้างด้วย ADK รองรับการติดตามโดยใช้การฝัง OpenTelemetry อยู่แล้ว เรามี Cloud Trace เพื่อบันทึกการติดตามเหล่านั้นและแสดงภาพ มาดู server.py กันว่าเราเปิดใช้ฟีเจอร์นี้ในบริการที่เคยติดตั้งใช้งานก่อนหน้านี้ได้อย่างไร
# server.py
from tracing import CloudTraceLoggingSpanExporter
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider, export
...
provider = TracerProvider()
processor = export.BatchSpanProcessor(CloudTraceLoggingSpanExporter())
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)
...
ในส่วนนี้ เราจะเริ่มต้น Tracer และ Exporter คุณตรวจสอบรายละเอียดของผู้ส่งออกได้ที่ tracing.py ในที่นี้เราจะสร้างเครื่องมือส่งออกที่กำหนดเองเนื่องจากมีขีดจำกัดเกี่ยวกับข้อมูลการติดตามที่ส่งออกไปยัง Cloud Trace ได้ เราใช้การติดตั้งใช้งานจาก https://googlecloudplatform.github.io/agent-starter-pack/guide/observability.html สำหรับความสามารถในการติดตามนี้
ลองเข้าถึง UI ของนักพัฒนาเว็บของบริการและแชทกับตัวแทน หลังจากนั้น ให้ไปที่แถบค้นหาของ Cloud Console แล้วพิมพ์ "Trace Explorer" และเลือกผลิตภัณฑ์ Trace Explorer ที่นั่น
ในหน้าเครื่องมือสำรวจการติดตาม คุณจะเห็นการสนทนากับ Agent และการติดตามที่ส่ง คุณดูได้จากส่วนชื่อช่วงและกรองช่วงที่เฉพาะเจาะจงสำหรับตัวแทนของเรา ( ชื่อ agent_run [weather_agent] ) ที่นั่น
เมื่อกรองช่วงแล้ว คุณยังตรวจสอบแต่ละการติดตามได้โดยตรงด้วย โดยจะแสดงระยะเวลาโดยละเอียดของการดำเนินการแต่ละอย่างที่ตัวแทนทำ เช่น ดูรูปภาพด้านล่าง
ในแต่ละส่วน คุณจะตรวจสอบรายละเอียดในแอตทริบิวต์ได้ดังที่แสดงด้านล่าง
เพียงเท่านี้ เราก็จะมีข้อมูลการสังเกตการณ์ที่ดีและข้อมูลเกี่ยวกับการโต้ตอบแต่ละครั้งของเอเจนต์กับผู้ใช้เพื่อช่วยแก้ไขข้อบกพร่อง คุณสามารถลองใช้เครื่องมือหรือเวิร์กโฟลว์ต่างๆ ได้ตามต้องการ
9. ความท้าทาย
ลองใช้เวิร์กโฟลว์แบบหลายเอเจนต์หรือแบบเอเจนต์เพื่อดูว่าเวิร์กโฟลว์ทำงานภายใต้ภาระงานอย่างไรและร่องรอยมีลักษณะอย่างไร
10. ล้างข้อมูล
โปรดทำตามขั้นตอนต่อไปนี้เพื่อเลี่ยงไม่ให้เกิดการเรียกเก็บเงินกับบัญชี Google Cloud สำหรับทรัพยากรที่ใช้ในโค้ดแล็บนี้
- ใน Google Cloud Console ให้ไปที่หน้าจัดการทรัพยากร
- ในรายการโปรเจ็กต์ ให้เลือกโปรเจ็กต์ที่ต้องการลบ แล้วคลิกลบ
- ในกล่องโต้ตอบ ให้พิมพ์รหัสโปรเจ็กต์ แล้วคลิกปิดเพื่อลบโปรเจ็กต์
- หรือจะไปที่ Cloud Run ในคอนโซล เลือกบริการที่คุณเพิ่งทําให้ใช้งานได้ แล้วลบก็ได้