Google ใช้เทคโนโลยี AI เพื่อแปลเนื้อหาเป็นภาษาที่คุณต้องการ การแปลโดย AI อาจมีข้อผิดพลาด

สร้างและติดตั้งใช้งานเอเจนต์ ADK ใน Cloud Run

1. บทนำ

แล็บนี้มุ่งเน้นที่การติดตั้งใช้งานและการติดตั้งบริการตัวแทนไคลเอ็นต์ คุณจะใช้ Agent Development Kit (ADK) เพื่อสร้าง AI Agent ที่ใช้เครื่องมือ

ในห้องทดลองนี้ เราจะสร้างเอเจนต์สวนสัตว์ที่ใช้ Wikipedia เพื่อตอบคำถามเกี่ยวกับสัตว์

จากซ้ายไปขวา สิงโต เพนกวิน 2 ตัว คนสวมหมวกซาฟารี ช้าง และหมียืนหันหลังให้ผู้ชมและมองขึ้นไปที่จรวดขนาดใหญ่สีแดงและสีขาวที่กำลังทะยานขึ้นสู่ท้องฟ้าสีครามที่มีเมฆสีขาว นอกจากนี้ ยังเห็นจรวดขนาดเล็ก 2 ลำกำลังพุ่งขึ้นไปในระยะไกลด้วย ฉากนี้ตั้งอยู่ภายในกรงสวนสัตว์ที่มีรั้วไม้และหน้าผาหิน

สุดท้าย เราจะติดตั้งใช้งานเอเจนต์ไกด์นำเที่ยวใน Cloud Run ของ Google แทนที่จะเรียกใช้ในเครื่องเท่านั้น

ข้อกำหนดเบื้องต้น

มีความคุ้นเคยกับ Python และอินเทอร์เฟซบรรทัดคำสั่ง
โปรเจ็กต์ Google Cloud ที่เปิดใช้การเรียกเก็บเงิน
เครื่องมือ CLI ที่ติดตั้ง: gcloud, gsutil, uv

สิ่งที่คุณจะได้เรียนรู้

วิธีจัดโครงสร้างโปรเจ็กต์ Python สำหรับการติดตั้งใช้งาน ADK
วิธีใช้เอเจนต์ที่ใช้เครื่องมือด้วย google-adk
วิธีติดตั้งใช้งานแอปพลิเคชัน Python เป็นคอนเทนเนอร์แบบ Serverless ใน Cloud Run
วิธีกำหนดค่าการตรวจสอบสิทธิ์แบบบริการต่อบริการที่ปลอดภัยโดยใช้บทบาท IAM
วิธีลบทรัพยากร Cloud เพื่อหลีกเลี่ยงค่าใช้จ่ายในอนาคต

สิ่งที่คุณต้องมี

บัญชี Google Cloud และโปรเจ็กต์ Google Cloud
เว็บเบราว์เซอร์ เช่น Chrome

2. เหตุผลที่ควรติดตั้งใช้งานใน Cloud Run

Cloud Run เป็นตัวเลือกที่ยอดเยี่ยมสำหรับการโฮสต์เอเจนต์ ADK เนื่องจากเป็นแพลตฟอร์มแบบ Serverless ซึ่งหมายความว่าคุณสามารถมุ่งเน้นไปที่โค้ดได้โดยไม่ต้องจัดการโครงสร้างพื้นฐานเบื้องหลัง เราจะจัดการงานด้านการปฏิบัติการให้คุณ

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

ฟีเจอร์สำคัญ

เรียกใช้คอนเทนเนอร์ได้ทุกที่

คุณนำคอนเทนเนอร์ (อิมเมจ Docker) ที่มีแอปของคุณอยู่ภายในมา
Cloud Run จะเรียกใช้ในโครงสร้างพื้นฐานของ Google
ไม่ต้องกังวลเรื่องการแพตช์ระบบปฏิบัติการ การตั้งค่า VM หรือการปรับขนาด

การปรับขนาดอัตโนมัติ

หากไม่มีผู้ใช้แอป → จะไม่มีอินสแตนซ์ที่ทำงาน (ลดขนาดลงเหลือ 0 อินสแตนซ์ ซึ่งประหยัดค่าใช้จ่าย)
หากมีคำขอ 1,000 รายการเข้ามา ระบบจะสร้างสำเนาตามจำนวนที่จำเป็น

ไม่เก็บสถานะโดยค่าเริ่มต้น:

คำขอแต่ละรายการอาจไปที่อินสแตนซ์อื่น
หากต้องการจัดเก็บสถานะ ให้ใช้บริการภายนอก เช่น Cloud SQL, Firestore หรือ Memorystore

รองรับภาษาหรือเฟรมเวิร์กใดก็ได้

Cloud Run ไม่สนใจว่าจะเป็น Python, Go, Node.js, Java หรือ .Net ตราบใดที่ทำงานในคอนเทนเนอร์ Linux

จ่ายเงินตามการใช้งานจริง:

การเรียกเก็บเงินตามคำขอ: เรียกเก็บเงินต่อคำขอ + เวลาในการคำนวณ (ต่ำสุด 100 มิลลิวินาที)
การเรียกเก็บเงินตามอินสแตนซ์: เรียกเก็บเงินตลอดอายุการใช้งานของอินสแตนซ์ (ไม่มีค่าธรรมเนียมต่อคำขอ)

3. การตั้งค่าโปรเจ็กต์

บัญชี Google

