สร้างตัวแทนท่องเที่ยวโดยใช้กล่องเครื่องมือ MCP สำหรับฐานข้อมูลและชุดพัฒนาตัวแทน (ADK)

สร้างตัวแทนท่องเที่ยวโดยใช้กล่องเครื่องมือ MCP สำหรับฐานข้อมูลและชุดพัฒนาตัวแทน (ADK)

เกี่ยวกับ Codelab นี้

อัปเดตล่าสุดเมื่อ มิ.ย. 13, 2025

เขียนโดย Romin Irani Jack Wotherspoon

1 บทนำ

ในโค้ดแล็บนี้ คุณจะได้สร้างตัวแทนโดยใช้ Agent Development Kit (ADK) ที่ใช้ MCP Toolbox for Databases

คุณจะทําตามขั้นตอนทีละขั้นตอนผ่าน Codelab ดังนี้

1. จัดสรรฐานข้อมูล Cloud SQL สำหรับ PostgreSQL ที่จะมีฐานข้อมูลโรงแรมและข้อมูลตัวอย่าง
2. ตั้งค่ากล่องเครื่องมือ MCP สําหรับฐานข้อมูลที่ให้สิทธิ์เข้าถึงข้อมูล
3. ออกแบบและพัฒนาตัวแทนโดยใช้ Agent Development Kit (ADK) ที่จะใช้กล่องเครื่องมือ MCP เพื่อตอบคำถามจากผู้ใช้
4. สํารวจตัวเลือกในการทดสอบ Agent และ MCP Toolbox สําหรับฐานข้อมูลในเครื่องและใน Google Cloud ผ่านบริการ Cloud Run

สิ่งที่ต้องทำ

• ออกแบบ สร้าง และติดตั้งใช้งานตัวแทนที่จะตอบคำถามของผู้ใช้เกี่ยวกับโรงแรมในสถานที่ตั้งหรือค้นหาโรงแรมตามชื่อ

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

• การจัดสรรและป้อนข้อมูลตัวอย่างลงในฐานข้อมูล Cloud SQL สำหรับ PostgreSQL
• ตั้งค่ากล่องเครื่องมือ MCP สำหรับฐานข้อมูลสําหรับอินสแตนซ์ฐานข้อมูล Cloud SQL สําหรับ PostgreSQL
• ออกแบบและพัฒนาตัวแทนโดยใช้ชุดพัฒนาตัวแทน (ADK) เพื่อตอบคําค้นหาของผู้ใช้
• ทดสอบ Agent และกล่องเครื่องมือ MCP สําหรับฐานข้อมูลในสภาพแวดล้อมในเครื่อง
• (ไม่บังคับ) ติดตั้งใช้งาน Agent และกล่องเครื่องมือ MCP สำหรับฐานข้อมูลใน Google Cloud

สิ่งที่ต้องมี

• เว็บเบราว์เซอร์ Chrome
• บัญชี Gmail
• โปรเจ็กต์ที่อยู่ในระบบคลาวด์ที่เปิดใช้การเรียกเก็บเงิน

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

2 ก่อนเริ่มต้น

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

1. ในคอนโซล Google Cloud ให้เลือกหรือสร้างโปรเจ็กต์ Google Cloud ในหน้าตัวเลือกโปรเจ็กต์
2. ตรวจสอบว่าเปิดใช้การเรียกเก็บเงินสำหรับโปรเจ็กต์ Cloud แล้ว ดูวิธีตรวจสอบว่าเปิดใช้การเรียกเก็บเงินในโปรเจ็กต์หรือไม่
3. คุณจะใช้ Cloud Shell ซึ่งเป็นสภาพแวดล้อมบรรทัดคำสั่งที่ทำงานใน Google Cloud และโหลด bq ไว้ล่วงหน้า คลิก "เปิดใช้งาน Cloud Shell" ที่ด้านบนของคอนโซล Google Cloud

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

gcloud auth list

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

gcloud config list project

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

gcloud config set project <YOUR_PROJECT_ID>

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

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

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

Operation "operations/..." finished successfully.

อีกทางเลือกหนึ่งสำหรับคำสั่ง gcloud คือผ่านคอนโซลโดยค้นหาผลิตภัณฑ์แต่ละรายการหรือใช้ลิงก์นี้

หากมี API ใดขาดหายไป คุณสามารถเปิดใช้งานได้ทุกเมื่อในระหว่างการติดตั้งใช้งาน

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

3 สร้างอินสแตนซ์ Cloud SQL

เราจะใช้อินสแตนซ์ Google Cloud SQL for PostgreSQL เพื่อจัดเก็บข้อมูลโรงแรม Cloud SQL สำหรับ PostgreSQL เป็นบริการฐานข้อมูลที่จัดการโดยสมบูรณ์ซึ่งจะช่วยคุณตั้งค่า บำรุงรักษา จัดการ และดูแลฐานข้อมูลเชิงสัมพันธ์ PostgreSQL ใน Google Cloud Platform

เรียกใช้คําสั่งต่อไปนี้ใน Cloud Shell เพื่อสร้างอินสแตนซ์

