ADK: ตั้งแต่พื้นฐานไปจนถึงเอเจนต์แบบมัลติทูล

1. บทนำ

Codelab นี้จะเริ่มต้นด้วยพื้นฐานและก้าวไปสู่การพัฒนา Agent แบบหลายเครื่องมือ โดยจะแนะนำการสร้าง Agent ด้วย ADK อย่างครอบคลุม

AI Agent อย่างง่ายที่สุดคือระบบซอฟต์แวร์ที่ใช้โมเดลภาษาขนาดใหญ่ (LLM) เป็น "เครื่องมือให้เหตุผล" เพื่อให้บรรลุเป้าหมายโดยการทำงานตามลำดับงานต่างๆ โดยอัตโนมัติ

หาก LLM เป็นที่ปรึกษาที่มีความสามารถสูงซึ่งสามารถให้คำแนะนำแก่คุณได้ เอเจนต์ AI ก็เป็นวิศวกรที่ทำงานเชิงรุกซึ่งสามารถใช้เครื่องมือเพื่อปฏิบัติตามคำแนะนำนั้น

LLM เทียบกับเอเจนต์

สมอง (LLM): ให้การให้เหตุผล การวางแผน และความเข้าใจภาษาธรรมชาติ โดยจะตัดสินใจว่าต้องทำอะไรบ้าง

มือ (เครื่องมือ): คือ API, SDK และฟังก์ชันที่กำหนดเองซึ่งช่วยให้ Agent โต้ตอบกับโลกแห่งความจริงได้ โดยจะดำเนินการตามแผน

Agent Development Kit (ADK)

Agent Development Kit (ADK) เป็นเฟรมเวิร์กเฉพาะที่ออกแบบมาเพื่อลดความซับซ้อนในการสร้าง การทำให้ใช้งานได้ และการจัดการเป็นกลุ่ม AI Agent โดยมีองค์ประกอบพื้นฐานที่ได้มาตรฐานซึ่งจำเป็นต่อการเปลี่ยนโมเดลภาษาขนาดใหญ่แบบคงที่ให้เป็น Agent แบบไดนามิกที่สามารถเรียกใช้โค้ด เรียกใช้ API และจัดการเวิร์กโฟลว์แบบหลายขั้นตอนได้

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

สิ่งที่คุณจะสร้าง

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

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

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

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

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

เปิดใช้งาน Cloud Shell

คุณจะใช้ Cloud Shell ซึ่งเป็นสภาพแวดล้อมบรรทัดคำสั่งที่ทำงานใน คอนโซล Google Cloud และโหลดภาษาที่จำเป็นไว้ล่วงหน้า จาก Cloud Console ให้คลิกเปิดใช้งาน Cloud Shell ที่มุมบนขวา

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

gcloud auth list

เรียกใช้คำสั่งต่อไปนี้ใน Cloud Shell เพื่อยืนยันว่าคำสั่ง gcloud รู้จักโปรเจ็กต์ของคุณ

gcloud config list project

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

gcloud config set project <YOUR_PROJECT_ID>

โปรดดูคำสั่งและการใช้งาน gcloud ในเอกสารประกอบ

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

สำหรับ Codelab นี้ เราจะใช้โปรแกรมแก้ไข Cloud ในตัว ในหน้าต่าง Cloud Shell ให้คลิกปุ่ม "เปิดเครื่องมือแก้ไข" ที่มุมขวาบน ซึ่งจะเปิดโปรแกรมแก้ไข VSCode ให้คุณ

3. การตั้งค่า ADK

ไปที่เทอร์มินัล Cloud Shell ที่เราเปิดใช้งานในส่วนก่อนหน้ากัน

สร้างและเปิดใช้งานสภาพแวดล้อมเสมือน (แนะนำ)

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

python -m venv .venv

เปิดใช้งานสภาพแวดล้อมเสมือน

source .venv/bin/activate

ติดตั้ง ADK

pip install google-adk

4. คีย์ Google API

สร้างคีย์ API ของ Google โดยใช้ AI Studio

