เครื่องมือสร้างเอเจนต์: จากศูนย์สู่ผู้ช่วยด้วย ADK

1. บทนำ

ใน Lab นี้ คุณจะได้สร้าง Agent ด้วย Agent Development Kit (ADK) คุณจะได้เรียนรู้วิธีสร้างเอเจนต์ผู้ช่วยในการแก้ไขข้อบกพร่องของซอฟต์แวร์โดยใช้ ADK และเครื่องมือประเภทต่างๆ คุณจะเริ่มต้นด้วยเอเจนต์พื้นฐานและค่อยๆ เพิ่มเครื่องมือเพื่อเพิ่มความสามารถ ซึ่งรวมถึงเครื่องมือฟังก์ชัน เครื่องมือในตัว เครื่องมือของบุคคลที่สาม และเครื่องมือ Model Context Protocol (MCP)

เครื่องมือสร้างเอเจนต์

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

  • วิธีตั้งค่าโปรเจ็กต์ Python สำหรับการพัฒนา ADK
  • วิธีสร้างตัวแทน ADK พื้นฐาน
  • วิธีติดตั้งใช้งานและใช้เครื่องมือฟังก์ชัน
  • วิธีผสานรวมเครื่องมือในตัว เช่น Google Search
  • วิธีใช้ประโยชน์จากเครื่องมือของบุคคลที่สามจากเฟรมเวิร์ก เช่น LangChain ภายใน ADK
  • วิธีใช้เครื่องมือ MCP เพื่อโต้ตอบกับฐานข้อมูล (Cloud SQL) และ API

2. ภาพรวม

สมมติว่าคุณเป็นผู้จัดการโปรเจ็กต์ที่ QuantumRoast ซึ่งเป็นบริษัทผู้ผลิตเครื่องชงกาแฟระดับโลก

Quantum Roast

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

ในวันปกติ คุณจะมีแท็บเบราว์เซอร์ที่เปิดอยู่ประมาณ 50 แท็บ ได้แก่ ระบบตั๋วสนับสนุนภายใน อีเมล แชท GitHub, Google Search, StackOverflow และอื่นๆ คุณชอบงานและเพื่อนร่วมงาน แต่บางวันก็รู้สึกเหนื่อยล้า

ผู้จัดการโปรเจ็กต์ที่ทำงานหนักเกินไป

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

AI Agent

ชุดพัฒนาเอเจนต์ (ADK)

Agent Development Kit (ADK) เป็นเฟรมเวิร์กที่ยืดหยุ่นและเป็นโมดูลสำหรับการพัฒนาและติดตั้งใช้งานเอเจนต์ AI แม้ว่า ADK จะได้รับการเพิ่มประสิทธิภาพสําหรับ Gemini และระบบนิเวศของ Google แต่ก็ไม่ได้ขึ้นอยู่กับโมเดลหรือการติดตั้งใช้งานใดๆ และสร้างขึ้นเพื่อให้ใช้งานร่วมกับเฟรมเวิร์กอื่นๆ ได้ ADK ออกแบบมาเพื่อให้การพัฒนาเอเจนต์มีความคล้ายกับการพัฒนาซอฟต์แวร์มากขึ้น เพื่อช่วยให้นักพัฒนาแอปสร้าง ปรับใช้ และจัดระเบียบสถาปัตยกรรมเอเจนต์ได้ง่ายขึ้น ซึ่งครอบคลุมตั้งแต่การทำงานง่ายๆ ไปจนถึงเวิร์กโฟลว์ที่ซับซ้อน

ADK เป็นเฟรมเวิร์กที่เราจะใช้สร้างผู้ช่วยตรวจหาข้อบกพร่องของซอฟต์แวร์ QuantumRoast

แผนภาพ Agent

เครื่องมือ 101

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

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

แต่เอเจนต์จะรู้ได้อย่างไรว่าเมื่อใดควรเรียกใช้เครื่องมือหนึ่งๆ และจะเรียกใช้อย่างไร โมเดลของเอเจนต์มีบทบาทสำคัญ 2-3 อย่างในที่นี้

วิธีการทำงานของเครื่องมือ

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

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

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

หากต้องการดูการทำงานทั้งหมดนี้ ก็ถึงเวลาสร้างเอเจนต์ผู้ช่วยแก้ไขข้อบกพร่อง QuantumRoast โดยใช้ ADK Python

ผู้ช่วยรายงานข้อบกพร่องของ QuantumRoast

3. ก่อนเริ่มต้น

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

  1. หากยังไม่มีบัญชี Google คุณต้องสร้างบัญชี Google
    • ใช้บัญชีส่วนตัวแทนบัญชีงานหรือบัญชีโรงเรียน บัญชีงานและบัญชีโรงเรียนอาจมีข้อจำกัดที่ทำให้คุณเปิดใช้ API ที่จำเป็นสำหรับห้องทดลองนี้ไม่ได้
  2. ลงชื่อเข้าใช้ Google Cloud Console
  3. เปิดใช้การเรียกเก็บเงินใน Cloud Console
    • การทำแล็บนี้ควรมีค่าใช้จ่ายน้อยกว่า $1 USD ในทรัพยากรระบบคลาวด์
    • คุณสามารถทำตามขั้นตอนที่ส่วนท้ายของแล็บนี้เพื่อลบทรัพยากรเพื่อหลีกเลี่ยงการเรียกเก็บเงินเพิ่มเติม
    • ผู้ใช้ใหม่มีสิทธิ์ใช้ช่วงทดลองใช้ฟรีมูลค่า$300 USD
  4. สร้างโปรเจ็กต์ใหม่หรือเลือกใช้โปรเจ็กต์ที่มีอยู่ซ้ำ

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

  1. ไปที่ Cloud Shell Editor
  2. หากเทอร์มินัลไม่ปรากฏที่ด้านล่างของหน้าจอ ให้เปิดโดยทำดังนี้
    • คลิกเมนู 3 ขีด ไอคอนเมนู 3 ขีด
    • คลิก Terminal
    • คลิกเทอร์มินัลใหม่เปิดเทอร์มินัลใหม่ใน Cloud Shell Editor
  3. ในเทอร์มินัล ให้ตั้งค่าโปรเจ็กต์ด้วยคำสั่งนี้ (แทนที่ YOUR_PROJECT_ID)
    • รูปแบบ:
      gcloud config set project YOUR_PROJECT_ID
    • ตัวอย่าง
      gcloud config set project lab-project-id-example
    • หากจำรหัสโปรเจ็กต์ไม่ได้ ให้ทำดังนี้
      • คุณแสดงรหัสโปรเจ็กต์ทั้งหมดได้โดยใช้คำสั่งต่อไปนี้
        gcloud projects list | awk '/PROJECT_ID/{print $2}'
      ตั้งค่ารหัสโปรเจ็กต์ในเทอร์มินัล Cloud Shell Editor
  4. หากได้รับแจ้งให้ให้สิทธิ์ ให้คลิกให้สิทธิ์เพื่อดำเนินการต่อ คลิกเพื่อให้สิทธิ์ Cloud Shell
  5. คุณควรเห็นข้อความต่อไปนี้
    Updated property [core/project].
    หากเห็น WARNING และระบบขอให้คุณ Do you want to continue (Y/N)? แสดงว่าคุณอาจป้อนรหัสโปรเจ็กต์ไม่ถูกต้อง กด N กด Enter แล้วลองเรียกใช้คำสั่ง gcloud config set project อีกครั้ง
  6. ในเทอร์มินัล ให้ตั้งค่าPROJECT_IDตัวแปรสภาพแวดล้อมที่จะใช้ในขั้นตอนต่อๆ ไป
    export PROJECT_ID=$(gcloud config get project)