gcloud sql instances create hoteldb-instance \
--database-version=POSTGRES_15 \
--cpu=2 \
--memory=8GiB \
--region=us-central1 \
--edition=ENTERPRISE \
--root-password=postgres

คำสั่งนี้จะใช้เวลาดำเนินการประมาณ 3-5 นาที เมื่อเรียกใช้คําสั่งสําเร็จแล้ว คุณควรเห็นเอาต์พุตที่ระบุว่าคําสั่งเสร็จสมบูรณ์แล้ว พร้อมกับข้อมูลอินสแตนซ์ Cloud SQL เช่น NAME, DATABASE_VERSION, LOCATION ฯลฯ

4 เตรียมฐานข้อมูลโรงแรม

ตอนนี้งานของเราคือสร้างข้อมูลตัวอย่างสำหรับตัวแทนโรงแรม

ไปที่หน้า Cloud SQL ในคอนโซลระบบคลาวด์ คุณควรเห็น hoteldb-instance พร้อมใช้งานและสร้างขึ้นแล้ว คลิกชื่ออินสแตนซ์ (hoteldb-instance) ดังที่แสดงด้านล่าง

จากเมนูด้านซ้ายของ Cloud SQL ให้ไปที่ตัวเลือกเมนู Cloud SQL Studio ดังที่แสดงด้านล่าง

ระบบจะขอให้คุณลงชื่อเข้าใช้ Cloud SQL Studio ซึ่งเราจะใช้สั่ง SQL 2-3 คำสั่ง เลือก postgres สำหรับตัวเลือกฐานข้อมูล และสำหรับทั้งผู้ใช้และรหัสผ่าน ค่าที่จะใช้คือ postgres คลิก AUTHENTICATE

ก่อนอื่นให้สร้างตารางโรงแรมตามสคีมาที่ระบุไว้ด้านล่าง ในแผงเครื่องมือแก้ไขใน Cloud SQL Studio ให้เรียกใช้ SQL ต่อไปนี้

CREATE TABLE hotels(
 id            INTEGER NOT NULL PRIMARY KEY,
 name          VARCHAR NOT NULL,
 location      VARCHAR NOT NULL,
 price_tier    VARCHAR NOT NULL,
 checkin_date  DATE    NOT NULL,
 checkout_date DATE    NOT NULL,
 booked        BIT     NOT NULL
);

ตอนนี้มาป้อนข้อมูลตัวอย่างในตารางโรงแรมกัน เรียกใช้ SQL ต่อไปนี้

INSERT INTO hotels(id, name, location, price_tier, checkin_date, checkout_date, booked)
VALUES
 (1, 'Hilton Basel', 'Basel', 'Luxury', '2024-04-22', '2024-04-20', B'0'),
 (2, 'Marriott Zurich', 'Zurich', 'Upscale', '2024-04-14', '2024-04-21', B'0'),
 (3, 'Hyatt Regency Basel', 'Basel', 'Upper Upscale', '2024-04-02', '2024-04-20', B'0'),
 (4, 'Radisson Blu Lucerne', 'Lucerne', 'Midscale', '2024-04-24', '2024-04-05', B'0'),
 (5, 'Best Western Bern', 'Bern', 'Upper Midscale', '2024-04-23', '2024-04-01', B'0'),
 (6, 'InterContinental Geneva', 'Geneva', 'Luxury', '2024-04-23', '2024-04-28', B'0'),
 (7, 'Sheraton Zurich', 'Zurich', 'Upper Upscale', '2024-04-27', '2024-04-02', B'0'),
 (8, 'Holiday Inn Basel', 'Basel', 'Upper Midscale', '2024-04-24', '2024-04-09', B'0'),
 (9, 'Courtyard Zurich', 'Zurich', 'Upscale', '2024-04-03', '2024-04-13', B'0'),
 (10, 'Comfort Inn Bern', 'Bern', 'Midscale', '2024-04-04', '2024-04-16', B'0');

มาตรวจสอบข้อมูลกันโดยเรียกใช้ SQL ของ SELECT ดังที่แสดงด้านล่าง

SELECT * FROM hotels;

คุณควรเห็นจํานวนระเบียนในตารางโรงแรมดังที่แสดงด้านล่าง

เราได้ดำเนินการตั้งค่าอินสแตนซ์ Cloud SQL และสร้างข้อมูลตัวอย่างเรียบร้อยแล้ว ในส่วนถัดไป เราจะตั้งค่ากล่องเครื่องมือ MCP สําหรับฐานข้อมูล

5 ตั้งค่ากล่องเครื่องมือ MCP สําหรับฐานข้อมูล

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

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

