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

1. บทนำ

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

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

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

สุดท้าย เราจะติดตั้งใช้งานเอเจนต์ไกด์นำเที่ยวใน 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

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

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

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

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

บัญชี Google

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

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

ลงชื่อเข้าใช้ Google Cloud Console

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

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

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

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

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

ข้อควรทราบ

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

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

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

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

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

5. เปิดใช้ API

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

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

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

  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 ทางด้านซ้ายจะรีเฟรช ตอนนี้คุณควรเห็นไดเรกทอรีที่สร้างขึ้น
    ภาพหน้าจอของไดเรกทอรีใหม่ในแผงด้านข้างของเครื่องมือสำรวจ

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

  1. ในเทอร์มินัล ให้ตั้งค่าโปรเจ็กต์ด้วยคำสั่งนี้
    gcloud config set project [PROJECT_ID]
    ตัวอย่าง: gcloud config set project lab-project-id-example ตั้งค่ารหัสโปรเจ็กต์ในเทอร์มินัล Cloud Shell Editor
  2. คุณควรเห็นข้อความต่อไปนี้
    Updated property [core/project].

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

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

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

  • ใช้คำสั่งต่อไปนี้ในเทอร์มินัลเพื่อสร้างไฟล์ .env
    # 1. Set the variables in your terminal first
PROJECT_ID=$(gcloud config get-value project)
PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
SA_NAME=lab2-cr-service

# 2. Create the .env file using those variables
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-2.5-flash"
EOF

7. สร้างเวิร์กโฟลว์ของ 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
import google.cloud.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 ---

cloud_logging_client = google.cloud.logging.Client()
cloud_logging_client.setup_logging()

load_dotenv()

model_name = os.getenv("MODEL")
    บล็อกแรกของไฟล์ agent.py จะนำเข้าไลบรารีที่จำเป็นทั้งหมดจาก ADK และ Google Cloud นอกจากนี้ ยังตั้งค่าการบันทึกและโหลดตัวแปรสภาพแวดล้อมจากไฟล์ .env ซึ่งมีความสำคัญอย่างยิ่งต่อการเข้าถึง URL ของโมเดลและเซิร์ฟเวอร์
  3. กำหนดเครื่องมือ: ความสามารถของเอเจนต์ขึ้นอยู่กับเครื่องมือที่ใช้ได้ เพิ่มโค้ดต่อไปนี้ที่ด้านล่างของ 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