เปิดใช้ API

ในเทอร์มินัล ให้เรียกใช้คำสั่งต่อไปนี้เพื่อเปิดใช้ Google Cloud APIs ที่จำเป็น

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

สร้างอินสแตนซ์ Cloud SQL สำหรับ PostgreSQL

QuantumRoast มีฐานข้อมูลคำขอแจ้งปัญหาที่เก็บคำขอแจ้งปัญหาภายในทั้งหมด มาตั้งค่ากันเลยโดยสร้างอินสแตนซ์ Cloud SQL สำหรับ PostgreSQL

gcloud sql instances create software-assistant \
   --database-version=POSTGRES_16 \
   --tier=db-custom-1-3840 \
   --region=us-central1 \
   --edition=ENTERPRISE \
   --enable-google-ml-integration \
   --database-flags cloudsql.enable_google_ml_integration=on \
   --root-password=admin

รอให้ระบบสร้างอินสแตนซ์ (อาจใช้เวลา 2-3 นาที)

เมื่อสร้างแล้ว คุณจะดูอินสแตนซ์ใน Cloud Console ได้ที่นี่

สร้างฐานข้อมูล Cloud SQL

สร้างฐานข้อมูล SQL (tickets-db) และให้สิทธิ์เข้าถึง Vertex AI แก่บัญชีบริการ Cloud SQL (เพื่อให้เราสร้างการฝังเพื่อทำการค้นหาความคล้ายคลึงได้)

gcloud sql databases create tickets-db --instance=software-assistant

SERVICE_ACCOUNT_EMAIL=$(gcloud sql instances describe software-assistant --format="value(serviceAccountEmailAddress)")
echo $SERVICE_ACCOUNT_EMAIL

gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$SERVICE_ACCOUNT_EMAIL" --role="roles/aiplatform.user"

ตั้งค่าตาราง tickets

จาก Cloud Console (Cloud SQL) ให้เปิด Cloud SQL Studio สำหรับอินสแตนซ์ software-assistant

เข้าสู่ระบบฐานข้อมูล tickets-db โดยใช้ผู้ใช้ postgres และ admin เป็นรหัสผ่าน

Cloud SQL Studio

เปิดแท็บ Editor ใหม่

ผู้แก้ไข Cloud SQL Studio

จากนั้นวางโค้ด SQL ต่อไปนี้เพื่อตั้งค่าตารางและสร้างการฝังเวกเตอร์ กดปุ่ม Run เพื่อเรียกใช้คำสั่ง

CREATE EXTENSION IF NOT EXISTS google_ml_integration CASCADE;
CREATE EXTENSION IF NOT EXISTS vector CASCADE;
GRANT EXECUTE ON FUNCTION embedding TO postgres;

CREATE TABLE tickets (
    ticket_id SERIAL PRIMARY KEY,             -- PostgreSQL's auto-incrementing integer type (SERIAL is equivalent to INT AUTO_INCREMENT)
    title VARCHAR(255) NOT NULL,              -- A concise summary or title of the bug/issue.
    description TEXT,                         -- A detailed description of the bug.
    assignee VARCHAR(100),                    -- The name or email of the person/team assigned to the ticket.
    priority VARCHAR(50),                     -- The priority level (e.g., 'P0 - Critical', 'P1 - High').
    status VARCHAR(50) DEFAULT 'Open',        -- The current status of the ticket (e.g., 'Open', 'In Progress', 'Resolved'). Default is 'Open'.
    creation_time TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP, -- Timestamp when the ticket was first created. 'WITH TIME ZONE' is recommended for clarity and compatibility.
    updated_time TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP  -- Timestamp when the ticket was last updated. Will be managed by a trigger.
);

ระบบได้สร้างticketsตารางแล้ว คลิก Clear เพื่อล้างการค้นหาเก่า

ตอนนี้ให้แทรกข้อมูลตัวอย่างแล้วกดปุ่ม Run อีกครั้ง

INSERT INTO tickets (title, description, assignee, priority, status) VALUES
('Login Page Freezes After Multiple Failed Attempts', 'Users are reporting that after 3 failed login attempts, the login page becomes unresponsive and requires a refresh. No specific error message is displayed.', 'samuel.green@example.com', 'P0 - Critical', 'Open');

INSERT INTO tickets (title, description, assignee, priority, status) VALUES
('Dashboard Sales Widget Intermittent Data Loading Failure', 'The "Sales Overview" widget on the main dashboard intermittently shows a loading spinner but no data. Primarily affects Chrome browser users.', 'maria.rodriguez@example.com', 'P1 - High', 'In Progress');

INSERT INTO tickets (title, description, assignee, priority, status) VALUES
('Broken Link in Footer - Privacy Policy', 'The "Privacy Policy" hyperlink located in the website footer leads to a 404 "Page Not Found" error.', 'maria.rodriguez@example.com', 'P3 - Low', 'Resolved');

INSERT INTO tickets (title, description, assignee, priority, status) VALUES
('UI Misalignment on Mobile Landscape View (iOS)', 'On specific iOS devices (e.g., iPhone 14 models), the top navigation bar shifts downwards when the device is viewed in landscape orientation, obscuring content.', 'maria.rodriguez@example.com', 'P2 - Medium', 'In Progress');

INSERT INTO tickets (title, description, assignee, priority, status) VALUES
('Critical XZ Utils Backdoor Detected in Core Dependency (CVE-2024-3094)', 'Urgent: A sophisticated supply chain compromise (CVE-2024-3094) has been identified in XZ Utils versions 5.6.0 and 5.6.1. This malicious code potentially allows unauthorized remote SSH access by modifying liblzma. Immediate investigation and action required for affected Linux/Unix systems and services relying on XZ Utils.', 'frank.white@example.com', 'P0 - Critical', 'Open');

INSERT INTO tickets (title, description, assignee, priority, status) VALUES
('Database Connection Timeouts During Peak Usage', 'The application is experiencing frequent database connection timeouts, particularly during peak hours (10 AM - 12 PM EDT), affecting all users and causing service interruptions.', 'frank.white@example.com', 'P1 - High', 'Open');

