หน้านี้ได้รับการแปลโดย Cloud Translation API

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

1. บทนำ

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

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

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

บทแนะนำนี้จะแนะนำวิธีติดตั้งใช้งาน จัดการ และตรวจสอบเอเจนต์ที่มีประสิทธิภาพซึ่งสร้างด้วย 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 ใหม่ใช้งานได้และค่อยๆ เพิ่มการเข้าชมไปยังการแก้ไขใหม่
ตั้งค่าการติดตามระบบคลาวด์และตรวจสอบการติดตามการเรียกใช้ 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. 🚀 เตรียมการตั้งค่าการพัฒนาเวิร์กช็อป

ขั้นตอนที่ 1: เลือกโปรเจ็กต์ที่ใช้งานอยู่ใน Cloud Console

ในคอนโซล Google Cloud ให้เลือกหรือสร้างโปรเจ็กต์ Google Cloud ในหน้าตัวเลือกโปรเจ็กต์ (ดูส่วนบนซ้ายของคอนโซล)

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

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

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

หากเห็น "บัญชีสำหรับการเรียกเก็บเงินของรุ่นทดลองใช้ Google Cloud Platform" ในส่วนหัวการเรียกเก็บเงิน / ภาพรวม ( ส่วนบนซ้ายของ Cloud Console) แสดงว่าโปรเจ็กต์พร้อมใช้งานสำหรับบทแนะนำนี้แล้ว หากยังไม่ได้ดำเนินการ ให้กลับไปที่จุดเริ่มต้นของบทแนะนำนี้และแลกรับบัญชีสำหรับการเรียกเก็บเงินช่วงทดลองใช้

ขั้นตอนที่ 2: เตรียมฐานข้อมูล Cloud SQL

เราจะต้องมีฐานข้อมูลที่ตัวแทน ADK จะใช้ในภายหลัง มาสร้างฐานข้อมูล PostgreSQL ใน Cloud SQL กัน ก่อนอื่น ให้ไปที่แถบค้นหาในส่วนบนของคอนโซลระบบคลาวด์ แล้วพิมพ์ "cloud sql" จากนั้นคลิกผลิตภัณฑ์ Cloud SQL

หลังจากนั้น เราจะต้องสร้างอินสแตนซ์ฐานข้อมูลใหม่ คลิกสร้างอินสแตนซ์ แล้วเลือก PostgreSQL

นอกจากนี้ คุณอาจต้องเปิดใช้ Compute Engine API หากเริ่มต้นด้วยโปรเจ็กต์ใหม่ เพียงคลิกเปิดใช้ API หากข้อความนี้ปรากฏขึ้น

จากนั้นเราจะเลือกข้อกำหนดของฐานข้อมูล เลือกฉบับEnterprise ที่ตั้งค่าล่วงหน้าเป็นฉบับSandbox

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

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

ในระหว่างที่รอให้การดำเนินการนี้เสร็จสิ้น เราสามารถไปยังส่วนถัดไปได้

ขั้นตอนที่ 3: ทำความคุ้นเคยกับ Cloud Shell

คุณจะใช้ Cloud Shell ในบทแนะนำส่วนใหญ่ คลิก "เปิดใช้งาน Cloud Shell" ที่ด้านบนของคอนโซล Google Cloud หากระบบแจ้งให้คุณให้สิทธิ์ ให้คลิกให้สิทธิ์

เมื่อเชื่อมต่อกับ Cloud Shell แล้ว เราจะต้องตรวจสอบว่า Shell ( หรือเทอร์มินัล) ได้รับการตรวจสอบสิทธิ์ด้วยบัญชีของเราแล้วหรือไม่

gcloud auth list

หากเห็น Gmail ส่วนตัวของคุณเหมือนเอาต์พุตตัวอย่างด้านล่าง แสดงว่าทุกอย่างเรียบร้อยดี

Credentialed Accounts

ACTIVE: *
ACCOUNT: alvinprayuda@gmail.com

To set the active account, run:
    $ gcloud config set account `ACCOUNT`

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

จากนั้นเรายังต้องตรวจสอบด้วยว่ามีการกำหนดค่า Shell ให้กับ PROJECT ID ที่ถูกต้องแล้วหรือไม่ หากคุณเห็นว่ามีค่าอยู่ภายใน ( ) ก่อนไอคอน $ ในเทอร์มินัล ( ในภาพหน้าจอด้านล่าง ค่าคือ "adk-cloudrun-deployment-476504") ค่านี้จะแสดงโปรเจ็กต์ที่กำหนดค่าไว้สำหรับเซสชัน Shell ที่ใช้งานอยู่

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

gcloud config set project <YOUR_PROJECT_ID>

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

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

ขั้นตอนที่ 4: ทำความคุ้นเคยกับ Cloud Shell Editor และตั้งค่าไดเรกทอรีการทำงานของแอปพลิเคชัน