หากยังไม่มีบัญชี Google ส่วนบุคคล คุณต้องสร้างบัญชี Google

ใช้บัญชีส่วนตัวแทนบัญชีของที่ทำงานหรือบัญชีโรงเรียน

ลงชื่อเข้าใช้คอนโซล Google Cloud โดยใช้บัญชี Google ส่วนบุคคล

เปิดใช้การเรียกเก็บเงิน

สร้างบัญชีสำหรับการเรียกเก็บเงินส่วนตัว

หากตั้งค่าการเรียกเก็บเงินโดยใช้เครดิต Google Cloud คุณสามารถข้ามขั้นตอนนี้ได้

หากต้องการตั้งค่าบัญชีสำหรับการเรียกเก็บเงินส่วนบุคคล ให้ไปที่นี่เพื่อเปิดใช้การเรียกเก็บเงินใน Cloud Console

ข้อควรทราบ

การทำ Lab นี้ให้เสร็จสมบูรณ์ควรมีค่าใช้จ่ายน้อยกว่า $1 USD ในทรัพยากรระบบคลาวด์
คุณสามารถทำตามขั้นตอนที่ส่วนท้ายของแล็บนี้เพื่อลบทรัพยากรเพื่อหลีกเลี่ยงการเรียกเก็บเงินเพิ่มเติม
ผู้ใช้ใหม่มีสิทธิ์ทดลองใช้ฟรีมูลค่า $300 USD

สร้างโปรเจ็กต์ (ไม่บังคับ)

หากไม่มีโปรเจ็กต์ปัจจุบันที่ต้องการใช้สำหรับแล็บนี้ ให้สร้างโปรเจ็กต์ใหม่ที่นี่

4. เปิดโปรแกรมแก้ไข Cloud Shell

คลิกลิงก์นี้เพื่อไปยังโปรแกรมแก้ไข Cloud Shell โดยตรง
หากระบบแจ้งให้ให้สิทธิ์ในวันนี้ ให้คลิกให้สิทธิ์เพื่อดำเนินการต่อ
หากเทอร์มินัลไม่ปรากฏที่ด้านล่างของหน้าจอ ให้เปิดโดยทำดังนี้
- คลิกดู
- คลิก Terminal

5. สร้างโปรเจ็กต์

ในเทอร์มินัล ให้ตั้งค่าโปรเจ็กต์ด้วยคำสั่งนี้
```
gcloud config set project [PROJECT_ID]
```
ตัวอย่าง: gcloud config set project lab-project-id-example
หากจำรหัสโปรเจ็กต์ไม่ได้ คุณสามารถแสดงรหัสโปรเจ็กต์ทั้งหมดได้โดยใช้คำสั่ง gcloud projects list
คุณควรเห็นข้อความต่อไปนี้
```
Updated property [core/project].
```
หากเห็น WARNING และระบบขอให้คุณ Do you want to continue (Y/n)? แสดงว่าคุณอาจป้อนรหัสโปรเจ็กต์ไม่ถูกต้อง กด n กด Enter แล้วลองเรียกใช้คำสั่ง gcloud config set project อีกครั้ง

6. เปิดใช้ API

หากต้องการใช้ Cloud Run, Artifact Registry, Cloud Build, Gemini Enterprise Agent Platform และ Compute Engine คุณต้องเปิดใช้ API ที่เกี่ยวข้องในโปรเจ็กต์ที่อยู่ในระบบคลาวด์ Google Cloud

ในเทอร์มินัล ให้เปิดใช้ API ดังนี้
```
gcloud services enable \
  run.googleapis.com \
  artifactregistry.googleapis.com \
  cloudbuild.googleapis.com \
  aiplatform.googleapis.com \
  compute.googleapis.com
```
เมื่อการดำเนินการนี้เสร็จสิ้น คุณควรเห็นเอาต์พุตดังต่อไปนี้
```
Operation "operations/acat.p2-[GUID]" finished successfully.
```

ขอแนะนำ API

Cloud Run Admin API (run.googleapis.com) ช่วยให้คุณเรียกใช้บริการส่วนหน้าและส่วนหลัง งานแบบเป็นชุด หรือเว็บไซต์ในสภาพแวดล้อมที่มีการจัดการอย่างเต็มรูปแบบได้ โดยจะจัดการโครงสร้างพื้นฐานสำหรับการติดตั้งใช้งานและปรับขนาดแอปพลิเคชันที่สร้างโดยใช้คอนเทนเนอร์
Artifact Registry API (artifactregistry.googleapis.com) มีที่เก็บข้อมูลส่วนตัวที่ปลอดภัยสำหรับจัดเก็บอิมเมจคอนเทนเนอร์ ซึ่งเป็นวิวัฒนาการของ Container Registry และผสานรวมกับ Cloud Run และ Cloud Build ได้อย่างราบรื่น
Cloud Build API (cloudbuild.googleapis.com) เป็นแพลตฟอร์ม CI/CD แบบไม่มีเซิร์ฟเวอร์ที่ดำเนินการกับบิลด์ของคุณบนโครงสร้างพื้นฐานของ Google Cloud ใช้เพื่อสร้างอิมเมจคอนเทนเนอร์ในระบบคลาวด์จาก Dockerfile
Gemini Enterprise Agent Platform API (aiplatform.googleapis.com) ช่วยให้แอปพลิเคชันที่ติดตั้งใช้งานสื่อสารกับโมเดล Gemini เพื่อทำงาน AI หลักได้ โดยมี API แบบรวมสำหรับบริการ AI ทั้งหมดของ Google Cloud
Compute Engine API (compute.googleapis.com) มีเครื่องเสมือนที่ปลอดภัยและปรับแต่งได้ซึ่งทำงานบนโครงสร้างพื้นฐานของ Google แม้ว่า Cloud Run จะได้รับการจัดการ แต่ก็มักจะต้องใช้ Compute Engine API เป็นการพึ่งพาพื้นฐานสำหรับทรัพยากรเครือข่ายและการประมวลผลต่างๆ