INSERT INTO tickets (title, description, assignee, priority, status) VALUES
('Export to PDF Truncates Long Text Fields in Reports', 'When generating PDF exports of reports containing extensive text fields, the text is abruptly cut off at the end of the page instead of wrapping or continuing to the next page.', 'samuel.green@example.com', 'P1 - High', 'Open');

INSERT INTO tickets (title, description, assignee, priority, status) VALUES
('Search Filter "Date Range" Not Applying Correctly', 'The "Date Range" filter on the search results page does not filter records accurately; results outside the specified date range are still displayed.', 'samuel.green@example.com', 'P2 - Medium', 'Resolved');

INSERT INTO tickets (title, description, assignee, priority, status) VALUES
('Typo in Error Message: "Unathorized Access"', 'The error message displayed when a user attempts an unauthorized action reads "Unathorized Access" instead of "Unauthorized Access."', 'maria.rodriguez@example.com', 'P3 - Low', 'Resolved');

INSERT INTO tickets (title, description, assignee, priority, status) VALUES
('Intermittent File Upload Failures for Large Files', 'Users are intermittently reporting that file uploads fail without a clear error message or explanation, especially for files exceeding 10MB in size.', 'frank.white@example.com', 'P1 - High', 'Open');

ที่ QuantumRoast เราอาจต้องการทราบว่ามีการอัปเดตข้อบกพร่อง/คำขอครั้งล่าสุดเมื่อใด

โดยเราสามารถสร้างทริกเกอร์เพื่ออัปเดตฟิลด์ updated_time ทุกครั้งที่มีการอัปเดตระเบียน

คลิก Clear แล้ววาง SQL ต่อไปนี้เพื่อใช้ทริกเกอร์

กดปุ่ม Run เพื่อดำเนินการ

CREATE OR REPLACE FUNCTION update_updated_time_tickets()
RETURNS TRIGGER AS $$
BEGIN
    NEW.updated_time = NOW();  -- Set the updated_time to the current timestamp
    RETURN NEW;                -- Return the new row
END;
$$ language 'plpgsql';        

CREATE TRIGGER update_tickets_updated_time
BEFORE UPDATE ON tickets
FOR EACH ROW                  -- This means the trigger fires for each row affected by the UPDATE statement
EXECUTE PROCEDURE update_updated_time_tickets();

สร้างการฝังเวกเตอร์จากฟิลด์ description ซึ่งจะช่วยให้ตัวแทนของเราสามารถค้นหาความคล้ายคลึงในฐานข้อมูลของเราได้ เช่น "มีปัญหาที่ยังไม่ได้รับการแก้ไขเกี่ยวกับหน้าแรกของเว็บไซต์ไหม"

ALTER TABLE tickets ADD COLUMN embedding vector(768) GENERATED ALWAYS AS (embedding('text-embedding-005',description)) STORED;

ตอนนี้คุณสามารถค้นหาฐานข้อมูลเพื่อยืนยันว่าพร้อมใช้งานแล้ว

SELECT * FROM tickets;

คุณควรเห็นแถว 10 แถวที่แสดงผลซึ่งมีลักษณะคล้ายกับต่อไปนี้

ยืนยันฐานข้อมูล Cloud SQL

ตอนนี้คุณก็พร้อมที่จะไปที่ส่วนที่สนุกที่สุดแล้ว นั่นก็คือโค้ด

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

ก่อนที่จะเจาะลึกการสร้างเอเจนต์ เราต้องตรวจสอบว่าได้ตั้งค่าโปรเจ็กต์ Python อย่างถูกต้องแล้ว เราจะทำทุกอย่างใน Cloud Shell

ก่อนอื่น ให้สร้างquantum-roastโฟลเดอร์cdและเข้าไปในโฟลเดอร์นั้น

mkdir quantum-roast && cd quantum-roast

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

เราจะใช้ uv (ตัวจัดการแพ็กเกจและโปรเจ็กต์ที่รวดเร็วมากของ Python) ซึ่งติดตั้งไว้ล่วงหน้าใน Cloud Shell เพื่อจัดการโปรเจ็กต์และการอ้างอิง Uv จะช่วยเราตั้งค่าไฟล์บางไฟล์ รวมถึงจัดการสภาพแวดล้อมเสมือนจริง การขึ้นต่อกัน ฯลฯ เพื่อให้เราไม่ต้องทำเอง

เริ่มต้นโปรเจ็กต์ใหม่ด้วย uv init โดยทำดังนี้

uv init --description "QuantumRoast Software Bug Assistant with ADK" --bare --python 3.10

หลังจากเรียกใช้คำสั่งแล้ว เราควรมีไฟล์ pyproject.toml สำหรับโปรเจ็กต์ หากต้องการยืนยัน ให้เรียกใช้ cat pyproject.toml ในเทอร์มินัล Cloud Shell

cat pyproject.toml

คุณควรเห็นเอาต์พุตต่อไปนี้

[project]
name = "quantum-roast"
version = "0.1.0"
description = "QuantumRoast Software Bug Assistant with ADK"
requires-python = ">=3.10"
dependencies = []

ถึงเวลาเพิ่ม google-adk (ADK) เป็นทรัพยากร Dependency ในโปรเจ็กต์โดยใช้ uv add

uv add google-adk==1.11.0

ซึ่งจะเป็นการเพิ่ม google-adk ลงในรายการ dependencies ในpyproject.toml

ADK คาดหวังโครงสร้างโปรเจ็กต์ที่แน่นอนเพื่อให้ได้ผลลัพธ์ที่ดีที่สุด

quantum-roast/
    software_bug_assistant/
        __init__.py
        agent.py
        .env

สร้างโฟลเดอร์ software_bug_assistant และไฟล์ภายในโฟลเดอร์ดังกล่าว

mkdir software_bug_assistant && touch software_bug_assistant/__init__.py \
software_bug_assistant/agent.py \
software_bug_assistant/tools.py \
software_bug_assistant/.env

ยืนยันการสร้างไฟล์โดยใช้ ls ดังนี้

ls -a software_bug_assistant/

คุณควรเห็นสิ่งต่อไปนี้

__init__.py	 .  ..	 .env	 agent.py    tools.py

ถึงเวลาป้อนข้อมูลในไฟล์ .env ด้วยตัวแปรสภาพแวดล้อมที่จำเป็นสำหรับ ADK เพื่อให้เรียกใช้โมเดล Gemini ได้อย่างถูกต้อง เราจะเข้าถึง Gemini ผ่าน Vertex API

echo "GOOGLE_GENAI_USE_VERTEXAI=TRUE" >> software_bug_assistant/.env \
&& echo "GOOGLE_CLOUD_PROJECT=$PROJECT_ID" >> software_bug_assistant/.env \
&& echo "GOOGLE_CLOUD_LOCATION=us-central1" >> software_bug_assistant/.env