ตอนนี้เราสามารถตั้งค่าโปรแกรมแก้ไขโค้ดเพื่อเขียนโค้ดได้แล้ว เราจะใช้ Cloud Shell Editor สำหรับการดำเนินการนี้

คลิกปุ่มเปิดตัวแก้ไข ซึ่งจะเปิด Cloud Shell Editor

หลังจากนั้น ให้ไปที่ส่วนบนของ Cloud Shell Editor แล้วคลิกไฟล์->เปิดโฟลเดอร์ ค้นหาไดเรกทอรี username แล้วค้นหาไดเรกทอรี deploy_and_manage_adk จากนั้นคลิกปุ่ม OK ซึ่งจะทำให้ไดเรกทอรีที่เลือกเป็นไดเรกทอรีการทำงานหลัก ในตัวอย่างนี้ ชื่อผู้ใช้คือ alvinprayuda ดังนั้นเส้นทางไดเรกทอรีจึงแสดงอยู่ด้านล่าง

ตอนนี้ไดเรกทอรีการทำงานของ Cloud Shell Editor ควรมีลักษณะดังนี้ ( ภายใน deploy_and_manage_adk)

ตอนนี้ให้เปิดเทอร์มินัลสำหรับเครื่องมือแก้ไข โดยคลิกเทอร์มินัล -> เทอร์มินัลใหม่ในแถบเมนู หรือใช้ Ctrl + Shift + C ซึ่งจะเปิดหน้าต่างเทอร์มินัลที่ส่วนล่างของเบราว์เซอร์

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

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

uv sync --frozen

ตอนนี้เราจะต้องเปิดใช้ API ที่จำเป็นผ่านคำสั่งที่แสดงด้านล่าง อาจใช้เวลาสักครู่

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

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

Operation "operations/..." finished successfully.

จากนั้นเราจะต้องตั้งค่าไฟล์การกำหนดค่าสำหรับโปรเจ็กต์นี้

เปลี่ยนชื่อไฟล์ .env.example เป็น .env

cp .env.example .env

เปิดไฟล์ .env แล้วอัปเดตค่า GOOGLE_CLOUD_PROJECT เป็น project-id

# .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

สำหรับโค้ดแล็บนี้ เราจะใช้ค่าที่กำหนดค่าไว้ล่วงหน้าสำหรับ GOOGLE_CLOUD_LOCATION และ GOOGLE_GENAI_USE_VERTEXAI. ส่วน DB_CONNECTION_NAME เราจะใส่เครื่องหมายความคิดเห็นไว้ก่อน

ตอนนี้เราสามารถไปยังขั้นตอนถัดไป ตรวจสอบตรรกะของเอเจนต์ และติดตั้งใช้งานได้แล้ว

3. 🚀 สร้างเอเจนต์สภาพอากาศด้วย ADK และ Gemini 2.5

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

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

ตั้งค่าโครงสร้างไดเรกทอรีของเอเจนต์
ลองโต้ตอบอย่างรวดเร็วผ่านอินพุตเอาต์พุตของ 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 บนเว็บ

ตอนนี้เราสามารถโต้ตอบกับเอเจนต์และตรวจสอบลักษณะการทำงานของเอเจนต์ในเครื่องได้แล้ว 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. 🚀 การทำให้ใช้งานได้กับ Cloud Run

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

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

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

gcloud config set project [PROJECT_ID]

ตอนนี้เราต้องกลับไปที่ไฟล์ .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 แล้วแก้ไขตัวแปร DB_CONNECTION_NAME ไฟล์ 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 สำหรับนักพัฒนาซอฟต์แวร์ของเอเจนต์ได้ ในระหว่างรอการติดตั้งใช้งาน เรามาดูรายละเอียดบริการที่เราเพิ่งติดตั้งใช้งานในส่วนถัดไปกัน

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

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

6. 🚀 ตรวจสอบการปรับขนาดอัตโนมัติของ 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

จากนั้นค้นหาบริการ 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. 🚀 ค่อยๆ เปิดตัวการแก้ไขใหม่

มาดูสถานการณ์ต่อไปนี้กัน เราต้องการอัปเดตพรอมต์ของเอเจนต์ เปิด 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 {YOUR_PROJECT_ID} \
                  --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 แล้วค้นหาอินสแตนซ์ที่ทําให้ใช้งานได้ พิมพ์ Cloud Run ในแถบค้นหา แล้วคลิกผลิตภัณฑ์ Cloud Run

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

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

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

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

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

8. 🚀 การติดตาม 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 ของนักพัฒนาเว็บของบริการและแชทกับตัวแทน หลังจากนั้น ให้ไปที่แถบค้นหาของ Cloud Console แล้วพิมพ์ "Trace Explorer" และเลือกผลิตภัณฑ์ Trace Explorer ที่นั่น

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

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

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

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

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

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

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

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

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