• การพัฒนาที่ง่ายขึ้น: ผสานรวมเครื่องมือกับตัวแทนได้โดยใช้โค้ดไม่ถึง 10 บรรทัด ใช้เครื่องมือซ้ำระหว่างตัวแทนหรือเฟรมเวิร์กหลายรายการ และทำให้ใช้งานเครื่องมือเวอร์ชันใหม่ได้ง่ายขึ้น
• ประสิทธิภาพที่ดีขึ้น: แนวทางปฏิบัติแนะนำ เช่น การรวมการเชื่อมต่อ การตรวจสอบสิทธิ์ และอื่นๆ
• การรักษาความปลอดภัยที่ดีขึ้น: การรับรองแบบรวมเพื่อการเข้าถึงข้อมูลที่ปลอดภัยยิ่งขึ้น
• การสังเกตการณ์จากต้นทางถึงปลายทาง: เมตริกและการติดตามที่พร้อมใช้งานทันทีพร้อมการรองรับ OpenTelemetry ในตัว

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

คุณจะเห็นว่าฐานข้อมูลหนึ่งที่ MCP Toolbox สำหรับฐานข้อมูลรองรับคือ Cloud SQL และเราได้จัดสรรข้อมูลในส่วนก่อนหน้านี้แล้ว

การติดตั้งกล่องเครื่องมือ

เปิดเทอร์มินัล Cloud Shell และสร้างโฟลเดอร์ชื่อ mcp-toolbox

mkdir mcp-toolbox

ไปที่โฟลเดอร์ mcp-toolbox ผ่านคําสั่งที่แสดงด้านล่าง

cd mcp-toolbox

ติดตั้ง MCP Toolbox สำหรับฐานข้อมูลเวอร์ชันไบนารีผ่านสคริปต์ที่ระบุไว้ด้านล่าง

export VERSION=0.6.0
curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox

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

การกําหนดค่า tools.yaml

วิธีหลักในการกำหนดค่ากล่องเครื่องมือคือผ่านไฟล์ tools.yaml สร้างไฟล์ชื่อ tools.yaml ในโฟลเดอร์เดียวกัน เช่น mcp-toolbox โดยเนื้อหาของไฟล์จะแสดงอยู่ด้านล่าง

คุณสามารถใช้เครื่องมือแก้ไข nano ที่มีอยู่ใน Cloud Shell คำสั่ง nano มีดังนี้ "nano tools.yaml"

อย่าลืมแทนที่ค่า YOUR_PROJECT_ID ด้วยรหัสโปรเจ็กต์ Google Cloud

sources:
 my-cloud-sql-source:
   kind: cloud-sql-postgres
   project: YOUR_PROJECT_ID
   region: us-central1
   instance: hoteldb-instance
   database: postgres
   user: postgres
   password: postgres

tools:
 search-hotels-by-name:
   kind: postgres-sql
   source: my-cloud-sql-source
   description: Search for hotels based on name.
   parameters:
     - name: name
       type: string
       description: The name of the hotel.
   statement: SELECT * FROM hotels WHERE name ILIKE '%' || $1 || '%';
 search-hotels-by-location:
   kind: postgres-sql
   source: my-cloud-sql-source
   description: Search for hotels based on location.
   parameters:
     - name: location
       type: string
       description: The location of the hotel.
   statement: SELECT * FROM hotels WHERE location ILIKE '%' || $1 || '%';

toolsets:
   my_first_toolset:
     - search-hotels-by-name
     - search-hotels-by-location

เราขออธิบายข้อมูลโดยย่อของไฟล์

1. Sources แสดงแหล่งข้อมูลต่างๆ ที่เครื่องมือโต้ตอบได้ แหล่งที่มาแสดงถึงแหล่งข้อมูลซึ่งเครื่องมือโต้ตอบได้ คุณสามารถกําหนด Sources เป็นแผนที่ได้ในส่วนแหล่งที่มาของไฟล์ tools.yaml โดยปกติแล้ว การกําหนดค่าแหล่งที่มาจะมีข้อมูลที่จําเป็นในการเชื่อมต่อและโต้ตอบกับฐานข้อมูล ในกรณีของเรา เราได้กําหนดค่าแหล่งที่มาแหล่งเดียวที่ชี้ไปยังอินสแตนซ์ Cloud SQL for PostgreSQL ด้วยข้อมูลเข้าสู่ระบบ ดูข้อมูลเพิ่มเติมได้ที่ข้อมูลอ้างอิงแหล่งที่มา
2. Tools กำหนดการดำเนินการที่ตัวแทนทำได้ เช่น การอ่านและเขียนไปยังแหล่งที่มา เครื่องมือแสดงการดำเนินการที่ตัวแทนสามารถทำได้ เช่น เรียกใช้คำสั่ง SQL คุณสามารถกําหนด Tools เป็นแผนที่ได้ในส่วนเครื่องมือของไฟล์ tools.yaml โดยทั่วไปแล้ว เครื่องมือจะต้องมีแหล่งที่มาเพื่อดำเนินการ ในกรณีนี้ เรากําหนดเครื่องมือ 2 อย่าง ได้แก่ search-hotels-by-name และ search-hotels-by-location และระบุแหล่งที่มาที่เครื่องมือจะทํางานด้วย รวมถึง SQL และพารามิเตอร์ ดูข้อมูลเพิ่มเติมได้ที่ข้อมูลอ้างอิงเครื่องมือ
3. สุดท้ายคือ Toolset ซึ่งช่วยให้คุณกําหนดกลุ่มเครื่องมือที่ต้องการโหลดร่วมกันได้ ซึ่งอาจมีประโยชน์ในการกําหนดกลุ่มต่างๆ ตามตัวแทนหรือแอปพลิเคชัน ในกรณีของเรา เรามีชุดเครื่องมือเดียวชื่อ my_first_toolset ซึ่งมีเครื่องมือ 2 รายการที่เราได้กําหนดไว้