หากต้องการยืนยันว่าระบบได้ป้อนข้อมูล .env อย่างถูกต้อง ให้เรียกใช้คำสั่งต่อไปนี้

cat software_bug_assistant/.env

คุณควรเห็นข้อมูลต่อไปนี้โดยที่ your-project-id คือรหัสโปรเจ็กต์

GOOGLE_GENAI_USE_VERTEXAI=TRUE
GOOGLE_CLOUD_PROJECT=your-project-id
GOOGLE_CLOUD_LOCATION=us-central1

ตอนนี้เราพร้อมที่จะเริ่มสร้างเอเจนต์ ADK แล้ว

5. Base ADK Agent

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

เปิด agent.py ใน Cloud Shell Editor โดยทำดังนี้

cloudshell edit software_bug_assistant/agent.py

วางโค้ดต่อไปนี้ลงใน agent.py แล้วบันทึกไฟล์ Ctrl + s

from google.adk.agents import Agent

# --- Agent Definition (model, instructions, tools) ---
root_agent = Agent(
    model="gemini-2.5-flash",
    name="software_assistant",
    instruction="""
    You are a skilled expert in triaging and debugging software issues for a
    coffee machine company, QuantumRoast.
    """,
    tools=[],
)

เรียกใช้เอเจนต์ที่สร้างขึ้นใหม่โดยเริ่ม UI สำหรับนักพัฒนาซอฟต์แวร์ของ ADK (adk web) การทำเช่นนี้ด้วย uv run จะสร้างสภาพแวดล้อมเสมือนที่มี ADK ติดตั้งไว้โดยอัตโนมัติ

uv run adk web --port 8080 --reload_agents

ในคอนโซล คุณควรเห็นการเริ่มต้นใช้งานเว็บเซิร์ฟเวอร์ ADK ที่สำเร็จ

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

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

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

เปิดตัวอย่างเว็บของ Cloud Shell เพื่อดู UI

ตัวอย่างเว็บของ Cloud Shell

คุณควรเห็นเว็บ UI ของ ADK

UI บนเว็บของ ADK

ลองแชทกับตัวแทน ADK เลย

ถามตัวแทน What day is it today?

ตัวอย่างเว็บ ADK

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

ถึงเวลาใช้งานเครื่องมือประเภทแรกของ ADK ซึ่งก็คือเครื่องมือฟังก์ชัน

6. เครื่องมือฟังก์ชัน

เครื่องมือ ADK ประเภทแรกและง่ายที่สุดคือเครื่องมือฟังก์ชัน ซึ่งก็คือฟังก์ชัน Python ที่เอเจนต์เรียกใช้นั่นเอง

เครื่องมือฟังก์ชัน

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

ที่ QuantumRoast เราต้องการกำหนดฟังก์ชันพื้นฐานเพื่อรับวันที่ของวันนี้ เพื่อที่จะจัดการคำค้นหาในภายหลังในแล็บนี้ เช่น "แสดงข้อบกพร่องจากสัปดาห์ที่แล้ว" หรือ "วันนี้วันที่เท่าไหร่" (เราทุกคนเคยเจอ)

ไฟล์ tools.py ในโฟลเดอร์ /software_bug_assistant คือที่ที่เราจะจัดระเบียบเครื่องมือทั้งหมดที่เราสร้างขึ้นตลอด Lab นี้

เปิดเทอร์มินัลใหม่โดยคลิกไอคอน +

เทอร์มินัลใหม่

ตอนนี้ในเทอร์มินัลใหม่ ให้ตั้งค่า PROJECT_ID แล้วเปิด tools.py ดังนี้

cd quantum-roast
export PROJECT_ID=$(gcloud config get project)
cloudshell edit software_bug_assistant/tools.py

ตอนนี้ให้กำหนดฟังก์ชัน get_current_date ซึ่งจะใช้เป็นเครื่องมือฟังก์ชัน

from datetime import datetime

# ----- Example of a Function tool -----
def get_current_date() -> dict:
    """
    Get the current date in the format YYYY-MM-DD
    """
    return {"current_date": datetime.now().strftime("%Y-%m-%d")}

ตอนนี้ได้กำหนดฟังก์ชันแล้ว ได้เวลาส่งต่อเป็นเครื่องมือให้ตัวแทนแล้ว

เปิด agent.py ใน Cloud Shell Editor โดยทำดังนี้

cloudshell edit software_bug_assistant/agent.py

เราต้องการนำเข้าฟังก์ชัน get_current_date จาก tools.py และส่งฟังก์ชันไปยังอาร์กิวเมนต์ tools ของเอเจนต์

agent.py ที่อัปเดตแล้วจะมีลักษณะดังนี้

from google.adk.agents import Agent

from .tools import get_current_date

# --- Agent Definition (model, instructions, tools) ---
root_agent = Agent(
    model="gemini-2.5-flash",
    name="software_assistant",
    instruction="""
    You are a skilled expert in triaging and debugging software issues for a
    coffee machine company, QuantumRoast.
    """,
    tools=[get_current_date],
)

ตอนนี้หากคุณกลับไปที่แท็บแสดงตัวอย่างเว็บที่เรียกใช้ ADK Web UI และถาม What day is it today? อีกครั้ง...

เครื่องมือฟังก์ชันเว็บ ADK

เอเจนต์สามารถบอกวันที่ได้สำเร็จโดยเรียกใช้get_current_dateเครื่องมือฟังก์ชัน 🎉

ถึงเวลาสำรวจเครื่องมือ ADK ประเภทถัดไปแล้ว

7. เครื่องมือในตัว

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

เครื่องมือในตัว

เปิดtools.pyเพื่อเพิ่มการรองรับเครื่องมือในตัวของ Google Search

cloudshell edit software_bug_assistant/tools.py

เพิ่มรายการต่อไปนี้ที่ด้านล่างของ tools.py

# ----- Built-in Tool Imports -----
from google.adk.agents import Agent
from google.adk.tools import google_search
from google.adk.tools.agent_tool import AgentTool

# ----- Example of a Built-in Tool -----
search_agent = Agent(
    model="gemini-2.5-flash",
    name="search_agent",
    description="A specialist in Google Search.",
    instruction="""
    You're a specialist in Google Search.
    """,
    tools=[google_search],
)

search_tool = AgentTool(search_agent)

ในที่นี้ เราจะห่อหุ้มเครื่องมือ Google Search นั้นไว้ในเอเจนต์ของตัวเองพร้อมคำสั่งของระบบของตัวเอง ซึ่งเป็นการใช้เอเจนต์เป็นเครื่องมืออย่างมีประสิทธิภาพ

ตอนนี้เราสามารถนำเข้าและส่ง search_tool ไปยังเอเจนต์รูทใน agent.py ได้แล้ว

cloudshell edit software_bug_assistant/agent.py

คุณสามารถแทนที่ agent.py ด้วยโค้ดต่อไปนี้เพื่อรวม search_tool

from google.adk.agents import Agent