7. เตรียมสภาพแวดล้อมในการพัฒนาซอฟต์แวร์

สร้างไดเรกทอรี

ในเทอร์มินัล ให้สร้างไดเรกทอรีโปรเจ็กต์และไดเรกทอรีย่อยที่จำเป็น
```
cd && mkdir zoo_guide_agent && cd zoo_guide_agent
```
ในเทอร์มินัล ให้เรียกใช้คำสั่งต่อไปนี้เพื่อเปิดไดเรกทอรี zoo_guide_agent ในโปรแกรมสำรวจ Cloud Shell Editor
```
cloudshell open-workspace ~/zoo_guide_agent
```
แผงสำรวจทางด้านซ้ายจะรีเฟรช ตอนนี้คุณควรเห็นไดเรกทอรีที่สร้างขึ้น

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

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

ข้อกำหนดในการติดตั้ง

เรียกใช้คำสั่งต่อไปนี้ในเทอร์มินัลเพื่อสร้างไฟล์ requirements.txt
```
cloudshell edit requirements.txt
```
เพิ่มข้อมูลต่อไปนี้ลงในไฟล์ requirements.txt ที่สร้างขึ้นใหม่
```
google-adk==2.4.0
langchain-community==0.3.27
wikipedia==1.4.0
```
ในเทอร์มินัล ให้สร้างและเปิดใช้งานสภาพแวดล้อมเสมือนโดยใช้ uv วิธีนี้ช่วยให้มั่นใจได้ว่าการอ้างอิงโปรเจ็กต์จะไม่ขัดแย้งกับ Python ของระบบ
```
uv venv
source .venv/bin/activate
```
หมายเหตุ: หากเซสชัน Cloud Shell รีเฟรชหรือคุณเปิดแท็บเทอร์มินัลใหม่ คุณอาจต้องเปิดใช้งานสภาพแวดล้อมเสมือนอีกครั้งโดยเรียกใช้ source .venv/bin/activate
ติดตั้งแพ็กเกจที่จำเป็นลงในสภาพแวดล้อมเสมือนในเทอร์มินัล
```
uv pip install -r requirements.txt
```

สร้างบัญชีบริการและกำหนดค่าสิทธิ์ IAM

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

ในเทอร์มินัล ให้สร้างบัญชีบริการเฉพาะสำหรับบริการ Cloud Run ดังนี้

SA_NAME=lab-service-account
PROJECT_ID=$(gcloud config get-value project)
gcloud iam service-accounts create ${SA_NAME} \
    --display-name="Service Account for Zoo Agent"

ให้บทบาทผู้ใช้แพลตฟอร์ม Agent ของ Gemini Enterprise แก่บัญชีบริการเพื่อให้ Agent เรียกใช้ Gemini ได้โดยทำดังนี้
```
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:${SA_NAME}@${PROJECT_ID}.iam.gserviceaccount.com" \
  --role="roles/aiplatform.user"
```

กำหนดค่าสิทธิ์ของ Cloud Build เนื่องจากโปรเจ็กต์ Google Cloud สมัยใหม่จำกัดสิทธิ์ของบัญชีบริการเริ่มต้น คุณจึงต้องให้บทบาทที่จำเป็นต่อการสร้างและติดตั้งใช้งานคอนเทนเนอร์แก่บัญชีบริการเริ่มต้นของ Compute Engine เรียกใช้คำสั่งต่อไปนี้ในเทอร์มินัล

PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")

# Grant Artifact Registry Writer role
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \
  --role="roles/artifactregistry.writer"

# Grant Storage Object Viewer role
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \
  --role="roles/storage.objectViewer"

# Grant Logs Writer role
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \
  --role="roles/logging.logWriter"

ตั้งค่าตัวแปรสภาพแวดล้อม

ตอนนี้คุณจะสร้างไฟล์ .env ที่มีตัวแปรสภาพแวดล้อมที่ใช้โดยเอเจนต์และสคริปต์การติดตั้งใช้งาน

เนื่องจากคุณได้กำหนดตัวแปรในเซสชันเทอร์มินัลในขั้นตอนก่อนหน้าแล้ว คุณจึงสร้างไฟล์ .env ได้โดยตรง
```
cat <<EOF > .env
PROJECT_ID=$PROJECT_ID
PROJECT_NUMBER=$PROJECT_NUMBER
SA_NAME=$SA_NAME
SERVICE_ACCOUNT=${SA_NAME}@${PROJECT_ID}.iam.gserviceaccount.com
MODEL="gemini-3.5-flash"
EOF
```
ตรวจสอบไฟล์ .env และตรวจสอบว่าได้กำหนดค่าให้กับทั้ง PROJECT_ID, PROJECT_NUMBER และ SERVICE_ACCOUNT แล้ว หากไม่มีรายละเอียดโปรเจ็กต์ ให้ค้นหาโดยเรียกใช้ gcloud projects list คุณตรวจสอบว่าบัญชีบริการมีอยู่จริงได้โดยเรียกใช้ gcloud iam service-accounts list

