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

1. บทนำ

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

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

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

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

• โปรเจ็กต์ Google Cloud ที่เปิดใช้การเรียกเก็บเงิน

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

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

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

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

2. ทำไมจึงควรติดตั้งใช้งานใน Cloud Run

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

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

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

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

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

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

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

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

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

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

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

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

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

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

บัญชี Google

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

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

บัญชีงานและบัญชีโรงเรียนอาจมีข้อจำกัดที่ทำให้คุณเปิดใช้ API ที่จำเป็นสำหรับ Lab นี้ไม่ได้

ลงชื่อเข้าใช้คอนโซล Google Cloud

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

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

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

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

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

ข้อควรทราบ

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

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

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

4. เปิดเครื่องมือแก้ไข Cloud Shell

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

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

1. ในเทอร์มินัล ให้ตั้งค่าโปรเจ็กต์ด้วยคำสั่งนี้

   gcloud config set project [PROJECT_ID]
   

   ตัวอย่าง: gcloud config set project lab-project-id-example

   หากจำรหัสโปรเจ็กต์ไม่ได้ คุณสามารถแสดงรหัสโปรเจ็กต์ทั้งหมดได้โดยใช้คำสั่ง gcloud projects list

   
2. คุณควรเห็นข้อความต่อไปนี้

   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, Vertex AI และ Compute Engine คุณต้องเปิดใช้ API ที่เกี่ยวข้องในโปรเจ็กต์ที่อยู่ในระบบคลาวด์ Google

• ในเทอร์มินัล ให้เปิดใช้ 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
• Vertex AI API (aiplatform.googleapis.com) ช่วยให้แอปพลิเคชันที่ติดตั้งใช้งานแล้วสื่อสารกับโมเดล Gemini เพื่อทำงาน AI หลักได้ ซึ่งมี API แบบรวมสำหรับบริการ AI ทั้งหมดของ Google Cloud
• Compute Engine API (compute.googleapis.com) มีเครื่องเสมือนที่ปลอดภัยและปรับแต่งได้ซึ่งทำงานบนโครงสร้างพื้นฐานของ Google แม้ว่า Cloud Run จะได้รับการจัดการ แต่ก็มักจะต้องใช้ Compute Engine API เป็นการพึ่งพาพื้นฐานสำหรับทรัพยากรเครือข่ายและการคำนวณต่างๆ

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

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

1. ในเทอร์มินัล ให้สร้างไดเรกทอรีโปรเจ็กต์และไดเรกทอรีย่อยที่จำเป็น

   cd && mkdir zoo_guide_agent && cd zoo_guide_agent
   

2. ในเทอร์มินัล ให้เรียกใช้คำสั่งต่อไปนี้เพื่อเปิดไดเรกทอรี zoo_guide_agent ในโปรแกรมสำรวจ Cloud Shell Editor

   cloudshell open-workspace ~/zoo_guide_agent
   

3. แผง Explorer ทางด้านซ้ายจะรีเฟรช ตอนนี้คุณควรเห็นไดเรกทอรีที่สร้างขึ้น
   
   

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

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

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

1. เรียกใช้คำสั่งต่อไปนี้ในเทอร์มินัลเพื่อสร้างไฟล์ requirements.txt

   cloudshell edit requirements.txt
   

2. เพิ่มข้อมูลต่อไปนี้ลงในไฟล์ requirements.txt ที่สร้างขึ้นใหม่

   google-adk==2.4.0
   langchain-community==0.3.27
   wikipedia==1.4.0
   

3. ในเทอร์มินัล ให้สร้างและเปิดใช้งานสภาพแวดล้อมเสมือนโดยใช้ uv ซึ่งจะช่วยให้มั่นใจได้ว่าการขึ้นต่อกันของโปรเจ็กต์จะไม่ขัดแย้งกับ Python ของระบบ

   uv venv
   source .venv/bin/activate
   

   หมายเหตุ: หากเซสชัน Cloud Shell รีเฟรชหรือคุณเปิดแท็บเทอร์มินัลใหม่ คุณอาจต้องเปิดใช้งานสภาพแวดล้อมเสมือนอีกครั้งโดยเรียกใช้ source .venv/bin/activate

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

   uv pip install -r requirements.txt
   

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

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

1. ในเทอร์มินัล ให้สร้างบัญชีบริการเฉพาะสำหรับบริการ 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"
   