from .tools import get_current_date, search_tool

# --- Agent Definition (model, instructions, tools) ---
root_agent = Agent(
    model="gemini-2.5-flash",
    name="software_assistant",
    instruction="""
    You are a skilled expert in triaging and debugging software issues for a
    coffee machine company, QuantumRoast.
    """,
    tools=[get_current_date, search_tool],
)

บันทึกไฟล์แล้วกลับไปที่แท็บที่เปิดอยู่ซึ่งมี ADK Web UI ทำงานอยู่

ที่ QuantumRoast เราต้องการตรวจสอบให้แน่ใจว่าเว็บไซต์และซอฟต์แวร์ของเราได้รับการปกป้องจาก Common Vulnerabilities and Exposures (CVE) ซึ่งเป็นช่องโหว่ด้านความปลอดภัยทางไซเบอร์ที่เปิดเผยต่อสาธารณะ เราสามารถใช้เครื่องมือ Google Search ใหม่ของเอเจนต์เพื่อค้นหา CVE ที่ค้นพบล่าสุดบนเว็บ

เรียกใช้การค้นหาต่อไปนี้ Do a web search for 5 of the most recent CVEs?

ตัวแทนของเราควรโทรหา search_agent เพื่อค้นหาเว็บ

ตัวอย่างเครื่องมือในตัวของ ADK Web

ตอนนี้เอเจนต์ของเราได้ปลดล็อกความสามารถในการค้นหาเว็บผ่านเครื่องมือในตัวของ ADK สำหรับ Google Search เรียบร้อยแล้ว 🎉

ไปที่เครื่องมือ ADK ประเภทถัดไป

8. เครื่องมือของบุคคลที่สาม

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

เครื่องมือของบุคคลที่สาม

หากต้องการเชื่อมต่อ Bug Agent กับข้อมูลคำถามและคำตอบที่มีประสิทธิภาพของ StackOverflow เราสามารถดึงข้อมูลจากคลังเครื่องมือที่ครอบคลุมของ LangChain โดยเฉพาะเครื่องมือ Wrapper API ของ StackExchange ADK รองรับเครื่องมือของบุคคลที่สาม เช่น LangChain ดังนั้นการเพิ่มเครื่องมือนี้ลงในเอเจนต์ ADK จึงต้องใช้โค้ดเพียงไม่กี่บรรทัด

ก่อนอื่นเราต้องเพิ่มการอ้างอิงใหม่สำหรับ LangChain และ StackOverflow (langchain-community และ stackapi) ลงในโปรเจ็กต์

uv add langchain-community==0.3.27 stackapi==0.3.1

เปิดไฟล์ tools.py เพื่อเพิ่มการรองรับเครื่องมือ LangChain StackExchange

cloudshell edit software_bug_assistant/tools.py

เพิ่มรายการต่อไปนี้ที่ด้านล่างของ tools.py

# ----- Example of a Third-Party Tool -----
from google.adk.tools.langchain_tool import LangchainTool
from langchain_community.tools import StackExchangeTool
from langchain_community.utilities import StackExchangeAPIWrapper

stack_exchange_tool = StackExchangeTool(api_wrapper=StackExchangeAPIWrapper())
langchain_tool = LangchainTool(stack_exchange_tool)

ตอนนี้เราสามารถนำเข้าและส่ง langchain_tool ไปยังเอเจนต์รูทใน agent.py ได้แล้ว

cloudshell edit software_bug_assistant/agent.py

คุณสามารถแทนที่ agent.py ด้วยโค้ดต่อไปนี้เพื่อรวม langchain_tool

from google.adk.agents import Agent

from .tools import get_current_date, langchain_tool, search_tool

# --- Agent Definition (model, instructions, tools) ---
root_agent = Agent(
    model="gemini-2.5-flash",
    name="software_assistant",
    instruction="""
    You are a skilled expert in triaging and debugging software issues for a
    coffee machine company, QuantumRoast.
    """,
    tools=[get_current_date, search_tool, langchain_tool],
)

บันทึกไฟล์แล้วกลับไปที่แท็บที่เปิดอยู่ซึ่งมี ADK Web UI

ลองถามตัวแทนเกี่ยวกับ CVE ก่อนหน้า "Are there similar issues on stack exchange?" หรือสิ่งใหม่ๆ เช่น "Our database queries with SQLAlchemy seem to be timing out, is there anything on StackExchange relevant to this?"

ตัวอย่างเครื่องมือของบุคคลที่สามสำหรับ ADK Web

ตอนนี้เอเจนต์ของเราใช้เครื่องมือ LangChain ใน ADK เพื่อค้นหา StackOverflow ได้แล้ว 🥳

ถึงเวลาสำหรับเครื่องมือ ADK ประเภทถัดไปแล้ว MCP Tools!

9. เครื่องมือ MCP (ฐานข้อมูล)

MCP ย่อมาจาก Model Context Protocol ซึ่งเป็นโปรโตคอลแบบเปิดที่ Anthropic เปิดตัวในปี 2024 MCP มีเลเยอร์การแยกส่วนระหว่างเอเจนต์ AI กับ "แบ็กเอนด์" ของเครื่องมือ (API, ฐานข้อมูล)

วิธีการทำงานของ MCP

MCP มีข้อกำหนดเฉพาะบางอย่าง MCP มีการเชื่อมต่อแบบ 2 ทางที่มีสถานะระหว่างไคลเอ็นต์และเซิร์ฟเวอร์ ซึ่งต่างจาก HTTP มาตรฐาน โดยจะมีวิธีของตัวเองในการกำหนดเครื่องมือและข้อความแสดงข้อผิดพลาดที่เฉพาะเจาะจงของเครื่องมือ จากนั้นผู้ให้บริการเครื่องมือจะสร้างเซิร์ฟเวอร์ MCP บน API ของตนเองได้ โดยจะแสดงเครื่องมือที่สร้างไว้ล่วงหน้าอย่างน้อย 1 รายการสำหรับนักพัฒนาแอปและผู้ใช้ จากนั้นเฟรมเวิร์กของ Agent จะเริ่มต้น MCP Client ภายในแอปพลิเคชัน Agent เพื่อค้นหาและเรียกใช้เครื่องมือเหล่านั้น

ที่ QuantumRoast เรามีฐานข้อมูล Cloud SQL สำหรับ PostgreSQL สำหรับข้อบกพร่องของซอฟต์แวร์ภายใน เราต้องการสร้างเครื่องมือ ADK เพื่อให้ตัวแทนของเราสามารถทำการค้นหาบางอย่างในฐานข้อมูลของเราได้

ฐานข้อมูลเครื่องมือ MCP

วิธีที่ง่ายที่สุดในการทำเช่นนี้คือการใช้ MCP Toolbox for Databases ซึ่งเป็นเซิร์ฟเวอร์ MCP แบบโอเพนซอร์สสำหรับฐานข้อมูล Toolbox รองรับฐานข้อมูลกว่า 15 รายการ ซึ่งรวมถึง Cloud SQL