เรียกใช้กล่องเครื่องมือ MCP สำหรับเซิร์ฟเวอร์ฐานข้อมูล

เรียกใช้คําสั่งต่อไปนี้ (จากโฟลเดอร์ mcp-toolbox) เพื่อเริ่มเซิร์ฟเวอร์

./toolbox --tools-file "tools.yaml"

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

./toolbox --tools-file "tools.yaml"
2025-04-23T14:32:29.564903079Z INFO "Initialized 1 sources." 
2025-04-23T14:32:29.565009291Z INFO "Initialized 0 authServices." 
2025-04-23T14:32:29.565070176Z INFO "Initialized 2 tools." 
2025-04-23T14:32:29.565120847Z INFO "Initialized 2 toolsets." 
2025-04-23T14:32:29.565510068Z INFO "Server ready to serve!" 

เซิร์ฟเวอร์ MCP Toolbox จะทำงานบนพอร์ต 5000 โดยค่าเริ่มต้น หากพบว่าพอร์ต 5000 มีการใช้งานอยู่แล้ว คุณก็ใช้พอร์ตอื่น (เช่น 7000) ได้ตามคำสั่งที่แสดงด้านล่าง โปรดใช้ 7000 แทนพอร์ต 5000 ในคำสั่งต่อๆ ไป

./toolbox --tools-file "tools.yaml" --port 7000

เรามาลองใช้ Cloud Shell เพื่อทดสอบกัน

คลิกตัวอย่างเว็บใน Cloud Shell ดังที่แสดงด้านล่าง

คลิกเปลี่ยนพอร์ต แล้วตั้งค่าพอร์ตเป็น 5000 ตามที่แสดงด้านล่าง แล้วคลิก "เปลี่ยนและแสดงตัวอย่าง"

ซึ่งจะแสดงผลลัพธ์ต่อไปนี้

ใน URL ของเบราว์เซอร์ ให้เพิ่มข้อความต่อไปนี้ต่อท้าย URL

/api/toolset

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

{
  "serverVersion": "0.3.0+container.12222fe27ae070f2689a0632d60fda45412d1f97",
  "tools": {
    "search-hotels-by-location": {
      "description": "Search for hotels based on location.",
      "parameters": [
        {
          "name": "location",
          "type": "string",
          "description": "The location of the hotel.",
          "authSources": []
        }
      ]
    },
    "search-hotels-by-name": {
      "description": "Search for hotels based on name.",
      "parameters": [
        {
          "name": "name",
          "type": "string",
          "description": "The name of the hotel.",
          "authSources": []
        }
      ]
    }
  }
}

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

6 การเขียน Agent ด้วย Agent Development Kit (ADK)

ติดตั้ง Agent Development Kit (ADK)

เปิดแท็บเทอร์มินัลใหม่ใน Cloud Shell และสร้างโฟลเดอร์ชื่อ my-agents ดังนี้ ไปที่โฟลเดอร์ my-agents ด้วย

mkdir my-agents
cd my-agents

ตอนนี้มาสร้างสภาพแวดล้อมเสมือนของ Python โดยใช้ venv กัน ดังนี้

python -m venv .venv

เปิดใช้งานสภาพแวดล้อมเสมือนโดยทำดังนี้

source .venv/bin/activate

ติดตั้งแพ็กเกจ ADK และ MCP Toolbox สำหรับฐานข้อมูลพร้อมกับการพึ่งพาของ langchain ดังนี้

pip install google-adk toolbox-core

ตอนนี้คุณเรียกใช้ยูทิลิตี adk ได้แล้ว ดังนี้

adk

รายการคำสั่งจะปรากฏขึ้น

$ adk
Usage: adk [OPTIONS] COMMAND [ARGS]...

  Agent Development Kit CLI tools.

Options:
  --help  Show this message and exit.

Commands:
  api_server  Starts a FastAPI server for agents.
  create      Creates a new app in the current folder with prepopulated agent template.
  deploy      Deploys agent to hosted environments.
  eval        Evaluates an agent given the eval sets.
  run         Runs an interactive CLI for a certain agent.
  web         Starts a FastAPI server with Web UI for agents.

การสร้างแอปพลิเคชันตัวแทนแอปแรก

ตอนนี้เราจะใช้ adk เพื่อสร้างสคาฟเฟิลดิ้งสําหรับแอปพลิเคชันตัวแทนโรงแรมผ่านคําสั่ง adk create ที่มีชื่อแอป **(hotel-agent-app)**ตามที่ระบุไว้ด้านล่าง