2. มอบบทบาทผู้ใช้ Vertex AI ให้กับบัญชีบริการเพื่อให้เอเจนต์เรียกใช้ Gemini ได้โดยทำดังนี้

   gcloud projects add-iam-policy-binding $PROJECT_ID \
     --member="serviceAccount:${SA_NAME}@${PROJECT_ID}.iam.gserviceaccount.com" \
     --role="roles/aiplatform.user"
   

3. กำหนดค่าสิทธิ์ 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}[e-mail]" \
     --role="roles/artifactregistry.writer"
   
   # Grant Storage Object Viewer role
   gcloud projects add-iam-policy-binding $PROJECT_ID \
     --member="serviceAccount:${PROJECT_NUMBER}[e-mail]" \
     --role="roles/storage.objectViewer"
   
   # Grant Logs Writer role
   gcloud projects add-iam-policy-binding $PROJECT_ID \
     --member="serviceAccount:${PROJECT_NUMBER}[e-mail]" \
     --role="roles/logging.logWriter"
   

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

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

1. เนื่องจากคุณได้กำหนดตัวแปรในเซสชันเทอร์มินัลแล้วในขั้นตอนก่อนหน้า คุณจึงสร้างไฟล์ .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

1. สร้างไฟล์ init.py โดยเรียกใช้คำสั่งต่อไปนี้ในเทอร์มินัล

   cloudshell edit __init__.py
   

   ไฟล์นี้จะบอก Python ว่าไดเรกทอรี zoo_guide_agent เป็นแพ็กเกจ
2. เพิ่มโค้ดต่อไปนี้ลงในไฟล์ __init__.py ใหม่

   from . import agent
   

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

1. สร้างไฟล์ agent.py หลักโดยวางคำสั่งต่อไปนี้ลงในเทอร์มินัล

   cloudshell edit agent.py
   

2. การนําเข้าและการตั้งค่าเริ่มต้น: เพิ่มโค้ดต่อไปนี้ลงในไฟล์ 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 ของโมเดลและเซิร์ฟเวอร์
3. กำหนดเครื่องมือ: 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 ที่แชร์ บริบทของเครื่องมือนี้แสดงถึงหน่วยความจำระยะสั้นของเอเจนต์สำหรับการสนทนาครั้งเดียว เอเจนต์รายหนึ่งบันทึกข้อมูลลงในสถานะแล้ว เอเจนต์รายถัดไปในเวิร์กโฟลว์จะอ่านข้อมูลนั้นได้
   • LangchainTool 🌍: การดำเนินการนี้จะช่วยให้เอเจนต์ไกด์นำเที่ยวมีความรู้ทั่วไปเกี่ยวกับโลก เมื่อผู้เข้าชมถามคำถามที่ไม่มีในฐานข้อมูลของสวนสัตว์ เช่น "สิงโตกินอะไรในป่า" เครื่องมือนี้จะช่วยให้ตัวแทนค้นหาคำตอบใน Wikipedia ได้ (ดูข้อมูลเพิ่มเติมเกี่ยวกับการกำหนดค่าและการเรียกใช้เครื่องมือ Wikipedia ได้ในคู่มือการใช้เครื่องมือ Wikipedia)
     วิธีการ: ทำหน้าที่เป็นตัวดัดแปลงที่ช่วยให้เอเจนต์ของเราใช้เครื่องมือ WikipediaQueryRun ที่สร้างไว้ล่วงหน้าจากไลบรารี LangChain ได้
     
     
4. กำหนด Agent ผู้เชี่ยวชาญ: เพิ่มโค้ดต่อไปนี้ที่ด้านล่างของ agent.py เพื่อกำหนด Agent 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 เอเจนต์คือ "สมอง" ของการทำงานของเรา โดยจะรับพรอมต์ของผู้ใช้จาก State ที่แชร์ ตรวจสอบว่าเป็นเครื่องมือ Wikipedia และตัดสินใจว่าจะใช้พรอมต์ใดเพื่อค้นหาคำตอบ
   • response_formatter บทบาทของเอเจนต์คือการนำเสนอ โดยจะใช้ข้อมูลดิบที่รวบรวมโดย Agent นักวิจัย (ส่งผ่านทางสถานะ) และใช้ทักษะด้านภาษาของ LLM เพื่อเปลี่ยนข้อมูลดังกล่าวให้เป็นการตอบกลับแบบสนทนาที่เป็นมิตร
     