กล่องเครื่องมือมีฟีเจอร์ต่อไปนี้

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

ADK รองรับกล่องเครื่องมือ MCP สำหรับเครื่องมือฐานข้อมูล ซึ่งช่วยให้ผสานรวมได้อย่างรวดเร็ว

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

ติดตั้งใช้งาน MCP Toolbox สำหรับเซิร์ฟเวอร์ฐานข้อมูลใน Cloud Run

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

กล่องเครื่องมือต้องใช้ไฟล์ YAML สำหรับการกำหนดค่า ซึ่งคุณจะระบุแหล่งที่มาของฐานข้อมูลและเครื่องมือที่จะกำหนดค่า

สร้างไฟล์ tools.yaml สำหรับการติดตั้งใช้งาน

cloudshell edit tools.yaml

วางเนื้อหาต่อไปนี้ลงใน tools.yaml

sources:
  postgresql:
    kind: cloud-sql-postgres
    project: ${PROJECT_ID}
    region: us-central1
    instance: software-assistant
    database: tickets-db
    user: postgres
    password: admin

tools:
  search-tickets:
    kind: postgres-sql
    source: postgresql
    description: Search for similar tickets based on their descriptions.
    parameters:
      - name: query
        type: string
        description: The query to perform vector search with.
    statement: |
      SELECT ticket_id, title, description, assignee, priority, status, (embedding <=> embedding('text-embedding-005', $1)::vector) as distance
      FROM tickets
      ORDER BY distance ASC
      LIMIT 3;
  get-ticket-by-id:
    kind: postgres-sql
    source: postgresql
    description: Retrieve a ticket's details using its unique ID.
    parameters:
      - name: ticket_id
        type: string
        description: The unique ID of the ticket.
    statement: SELECT * FROM tickets WHERE ticket_id = $1;
  get-tickets-by-assignee:
    kind: postgres-sql
    source: postgresql
    description: Search for tickets based on assignee (email).
    parameters:
      - name: assignee
        type: string
        description: The email of the assignee.
    statement: SELECT * FROM tickets WHERE assignee ILIKE '%' || $1 || '%';
  update-ticket-priority:
    kind: postgres-sql
    source: postgresql
    description: Update the priority of a ticket based on its ID.
    parameters:
      - name: priority
        type: string
        description: The priority of the ticket. Can be one of 'P0 - Critical', 'P1 - High', 'P2 - Medium', or 'P3 - Low'.
      - name: ticket_id
        type: string
        description: The ID of the ticket.
    statement: UPDATE tickets SET priority = $1 WHERE ticket_id = $2;
  update-ticket-status:
    kind: postgres-sql
    source: postgresql
    description: Update the status of a ticket based on its ID.
    parameters:
      - name: status
        type: string
        description: The new status of the ticket (e.g., 'Open', 'In Progress', 'Closed', 'Resolved').
      - name: ticket_id
        type: string
        description: The ID of the ticket.
    statement: UPDATE tickets SET status = $1 WHERE ticket_id = $2;
  get-tickets-by-status:
    kind: postgres-sql
    source: postgresql
    description: Search for tickets based on their current status.
    parameters:
      - name: status
        type: string
        description: The status of the tickets to retrieve (e.g., 'Open', 'In Progress', 'Closed', 'Resolved').
    statement: SELECT * FROM tickets WHERE status ILIKE '%' || $1 || '%';
  get-tickets-by-priority:
    kind: postgres-sql
    source: postgresql
    description: Search for tickets based on their priority.
    parameters:
      - name: priority
        type: string
        description: The priority of the tickets to retrieve (e.g., 'P0 - Critical', 'P1 - High', 'P2 - Medium', 'P3 - Low').
    statement: SELECT * FROM tickets WHERE priority ILIKE '%' || $1 || '%';
  create-new-ticket:
    kind: postgres-sql
    source: postgresql
    description: Create a new software ticket.
    parameters:
      - name: title
        type: string
        description: The title of the new ticket.
      - name: description
        type: string
        description: A detailed description of the bug or issue.
      - name: assignee
        type: string
        description: (Optional) The email of the person to whom the ticket should be assigned.
      - name: priority
        type: string
        description: (Optional) The priority of the ticket. Can be 'P0 - Critical', 'P1 - High', 'P2 - Medium', or 'P3 - Low'. Default is 'P3 - Low'.
      - name: status
        type: string
        description: (Optional) The initial status of the ticket. Default is 'Open'.
    statement: INSERT INTO tickets (title, description, assignee, priority, status) VALUES ($1, $2, $3, COALESCE($4, 'P3 - Low'), COALESCE($5, 'Open')) RETURNING ticket_id;
  get-tickets-by-date-range:
    kind: postgres-sql
    source: postgresql
    description: Retrieve tickets created or updated within a specific date range.
    parameters:
      - name: start_date
        type: string
        description: The start date (inclusive) for the range (e.g., 'YYYY-MM-DD').
      - name: end_date
        type: string
        description: The end date (inclusive) for the range (e.g., 'YYYY-MM-DD').
      - name: date_field
        type: string
        description: The date field to filter by ('creation_time' or 'updated_time').
    statement: SELECT * FROM tickets WHERE CASE WHEN $3 = 'creation_time' THEN creation_time ELSE updated_time END BETWEEN $1::timestamp AND $2::timestamp;

toolsets:
  tickets_toolset:
    - search-tickets
    - get-ticket-by-id
    - get-tickets-by-assignee
    - get-tickets-by-status
    - get-tickets-by-priority
    - get-tickets-by-date-range
    - update-ticket-priority
    - update-ticket-status
    - create-new-ticket

ไฟล์ YAML จะกำหนดเครื่องมือ 9 รายการที่เกี่ยวข้องกับฐานข้อมูลตั๋ว QuantumRoast

ถึงเวลาที่ต้องกำหนดค่าบัญชีบริการสำหรับบริการ Toolbox Cloud Run มอบสิทธิ์ให้เข้าถึง Cloud SQL และ Secret Manager รวมถึงสร้างข้อมูลลับของ Secret Manager สำหรับไฟล์ tools.yaml

Secret Manager คือที่ที่เราจะจัดเก็บไฟล์ tools.yaml เนื่องจากมีข้อมูลเข้าสู่ระบบ 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

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

เวลาในการติดตั้งใช้งานกล่องเครื่องมือ MCP สำหรับฐานข้อมูลไปยัง Cloud Run เราจะใช้เวอร์ชันที่เผยแพร่ล่าสุดของอิมเมจคอนเทนเนอร์ MCP Toolbox

gcloud run deploy toolbox \
    --image us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest \
    --service-account toolbox-identity \
    --region us-central1 \
    --set-secrets "/app/tools.yaml=tools:latest" \
    --set-env-vars="PROJECT_ID=$PROJECT_ID" \
    --args="--tools-file=/app/tools.yaml","--address=0.0.0.0","--port=8080" \
    --labels=dev-tutorial=codelab-toolbox \
    --no-invoker-iam-check