ไปที่ https://aistudio.google.com/ แล้วคลิก Get API Key จากเมนูด้านซ้ายล่าง

คุณจะเห็นหน้าต่างคีย์ API ให้คลิกสร้างคีย์ API ในหน้าต่างนี้

คุณจะเห็นป๊อปอัปสำหรับการสร้างคีย์ใหม่ ตั้งชื่อคีย์เป็น healthy-hints-key

ไปที่เมนูแบบเลื่อนลง "เลือกโปรเจ็กต์ที่นำเข้า"

คลิก Import Project จะมีหน้าต่างด้านข้างแสดงโปรเจ็กต์ Google Cloud ทั้งหมดของคุณ ให้เลือกโปรเจ็กต์ที่ต้องการใช้

คลิกนำเข้า

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

5. ตัวอย่าง Agent

จากเทอร์มินัล Cloud Shell ให้สร้างไดเรกทอรีรากสำหรับ Agent ในตำแหน่งโปรเจ็กต์ที่ต้องการ

adk create healthy_hints

คุณเลือกโมเดลใดก็ได้ แต่สำหรับ Codelab นี้ เราจะใช้ gemini-2.5-flash

สำหรับ Codelab นี้ เราจะใช้ Google AI วางคีย์ API ที่คุณสร้างไว้ในขั้นตอนก่อนหน้า

มาเปิดโฟลเดอร์ที่เราเพิ่งสร้างกัน ในเมนูทางซ้ายสุด ให้คลิกไอคอน แล้วคลิกไฟล์ -> เปิดโฟลเดอร์ เลือกโฟลเดอร์ healthy_hints ที่เพิ่งสร้าง ซึ่งโดยปกติจะอยู่ในโฟลเดอร์ /home/<username>
โดยปกติแล้ว โครงสร้างโฟลเดอร์ healthy_hints จะมีลักษณะดังนี้

คุณจะเห็นไฟล์ .env ซึ่งมีคีย์ API ของ Google คุณใช้ไฟล์นี้เพื่อตั้งค่าตัวแปรสภาพแวดล้อมได้
นอกจากนี้ ระบบยังสร้างไฟล์อื่นชื่อ agent.py ซึ่งเป็นไฟล์ Agent หลักของเราด้วย ระบบจะสร้างตัวแทนรูทตัวอย่างที่นี่ มาดูเนื้อหาของไฟล์นี้อย่างละเอียดกันก่อน โดยเราจะนำเข้า llm_agent จาก ADK ก่อน จากนั้นเราจะใช้ ADK DSL เพื่อสร้างเอเจนต์รูท เราจะระบุชื่อโมเดลเป็น Gemini-2.5-flash ตั้งชื่อเอเจนต์ และใส่คำอธิบายที่เหมาะสม คำสั่งเป็นสิ่งสำคัญที่สุดในที่นี้ ซึ่งเป็นส่วนที่เราบอกตัวแทนในภาษาที่เป็นธรรมชาติว่าต้องทำอะไร
Agent ตัวอย่างนี้ค่อนข้างทั่วไป โดยจะตอบคำถามใดๆ ก็ตามที่ผู้ใช้ถาม
ตอนนี้เรามาเรียกใช้ Agent นี้ในเครื่องกัน คุณโต้ตอบกับเอเจนต์นี้ได้ 2 วิธี ได้แก่ CLI และเว็บ
CLI: เรียกใช้คำสั่งต่อไปนี้จากภายนอกไดเรกทอรี healthy_hints

adk run healthy_hints

หรือหากคุณอยู่ในไดเรกทอรี healthy_hints ให้เรียกใช้คำสั่งต่อไปนี้

adk run .

คุณจะเห็นเอาต์พุตที่คล้ายกันดังนี้

เขียนว่า "สวัสดี" หรือคำถามที่คุณมี คำตอบอาจแตกต่างกันไปสำหรับแต่ละคน ซึ่งเป็นลักษณะของ GenAI

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

adk web

6. Agent เครื่องมืออเนกประสงค์

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