adk create hotel-agent-app

ทำตามขั้นตอนและเลือกสิ่งต่อไปนี้

• โมเดล Gemini สำหรับเลือกโมเดลของตัวแทนรูท
• เลือก Vertex AI สำหรับแบ็กเอนด์
• รหัสโปรเจ็กต์ Google และภูมิภาคเริ่มต้นจะแสดงขึ้น เลือกค่าเริ่มต้นเอง

Choose a model for the root agent:
1. gemini-2.0-flash-001
2. Other models (fill later)

Choose model (1, 2): 1
1. Google AI
2. Vertex AI
Choose a backend (1, 2): 2

You need an existing Google Cloud account and project, check out this link for details:
https://google.github.io/adk-docs/get-started/quickstart/#gemini---google-cloud-vertex-ai

Enter Google Cloud project ID [gcp-experiments-349209]: 
Enter Google Cloud region [us-central1]: 

Agent created in /home/romin/hotel-agent-app:
- .env
- __init__.py
- agent.py

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

ไฟล์แรกคือไฟล์ .env เนื้อหาของนโยบายมีดังนี้

GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=YOUR_GOOGLE_PROJECT_ID
GOOGLE_CLOUD_LOCATION=YOUR_GOOGLE_PROJECT_REGION

ค่าดังกล่าวบ่งบอกว่าเราจะใช้ Gemini ผ่าน Vertex AI พร้อมกับค่าที่เกี่ยวข้องสำหรับรหัสและตำแหน่งโปรเจ็กต์ Google Cloud

จากนั้นเรามีไฟล์ __init__.py ที่ทำเครื่องหมายโฟลเดอร์เป็นโมดูล และมีคำสั่งเดียวที่นำเข้าตัวแทนจากไฟล์ agent.py

from . import agent

สุดท้ายนี้ มาดูไฟล์ agent.py เนื้อหามีดังนี้

from google.adk.agents import Agent

root_agent = Agent(
    model='gemini-2.0-flash-001',
    name='root_agent',
    description='A helpful assistant for user questions.',
    instruction='Answer user questions to the best of your knowledge',
)

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

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

มาแก้ไขโค้ดสําหรับ agent.py กันดังนี้

from google.adk.agents import Agent

root_agent = Agent(
    model='gemini-2.0-flash-001',
    name='hotel_agent',
    description='A helpful assistant that answers questions about a specific city.',
    instruction='Answer user questions about a specific city to the best of your knowledge. Do not answer questions outside of this.',
)

ทดสอบแอปตัวแทนในเครื่อง

จากหน้าต่างเทอร์มินัลที่มีอยู่ ให้ป้อนคำสั่งต่อไปนี้ ตรวจสอบว่าคุณอยู่ในโฟลเดอร์หลัก (my-agents) ที่มีโฟลเดอร์ hotel-agent-app

adk web

ตัวอย่างการดำเนินการแสดงอยู่ด้านล่าง

INFO:     Started server process [5015]
INFO:     Waiting for application startup.

+-----------------------------------------------------------------------------+
| ADK Web Server started                                                      |
|                                                                             |
| For local testing, access at http://localhost:8000.                         |
+-----------------------------------------------------------------------------+

INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

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

โปรดสังเกตที่ด้านซ้ายบนว่ามีการกำหนด hotel-agent-app แล้ว ตอนนี้คุณเริ่มสนทนากับตัวแทนได้แล้ว ระบุพรอมต์ 2-3 รายการที่สอบถามเกี่ยวกับเมือง ตัวอย่างการสนทนาแสดงอยู่ด้านล่าง

คุณสามารถปิดกระบวนการที่ทำงานอยู่ในเทอร์มินัล Cloud Shell (Ctrl-C)

อีกวิธีในการทดสอบ Agent คือผ่านคําสั่ง adk run ตามที่ระบุไว้ด้านล่างจากโฟลเดอร์ my-agents

adk run hotel-agent-app

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

7 การเชื่อมต่อตัวแทนกับเครื่องมือ

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

ในกรณีนี้ เราจะให้เครื่องมือที่เรากำหนดค่าไว้ในกล่องเครื่องมือ MCP สำหรับฐานข้อมูลแก่ตัวแทน

แก้ไขไฟล์ agent.py ด้วยโค้ดต่อไปนี้ โปรดทราบว่าเราใช้พอร์ตเริ่มต้น 5000 ในโค้ด แต่หากคุณใช้หมายเลขพอร์ตอื่น โปรดใช้หมายเลขนั้น

from google.adk.agents import Agent
from toolbox_core import ToolboxSyncClient

toolbox = ToolboxSyncClient("http://127.0.0.1:5000")

# Load single tool
# tools = toolbox.load_tool('search-hotels-by-location')

# Load all the tools
tools = toolbox.load_toolset('my_first_toolset')

root_agent = Agent(
    name="hotel_agent",
    model="gemini-2.0-flash",
    description=(
        "Agent to answer questions about hotels in a city or hotels by name."
    ),
    instruction=(
        "You are a helpful agent who can answer user questions about the hotels in a specific city or hotels by name. Use the tools to answer the question"
    ),
    tools=tools,
)