wikipedia_tool = LangchainTool(
    tool=WikipediaQueryRun(api_wrapper=WikipediaAPIWrapper())
)
    คำอธิบายเครื่องมือ
    • add_prompt_to_state 📝: เครื่องมือนี้จะจดจำสิ่งที่ผู้เข้าชมสวนสัตว์ถาม เมื่อผู้เข้าชมถามว่า "สิงโตอยู่ตรงไหน" เครื่องมือนี้จะบันทึกคำถามนั้นลงในหน่วยความจำของตัวแทน เพื่อให้ตัวแทนคนอื่นๆ ในเวิร์กโฟลว์รู้ว่าต้องค้นหาอะไร
      วิธี: เป็นฟังก์ชัน Python ที่เขียนพรอมต์ของผู้เข้าชมลงในพจนานุกรม tool_context.state ที่แชร์ บริบทของเครื่องมือนี้แสดงถึงหน่วยความจำระยะสั้นของเอเจนต์สำหรับการสนทนาครั้งเดียว ตัวแทนรายหนึ่งบันทึกข้อมูลลงในสถานะได้ และตัวแทนรายถัดไปในเวิร์กโฟลว์จะอ่านข้อมูลนั้นได้
    • LangchainTool 🌍: การดำเนินการนี้จะช่วยให้เอเจนต์ไกด์นำเที่ยวมีความรู้ทั่วไปเกี่ยวกับโลก เมื่อผู้เข้าชมถามคำถามที่ไม่มีในฐานข้อมูลของสวนสัตว์ เช่น "สิงโตกินอะไรในป่า" เครื่องมือนี้จะช่วยให้ตัวแทนค้นหาคำตอบใน Wikipedia ได้
      วิธี: ทำหน้าที่เป็นอะแดปเตอร์ที่ช่วยให้เอเจนต์ของเราใช้เครื่องมือ WikipediaQueryRun ที่สร้างไว้ล่วงหน้าจากไลบรารี LangChain ได้
      หุ่นยนต์หน้าตาเป็นมิตรถือสมุดโน้ตที่มีภาพวาดสัตว์และบับเบิลความคิดเป็นรูปสิงโต โดยกำลังพูดคุยกับชายและเด็กชายสะพายเป้ ยีราฟและองค์ประกอบอื่นๆ ของสวนสัตว์อยู่ด้านหลัง โดยมีต้นปาล์มอยู่บริเวณทางเข้า
  4. กำหนดตัวแทนผู้เชี่ยวชาญ: เพิ่มโค้ดต่อไปนี้ที่ด้านล่างของ 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 เอเจนต์คือ "สมอง" ของการทำงานของเรา โดยจะรับพรอมต์ของผู้ใช้จาก State ที่แชร์ ตรวจสอบว่าพรอมต์นั้นเป็นเครื่องมือ Wikipedia หรือไม่ และตัดสินใจว่าจะใช้พรอมต์ใดเพื่อค้นหาคำตอบ
    • response_formatter บทบาทของเอเจนต์คือการนำเสนอ โดยจะใช้ข้อมูลดิบที่รวบรวมโดยเอเจนต์ Researcher (ส่งผ่านทาง State) และใช้ทักษะด้านภาษาของ LLM เพื่อเปลี่ยนข้อมูลดังกล่าวให้เป็นการตอบกลับแบบสนทนาที่เป็นมิตร
      หุ่นยนต์ที่มีดวงตาสีน้ำเงินเรืองแสงนั่งอยู่หน้าจอโค้งขนาดใหญ่ที่แสดง MCP ZOO SERVER ทางด้านซ้ายและหน้า Wikipedia ของ ZOO ทางด้านขวา ไอคอนสัตว์จะปรากฏในอินเทอร์เฟซเซิร์ฟเวอร์ โต๊ะมีทัชแพดสีน้ำเงินเรืองแสงหลายอัน พื้นหลังแสดงภาพทิวทัศน์เส้นขอบฟ้าในเมืองผ่านหน้าต่างบานใหญ่
  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 ทำหน้าที่เป็นผู้จัดการ "แบ็กออฟฟิศ" สำหรับทัวร์สวนสัตว์ โดยจะรับคำขอการค้นคว้าและตรวจสอบว่าเอเจนต์ 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 เป็นจุดเริ่มต้นของการสนทนาใหม่ทั้งหมด โดยมีบทบาทหลักในการประสานงานกระบวนการโดยรวม โดยจะทำหน้าที่เป็นตัวควบคุมเริ่มต้นที่จัดการการสนทนาในรอบแรก
    หุ่นยนต์ 3 ตัวปรากฏในภาพ โดยมีหุ่นยนต์ต้อนรับทางด้านซ้ายกำลังเขียนบนสมุดโน้ตพร้อมฟองคำพูดรูปสิงโต หุ่นยนต์นักวิจัยตรงกลางนั่งอยู่ที่โต๊ะพร้อมคอมพิวเตอร์ที่แสดงข้อมูลและลูกศรคำค้นหาที่ชี้ไปที่หุ่นยนต์ตัวนั้น และหุ่นยนต์ผู้นำเสนอทางด้านขวากำลังยิ้มขณะถือแผนภูมิที่มีป้ายกำกับว่า &quot;ข้อมูลที่วิเคราะห์แล้ว&quot; พร้อมลูกศรที่ชี้ไปที่แผนภูมินั้นจากหุ่นยนต์นักวิจัย มองเห็นยีราฟและช้างอยู่ด้านหลัง และมีต้นปาล์มเป็นกรอบของฉาก

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

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

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

import os
import logging
import google.cloud.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 ---

cloud_logging_client = google.cloud.logging.Client()
cloud_logging_client.setup_logging()

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
wikipedia_tool = LangchainTool(
    tool=WikipediaQueryRun(api_wrapper=WikipediaAPIWrapper())
)

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

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

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

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

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

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

ตั้งค่าสิทธิ์ IAM

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

  1. ในเทอร์มินัล ให้โหลดตัวแปรลงในเซสชันเชลล์
    source .env
  2. สร้างบัญชีบริการเฉพาะสำหรับบริการ Cloud Run เพื่อให้มีสิทธิ์เฉพาะของตัวเอง วางข้อความต่อไปนี้ลงในเทอร์มินัล
    gcloud iam service-accounts create ${SA_NAME} \
    --display-name="Service Account for lab 2 "
    การสร้างข้อมูลประจำตัวเฉพาะสำหรับแอปพลิเคชันนี้จะช่วยให้มั่นใจได้ว่าเอเจนต์จะมีสิทธิ์ที่จำเป็นเท่านั้น แทนที่จะใช้บัญชีเริ่มต้นที่มีสิทธิ์เข้าถึงที่กว้างเกินไป
  3. มอบบทบาทผู้ใช้ Vertex AI ให้กับบัญชีบริการ ซึ่งจะให้สิทธิ์ในการเรียกใช้โมเดลของ Google
    # Grant the "Vertex AI User" role to your service account
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$SERVICE_ACCOUNT" \
  --role="roles/aiplatform.user"