ประเภทของเครื่องมือใน ADK

เครื่องมือฟังก์ชัน: ตรรกะที่กำหนดเองซึ่งคุณเขียนขึ้นเอง เช่น ฟังก์ชันที่เชื่อมต่อกับฐานข้อมูลที่เฉพาะเจาะจง หรือ "ตัวแยกวิเคราะห์บันทึก" ที่กำหนดเองสำหรับรูปแบบเฉพาะของบริษัท
เครื่องมือในตัว: ความสามารถที่พร้อมใช้งานซึ่ง Google หรือ ADK จัดหาให้ เช่น Google Search, Code Interpreter หรือ Google RAG Engine
Agents-as-Tools: ในระบบ "มัลติทูล" หรือ "มัลติเอเจนต์" ขั้นสูง เอเจนต์เฉพาะทางหนึ่งตัวสามารถทำหน้าที่เป็นเครื่องมือสำหรับอีกตัวหนึ่งได้ ตัวอย่างเช่น "Search Agent" อาจเป็นเครื่องมือที่ "Research Manager Agent" ใช้

ใน Codelab นี้ เราจะพูดถึงเครื่องมือฟังก์ชัน ตอนนี้เรามาพัฒนา Agent และทำให้เป็นเครื่องมืออเนกประสงค์กัน

มาเพิ่มเมธอดใหม่ get_weather ใน agent.py กัน

def get_weather(city: str) -> dict:
  """Retrieves the current weather report for a specified city.

  Args:
    city (str): The name of the city for which to retrieve the weather report.

  Returns:
    dict: status and result or error msg.
  """
  if city.lower() == "new york":
    return {
      "status": "success",
      "report": (
          "The weather in New York is sunny with a temperature of 25 degrees"
          " Celsius (77 degrees Fahrenheit)."
      ),
    }
  else:
    return {
      "status": "error",
      "error_message": f"Weather information for '{city}' is not available.",
    }

มาแก้ไข agent.py และเปลี่ยนชื่อ คำอธิบาย และวิธีการของเอเจนต์กัน

root_agent = Agent(
    model='gemini-2.5-flash',
    name='healthy_hints_agent',
    description='Agent to answer questions about the weather in a city.',
    instruction='You are a helpful agent who can answer user questions about the weather in a city.',
    tools=[get_weather],
)

ขณะนี้เราได้สร้างเครื่องมือเพียงอย่างเดียว ตอนนี้มาสร้างเครื่องมือหลายอย่างกัน

มาสร้างเมธอดอื่นที่ชื่อ get_current_time กัน

def get_current_time(city: str) -> dict:
  """Returns the current time in a specified city.

  Args:
    city (str): The name of the city for which to retrieve the current time.

  Returns:
    dict: status and result or error msg.
  """

  if city.lower() == "new york":
    tz_identifier = "America/New_York"
  else:
    return {
      "status": "error",
      "error_message": (
        f"Sorry, I don't have timezone information for {city}."
      ),
    }

  tz = ZoneInfo(tz_identifier)
  now = datetime.datetime.now(tz)
  report = (
    f'The current time in {city} is {now.strftime("%Y-%m-%d %H:%M:%S %Z%z")}'
  )
  return {"status": "success", "report": report}

และมาแก้ไข Agent เพื่อเรียกใช้เครื่องมือนี้กัน

root_agent = Agent(
  model='gemini-2.5-flash',
  name='healthy_hints_agent',
  description='Agent to answer questions about the time and weather in a city.',
  instruction='You are a helpful agent who can answer user questions about the time and weather in a city.',
  tools=[get_weather, get_current_time],
)

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

7. การผสานรวม SDK

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

มาสร้าง Bucket ก่อนเพื่ออัปโหลดรูปภาพใน Google Cloud Storage มาเปิดแท็บใหม่แล้วไปที่ https://console.cloud.google.com/ แล้วพิมพ์ Cloud Storage ในแถบค้นหา ตอนนี้ ให้เลือก Cloud Storage ในส่วนผลิตภัณฑ์และหน้าเว็บ

