ทำให้ใช้งานได้ จัดการ และตรวจสอบ ADK Agent ใน Cloud Run

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
ตั้งค่า Agent ของ ADK ขั้นพื้นฐาน
ตั้งค่าบริการเซสชันฐานข้อมูลเพื่อให้ ADK Runner ใช้
ทำให้ Agent ใช้งานได้กับ Cloud Run เป็นครั้งแรก
การทดสอบโหลดและการตรวจสอบการปรับขนาดอัตโนมัติของ Cloud Run
ทำให้การแก้ไข Agent ใหม่ใช้งานได้และค่อยๆ เพิ่มการเข้าชมไปยังการแก้ไขใหม่
ตั้งค่าการติดตามระบบคลาวด์และตรวจสอบการติดตามการเรียกใช้ 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. 🚀 เตรียมการตั้งค่าเวิร์กช็อป

หมายเหตุสำคัญ:

บทแนะนำนี้ต้องใช้โปรเจ็กต์ Google Cloud ที่มีบัญชีสำหรับการเรียกเก็บเงินที่ใช้งานอยู่ หากยังไม่มีบัญชี โปรดทำตามขั้นตอนด้านล่างเพื่อรับบัญชีสำหรับการเรียกเก็บเงินช่วงทดลองใช้ที่ใช้กับบทแนะนำนี้ได้

เปิดหน้าต่างที่ไม่ระบุตัวตน
หากเข้าร่วมเซสชันเวิร์กช็อป โดยปกติแล้ว URL ของพอร์ทัลการแลกรับข้อเสนอจะอยู่ในเซสชันดังกล่าว หรือคุณจะไปที่พอร์ทัลการแลกรับข้อเสนอสำหรับบัญชีการเรียกเก็บเงินแบบทดลองใช้นี้ก็ได้
เข้าสู่ระบบโดยใช้บัญชี Gmail ส่วนตัว ( Google Workspace / อีเมลอื่นๆ จะใช้ไม่ได้ )
ทำตามวิธีการแลกรับข้อเสนอแบบทีละขั้นตอนเพื่อสร้างโปรเจ็กต์ Google Cloud ใหม่ที่ลิงก์กับบัญชีสำหรับการเรียกเก็บเงินรุ่นทดลองที่อ้างสิทธิ์ไว้ก่อนหน้านี้สำหรับบทแนะนำนี้ให้สำเร็จ

ตอนนี้เราจะใช้ Cloud Shell IDE สำหรับบทแนะนำนี้ ให้คลิกปุ่มต่อไปนี้เพื่อไปยังที่นั่น

เมื่ออยู่ใน Cloud Shell แล้ว ให้โคลนไดเรกทอรีการทำงานของเทมเพลตสำหรับโค้ดแล็บนี้จาก Github โดยเรียกใช้คำสั่งต่อไปนี้ ซึ่งจะสร้างไดเรกทอรีการทำงานในไดเรกทอรี deploy_and_manage_adk

git clone https://github.com/alphinside/deploy-and-manage-adk-service.git deploy_and_manage_adk

จากนั้นเรียกใช้คำสั่งต่อไปนี้ในเทอร์มินัลเพื่อเปิดที่เก็บที่โคลนเป็นไดเรกทอรีการทำงาน

cloudshell workspace ~/deploy_and_manage_adk && cd ~/deploy_and_manage_adk

หลังจากนั้น อินเทอร์เฟซของคุณควรมีลักษณะคล้ายกับภาพนี้