8. สร้างเวิร์กโฟลว์ของ Agent

สร้างไฟล์ `init.py`

สร้างไฟล์ init.py โดยเรียกใช้คำสั่งต่อไปนี้ในเทอร์มินัล
```
cloudshell edit __init__.py
```
ไฟล์นี้จะบอก Python ว่าไดเรกทอรี zoo_guide_agent เป็นแพ็กเกจ
เพิ่มโค้ดต่อไปนี้ลงในไฟล์ __init__.py ใหม่
```
from . import agent
```

สร้างไฟล์ `agent.py`

สร้างไฟล์ agent.py หลักโดยวางคำสั่งต่อไปนี้ลงในเทอร์มินัล
```
cloudshell edit agent.py
```
การนําเข้าและการตั้งค่าเริ่มต้น: เพิ่มโค้ดต่อไปนี้ลงในไฟล์ agent.py ที่ว่างอยู่ในปัจจุบัน
```
import os
import logging
from dotenv import load_dotenv

from google.adk import Agent
from google.adk.agents import SequentialAgent
from google.adk.tools.tool_context import ToolContext
from google.adk.tools.langchain_tool import LangchainTool

from langchain_community.tools import WikipediaQueryRun
from langchain_community.utilities import WikipediaAPIWrapper

import google.auth
import google.auth.transport.requests
import google.oauth2.id_token

# --- Setup Logging and Environment ---

load_dotenv()

model_name = os.getenv("MODEL")
```
บล็อกแรกของไฟล์ agent.py จะนำเข้าไลบรารีที่จำเป็นทั้งหมดจาก ADK และ Google Cloud นอกจากนี้ ยังตั้งค่าการบันทึกและโหลดตัวแปรสภาพแวดล้อมจากไฟล์ .env ซึ่งมีความสำคัญต่อการเข้าถึง URL ของโมเดลและเซิร์ฟเวอร์
กำหนดเครื่องมือ: Agent จะทำงานได้ดีมากน้อยแค่ไหนนั้นขึ้นอยู่กับเครื่องมือที่ใช้ได้ เพิ่มโค้ดต่อไปนี้ที่ด้านล่างของ agent.py เพื่อกำหนดเครื่องมือ
```
# Greet user and save their prompt

def add_prompt_to_state(
    tool_context: ToolContext, prompt: str
) -> dict[str, str]:
    """Saves the user's initial prompt to the state."""
    tool_context.state["PROMPT"] = prompt
    logging.info(f"[State updated] Added to PROMPT: {prompt}")
    return {"status": "success"}

# Configuring the Wikipedia Tool
api_wrapper = WikipediaAPIWrapper(top_k_results=1, doc_content_chars_max=1000)
api_wrapper.wiki_client.set_user_agent("ZooTourGuideAgent/1.0")
wikipedia_tool = LangchainTool(
    tool=WikipediaQueryRun(api_wrapper=api_wrapper)
)
```
คำอธิบายเกี่ยวกับเครื่องมือ
- add_prompt_to_state 📝: เครื่องมือนี้จะจดจำสิ่งที่ผู้เข้าชมสวนสัตว์ถาม เมื่อผู้เข้าชมถามว่า "สิงโตอยู่ที่ไหน" เครื่องมือนี้จะบันทึกคำถามนั้นลงในหน่วยความจำของเอเจนต์ เพื่อให้เอเจนต์อื่นๆ ในเวิร์กโฟลว์รู้ว่าต้องค้นหาอะไร
  วิธี: เป็นฟังก์ชัน Python ที่เขียนพรอมต์ของผู้เข้าชมลงในพจนานุกรม tool_context.state ที่แชร์ บริบทของเครื่องมือนี้แสดงถึงหน่วยความจำระยะสั้นของ Agent สำหรับการสนทนาครั้งเดียว Agent ตัวถัดไปในเวิร์กโฟลว์จะอ่านข้อมูลที่ Agent ตัวหนึ่งบันทึกลงในสถานะได้
- LangchainTool 🌍: ตัวเลือกนี้จะช่วยให้เอเจนต์ไกด์นำเที่ยวมีความรู้ทั่วไปเกี่ยวกับโลก เมื่อผู้เข้าชมถามคำถามที่ไม่มีในฐานข้อมูลของสวนสัตว์ เช่น "สิงโตกินอะไรในป่า" เครื่องมือนี้จะช่วยให้ตัวแทนค้นหาคำตอบใน Wikipedia ได้ (ดูข้อมูลเพิ่มเติมเกี่ยวกับการกำหนดค่าและการเรียกใช้เครื่องมือ Wikipedia ได้ในคู่มือการใช้เครื่องมือ Wikipedia)
  วิธี: ทำหน้าที่เป็นตัวดัดแปลงที่ช่วยให้เอเจนต์ของเราใช้เครื่องมือ WikipediaQueryRun ที่สร้างไว้ล่วงหน้าจากไลบรารี LangChain ได้

กำหนดตัวแทนผู้เชี่ยวชาญ: เพิ่มโค้ดต่อไปนี้ที่ด้านล่างของ agent.py เพื่อกำหนดตัวแทน comprehensive_researcher และ response_formatter