รอให้การติดตั้งใช้งานเสร็จสิ้น...

ยืนยันว่า Toolbox ทำงานอยู่โดยค้นหาบันทึกของ Cloud Run ดังนี้

gcloud run services logs read toolbox --region us-central1 --limit 10

คุณควรเห็นข้อมูลต่อไปนี้

2025-08-20 18:03:55 2025-08-20T18:03:55.465847801Z INFO "Initialized 1 sources."
2025-08-20 18:03:55 2025-08-20T18:03:55.466152914Z INFO "Initialized 0 authServices."
2025-08-20 18:03:55 2025-08-20T18:03:55.466374245Z INFO "Initialized 9 tools."
2025-08-20 18:03:55 2025-08-20T18:03:55.466477938Z INFO "Initialized 2 toolsets."
2025-08-20 18:03:55 2025-08-20T18:03:55.467492303Z INFO "Server ready to serve!"

บันทึก URL ของ Cloud Run สำหรับบริการกล่องเครื่องมือเป็นตัวแปรสภาพแวดล้อมเพื่อให้ Agent ของ ADK รู้ว่าจะค้นหาได้จากที่ใด

export MCP_TOOLBOX_URL=$(gcloud run services describe toolbox --region us-central1 --format "value(status.url)")
echo MCP_TOOLBOX_URL=$MCP_TOOLBOX_URL >> software_bug_assistant/.env

อัปเดตเอเจนต์ QuantumRoast

ประการที่ 2 เราต้องเพิ่มทรัพยากร Dependency สำหรับ MCP Toolbox for Databases SDK (toolbox-core) ลงในโปรเจ็กต์

uv add toolbox-core==0.5.0

เปิดไฟล์ tools.py เพื่อเพิ่มการรองรับเครื่องมือ MCP Toolbox

cloudshell edit software_bug_assistant/tools.py

เพิ่มรายการต่อไปนี้ที่ด้านล่างของ tools.py

# ----- Example MCP Toolbox for Databases tools -----
import os
from toolbox_core import ToolboxSyncClient

TOOLBOX_URL = os.getenv("MCP_TOOLBOX_URL", "http://127.0.0.1:5000")

# Initialize Toolbox client
toolbox = ToolboxSyncClient(TOOLBOX_URL)
# Load all the tools from toolset
toolbox_tools = toolbox.load_toolset("tickets_toolset")

ตอนนี้เราสามารถนำเข้าและส่ง toolbox_tools ไปยังเอเจนต์รูทใน agent.py ได้แล้ว

cloudshell edit software_bug_assistant/agent.py

คุณสามารถแทนที่ agent.py ด้วยโค้ดต่อไปนี้เพื่อรวม toolbox_tools

from google.adk.agents import Agent

from .tools import get_current_date, langchain_tool, search_tool, toolbox_tools

# --- Agent Definition (model, instructions, tools) ---
root_agent = Agent(
    model="gemini-2.5-flash",
    name="software_assistant",
    instruction="""
    You are a skilled expert in triaging and debugging software issues for a
    coffee machine company, QuantumRoast.
    """,
    tools=[get_current_date, search_tool, langchain_tool, *toolbox_tools],
)

บันทึกไฟล์แล้วกลับไปที่แท็บที่เปิดอยู่ซึ่งมี ADK Web UI

ตอนนี้คุณสามารถถามคำถามเกี่ยวกับตั๋วที่จัดเก็บไว้ในฐานข้อมูลตั๋วภายในของ Cloud SQL ได้แล้ว

ถามคำถามอย่างเช่นคำถามต่อไปนี้

  • I am seeing an issue with database timeouts, has anyone else seen a similar issue?
  • How many bugs are assigned to samuel.green@example.com? Show a table.
  • Can you bump the priority of ticket with ID 6 to to P0 - Critical priority
  • Create a new ticket (ให้ตัวแทนแนะนำขั้นตอนการสร้างข้อบกพร่อง)

ตัวอย่างเครื่องมือฐานข้อมูล MCP

ตอนนี้ Agent ADK ของเราได้ค้นหาฐานข้อมูลผ่านเครื่องมือ MCP Toolbox สำหรับฐานข้อมูลเรียบร้อยแล้ว🚀

10. ไม่บังคับ: เครื่องมือ MCP (API)

แล้วการเชื่อมต่อตัวแทน ADK กับเครื่องมือ MCP ที่ไม่มี SDK ของตัวเอง เช่น MCP Toolbox สำหรับฐานข้อมูลล่ะ

ADK รองรับเครื่องมือ MCP ทั่วไปผ่านคลาส MCPToolset MCPToolset คลาสเป็นกลไกหลักของ ADK ในการผสานรวมเครื่องมือจากเซิร์ฟเวอร์ MCP

เครื่องมือ MCP (API)

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

GitHub ของเครื่องมือ MCP

โทเค็นเพื่อการเข้าถึงส่วนบุคคล (PAT) ของ GitHub

หากต้องการตรวจสอบสิทธิ์กับเซิร์ฟเวอร์ GitHub MCP คุณต้องมีโทเค็นเพื่อการเข้าถึงแบบส่วนตัวของ GitHub

หากต้องการรับหมายเลขดังกล่าว ให้ทำตามขั้นตอนต่อไปนี้

  1. ไปที่การตั้งค่าสำหรับนักพัฒนาซอฟต์แวร์ GitHub
  2. คลิก "โทเค็นการเข้าถึงส่วนบุคคล" -> "โทเค็น (คลาสสิก)"
  3. คลิก "สร้างโทเค็นใหม่" -> "สร้างโทเค็นใหม่ (คลาสสิก)"
  4. ตั้งชื่อโทเค็นที่สื่อความหมาย
  5. กำหนดวันที่หมดอายุสำหรับโทเค็น
  6. สำคัญ: เพื่อความปลอดภัย ให้กำหนดขอบเขตที่จำกัดที่สุดเท่าที่จำเป็นสำหรับโทเค็น สำหรับสิทธิ์การอ่านอย่างเดียวในที่เก็บ มักจะใช้ขอบเขต repo:status, public_repo และ read:user ก็เพียงพอแล้ว หลีกเลี่ยงการให้สิทธิ์ระดับที่เก็บหรือสิทธิ์ผู้ดูแลระบบอย่างเต็มรูปแบบ เว้นแต่จะจำเป็นจริงๆ
  7. คลิก Generate token
  8. คัดลอกโทเค็นที่สร้างขึ้น

ในเทอร์มินัล Cloud Shell ให้เรียกใช้คำสั่งต่อไปนี้เพื่อตั้งค่า PAT ของ GitHub เพื่อให้ Agent ใช้ได้ แทนที่ YOUR_GITHUB_PAT ด้วย PAT ที่สร้างขึ้น