9. ติดตั้งใช้งานเอเจนต์โดยใช้ ADK CLI

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

  1. เรียกใช้คำสั่งต่อไปนี้ในเทอร์มินัลเพื่อติดตั้งใช้งานเอเจนต์
    # Run the deployment command
uvx --from google-adk \
adk deploy cloud_run \
  --project=$PROJECT_ID \
  --region=europe-west1 \
  --service_name=zoo-tour-guide \
  --with_ui \
  . \
  -- \
  --labels=dev-tutorial=codelab-adk \
  --service-account=$SERVICE_ACCOUNT
    คำสั่ง uvx ช่วยให้คุณเรียกใช้เครื่องมือบรรทัดคำสั่งที่เผยแพร่เป็นแพ็กเกจ Python ได้โดยไม่ต้องติดตั้งเครื่องมือเหล่านั้นทั่วโลก
  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. หากระบบแจ้งให้คุณดำเนินการต่อไปนี้
    Allow unauthenticated invocations to [your-service-name] (y/N)?.
    พิมพ์ y แล้วกด ENTER ซึ่งจะช่วยให้เรียกใช้ที่ไม่ผ่านการตรวจสอบสิทธิ์สำหรับห้องทดลองนี้ได้เพื่อให้ทดสอบได้ง่าย เมื่อดำเนินการสำเร็จแล้ว คำสั่งจะแสดง URL ของบริการ Cloud Run ที่ใช้งาน (จะมีลักษณะคล้ายกับ https://zoo-tour-guide-123456789.europe-west1.run.app)
  4. คัดลอก URL ของบริการ Cloud Run ที่ติดตั้งใช้งานแล้วสำหรับงานถัดไป

10. ทดสอบ 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?
    ภาพหน้าจอของเอเจนต์ ADK ที่ทําลําดับการดําเนินการ ได้แก่ add_prompt_to_state, transfer_to_agent, wikipedia และ get_animals_by_species คำตอบแรกบอกว่า &quot;ฉันบอกคุณไม่ได้ว่าหมีขั้วโลกอยู่ในส่วนใดของสวนสัตว์แห่งนี้ แต่ฉันบอกคุณได้ว่าพวกมันกินอะไร&quot; คำตอบที่ 2 ระบุว่า &quot;หมีขั้วโลกอยู่ที่นิทรรศการอาร์กติกบนเส้นทางขั้วโลก เราไม่สามารถดึงข้อมูลเกี่ยวกับอาหารของสัตว์ดังกล่าวด้วยเครื่องมือที่มีอยู่ได้&quot; คำตอบที่ 3 ซึ่งครอบคลุมที่สุดกล่าวว่า &quot;เรายินดีที่จะบอกคุณเกี่ยวกับหมีขั้วโลก คุณสามารถชมหมีขั้วโลกได้ที่นิทรรศการอาร์กติกบนเส้นทางขั้วโลก เรามีหมีขั้วโลก 3 ตัวที่นี่ ได้แก่ สโนว์เฟลก ซึ่งมีอายุ 7 ปี Blizzard อายุ 5 ขวบ ไอซ์เบิร์กอายุ 9 ขวบ ส่วนเรื่องอาหารการกิน หมีขั้วโลกส่วนใหญ่เป็นสัตว์กินเนื้อ โดยจะล่าแมวน้ำเป็นอาหาร โดยเฉพาะแมวน้ำวงแหวน นอกจากนี้ ยังกินวอลรัส วาฬเบลูกา และสัตว์บกบางชนิดด้วย&quot;

คำอธิบาย Agent Flow

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

1. The Zoo Greeter (โต๊ะต้อนรับ)

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

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

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

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

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

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

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

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

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

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

11. ล้างข้อมูลในสภาพแวดล้อม

โปรดลบโปรเจ็กต์ที่มีทรัพยากรหรือเก็บโปรเจ็กต์ไว้และลบทรัพยากรแต่ละรายการเพื่อหลีกเลี่ยงการเรียกเก็บเงินจากบัญชี 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

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

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

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

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

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

สรุป

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

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

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

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

13. แบบสำรวจ

เอาต์พุต:

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

อ่านอย่างเดียว อ่านและทำแบบฝึกหัดให้เสร็จ