ระบบจะนำคุณไปยังหน้าภาพรวมของ Google Cloud Storage คลิกปุ่ม Create bucket ในหน้าสร้าง Bucket ให้ป้อนชื่อ Bucket คุณจะตั้งชื่ออะไรก็ได้ แต่สำหรับ Codelab นี้ เราจะตั้งชื่อเป็น healthy-hints-bucket-kolkata ปล่อยให้ส่วนอื่นๆ เหมือนเดิม แล้วคลิกปุ่ม Create

มาสร้างไฟล์ใหม่ชื่อ requirements.txt แล้วเพิ่ม google-cloud-storage ลงในไฟล์กัน เราจะใช้ Python Storage SDK เพื่ออัปโหลดรูปภาพใน Storage

ก่อนอื่นมาติดตั้งการอ้างอิงกัน

pip install -r requirements.txt

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

gcloud services enable storage.googleapis.com

ตอนนี้มาเพิ่มเครื่องมือใหม่เพื่ออัปโหลดรูปภาพกัน

def upload_image() -> str:
  storage_client = storage.Client()
  bucket_name = "healthy-hints-bucket-kolkata"
  bucket = storage_client.bucket(bucket_name)
  blob = bucket.blob("ingredirents")
  blob.upload_from_filename(<image-file-path>)

ตอนนี้เรามาอัปเดต Agent เพื่อให้ใช้เครื่องมือใหม่กัน

root_agent = Agent(
  model='gemini-2.5-flash',
  name='healthy_hints_agent',
  description='Agent to upload image to Google Cloud Storage',
  instruction='You are a helpful agent who will upload the image to Google Cloud Storage using `upload_image` tool.',
  tools=[upload_image],
)

ตอนนี้เราจะเพิ่มเครื่องมืออีกอย่างเพื่ออ่านส่วนผสมจากรูปภาพ มาเพิ่ม google-cloud-vision ใน requirements.txt และติดตั้งทรัพยากร Dependency ใหม่กัน

pip install -r requirements.txt

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

gcloud services enable vision.googleapis.com

ตอนนี้มาเพิ่มเครื่องมือใหม่ read_ingredients กัน

def read_ingredients() -> str:
  vision_client = vision.ImageAnnotatorClient()

  with io.open("/home/bajajnehaa/healthy_hints/images/Ingredients-list.jpg", 'rb') as image_file:
    content = image_file.read()

  image = vision.Image(content=content)
  response = vision_client.text_detection(image=image)
  texts = response.text_annotations
  return texts[0].description

และตอนนี้เรามาอัปเดต Agent ให้ใช้เครื่องมือนี้กัน

root_agent = Agent(
  model='gemini-2.5-flash',
  name='healthy_hints_agent',
  description='Agent to upload image to Google Cloud Storage, read the list of ingredients from the image and explain if the ingredient is healthy or not',
  instruction='You are a helpful agent who will upload the image to Google Cloud Storage using `upload_image` tool, read the ingredients of the image using `read_ingredients` tool and explain if the ingredient is healthy or not in one line.',
  tools=[upload_image, read_ingredients],
)

8. บทสรุป

ขอแสดงความยินดีที่ทำ Codelab เคล็ดลับเพื่อสุขภาพสำเร็จ คุณเปลี่ยน AI มาตรฐานจากเครื่องมือสร้างข้อความให้เป็นเอเจนต์แบบมัลติทูลเชิงรุกได้สำเร็จแล้ว การใช้ ADK เพื่อผสานรวม Vision API และ Cloud Storage SDK ทำให้เอเจนต์มี "ดวงตา" เพื่ออ่านป้ายกำกับและ "หน่วยความจำ" เพื่อเก็บถาวร คุณได้เห็นแล้วว่า Agent ตัดสินใจด้วยตนเองว่าจะบันทึกไฟล์เมื่อใดและตีความข้อมูลดิบเพื่อให้คำแนะนำด้านสุขภาพในชีวิตจริงได้อย่างไร

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