export GITHUB_PAT=YOUR_GITHUB_PAT

อัปเดตเอเจนต์ QuantumRoast

สำหรับผู้ช่วยด้านข้อบกพร่อง เราจะแสดงเครื่องมือ GitHub แบบอ่านอย่างเดียวบางส่วน เพื่อให้พนักงานของ QuantumRoast ค้นหาปัญหาที่เกี่ยวข้องกับการขึ้นอยู่กับโอเพนซอร์ส และดูว่าเครื่องมือดังกล่าวจะช่วยระบุสาเหตุหลักของข้อบกพร่องที่พนักงานเห็นในระบบการแจ้งปัญหาภายในได้หรือไม่ เราจะใช้ MCPToolset ของ ADK กับ tool_filter เพื่อตั้งค่า tool-filter จะแสดงเฉพาะเครื่องมือ GitHub ที่เราต้องการ ซึ่งไม่เพียงซ่อนเครื่องมือที่เราไม่ต้องการให้ผู้ใช้เข้าถึง (เช่น การดำเนินการกับที่เก็บข้อมูลที่ละเอียดอ่อน) แต่ยังปกป้องโมเดลของเอเจนต์ไม่ให้ทำงานหนักเกินไปเมื่อพยายามเลือกเครื่องมือที่เหมาะสมกับงาน

เปิดไฟล์ tools.py เพื่อเพิ่มการรองรับเครื่องมือ GitHub

cloudshell edit software_bug_assistant/tools.py

เพิ่มรายการต่อไปนี้ที่ด้านล่างของ tools.py

# ----- Example MCP Tools with MCPToolset (GitHub) -----
from google.adk.tools.mcp_tool import MCPToolset, StreamableHTTPConnectionParams

mcp_tools = MCPToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://api.githubcopilot.com/mcp/",
        headers={
            "Authorization": "Bearer " + os.getenv("GITHUB_PAT"),
        },
    ),
    # Read only tools
    tool_filter=[
        "search_repositories",
        "search_issues",
        "list_issues",
        "get_issue",
        "list_pull_requests",
        "get_pull_request",
    ],
)

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

ตอนนี้เราสามารถนำเข้าและส่ง mcp_tools ไปยังเอเจนต์รูทใน agent.py ได้แล้ว

cloudshell edit software_bug_assistant/agent.py

คุณสามารถแทนที่ agent.py ด้วยโค้ดต่อไปนี้เพื่อรวม mcp_tools

from google.adk.agents import Agent

from .tools import get_current_date, langchain_tool, mcp_tools, search_tool, toolbox_tools

# --- Agent Definition (model, instructions, tools) ---
root_agent = Agent(
    model="gemini-2.5-flash",
    name="software_assistant",
    instruction="""
    You are a skilled expert in triaging and debugging software issues for a
    coffee machine company, QuantumRoast.
    """,
    tools=[get_current_date, search_tool, langchain_tool, *toolbox_tools, mcp_tools],
)

บันทึกไฟล์แล้วกลับไปที่แท็บที่เปิดอยู่ซึ่งมี ADK Web UI

ตอนนี้เรามีชุดเครื่องมือ MCP ของ GitHub ที่ตัวแทนของเราสามารถเรียกใช้ได้ บริการของ QuantumRoast อาศัย XZ Utils ซึ่งเป็นเครื่องมือบีบอัดข้อมูล ระบบตั๋วสนับสนุนข้อบกพร่องภายในของเรากำลังติดตาม CVE (ช่องโหว่ด้านความปลอดภัย) จากปีที่แล้ว ซึ่งเราสามารถย้อนกลับไปที่ที่เก็บ XZ Utils GitHub ได้โดยใช้เครื่องมือ StackOverflow และ Google Search จากนั้นเราจะใช้เครื่องมือ MCP ของ GitHub อย่างใดอย่างหนึ่ง search_issues เพื่อพิจารณาว่ามีการแก้ไข CVE นั้นเมื่อใดและอย่างไร

ถามตัวแทนดังนี้

  • Find the official XZ Utils GitHub repository
  • Search the repository for issues related to CVE-2024-3094

คุณควรเห็นว่าเอเจนต์เรียกใช้เครื่องมือ GitHub

ตัวอย่าง GitHub ของเครื่องมือ MCP

ตอนนี้เอเจนต์ QuantumRoast ADK สามารถโต้ตอบกับเครื่องมือเซิร์ฟเวอร์ GitHub MCP ได้แล้ว 🤩

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

ยินดีด้วย คุณสร้างเอเจนต์ผู้ช่วยรายงานข้อบกพร่อง QuantumRoast โดยใช้ Agent Development Kit (ADK) และผสานรวมเครื่องมือประเภทต่างๆ เพื่อเพิ่มความสามารถของเอเจนต์ได้สำเร็จ คุณเริ่มต้นด้วยเอเจนต์พื้นฐานและค่อยๆ เพิ่มเครื่องมือฟังก์ชัน เครื่องมือในตัว เครื่องมือของบุคคลที่สาม และเครื่องมือ MCP

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

  • วิธีตั้งค่าโปรเจ็กต์ Python สำหรับการพัฒนา ADK
  • วิธีสร้างตัวแทน ADK พื้นฐาน
  • วิธีติดตั้งใช้งานและใช้เครื่องมือฟังก์ชัน
  • วิธีผสานรวมเครื่องมือในตัว เช่น Google Search
  • วิธีใช้ประโยชน์จากเครื่องมือของบุคคลที่สามจากเฟรมเวิร์ก เช่น LangChain ภายใน ADK
  • วิธีใช้เครื่องมือ MCP เพื่อโต้ตอบกับฐานข้อมูล (Cloud SQL) และ API

QuantumRoast Final

ล้างข้อมูล

คุณสามารถลบโปรเจ็กต์ Cloud เพื่อหลีกเลี่ยงการเรียกเก็บเงินเพิ่มเติม

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

หากต้องการ ให้ลบโปรเจ็กต์โดยทำดังนี้

gcloud projects delete $GOOGLE_CLOUD_PROJECT

นอกจากนี้ คุณอาจต้องการลบทรัพยากรที่ไม่จำเป็นออกจากดิสก์ Cloud Shell ด้วย ดังนี้

  1. ลบไดเรกทอรีโปรเจ็กต์ Codelab 
    rm -rf ~/quantum-roast
  2. คำเตือน! การดำเนินการถัดไปนี้จะยกเลิกไม่ได้ หากต้องการลบทุกอย่างใน Cloud Shell เพื่อเพิ่มพื้นที่ว่าง คุณสามารถลบทั้งไดเรกทอรีหน้าแรกได้ โปรดระมัดระวังและตรวจสอบว่าได้บันทึกทุกอย่างที่คุณต้องการเก็บไว้ที่อื่นแล้ว 
    sudo rm -rf $HOME