# 1. Researcher Agent
comprehensive_researcher = Agent(
    name="comprehensive_researcher",
    model=model_name,
    description="The primary researcher that can access both internal zoo data and external knowledge from Wikipedia.",
    instruction="""
    You are a helpful research assistant. Your goal is to fully answer the user's PROMPT.
    You have access to two tools:
    1. A tool for getting specific data about animals AT OUR ZOO (names, ages, locations).
    2. A tool for searching Wikipedia for general knowledge (facts, lifespan, diet, habitat).

    First, analyze the user's PROMPT.
    - If the prompt can be answered by only one tool, use that tool.
    - If the prompt is complex and requires information from both the zoo's database AND Wikipedia,
      you MUST use both tools to gather all necessary information.
    - Synthesize the results from the tool(s) you use into preliminary data outputs.

    PROMPT:
    { PROMPT }
    """,
    tools=[
        wikipedia_tool
    ],
    output_key="research_data" # A key to store the combined findings
)

# 2. Response Formatter Agent
response_formatter = Agent(
    name="response_formatter",
    model=model_name,
    description="Synthesizes all information into a friendly, readable response.",
    instruction="""
    You are the friendly voice of the Zoo Tour Guide. Your task is to take the
    RESEARCH_DATA and present it to the user in a complete and helpful answer.

    - First, present the specific information from the zoo (like names, ages, and where to find them).
    - Then, add the interesting general facts from the research.
    - If some information is missing, just present the information you have.
    - Be conversational and engaging.

    RESEARCH_DATA:
    { research_data }
    """
)

comprehensive_researcher Agent เป็น "สมอง" ของการดำเนินการของเรา โดยจะรับพรอมต์ของผู้ใช้จาก State ที่แชร์ ตรวจสอบว่าพรอมต์นั้นเป็นเครื่องมือ Wikipedia หรือไม่ และตัดสินใจว่าจะใช้พรอมต์ใดเพื่อค้นหาคำตอบ
บทบาทของเอเจนต์ response_formatter คือการนำเสนอ โดยจะใช้ข้อมูลดิบที่รวบรวมโดย Agent นักวิจัย (ส่งผ่านทางสถานะ) และใช้ทักษะด้านภาษาของ LLM เพื่อเปลี่ยนข้อมูลดังกล่าวให้เป็นการตอบกลับแบบสนทนาที่เป็นมิตร

กำหนด Agent เวิร์กโฟลว์: เพิ่มบล็อกโค้ดนี้ที่ด้านล่างของ agent.py เพื่อกำหนด Agent แบบลำดับ tour_guide_workflow
```
tour_guide_workflow = SequentialAgent(
    name="tour_guide_workflow",
    description="The main workflow for handling a user's request about an animal.",
    sub_agents=[
        comprehensive_researcher, # Step 1: Gather all data
        response_formatter,       # Step 2: Format the final response
    ]
)
```
เอเจนต์เวิร์กโฟลว์ทำหน้าที่เป็นผู้จัดการ "แบ็กออฟฟิศ" สำหรับทัวร์สวนสัตว์ โดยจะรับคำขอการวิจัยและตรวจสอบว่า Agent 2 รายที่เรากำหนดไว้ข้างต้นทำงานตามลำดับที่ถูกต้อง นั่นคือ ค้นคว้าก่อน แล้วจึงจัดรูปแบบ ซึ่งจะช่วยสร้างกระบวนการที่คาดการณ์ได้และเชื่อถือได้ในการตอบคำถามของผู้เข้าชม
วิธีการ: เป็นSequentialAgent ซึ่งเป็น Agent ประเภทพิเศษที่ไม่คิดเอง หน้าที่เดียวของมันคือการเรียกใช้รายการ sub_agents (นักวิจัยและผู้จัดรูปแบบ) ตามลำดับที่กำหนด โดยส่งหน่วยความจำที่ใช้ร่วมกันจากหนึ่งไปยังอีกหนึ่งโดยอัตโนมัติ
ประกอบเวิร์กโฟลว์หลัก: เพิ่มโค้ดบล็อกสุดท้ายนี้ที่ด้านล่างของ agent.py เพื่อกำหนด root_agent
```
root_agent = Agent(
    name="greeter",
    model=model_name,
    description="The main entry point for the Zoo Tour Guide.",
    instruction="""
    - Let the user know you will help them learn about the animals we have in the zoo.
    - When the user responds, use the 'add_prompt_to_state' tool to save their response.
    After using the tool, transfer control to the 'tour_guide_workflow' agent.
    """,
    tools=[add_prompt_to_state],
    sub_agents=[tour_guide_workflow]
)
```
เฟรมเวิร์ก ADK ใช้ root_agent เป็นจุดเริ่มต้นของการสนทนาใหม่ทั้งหมด โดยมีบทบาทหลักในการประสานงานกระบวนการโดยรวม โดยจะทำหน้าที่เป็นตัวควบคุมเริ่มต้น ซึ่งจัดการการสนทนาในรอบแรก

ไฟล์ `agent.py` แบบเต็ม

ตอนนี้ไฟล์ agent.py ของคุณเสร็จสมบูรณ์แล้ว การสร้างในลักษณะนี้จะช่วยให้คุณเห็นว่าคอมโพเนนต์แต่ละอย่าง ไม่ว่าจะเป็นเครื่องมือ เอเจนต์ของ Worker และเอเจนต์ของ Manager มีบทบาทเฉพาะในการสร้างระบบอัจฉริยะขั้นสุดท้ายอย่างไร

ไฟล์ที่สมบูรณ์ควรมีลักษณะดังนี้

import os
import logging
from dotenv import load_dotenv

from google.adk import Agent
from google.adk.agents import SequentialAgent
from google.adk.tools.tool_context import ToolContext
from google.adk.tools.langchain_tool import LangchainTool