ตอนนี้เราทดสอบ Agent ที่จะดึงข้อมูลจริงจากฐานข้อมูล PostgreSQL ที่กำหนดค่าด้วย MCP Toolbox สําหรับฐานข้อมูลได้แล้ว

โดยทำตามลำดับต่อไปนี้

เปิดกล่องเครื่องมือ MCP สำหรับฐานข้อมูลในเทอร์มินัลของ Cloud Shell 1 เครื่อง คุณอาจเรียกใช้แอปนี้ในเครื่องแล้วบนพอร์ต 5000 ตามที่เราทดสอบก่อนหน้านี้ หากไม่ ให้เรียกใช้คำสั่งต่อไปนี้ (จากโฟลเดอร์ mcp-toolbox) เพื่อเริ่มเซิร์ฟเวอร์

./toolbox --tools_file "tools.yaml"

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

./toolbox --tools-file "tools.yaml"
2025-04-23T14:32:29.564903079Z INFO "Initialized 1 sources." 
2025-04-23T14:32:29.565009291Z INFO "Initialized 0 authServices." 
2025-04-23T14:32:29.565070176Z INFO "Initialized 2 tools." 
2025-04-23T14:32:29.565120847Z INFO "Initialized 2 toolsets." 
2025-04-23T14:32:29.565510068Z INFO "Server ready to serve!" 

เมื่อเซิร์ฟเวอร์ MCP เริ่มทำงานเรียบร้อยแล้ว ให้เปิด Agent ในเทอร์มินัลอื่นตามที่เราทําก่อนหน้านี้ผ่านคําสั่ง adk run (จากโฟลเดอร์ my-agents) ที่แสดงด้านล่าง หรือจะใช้คําสั่ง adk web ก็ได้หากต้องการ

$ adk run hotel-agent-app/

Log setup complete: /tmp/agents_log/agent.20250423_170001.log
To access latest log: tail -F /tmp/agents_log/agent.latest.log
Running agent hotel_agent, type exit to exit.

user: what can you do for me?
[hotel_agent]: I can help you find hotels in a specific city or search for hotels by name.

user: I would like to search for hotels
[hotel_agent]: Great, do you have a specific city or hotel name in mind?

user: Yes a specific city
[hotel_agent]: Great, which city are you interested in?

user: Basel
[hotel_agent]: OK. I found three hotels in Basel: Hilton Basel, Hyatt Regency Basel, and Holiday Inn Basel.

โปรดทราบว่าตอนนี้ตัวแทนกำลังใช้เครื่องมือ 2 รายการที่เรากำหนดค่าไว้ในกล่องเครื่องมือ MCP สำหรับฐานข้อมูล (search-hotels-by-name และ search-hotels-by-location) และแสดงตัวเลือกที่ถูกต้องให้เรา จากนั้นจึงดึงข้อมูลจากฐานข้อมูลอินสแตนซ์ PostgreSQL และจัดรูปแบบการตอบกลับได้อย่างราบรื่น

การดำเนินการนี้ถือเป็นการพัฒนาและการทดสอบในเครื่องของตัวแทนโรงแรมที่เราสร้างขึ้นโดยใช้ชุดเครื่องมือการพัฒนาตัวแทน (ADK) ซึ่งทำงานด้วยเครื่องมือที่เรากำหนดค่าไว้ในกล่องเครื่องมือ MCP สำหรับฐานข้อมูล

8 (ไม่บังคับ) การติดตั้งใช้งาน MCP Toolbox สําหรับฐานข้อมูลและ Agent ไปยัง Cloud Run

ในส่วนก่อนหน้านี้ เราใช้เทอร์มินัล Cloud Shell เพื่อเปิดเซิร์ฟเวอร์ MCP Toolbox และทดสอบเครื่องมือกับ Agent ซึ่งทำงานภายในเครื่องในสภาพแวดล้อม Cloud Shell

คุณมีตัวเลือกในการติดตั้งใช้งานทั้งเซิร์ฟเวอร์ MCP Toolbox และตัวแทนในบริการ Google Cloud ที่สามารถโฮสต์แอปพลิเคชันเหล่านี้ให้เราได้

การโฮสต์เซิร์ฟเวอร์ MCP Toolbox ใน Cloud Run

ก่อนอื่น เรามาเริ่มด้วยเซิร์ฟเวอร์ MCP Toolbox และโฮสต์ไว้ใน Cloud Run ซึ่งจะให้ปลายทางสาธารณะที่เราผสานรวมกับแอปพลิเคชันอื่นๆ และ/หรือแอปพลิเคชันตัวแทนได้ด้วย ดูวิธีการโฮสต์ข้อมูลนี้ใน Cloud Run ได้ที่นี่ เรามาเริ่มดูขั้นตอนสำคัญกัน