นี่จะเป็นอินเทอร์เฟซหลักของเรา โดยมี IDE อยู่ด้านบนและเทอร์มินัลอยู่ด้านล่าง ตอนนี้เราต้องเตรียมเทอร์มินัลเพื่อสร้างและเปิดใช้งานโปรเจ็กต์ Google Cloud ซึ่งจะลิงก์กับบัญชีสำหรับการเรียกเก็บเงินแบบทดลองใช้ที่เราอ้างสิทธิ์ไปก่อนหน้านี้ เราได้เตรียมสคริปต์เพื่อให้คุณมั่นใจได้เสมอว่าเซสชันเทอร์มินัลพร้อมใช้งาน เรียกใช้คำสั่งต่อไปนี้ ( ตรวจสอบว่าคุณอยู่ในพื้นที่ทำงาน deploy_and_manage_adk แล้ว

bash setup_trial_project.sh && source .env

เมื่อเรียกใช้คำสั่งนี้ ระบบจะแจ้งให้คุณทราบชื่อรหัสโปรเจ็กต์ที่แนะนำ คุณสามารถกด Enter เพื่อดำเนินการต่อ

หลังจากรอสักครู่ หากคุณเห็นเอาต์พุตนี้ในคอนโซล แสดงว่าคุณพร้อมที่จะไปยังขั้นตอนถัดไปแล้ว

ซึ่งแสดงว่าเทอร์มินัลได้รับการตรวจสอบสิทธิ์แล้วและตั้งค่าเป็นรหัสโปรเจ็กต์ที่ถูกต้อง ( สีเหลืองข้างเส้นทางไดเรกทอรีปัจจุบัน) คำสั่งนี้จะช่วยคุณสร้างโปรเจ็กต์ใหม่ ค้นหาและลิงก์โปรเจ็กต์กับบัญชีการเรียกเก็บเงินแบบทดลอง เตรียมไฟล์ .env สำหรับการกำหนดค่าตัวแปรสภาพแวดล้อม และเปิดใช้งานรหัสโปรเจ็กต์ที่ถูกต้องในเทอร์มินัลให้คุณด้วย

ตอนนี้เราพร้อมที่จะดำเนินการในขั้นตอนถัดไปแล้ว

3. 🚀 การเปิดใช้ API

ในบทแนะนำนี้ เราจะโต้ตอบกับฐานข้อมูล CloudSQL, โมเดล Gemini และ Cloud Run โดยผลิตภัณฑ์เหล่านี้จะต้องเปิดใช้งาน API ต่อไปนี้ เรียกใช้คำสั่งเหล่านี้เพื่อเปิดใช้

อาจใช้เวลาสักครู่

gcloud services enable aiplatform.googleapis.com \
                       run.googleapis.com \
                       cloudbuild.googleapis.com \
                       cloudresourcemanager.googleapis.com \
                       sqladmin.googleapis.com \
                       compute.googleapis.com

เมื่อเรียกใช้คำสั่งสำเร็จ คุณควรเห็นข้อความที่คล้ายกับข้อความที่แสดงด้านล่าง

Operation "operations/..." finished successfully.

4. 🚀 การตั้งค่าสภาพแวดล้อม Python และตัวแปรสภาพแวดล้อม

เราจะใช้ Python 3.12 ในโค้ดแล็บนี้ และจะใช้ตัวจัดการโปรเจ็กต์ Python ของ uv เพื่อลดความจำเป็นในการสร้างและจัดการเวอร์ชัน Python และสภาพแวดล้อมเสมือน แพ็กเกจ uv ได้รับการติดตั้งล่วงหน้าใน Cloud Shell แล้ว

เรียกใช้คำสั่งนี้เพื่อติดตั้งการอ้างอิงที่จำเป็นลงในสภาพแวดล้อมเสมือนในไดเรกทอรี .venv

uv sync --frozen

จากนั้นเราจะตรวจสอบไฟล์ตัวแปรสภาพแวดล้อมที่จำเป็นสำหรับโปรเจ็กต์นี้ ก่อนหน้านี้สคริปต์ setup_trial_project.sh เป็นผู้ตั้งค่าไฟล์นี้ เรียกใช้คำสั่งต่อไปนี้เพื่อเปิดไฟล์ .env ในโปรแกรมแก้ไข

cloudshell open .env

คุณจะเห็นการกำหนดค่าต่อไปนี้ที่ใช้กับไฟล์ .env อยู่แล้ว

# .env

# 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
# DB_CONNECTION_NAME=your-db-connection-name

สำหรับ Codelab นี้ เราจะใช้ค่าที่กำหนดค่าไว้ล่วงหน้าสำหรับ GOOGLE_CLOUD_LOCATION และ GOOGLE_GENAI_USE_VERTEXAI.

ตอนนี้เราสามารถไปยังขั้นตอนถัดไปได้แล้ว นั่นคือการสร้างฐานข้อมูลที่เอเจนต์จะใช้เพื่อความคงทนของสถานะและเซสชัน

5. 🚀 เตรียมฐานข้อมูล CloudSQL

เราจะต้องมีฐานข้อมูลที่ตัวแทน ADK จะใช้ในภายหลัง มาสร้างฐานข้อมูล PostgreSQL ใน Cloud SQL กัน เรียกใช้คำสั่งต่อไปนี้เพื่อสร้างอินสแตนซ์ฐานข้อมูลก่อน เราจะใช้ชื่อฐานข้อมูล postgres เริ่มต้น ดังนั้นเราจะข้ามการสร้างฐานข้อมูลในที่นี้ นอกจากนี้ เรายังต้องกำหนดค่าชื่อผู้ใช้ฐานข้อมูลเริ่มต้นด้วย (postgres เช่นกัน) เพื่อให้บทแนะนำนี้สมบูรณ์ เราจะใช้ ADK-deployment123 เป็นรหัสผ่าน

gcloud sql instances create adk-deployment \
  --database-version=POSTGRES_17 \
  --edition=ENTERPRISE \
  --tier=db-g1-small \
  --region=us-central1 \
  --availability-type=ZONAL \
  --project=${GOOGLE_CLOUD_PROJECT} && \
gcloud sql users set-password postgres \
  --instance=adk-deployment \
  --password=ADK-deployment123

ในคำสั่งข้างต้น gcloud sql instances create adk-deployment แรกคือคำสั่งที่เราใช้เพื่อสร้างอินสแตนซ์ฐานข้อมูล เราใช้ข้อกำหนดขั้นต่ำของแซนด์บ็อกซ์เพื่อประโยชน์ของบทแนะนำนี้ คำสั่งที่ 2 gcloud sql users set-password postgres ใช้เพื่อเปลี่ยนรหัสผ่านชื่อผู้ใช้เริ่มต้น postgres

โปรดทราบว่าเราใช้ adk-deployment เป็นชื่ออินสแตนซ์ฐานข้อมูล เมื่อเสร็จแล้ว คุณควรเห็นเอาต์พุตในเทอร์มินัลตามที่แสดงด้านล่าง ซึ่งแสดงว่าอินสแตนซ์พร้อมใช้งานและมีการอัปเดตรหัสผ่านของผู้ใช้เริ่มต้นแล้ว

Created [https://sqladmin.googleapis.com/sql/v1beta4/projects/your-project-id/instances/adk-deployment].
NAME: adk-deployment
DATABASE_VERSION: POSTGRES_17
LOCATION: us-central1-a
TIER: db-g1-small
PRIMARY_ADDRESS: xx.xx.xx.xx
PRIVATE_ADDRESS: -
STATUS: RUNNABLE
Updating Cloud SQL user...done.

เนื่องจากการติดตั้งใช้งานฐานข้อมูลนี้จะต้องใช้เวลาสักครู่ เรามาต่อกันที่ส่วนถัดไปในขณะที่รอให้การติดตั้งใช้งานฐานข้อมูล CloudSQL พร้อมใช้งาน

6. 🚀 สร้าง Weather Agent ด้วย ADK และ Gemini 2.5

ข้อมูลเบื้องต้นเกี่ยวกับโครงสร้างไดเรกทอรี ADK

มาเริ่มสำรวจสิ่งที่ ADK มีให้และวิธีสร้าง Agent กัน คุณเข้าถึงเอกสารประกอบ ADK ฉบับสมบูรณ์ได้ใน URL นี้ ADK มีเครื่องมือมากมายให้เราใช้ในการเรียกใช้คำสั่ง CLI ตัวอย่างเช่น

ตั้งค่าโครงสร้างไดเรกทอรีของ Agent
ลองโต้ตอบอย่างรวดเร็วผ่านอินพุตเอาต์พุต CLI
ตั้งค่าอินเทอร์เฟซเว็บ UI การพัฒนาในเครื่องอย่างรวดเร็ว

ตอนนี้เรามาตรวจสอบโครงสร้างของ Agent ในไดเรกทอรี weather_agent กัน

weather_agent/
├── __init__.py
├── agent.py
└── tool.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 weather_agent.tool import get_weather

# 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")

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 บนเว็บในเครื่อง

ตอนนี้เราสามารถโต้ตอบกับ Agent และตรวจสอบลักษณะการทำงานของ Agent ในเครื่องได้แล้ว 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 เพื่อให้เรามีการติดตามคำขอทั้งหมดแบบรวมศูนย์

7. 🚀 การทำให้ใช้งานได้กับ Cloud Run

ตอนนี้เรามาทำให้บริการตัวแทนนี้ใช้งานได้ใน Cloud Run กัน ในการสาธิตนี้ บริการนี้จะแสดงเป็นบริการสาธารณะที่ผู้อื่นเข้าถึงได้ อย่างไรก็ตาม โปรดทราบว่านี่ไม่ใช่แนวทางปฏิบัติแนะนำเนื่องจากไม่ปลอดภัย

สถานการณ์การติดตั้งใช้งานนี้ช่วยให้คุณปรับแต่งบริการแบ็กเอนด์ของเอเจนต์ได้ โดยเราจะใช้ Dockerfile เพื่อติดตั้งใช้งานเอเจนต์ใน Cloud Run ตอนนี้เรามีไฟล์ทั้งหมดที่จำเป็น ( Dockerfile และ server.py) เพื่อทำให้แอปพลิเคชันใช้งานได้ใน Cloud Run แล้ว เมื่อมี 2 รายการนี้ คุณจะปรับแต่งการติดตั้งใช้งานเอเจนต์ได้อย่างยืดหยุ่น ( เช่น การเพิ่มเส้นทางแบ็กเอนด์ที่กำหนดเอง และ/หรือการเพิ่มบริการ Sidecar เพิ่มเติมเพื่อวัตถุประสงค์ในการตรวจสอบ) เราจะพูดถึงเรื่องนี้อย่างละเอียดในภายหลัง

ตอนนี้มาทำให้บริการใช้งานได้ก่อน ไปที่เทอร์มินัล Cloud Shell และตรวจสอบว่าโปรเจ็กต์ปัจจุบันได้รับการกำหนดค่าเป็นโปรเจ็กต์ที่ใช้งานอยู่แล้ว จากนั้นเรียกใช้สคริปต์การตั้งค่าอีกครั้ง หรือคุณจะใช้คำสั่ง gcloud config set project [PROJECT_ID] เพื่อกำหนดค่าโปรเจ็กต์ที่ใช้งานอยู่ก็ได้

bash setup_trial_project.sh && source .env

ตอนนี้เราต้องกลับไปที่ไฟล์ .env อีกครั้ง เปิดไฟล์ แล้วคุณจะเห็นว่าเราต้องยกเลิกการแสดงความคิดเห็นของตัวแปร DB_CONNECTION_NAME และกรอกค่าที่ถูกต้อง

# 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
DB_CONNECTION_NAME=your-db-connection-name

หากต้องการรับค่า DB_CONNECTION_NAME ให้ไปที่แดชบอร์ด Cloud SQL

จากนั้นคลิกอินสแตนซ์ที่คุณสร้าง ไปที่แถบค้นหาในส่วนบนของคอนโซลระบบคลาวด์ แล้วพิมพ์ "Cloud SQL" จากนั้นคลิกผลิตภัณฑ์ Cloud SQL

หลังจากนั้นคุณจะเห็นอินสแตนซ์ที่สร้างไว้ก่อนหน้านี้ ให้คลิกอินสแตนซ์นั้น

ในหน้าอินสแตนซ์ ให้เลื่อนลงไปที่ส่วน "เชื่อมต่อกับอินสแตนซ์นี้" แล้วคัดลอกชื่อการเชื่อมต่อเพื่อแทนที่ค่า DB_CONNECTION_NAME

หลังจากนั้น ให้เปิดไฟล์ .env ด้วยคำสั่งต่อไปนี้

cloudshell edit .env

และแก้ไขตัวแปร DB_CONNECTION_NAME ในไฟล์ .env ไฟล์ env ควรมีลักษณะดังตัวอย่างด้านล่าง

# 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
DB_CONNECTION_NAME=your-project-id:your-location:your-instance-name

หลังจากนั้น ให้เรียกใช้สคริปต์การติดตั้งใช้งาน

bash deploy_to_cloudrun.sh

หากระบบแจ้งให้รับทราบการสร้างรีจิสทรีของ Artifact สำหรับที่เก็บ Docker เพียงตอบว่า Y

ในระหว่างที่รอขั้นตอนการติดตั้งใช้งาน เรามาดู deploy_to_cloudrun.sh กัน

#!/bin/bash

# Load environment variables from .env file
if [ -f .env ]; then
    export $(cat .env | grep -v '^#' | xargs)
else
    echo "Error: .env file not found"
    exit 1
fi

# Validate required variables
required_vars=("GOOGLE_CLOUD_PROJECT" "DB_CONNECTION_NAME")
for var in "${required_vars[@]}"; do
    if [ -z "${!var}" ]; then
        echo "Error: $var is not set in .env file"
        exit 1
    fi
done

gcloud run deploy weather-agent \
    --source . \
    --port 8080 \
    --project ${GOOGLE_CLOUD_PROJECT} \
    --allow-unauthenticated \
    --add-cloudsql-instances ${DB_CONNECTION_NAME} \
    --update-env-vars SESSION_SERVICE_URI="postgresql+pg8000://postgres:ADK-deployment123@postgres/?unix_sock=/cloudsql/${DB_CONNECTION_NAME}/.s.PGSQL.5432",GOOGLE_CLOUD_PROJECT=${GOOGLE_CLOUD_PROJECT} \
    --region us-central1 \
    --min 1 \
    --memory 1G \
    --concurrency 10

สคริปต์นี้จะโหลดตัวแปร .env จากนั้นเรียกใช้คำสั่งการติดตั้งใช้งาน

หากพิจารณาอย่างละเอียดแล้ว เราจะเห็นว่าเราต้องการคำสั่ง gcloud run deploy เพียงคำสั่งเดียวเพื่อทำสิ่งจำเป็นทั้งหมดที่ต้องดำเนินการหากต้องการติดตั้งใช้งานบริการ ได้แก่ การสร้างอิมเมจ การพุชไปยังรีจิสทรี การติดตั้งใช้งานบริการ การตั้งค่านโยบาย IAM การสร้างรีวิชัน และแม้แต่การกำหนดเส้นทางการรับส่งข้อมูล ในตัวอย่างนี้ เราได้ระบุ Dockerfile ไว้แล้ว ดังนั้นคำสั่งนี้จะใช้ Dockerfile เพื่อสร้างแอป

หมายเหตุ: ในสคริปต์การติดตั้งใช้งาน เราจะตั้งค่าตัวแปรสภาพแวดล้อม SESSION_SERVICE_URI หากตั้งค่าตัวแปรนี้ไว้ เอเจนต์ ADK จะใช้ URI สำหรับบริการเพื่อจัดเก็บข้อมูลเซสชันและสถานะ (กำหนดไว้ใน server.py) ในบทแนะนำนี้ เราจะใช้การเชื่อมต่อซ็อกเก็ต Unix ของ PostgreSQL กับไดรเวอร์ pg8000

โปรดทราบว่าในตัวอย่าง เราใช้ผู้ใช้เริ่มต้น postgres และฐานข้อมูลเริ่มต้น postgres (ที่มีรหัสผ่าน ADK-deployment123)

เมื่อการติดตั้งใช้งานเสร็จสมบูรณ์แล้ว คุณจะได้รับลิงก์ที่คล้ายกับลิงก์ด้านล่าง

https://weather-agent-*******.us-central1.run.app

หลังจากได้รับ URL นี้แล้ว คุณจะใช้แอปพลิเคชันจากหน้าต่างโหมดไม่ระบุตัวตนหรืออุปกรณ์เคลื่อนที่ และเข้าถึง UI สำหรับนักพัฒนาซอฟต์แวร์ของเอเจนต์ได้ ในระหว่างรอการติดตั้งใช้งาน เรามาดูบริการโดยละเอียดที่เราเพิ่งติดตั้งใช้งานในส่วนถัดไปกัน

8. 💡 Dockerfile และสคริปต์เซิร์ฟเวอร์แบ็กเอนด์

เพื่อให้เข้าถึง Agent เป็นบริการได้ เราจะห่อหุ้ม Agent ไว้ภายในแอป FastAPI ซึ่งจะเรียกใช้ในคำสั่ง Dockerfile ด้านล่างนี้คือเนื้อหาของ 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"]

เราสามารถกำหนดค่าบริการที่จำเป็นเพื่อรองรับเอเจนต์ได้ที่นี่ เช่น การเตรียมบริการ 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


# 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, "trace_to_cloud": 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",
    )

# 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 = ""


# Example if you want to add your custom endpoint
@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 บริการเซสชันจะใช้ตัวแปรดังกล่าว ไม่เช่นนั้นจะใช้เซสชันในหน่วยความจำ
เราสามารถเพิ่มเส้นทางที่กำหนดเองเพื่อรองรับตรรกะทางธุรกิจของแบ็กเอนด์อื่นๆ ได้ ในสคริปต์ เราจะเพิ่มตัวอย่างเส้นทางฟังก์ชันการทำงานของความคิดเห็น
เปิดใช้การติดตามระบบคลาวด์ในพารามิเตอร์ get_fast_api_app arg เพื่อส่งการติดตามไปยัง Google Cloud Trace
เรียกใช้บริการ FastAPI โดยใช้ Uvicorn

ตอนนี้หากการติดตั้งใช้งานเสร็จสมบูรณ์แล้ว โปรดลองโต้ตอบกับตัวแทนจาก UI สำหรับนักพัฒนาเว็บโดยเข้าถึง URL ของ Cloud Run

9. 🚀 ตรวจสอบการปรับขนาดอัตโนมัติของ Cloud Run ด้วยการทดสอบโหลด

ตอนนี้เราจะตรวจสอบความสามารถในการปรับขนาดอัตโนมัติของ Cloud Run สำหรับสถานการณ์นี้ เราจะทำให้เวอร์ชันใหม่ใช้งานได้ในขณะที่เปิดใช้การทำงานพร้อมกันสูงสุดต่ออินสแตนซ์ ในส่วนก่อนหน้า เราตั้งค่าการทำงานพร้อมกันสูงสุดเป็น 10 ( แฟล็ก --concurrency 10 ) ดังนั้นเราจึงคาดหวังได้ว่า Cloud Run จะพยายามปรับขนาดอินสแตนซ์เมื่อเราทำการทดสอบโหลดที่เกินจำนวนนี้

มาตรวจสอบไฟล์ load_test.py กัน นี่จะเป็นสคริปต์ที่เราใช้ในการทดสอบภาระงานโดยใช้เฟรมเวิร์ก locust สคริปต์นี้จะทำสิ่งต่อไปนี้

user_id และ session_id แบบสุ่ม
สร้าง session_id สำหรับ user_id
เรียกใช้ปลายทาง "/run_sse" ด้วย user_id และ session_id ที่สร้างขึ้น

เราจะต้องทราบ URL ของบริการที่ติดตั้งใช้งาน หากคุณพลาดไป เราสามารถไปที่คอนโซล Cloud Run

จากนั้นค้นหาบริการ weather-agent แล้วคลิก

URL ของบริการจะแสดงอยู่ข้างข้อมูลภูมิภาค เช่น

เราจะเรียกใช้สคริปต์ต่อไปนี้เพื่อรับ URL ของบริการที่เพิ่งติดตั้งใช้งานและจัดเก็บไว้ในตัวแปรสภาพแวดล้อม SERVICE_URL เพื่อให้คุณใช้งานได้ง่ายขึ้น

export SERVICE_URL=$(gcloud run services describe weather-agent \
    --platform managed \
    --region us-central1 \
    --format 'value(status.url)')

จากนั้นเรียกใช้คำสั่งต่อไปนี้เพื่อทดสอบการโหลดแอปตัวแทนของเรา

uv run locust -f load_test.py \
              -H $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 จึงจะพยายามปรับจำนวนคอนเทนเนอร์ให้เป็นไปตามเงื่อนไขนี้โดยอัตโนมัติ

10. 🚀 การเปิดตัวการแก้ไขใหม่แบบค่อยเป็นค่อยไป

ลองพิจารณาสถานการณ์ต่อไปนี้ เราต้องการอัปเดตพรอมต์ของเอเจนต์ เปิด weather_agent/agent.py ด้วยคำสั่งต่อไปนี้

cloudshell edit weather_agent/agent.py

และเขียนทับด้วยโค้ดต่อไปนี้

# weather_agent/agent.py

import os
from pathlib import Path

import google.auth
from dotenv import load_dotenv
from google.adk.agents import Agent
from weather_agent.tool import get_weather

# 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")

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.
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 $GOOGLE_CLOUD_PROJECT \
                  --allow-unauthenticated \
                  --region us-central1 \
                  --no-traffic

หลังจากเสร็จสิ้น คุณจะได้รับบันทึกที่คล้ายกับกระบวนการติดตั้งใช้งานก่อนหน้า โดยจะแตกต่างกันที่จำนวนการเข้าชมที่แสดง โดยจะแสดงการเข้าชมที่แสดงเป็น 0 เปอร์เซ็นต์

Service [weather-agent] revision [weather-agent-xxxx-xxx] has been deployed and is serving 0 percent of traffic.

จากนั้นไปที่แดชบอร์ด Cloud Run

จากนั้นค้นหาบริการ weather-agent แล้วคลิก

ไปที่แท็บการแก้ไข แล้วคุณจะเห็นรายการการแก้ไขที่ใช้งานอยู่

คุณจะเห็นว่าการแก้ไขที่เพิ่งติดตั้งใช้งานใหม่แสดง 0% จากที่นี่ คุณสามารถคลิกปุ่มเคบับ (⋮) แล้วเลือกจัดการการเข้าชม

ในหน้าต่างที่เพิ่งปรากฏขึ้น คุณจะแก้ไขเปอร์เซ็นต์ของการเข้าชมที่ไปยังการแก้ไขใดก็ได้

หลังจากรอสักครู่ ระบบจะกำหนดเส้นทางการเข้าชมตามสัดส่วนโดยอิงตามการกำหนดค่าเปอร์เซ็นต์ ด้วยวิธีนี้ เราจึงสามารถย้อนกลับไปใช้การแก้ไขก่อนหน้าได้อย่างง่ายดายหากเกิดปัญหาขึ้นกับการเปิดตัวเวอร์ชันใหม่

11. 🚀 การติดตาม ADK

เอเจนต์ที่สร้างด้วย ADK รองรับการติดตามโดยใช้การฝัง OpenTelemetry อยู่แล้ว เรามี Cloud Trace เพื่อบันทึกการติดตามเหล่านั้นและแสดงภาพ มาดู server.py กันว่าเราเปิดใช้ฟีเจอร์นี้ในบริการที่ติดตั้งใช้งานก่อนหน้านี้ได้อย่างไร

# server.py

...

app_args = {"agents_dir": AGENT_DIR, "web": True, "trace_to_cloud": True}

...

app: FastAPI = get_fast_api_app(**app_args)

...

ในที่นี้ เราจะส่งอาร์กิวเมนต์ trace_to_cloud ไปยัง True หากคุณติดตั้งใช้งานด้วยตัวเลือกอื่นๆ โปรดดูรายละเอียดเพิ่มเติมเกี่ยวกับวิธีเปิดใช้การติดตามไปยัง Cloud Trace จากตัวเลือกการติดตั้งใช้งานต่างๆ ได้ในเอกสารประกอบนี้

ลองเข้าถึง UI ของนักพัฒนาเว็บของบริการและแชทกับตัวแทน หลังจากนั้น ให้ไปที่หน้าเครื่องมือสำรวจการติดตาม

ในหน้าเครื่องมือสำรวจการติดตาม คุณจะเห็นว่าเราได้ส่งการติดตามการสนทนากับตัวแทนแล้ว คุณดูได้จากส่วนชื่อช่วง และกรองช่วงที่เฉพาะเจาะจงสำหรับตัวแทนของเรา ( ชื่อคือ agent_run [weather_agent] ) ที่นั่น

เมื่อกรองช่วงแล้ว คุณยังตรวจสอบแต่ละการติดตามได้โดยตรงด้วย โดยจะแสดงระยะเวลาโดยละเอียดของการดำเนินการแต่ละอย่างที่ตัวแทนทำ เช่น ดูรูปภาพด้านล่าง

ในแต่ละส่วน คุณจะตรวจสอบรายละเอียดในแอตทริบิวต์ได้ดังที่แสดงด้านล่าง

เพียงเท่านี้ เราก็จะมีข้อมูลการสังเกตการณ์ที่ดีและข้อมูลเกี่ยวกับการโต้ตอบแต่ละครั้งของเอเจนต์กับผู้ใช้เพื่อช่วยแก้ไขข้อบกพร่อง คุณสามารถลองใช้เครื่องมือหรือเวิร์กโฟลว์ต่างๆ ได้

12. 🎯 ความท้าทาย

ลองใช้เวิร์กโฟลว์แบบหลายเอเจนต์หรือแบบเอเจนต์เพื่อดูว่าเวิร์กโฟลว์ทำงานภายใต้ภาระงานอย่างไรและร่องรอยมีลักษณะอย่างไร

13. 🧹 ล้างข้อมูล

โปรดทำตามขั้นตอนต่อไปนี้เพื่อเลี่ยงไม่ให้เกิดการเรียกเก็บเงินกับบัญชี Google Cloud สำหรับทรัพยากรที่ใช้ในโค้ดแล็บนี้

ใน Google Cloud Console ให้ไปที่หน้าจัดการทรัพยากร
ในรายการโปรเจ็กต์ ให้เลือกโปรเจ็กต์ที่ต้องการลบ แล้วคลิกลบ
ในกล่องโต้ตอบ ให้พิมพ์รหัสโปรเจ็กต์ แล้วคลิกปิดเพื่อลบโปรเจ็กต์
หรือคุณจะไปที่ Cloud Run ในคอนโซล เลือกบริการที่คุณเพิ่งติดตั้งใช้งาน แล้วลบก็ได้