from langchain_community.tools import WikipediaQueryRun
from langchain_community.utilities import WikipediaAPIWrapper

import google.auth
import google.auth.transport.requests
import google.oauth2.id_token

# --- Setup Logging and Environment ---

load_dotenv()

model_name = os.getenv("MODEL")

# Greet user and save their prompt

def add_prompt_to_state(
    tool_context: ToolContext, prompt: str
) -> dict[str, str]:
    """Saves the user's initial prompt to the state."""
    tool_context.state["PROMPT"] = prompt
    logging.info(f"[State updated] Added to PROMPT: {prompt}")
    return {"status": "success"}

# Configuring the Wikipedia Tool
api_wrapper = WikipediaAPIWrapper(top_k_results=1, doc_content_chars_max=1000)
api_wrapper.wiki_client.set_user_agent("ZooTourGuideAgent/1.0")
wikipedia_tool = LangchainTool(
    tool=WikipediaQueryRun(api_wrapper=api_wrapper)
)

# 1. Researcher Agent
comprehensive_researcher = Agent(
    name="comprehensive_researcher",
    model=model_name,
    description="The primary researcher that can access both internal zoo data and external knowledge from Wikipedia.",
    instruction="""
    You are a helpful research assistant. Your goal is to fully answer the user's PROMPT.
    You have access to two tools:
    1. A tool for getting specific data about animals AT OUR ZOO (names, ages, locations).
    2. A tool for searching Wikipedia for general knowledge (facts, lifespan, diet, habitat).

    First, analyze the user's PROMPT.
    - If the prompt can be answered by only one tool, use that tool.
    - If the prompt is complex and requires information from both the zoo's database AND Wikipedia,
        you MUST use both tools to gather all necessary information.
    - Synthesize the results from the tool(s) you use into preliminary data outputs.

    PROMPT:
    { PROMPT }
    """,
    tools=[
        wikipedia_tool
    ],
    output_key="research_data" # A key to store the combined findings
)

# 2. Response Formatter Agent
response_formatter = Agent(
    name="response_formatter",
    model=model_name,
    description="Synthesizes all information into a friendly, readable response.",
    instruction="""
    You are the friendly voice of the Zoo Tour Guide. Your task is to take the
    RESEARCH_DATA and present it to the user in a complete and helpful answer.

    - First, present the specific information from the zoo (like names, ages, and where to find them).
    - Then, add the interesting general facts from the research.
    - If some information is missing, just present the information you have.
    - Be conversational and engaging.

    RESEARCH_DATA:
    { research_data }
    """
)

tour_guide_workflow = SequentialAgent(
    name="tour_guide_workflow",
    description="The main workflow for handling a user's request about an animal.",
    sub_agents=[
        comprehensive_researcher, # Step 1: Gather all data
        response_formatter,       # Step 2: Format the final response
    ]
)

root_agent = Agent(
    name="greeter",
    model=model_name,
    description="The main entry point for the Zoo Tour Guide.",
    instruction="""
    - Let the user know you will help them learn about the animals we have in the zoo.
    - When the user responds, use the 'add_prompt_to_state' tool to save their response.
    After using the tool, transfer control to the 'tour_guide_workflow' agent.
    """,
    tools=[add_prompt_to_state],
    sub_agents=[tour_guide_workflow]
)

ขั้นตอนต่อไปคือการติดตั้งใช้งาน

9. เตรียมแอปพลิเคชันสำหรับการนำไปใช้งาน

ตรวจสอบโครงสร้างสุดท้าย

ก่อนที่จะติดตั้งใช้งาน ให้ตรวจสอบว่าไดเรกทอรีโปรเจ็กต์มีไฟล์ที่ถูกต้อง

ตรวจสอบว่าโฟลเดอร์ zoo_guide_agent มีลักษณะดังนี้
```
zoo_guide_agent/
├── .env
├── __init__.py
├── agent.py
└── requirements.txt
```

กำหนดค่า .gcloudignore และโหลดตัวแปรสภาพแวดล้อม

สร้างไฟล์ .gcloudignore ในไดเรกทอรี zoo_guide_agent เพื่อป้องกันการอัปโหลดสภาพแวดล้อมเสมือน (.venv/) และไฟล์อื่นๆ ที่ไม่จำเป็นไปยัง Google Cloud
```
cloudshell edit .gcloudignore
```
เพิ่มเนื้อหาต่อไปนี้ไปยัง .gcloudignore
```
.gcloudignore
.git
.gitignore
.venv/
venv/
__pycache__/
.env
```
โหลดตัวแปรสภาพแวดล้อมลงในเซสชันเทอร์มินัล
```
source .env
```
หมายเหตุ: หากเซสชัน Cloud Shell รีเฟรชหรือคุณเปิดแท็บเทอร์มินัลใหม่ คุณต้องเรียกใช้ source .env อีกครั้งเพื่อโหลดตัวแปรเหล่านี้ซ้ำก่อนที่จะทำการติดตั้งใช้งาน

10. ติดตั้งใช้งาน Agent โดยใช้ ADK CLI

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