เปิดเทอร์มินัล Cloud Shell ใหม่หรือใช้เทอร์มินัล Cloud Shell ที่มีอยู่ ไปที่โฟลเดอร์ mcp-toolbox ซึ่งมีไฟล์ toolbox ฐานสองและ tools.yaml

เรียกใช้คําสั่งต่อไปนี้ (คําอธิบายสําหรับคําสั่งแต่ละรายการมีให้)

ตั้งค่าตัวแปร PROJECT_ID ให้ชี้ไปยังรหัสโปรเจ็กต์ Google Cloud

export PROJECT_ID="YOUR_GOOGLE_CLOUD_PROJECT_ID" 

ถัดไป ให้ตรวจสอบว่าเปิดใช้บริการ Google Cloud ต่อไปนี้ในโปรเจ็กต์แล้ว

gcloud services enable run.googleapis.com \
                       cloudbuild.googleapis.com \
                       artifactregistry.googleapis.com \
                       iam.googleapis.com \
                       secretmanager.googleapis.com

มาสร้างบัญชีบริการแยกต่างหากที่จะทำหน้าที่เป็นข้อมูลประจำตัวสําหรับบริการ Toolbox ที่เราจะนำไปใช้กับ Google Cloud Run นอกจากนี้ เรายังตรวจสอบว่าบัญชีบริการนี้มีบทบาทที่ถูกต้องด้วย เช่น ความสามารถในการเข้าถึง Secret Manager และพูดคุยกับ Cloud SQL

gcloud iam service-accounts create toolbox-identity

gcloud projects add-iam-policy-binding $PROJECT_ID \
   --member serviceAccount:toolbox-identity@$PROJECT_ID.iam.gserviceaccount.com \
   --role roles/secretmanager.secretAccessor

gcloud projects add-iam-policy-binding $PROJECT_ID \
   --member serviceAccount:toolbox-identity@$PROJECT_ID.iam.gserviceaccount.com \
   --role roles/cloudsql.client

เราจะอัปโหลดไฟล์ tools.yaml เป็นข้อมูลลับ และเนื่องจากเราต้องติดตั้งกล่องเครื่องมือใน Cloud Run เราจึงจะใช้อิมเมจคอนเทนเนอร์ล่าสุดสำหรับกล่องเครื่องมือและตั้งค่าในตัวแปร IMAGE

gcloud secrets create tools --data-file=tools.yaml

export IMAGE=us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest

ขั้นตอนสุดท้ายในคําสั่งการทําให้ใช้งานได้ที่คุ้นเคยกับ Cloud Run

gcloud run deploy toolbox \
--image $IMAGE \
--service-account toolbox-identity \
--region us-central1 \
--set-secrets "/app/tools.yaml=tools:latest" \
--args="--tools_file=/app/tools.yaml","--address=0.0.0.0","--port=8080" \
--allow-unauthenticated

ซึ่งจะเป็นการเริ่มกระบวนการทำให้เซิร์ฟเวอร์ Toolbox พร้อมใช้งานด้วย tools.yaml ที่กําหนดค่าไว้ไปยัง Cloud Run เมื่อติดตั้งใช้งานสําเร็จ คุณควรเห็นข้อความคล้ายกับข้อความต่อไปนี้

Deploying container to Cloud Run service [toolbox] in project [YOUR_PROJECT_ID] region [us-central1]
OK Deploying new service... Done.                                                                                                                                                                                     
  OK Creating Revision...                                                                                                                                                                                             
  OK Routing traffic...                                                                                                                                                                                               
  OK Setting IAM Policy...                                                                                                                                                                                            
Done.                                                                                                                                                                                                                 
Service [toolbox] revision [toolbox-00001-zsk] has been deployed and is serving 100 percent of traffic.
Service URL: https://toolbox-<SOME_ID>.us-central1.run.app

ตอนนี้คุณไปที่ Service URL ที่แสดงด้านบนในเบราว์เซอร์ได้แล้ว ซึ่งควรแสดงข้อความ "Hello World" ที่เราเห็นก่อนหน้านี้ นอกจากนี้ คุณยังไปที่ URL ต่อไปนี้เพื่อดูเครื่องมือที่มีให้ใช้งานได้ด้วย

SERVICE URL/api/toolset

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

หมายเหตุ: หากยังต้องการเรียกใช้ตัวแทนโรงแรมในเครื่องและเชื่อมต่อกับบริการ Cloud Run ที่เพิ่งทำให้ใช้งานได้ คุณต้องทำการเปลี่ยนแปลงเพียงครั้งเดียวในไฟล์ my-agents/hotel-agent-app/agent.py

แทนที่จะใช้ข้อความต่อไปนี้

toolbox = ToolboxTool("http://127.0.0.1:5000")

เปลี่ยนเป็น URL ของบริการ Cloud Run ตามที่ระบุไว้ด้านล่าง

toolbox = ToolboxTool("CLOUD_RUN_SERVICE_URL")

ทดสอบแอปพลิเคชันตัวแทนโดยใช้ adk run หรือ adk web ตามที่เราได้ดูก่อนหน้านี้