5. กำหนด 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
       ]
   )
   

   Workflow Agent ทำหน้าที่เป็นผู้จัดการ "แบ็กออฟฟิศ" สำหรับการนำเที่ยวสวนสัตว์ โดยจะรับคำขอการวิจัยและตรวจสอบว่า Agent 2 รายที่เรากำหนดไว้ข้างต้นทำงานตามลำดับที่ถูกต้อง นั่นคือ ค้นคว้าก่อน แล้วจึงจัดรูปแบบ ซึ่งจะช่วยสร้างกระบวนการที่คาดการณ์ได้และเชื่อถือได้ในการตอบคำถามของผู้เข้าชม
   วิธีการ: เป็นSequentialAgent ซึ่งเป็นเอเจนต์ประเภทพิเศษที่ไม่คิดเอง หน้าที่ของมันมีเพียงการเรียกใช้รายการ sub_agents (ผู้ค้นคว้าและผู้จัดรูปแบบ) ตามลำดับที่กำหนด โดยจะส่งต่อหน่วยความจำที่แชร์จากหนึ่งไปยังอีกหนึ่งโดยอัตโนมัติ
6. ประกอบขั้นตอนการทำงานหลัก: เพิ่มโค้ดบล็อกสุดท้ายนี้ที่ด้านล่างของ 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 และโหลดตัวแปรสภาพแวดล้อม

1. สร้างไฟล์ .gcloudignore ในไดเรกทอรี zoo_guide_agent เพื่อป้องกันการอัปโหลดสภาพแวดล้อมเสมือน (.venv/) และไฟล์อื่นๆ ที่ไม่จำเป็นไปยัง Google Cloud โดยทำดังนี้

   cloudshell edit .gcloudignore
   

2. เพิ่มเนื้อหาต่อไปนี้ไปยัง .gcloudignore

   .gcloudignore
   .git
   .gitignore
   .venv/
   venv/
   __pycache__/
   .env
   

3. โหลดตัวแปรสภาพแวดล้อมลงในเซสชันเทอร์มินัล

   source .env
   

   หมายเหตุ: หากเซสชัน Cloud Shell รีเฟรชหรือคุณเปิดแท็บเทอร์มินัลใหม่ คุณต้องเรียกใช้ source .env อีกครั้งเพื่อโหลดตัวแปรเหล่านี้ซ้ำก่อนที่จะทำการติดตั้งใช้งาน

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

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

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

   # 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_VERTEXAI=TRUE,GOOGLE_CLOUD_PROJECT=$PROJECT_ID,GOOGLE_CLOUD_LOCATION=global \
     --labels=dev-tutorial=codelab-adk \
     --service-account=$SERVICE_ACCOUNT
   

   คำสั่ง uvx ช่วยให้คุณเรียกใช้เครื่องมือบรรทัดคำสั่งที่เผยแพร่เป็นแพ็กเกจ Python ได้โดยไม่ต้องติดตั้งเครื่องมือเหล่านั้นทั่วโลก

   หมายเหตุ: คำสั่งการทำให้ใช้งานได้ด้านล่างนี้จะใช้เวลา 2-3 นาทีจึงจะทำงานเสร็จ

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

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

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

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

1. เปิด URL ของบริการ Cloud Run สาธารณะในเว็บเบราว์เซอร์ เนื่องจากคุณใช้ --with_ui flag คุณจึงควรเห็น UI ของนักพัฒนาแอป ADK
2. เปิดToken Streamingที่ด้านขวาบน
   ตอนนี้คุณโต้ตอบกับตัวแทนสวนสัตว์ได้แล้ว
3. พิมพ์ hello แล้วกด Enter เพื่อเริ่มการสนทนาใหม่
4. สังเกตผลลัพธ์ เอเจนต์ควรตอบกลับอย่างรวดเร็วด้วยคำทักทายซึ่งจะมีลักษณะดังนี้

   "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?"
   

5. ถามคำถามกับตัวแทน เช่น

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

   

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

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

1. The Zoo Greeter (The Welcome Desk)

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

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

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

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

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

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

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

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

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

1. เอกสาร ADK
2. การสร้างเครื่องมือที่กำหนดเองสำหรับ ADK Agent

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

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

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

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

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

  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
  

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

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

• ในเทอร์มินัล ให้เรียกใช้คำสั่งต่อไปนี้ (แทนที่ [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
• วิธีติดตั้งใช้งานเอเจนต์ใน Cloud Run โดยใช้คำสั่ง adk deploy

14. แบบสำรวจ

เอาต์พุต:

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

อ่านอย่างเดียว อ่านและทำแบบฝึกหัด