เรียกใช้คำสั่งต่อไปนี้ในเทอร์มินัลเพื่อติดตั้งใช้งานเอเจนต์
```
# Run the deployment command
uvx --from google-adk==2.4.0 \
adk deploy cloud_run \
  --project=$PROJECT_ID \
  --region=europe-west1 \
  --service_name=zoo-tour-guide \
  --with_ui \
  . \
  -- \
  --allow-unauthenticated \
  --set-env-vars=MODEL=$MODEL,GOOGLE_GENAI_USE_ENTERPRISE=true,GOOGLE_CLOUD_PROJECT=$PROJECT_ID,GOOGLE_CLOUD_LOCATION=global \
  --labels=dev-tutorial=codelab-adk \
  --service-account=$SERVICE_ACCOUNT
```
คำสั่ง uvx ช่วยให้คุณเรียกใช้เครื่องมือบรรทัดคำสั่งที่เผยแพร่เป็นแพ็กเกจ Python ได้โดยไม่ต้องติดตั้งเครื่องมือเหล่านั้นทั่วโลก
หมายเหตุ: คำสั่งการติดตั้งใช้งานด้านล่างนี้จะใช้เวลา 2-3 นาทีจึงจะทำงานเสร็จ

หากระบบแจ้งให้คุณดำเนินการต่อไปนี้

Deploying from source requires an Artifact Registry Docker repository to store built containers. A repository named [cloud-run-source-deploy] in region 
[europe-west1] will be created.

Do you want to continue (Y/n)?

หากใช่ ให้พิมพ์ Y แล้วกด Enter