การทําให้แอปตัวแทนโรงแรมใช้งานได้ใน Cloud Run

ขั้นตอนแรกคือตรวจสอบว่าคุณได้ทําการเปลี่ยนแปลงใน my-agents/hotel-agent-app/agent.py ตามวิธีการด้านบนเพื่อชี้ไปยัง URL ของบริการ Toolbox ที่ทํางานบน Cloud Run ไม่ใช่โฮสต์ในเครื่อง

ในเทอร์มินัล Cloud Shell ใหม่หรือเซสชันเทอร์มินัลที่มีอยู่ ให้ตรวจสอบว่าคุณอยู่ในสภาพแวดล้อมเสมือนของ Python ที่ถูกต้องซึ่งเราได้ตั้งค่าไว้ก่อนหน้านี้

ก่อนอื่น ให้สร้างไฟล์ requirements.txt ในโฟลเดอร์ my-agents/hotel-agent-app ดังที่แสดงด้านล่าง

google-adk
toolbox-core

ไปที่โฟลเดอร์ my-agents และมาตั้งค่าตัวแปรสภาพแวดล้อมต่อไปนี้กันก่อน

export GOOGLE_CLOUD_PROJECT=YOUR_GOOGLE_CLOUD_PROJECT_ID
export GOOGLE_CLOUD_LOCATION=us-central1
export AGENT_PATH="hotel-agent-app/"
export SERVICE_NAME="hotels-service"
export APP_NAME="hotels-app"
export GOOGLE_GENAI_USE_VERTEXAI=True

สุดท้ายนี้ ให้ทำให้แอปพลิเคชัน Agent ใช้งานได้ใน Cloud Run ผ่านคําสั่ง adk deploy cloud_run ตามที่ระบุไว้ด้านล่าง หากระบบขอให้คุณอนุญาตการเรียกใช้ที่ไม่ผ่านการตรวจสอบสิทธิ์ในบริการ โปรดระบุ "y" เป็นค่าในตอนนี้

adk deploy cloud_run \
--project=$GOOGLE_CLOUD_PROJECT \
--region=$GOOGLE_CLOUD_LOCATION \
--service_name=$SERVICE_NAME  \
--app_name=$APP_NAME \
--with_ui \
$AGENT_PATH

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

คุณควรเห็นข้อความที่คล้ายกับข้อความด้านล่าง

Start generating Cloud Run source files in /tmp/cloud_run_deploy_src/20250424_045623
Copying agent source code...
Copying agent source code complete.
Creating Dockerfile...
Creating Dockerfile complete: /tmp/cloud_run_deploy_src/20250424_045623/Dockerfile
Deploying to Cloud Run...
Building using Dockerfile and deploying container to Cloud Run service [hotels-service] in project [YOUR_GOOGLE_CLOUD_PROJECT] region [us-central1]
|  Building and deploying... Uploading sources.                                                                                                                                                                       
  |  Uploading sources...                                                                                                                                                                                             
OK Building and deploying... Done.                                                                                                                                                                                    
  OK Uploading sources...                                                                                                                                                                                             
  OK Building Container... Logs are available at [https://console.cloud.google.com/cloud-build/builds;region=us-central1/b02f5a74-6da6-4367-aaba-0c8aa098edf5?project=415458962931].                                  
  OK Creating Revision...                                                                                                                                                                                             
  OK Routing traffic...                                                                                                                                                                                               
Done.                                                                                                                                                                                                                 
Service [hotels-service] revision [hotels-service-00002-cpm] has been deployed and is serving 100 percent of traffic.
Service URL: https://hotels-service-<SOME_ID>.us-central1.run.app
Cleaning up the temp folder: /tmp/cloud_run_deploy_src/20250424_045623

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

9 ล้างข้อมูล

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

ตรวจสอบว่าได้ตั้งค่าตัวแปรสภาพแวดล้อมต่อไปนี้อย่างถูกต้องตามโปรเจ็กต์และภูมิภาค

export PROJECT_ID="YOUR_PROJECT_ID"
export REGION="YOUR_REGION"

คำสั่ง 2 รายการต่อไปนี้จะลบบริการ Cloud Run ที่เราได้ติดตั้งใช้งาน

gcloud run services delete toolbox --platform=managed --region=${REGION} --project=${PROJECT_ID} --quiet

gcloud run services delete hotels-service --platform=managed --region=${REGION} --project=${PROJECT_ID} --quiet

คำสั่งต่อไปนี้จะลบอินสแตนซ์ Cloud SQL

gcloud sql instances delete hoteldb-instance

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

ยินดีด้วย คุณสร้างตัวแทนโดยใช้ Agent Development Kit (ADK) ที่ใช้ MCP Toolbox สําหรับฐานข้อมูลเรียบร้อยแล้ว

เอกสารอ้างอิง

• ชุดเครื่องมือสำหรับนักพัฒนาแอป
• กล่องเครื่องมือ MCP สําหรับฐานข้อมูล
• การเชื่อมต่อกับ MCP Toolbox จาก IDE
• Cloud SQL สำหรับ PostgreSQL