เมื่อดำเนินการสำเร็จแล้ว คำสั่งจะแสดง URL ของบริการ Cloud Run ที่ใช้งาน (จะมีลักษณะคล้ายกับ https://zoo-tour-guide-123456789.europe-west1.run.app)
คัดลอก URL ของบริการ Cloud Run ที่ใช้งานแล้วสำหรับงานถัดไป

11. ทดสอบ Agent ที่ทำให้ใช้งานได้

เมื่อตัวแทนใช้งานได้ใน Cloud Run แล้ว คุณจะต้องทำการทดสอบเพื่อยืนยันว่าการติดตั้งใช้งานสำเร็จและตัวแทนทำงานได้ตามที่คาดไว้ คุณจะใช้ URL ของบริการสาธารณะ (เช่น https://zoo-tour-guide-123456789.europe-west1.run.app/) เพื่อเข้าถึงอินเทอร์เฟซเว็บของ ADK และโต้ตอบกับตัวแทน

เปิด URL ของบริการ Cloud Run สาธารณะในเว็บเบราว์เซอร์ เนื่องจากคุณใช้ --with_ui flag คุณจึงควรเห็น UI ของนักพัฒนาแอป ADK
เปิดToken Streamingที่ด้านขวาบน
ตอนนี้คุณโต้ตอบกับ Agent สวนสัตว์ได้แล้ว
พิมพ์ hello แล้วกด Enter เพื่อเริ่มการสนทนาใหม่
สังเกตผลลัพธ์ เอเจนต์ควรตอบกลับอย่างรวดเร็วด้วยคำทักทายซึ่งจะมีลักษณะดังนี้
```
"Hello! I'm your Zoo Tour Guide. I can help you learn about the amazing animals we have here. What would you like to know or explore today?"
```

ถามคำถามต่อไปนี้กับตัวแทน

Where can I find the polar bears in the zoo and what is their diet?

ภาพหน้าจอของ Agent ADK ที่ทําการดําเนินการตามลําดับ ได้แก่ add_prompt_to_state, transfer_to_agent, wikipedia และ get_animals_by_species

คำตอบแรกบอกว่า "ฉันบอกคุณไม่ได้ว่าหมีขั้วโลกอยู่ในส่วนใดของสวนสัตว์แห่งนี้ แต่ฉันบอกคุณได้ว่าหมีขั้วโลกกินอะไร" คำตอบที่ 2 ระบุว่า "หมีขั้วโลกอยู่ที่นิทรรศการอาร์กติกบนเส้นทางขั้วโลก เราไม่สามารถดึงข้อมูลเกี่ยวกับอาหารของสัตว์เลี้ยงด้วยเครื่องมือที่มีอยู่ได้" คำตอบที่ 3 ซึ่งครอบคลุมมากที่สุดกล่าวว่า "เรายินดีที่จะบอกคุณเกี่ยวกับหมีขั้วโลก คุณสามารถชมหมีขั้วโลกได้ที่นิทรรศการอาร์กติกบนเส้นทางขั้วโลก เรามีหมีขั้วโลก 3 ตัวที่นี่ ได้แก่ สโนว์เฟลก ซึ่งมีอายุ 7 ปี Blizzard อายุ 5 ขวบ ไอซ์เบิร์กอายุ 9 ขวบ ส่วนเรื่องอาหารการกิน หมีขั้วโลกส่วนใหญ่เป็นสัตว์กินเนื้อ โดยจะล่าแมวน้ำเป็นอาหาร โดยเฉพาะแมวน้ำวงแหวน นอกจากนี้ ยังกินวอลรัส วาฬเบลูกา และสัตว์บกบางชนิดด้วย"

คำอธิบายโฟลว์ของ Agent

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

1. The Zoo Greeter (The Welcome Desk)

กระบวนการทั้งหมดเริ่มต้นด้วยตัวแทนต้อนรับ

หน้าที่: เริ่มการสนทนา คำสั่งของฟังก์ชันนี้คือการทักทายผู้ใช้และถามว่าต้องการเรียนรู้เกี่ยวกับสัตว์ชนิดใด
เครื่องมือ: เมื่อผู้ใช้ตอบกลับ ผู้ทักทายจะใช้เครื่องมือ add_prompt_to_state เพื่อบันทึกคำพูดที่แน่นอนของผู้ใช้ (เช่น "เล่าเรื่องสิงโตให้ฟังหน่อย") และบันทึกไว้ในหน่วยความจำของระบบ
การส่งต่อ: หลังจากบันทึกพรอมต์แล้ว ระบบจะส่งต่อการควบคุมไปยัง Agent ย่อย ซึ่งก็คือ tour_guide_workflow ทันที

2. นักวิจัยที่ครอบคลุม (นักวิจัยขั้นสุด)

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

หน้าที่: วิเคราะห์คำถามของผู้ใช้และวางแผนอย่างชาญฉลาด โดยจะใช้ความสามารถในการใช้เครื่องมือของโมเดลภาษาเพื่อพิจารณาว่าจำเป็นต้องทำสิ่งต่อไปนี้หรือไม่
- ความรู้ทั่วไปจากเว็บ (ผ่าน Wikipedia API)
- หรือสำหรับคำถามที่ซับซ้อน ให้ใช้ทั้ง 2 อย่าง

3. Response Formatter (ผู้นำเสนอ)

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

หน้าที่: ทำหน้าที่เป็นเสียงที่เป็นมิตรของไกด์นำเที่ยวสวนสัตว์ โดยจะนำข้อมูลดิบ (ซึ่งอาจมาจากแหล่งที่มาใดแหล่งที่มาหนึ่งหรือทั้ง 2 แหล่ง) มาปรับปรุง
การทำงานของ Gemini: สังเคราะห์ข้อมูลทั้งหมดเป็นคำตอบเดียวที่สอดคล้องและน่าสนใจ โดยจะแสดงข้อมูลเฉพาะของสวนสัตว์ก่อน แล้วจึงเพิ่มข้อเท็จจริงทั่วไปที่น่าสนใจตามคำสั่ง
ผลลัพธ์สุดท้าย: ข้อความที่ Agent นี้สร้างขึ้นคือคำตอบที่สมบูรณ์และละเอียดซึ่งผู้ใช้จะเห็นในหน้าต่างแชท

หากสนใจดูข้อมูลเพิ่มเติมเกี่ยวกับการสร้างเอเจนต์ โปรดดูแหล่งข้อมูลต่อไปนี้

12. ล้างสภาพแวดล้อม

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

ลบบริการ รูปภาพ และทรัพยากร Cloud Run

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

เรียกใช้คำสั่งต่อไปนี้ในเทอร์มินัล

gcloud run services delete zoo-tour-guide --region=europe-west1 --quiet
gcloud artifacts repositories delete cloud-run-source-deploy --location=europe-west1 --quiet
gsutil rm -r gs://run-sources-${PROJECT_ID}-europe-west1
gcloud iam service-accounts delete lab-service-account@${PROJECT_ID}.iam.gserviceaccount.com --quiet

ลบโปรเจ็กต์ (ไม่บังคับ)

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

ในเทอร์มินัล ให้เรียกใช้คำสั่งต่อไปนี้ (แทนที่ [YOUR_PROJECT_ID] ด้วยรหัสโปรเจ็กต์จริง)
```
gcloud projects delete $PROJECT_ID
```
การลบโปรเจ็กต์เป็นการดำเนินการที่ย้อนกลับไม่ได้ โปรดตรวจสอบว่าไม่ได้ใช้โปรเจ็กต์นี้กับงานอื่นๆ ก่อนดำเนินการต่อ

13. ขอแสดงความยินดี

คุณสร้างและทำให้แอปพลิเคชัน AI แบบหลาย Agent ใช้งานได้กับ Google Cloud เรียบร้อยแล้ว

สรุป

ในแล็บนี้ คุณได้เปลี่ยนจากไดเรกทอรีว่างเปล่าไปเป็นบริการ AI ที่ใช้งานได้จริงและเข้าถึงได้แบบสาธารณะ นี่คือสิ่งที่คุณสร้าง

คุณสร้างทีมผู้เชี่ยวชาญ: คุณไม่ได้ใช้ AI ทั่วไปเพียงตัวเดียว แต่สร้าง "นักวิจัย" เพื่อค้นหาข้อเท็จจริง และ "ผู้จัดรูปแบบ" เพื่อปรับแต่งคำตอบ
คุณมอบเครื่องมือให้พวกเขา: คุณเชื่อมต่อเอเจนต์กับโลกภายนอกโดยใช้ Wikipedia API
คุณได้ทำให้ใช้งานได้แล้ว: คุณนำโค้ด Python ในเครื่องไปทำให้ใช้งานได้เป็นคอนเทนเนอร์แบบ Serverless ใน Cloud Run โดยรักษาความปลอดภัยด้วยบัญชีบริการเฉพาะ

สิ่งที่เราได้พูดถึงไปแล้ว

วิธีจัดโครงสร้างโปรเจ็กต์ Python เพื่อการติดตั้งใช้งานด้วย ADK
วิธีใช้เวิร์กโฟลว์แบบหลายเอเจนต์โดยใช้ [SequentialAgent](https://google.github.io/adk-docs/agents/workflow-agents/sequential-agents/)
วิธีผสานรวมเครื่องมือภายนอก เช่น Wikipedia API
วิธีติดตั้งใช้งาน Agent ใน Cloud Run โดยใช้คำสั่ง adk deploy

14. แบบสำรวจ

เอาต์พุต:

คุณจะใช้บทแนะนำนี้อย่างไร

อ่านอย่างเดียว

อ่านและทำแบบฝึกหัด