Xây dựng một đại lý du lịch bằng Hộp công cụ MCP cho cơ sở dữ liệu và Bộ phát triển đại lý (ADK)
Thông tin về lớp học lập trình này
1. Giới thiệu
Trong lớp học lập trình này, bạn sẽ xây dựng một tác nhân bằng cách sử dụng Bộ phát triển tác nhân (ADK), bộ phát triển này sử dụng Bộ công cụ MCP cho cơ sở dữ liệu.
Trong lớp học lập trình này, bạn sẽ áp dụng phương pháp từng bước như sau:
- Cung cấp cơ sở dữ liệu Cloud SQL cho PostgreSQL. Cơ sở dữ liệu này sẽ có cơ sở dữ liệu khách sạn và dữ liệu mẫu.
- Thiết lập Bộ công cụ MCP cho Cơ sở dữ liệu để cung cấp quyền truy cập vào dữ liệu.
- Thiết kế và phát triển một tác nhân bằng Bộ phát triển tác nhân (ADK) sẽ sử dụng Hộp công cụ MCP để trả lời các truy vấn của người dùng.
- Khám phá các tuỳ chọn để kiểm thử Trình quản lý và Hộp công cụ MCP cho Cơ sở dữ liệu trên máy và trên Google Cloud thông qua dịch vụ Cloud Run.
Bạn sẽ thực hiện
- Thiết kế, xây dựng và triển khai một Trợ lý sẽ trả lời các truy vấn của người dùng về khách sạn ở một vị trí hoặc tìm khách sạn theo tên.
Kiến thức bạn sẽ học được
- Cung cấp và điền dữ liệu mẫu vào cơ sở dữ liệu Cloud SQL cho PostgreSQL.
- Thiết lập Hộp công cụ MCP cho cơ sở dữ liệu cho phiên bản cơ sở dữ liệu Cloud SQL cho PostgreSQL.
- Thiết kế và phát triển một Trợ lý bằng Bộ phát triển trợ lý (ADK) để trả lời truy vấn của người dùng.
- Kiểm thử Trình đại diện và Hộp công cụ MCP cho Cơ sở dữ liệu trong môi trường cục bộ.
- (Không bắt buộc) Triển khai Trình quản lý và Hộp công cụ MCP cho Cơ sở dữ liệu trong Google Cloud.
Bạn cần có
- Trình duyệt web Chrome
- Tài khoản Gmail
- Một dự án trên Google Cloud đã bật tính năng thanh toán
Lớp học lập trình này được thiết kế cho các nhà phát triển ở mọi cấp độ (kể cả người mới bắt đầu), sử dụng Python trong ứng dụng mẫu. Tuy nhiên, bạn không cần phải có kiến thức về Python để hiểu các khái niệm được trình bày.
2. Trước khi bắt đầu
Tạo một dự án
- Trong Google Cloud Console, trên trang bộ chọn dự án, hãy chọn hoặc tạo một dự án trên Google Cloud.
- Đảm bảo bạn đã bật tính năng thanh toán cho dự án trên Cloud. Tìm hiểu cách kiểm tra xem tính năng thanh toán có được bật trên dự án hay không .
- Bạn sẽ sử dụng Cloud Shell, một môi trường dòng lệnh chạy trong Google Cloud và được tải sẵn bq. Nhấp vào Kích hoạt Cloud Shell ở đầu bảng điều khiển Google Cloud.
- Sau khi kết nối với Cloud Shell, hãy kiểm tra để đảm bảo bạn đã được xác thực và dự án được đặt thành mã dự án của bạn bằng lệnh sau:
gcloud auth list
- Chạy lệnh sau trong Cloud Shell để xác nhận rằng lệnh gcloud biết về dự án của bạn.
gcloud config list project
- Nếu dự án của bạn chưa được đặt, hãy sử dụng lệnh sau để đặt dự án:
gcloud config set project <YOUR_PROJECT_ID>
- Bật các API bắt buộc thông qua lệnh hiển thị bên dưới. Quá trình này có thể mất vài phút. Vui lòng kiên nhẫn chờ đợi.
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
Khi thực thi thành công lệnh này, bạn sẽ thấy một thông báo tương tự như thông báo dưới đây:
Operation "operations/..." finished successfully.
Bạn có thể sử dụng bảng điều khiển để tìm kiếm từng sản phẩm hoặc sử dụng đường liên kết này thay cho lệnh gcloud.
Nếu thiếu bất kỳ API nào, bạn luôn có thể bật API đó trong quá trình triển khai.
Tham khảo tài liệu để biết các lệnh và cách sử dụng gcloud.
3. Tạo phiên bản Cloud SQL
Chúng ta sẽ sử dụng một phiên bản Google Cloud SQL cho PostgreSQL để lưu trữ dữ liệu về khách sạn. Cloud SQL cho PostgreSQL là một dịch vụ cơ sở dữ liệu được quản lý hoàn toàn, giúp bạn thiết lập, duy trì, quản lý và quản trị cơ sở dữ liệu quan hệ PostgreSQL trên Google Cloud Platform.
Chạy lệnh sau trong Cloud Shell để tạo thực thể:
gcloud sql instances create hoteldb-instance \
--database-version=POSTGRES_15 \
--cpu=2 \
--memory=8GiB \
--region=us-central1 \
--edition=ENTERPRISE \
--root-password=postgres
Lệnh này sẽ mất khoảng 3 đến 5 phút để thực thi. Sau khi lệnh được thực thi thành công, bạn sẽ thấy kết quả cho biết lệnh đã hoàn tất, cùng với thông tin về phiên bản Cloud SQL như NAME, DATABASE_VERSION, LOCATION, v.v.
4. Chuẩn bị cơ sở dữ liệu Khách sạn
Nhiệm vụ của chúng ta bây giờ là tạo một số dữ liệu mẫu cho Trợ lý khách sạn.
Truy cập vào trang Cloud SQL trong Cloud Console.Bạn sẽ thấy hoteldb-instance đã sẵn sàng và được tạo. Nhấp vào tên của thực thể (hoteldb-instance) như minh hoạ dưới đây:
Trên trình đơn bên trái của Cloud SQL, hãy truy cập vào tuỳ chọn trình đơn Cloud SQL Studio như minh hoạ bên dưới:
Thao tác này sẽ yêu cầu bạn đăng nhập vào Cloud SQL Studio. Chúng tôi sẽ đưa ra một vài lệnh SQL thông qua Cloud SQL Studio. Chọn postgres cho tuỳ chọn Cơ sở dữ liệu và cho cả Người dùng và Mật khẩu, giá trị cần sử dụng là postgres. Nhấp vào biểu tượng AUTHENTICATE.
Trước tiên, hãy tạo bảng khách sạn theo giản đồ dưới đây. Trong một trong các ngăn Trình chỉnh sửa trong Cloud SQL Studio, hãy thực thi SQL sau:
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
);
Bây giờ, hãy điền dữ liệu mẫu vào bảng khách sạn. Thực thi SQL sau:
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');
Hãy xác thực dữ liệu bằng cách chạy một câu lệnh SELECT SQL như dưới đây:
SELECT * FROM hotels;
Bạn sẽ thấy một số bản ghi trong bảng khách sạn như minh hoạ dưới đây:
Chúng ta đã hoàn tất quy trình thiết lập một phiên bản Cloud SQL và tạo dữ liệu mẫu. Trong phần tiếp theo, chúng ta sẽ thiết lập Hộp công cụ MCP cho Cơ sở dữ liệu.
5. Thiết lập Hộp công cụ MCP cho cơ sở dữ liệu
MCP Toolbox for Databases (Hộp công cụ MCP cho cơ sở dữ liệu) là một máy chủ MCP nguồn mở dành cho cơ sở dữ liệu. Hộp công cụ này được thiết kế để đáp ứng chất lượng sản xuất và cấp doanh nghiệp. Thư viện này giúp bạn phát triển các công cụ dễ dàng, nhanh chóng và an toàn hơn bằng cách xử lý các vấn đề phức tạp như gộp kết nối, xác thực, v.v.
Hộp công cụ giúp bạn xây dựng các công cụ AI tạo sinh để cho phép nhân viên hỗ trợ truy cập vào dữ liệu trong cơ sở dữ liệu của bạn. Hộp công cụ cung cấp:
- Đơn giản hoá quá trình phát triển: Tích hợp các công cụ vào tác nhân của bạn trong chưa đến 10 dòng mã, sử dụng lại các công cụ giữa nhiều tác nhân hoặc khung và triển khai các phiên bản công cụ mới dễ dàng hơn.
- Hiệu suất cao hơn: Các phương pháp hay nhất như gộp kết nối, xác thực và nhiều phương pháp khác.
- Tăng cường bảo mật: Tích hợp tính năng xác thực để truy cập vào dữ liệu của bạn một cách an toàn hơn
- Khả năng quan sát toàn diện: Các chỉ số và tính năng theo dõi ngay từ đầu với tính năng hỗ trợ tích hợp cho OpenTelemetry.
Hộp công cụ nằm giữa khung điều phối của ứng dụng và cơ sở dữ liệu, cung cấp một vùng điều khiển dùng để sửa đổi, phân phối hoặc gọi các công cụ. Công cụ này giúp đơn giản hoá việc quản lý các công cụ bằng cách cung cấp cho bạn một vị trí tập trung để lưu trữ và cập nhật các công cụ, cho phép bạn chia sẻ các công cụ giữa các tác nhân và ứng dụng, đồng thời cập nhật các công cụ đó mà không cần triển khai lại ứng dụng.
Bạn có thể thấy rằng một trong những cơ sở dữ liệu được Hộp công cụ MCP cho Cơ sở dữ liệu hỗ trợ là Cloud SQL và chúng tôi đã cấp phép cơ sở dữ liệu đó trong phần trước.
Cài đặt Hộp công cụ
Mở Cloud Shell Terminal và tạo một thư mục có tên mcp-toolbox.
mkdir mcp-toolbox
Chuyển đến thư mục mcp-toolbox thông qua lệnh hiển thị bên dưới:
cd mcp-toolbox
Cài đặt phiên bản tệp nhị phân của Hộp công cụ MCP cho cơ sở dữ liệu thông qua tập lệnh dưới đây:
export VERSION=0.3.0
curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox
Chúng ta hiện đã có phiên bản tệp nhị phân của hộp công cụ để sử dụng. Bước tiếp theo là định cấu hình hộp công cụ bằng các nguồn dữ liệu và cấu hình khác.
Định cấu hình tools.yaml
Cách chính để định cấu hình Hộp công cụ là thông qua tệp tools.yaml. Tạo một tệp có tên tools.yaml trong cùng thư mục, tức là mcp-toolbox, nội dung của tệp này được hiển thị bên dưới.
Bạn có thể sử dụng trình chỉnh sửa nano có trong Cloud Shell. Lệnh nano như sau: "nano tools.yaml".
Hãy nhớ thay thế giá trị YOUR_PROJECT_ID bằng Mã dự án Google Cloud của bạn.
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
Hãy cùng tìm hiểu ngắn gọn về tệp này:
Sourcesđại diện cho các nguồn dữ liệu mà một công cụ có thể tương tác. Nguồn (Source) đại diện cho một nguồn dữ liệu mà công cụ có thể tương tác. Bạn có thể xác địnhSourcesdưới dạng một bản đồ trong phần nguồn của tệp tools.yaml. Thông thường, cấu hình nguồn sẽ chứa mọi thông tin cần thiết để kết nối và tương tác với cơ sở dữ liệu. Trong trường hợp này, chúng ta đã định cấu hình một nguồn duy nhất trỏ đến phiên bản Cloud SQL cho PostgreSQL bằng thông tin xác thực. Để biết thêm thông tin, hãy tham khảo tài liệu tham khảo về Nguồn.Toolsxác định các hành động mà tác nhân có thể thực hiện – chẳng hạn như đọc và ghi vào một nguồn. Công cụ đại diện cho một hành động mà tác nhân của bạn có thể thực hiện, chẳng hạn như chạy một câu lệnh SQL. Bạn có thể xác địnhToolsdưới dạng một bản đồ trong phần công cụ của tệp tools.yaml. Thông thường, một công cụ sẽ yêu cầu một nguồn để thực hiện hành động. Trong trường hợp này, chúng ta đang xác định hai công cụ:search-hotels-by-namevàsearch-hotels-by-location, đồng thời chỉ định nguồn mà công cụ đó đang hoạt động, cùng với SQL và các tham số. Để biết thêm thông tin, hãy tham khảo tài liệu tham khảo về Công cụ.- Cuối cùng, chúng ta có
Toolset, cho phép bạn xác định các nhóm công cụ mà bạn muốn tải cùng nhau. Điều này có thể hữu ích khi xác định các nhóm khác nhau dựa trên tác nhân hoặc ứng dụng. Trong trường hợp này, chúng ta có một bộ công cụ duy nhất có tên làmy_first_toolset, trong đó chứa hai công cụ mà chúng ta đã xác định.
Chạy Hộp công cụ MCP cho máy chủ cơ sở dữ liệu
Chạy lệnh sau (từ thư mục mcp-toolbox) để khởi động máy chủ:
./toolbox --tools-file "tools.yaml"
Tốt nhất là bạn sẽ thấy kết quả cho biết Máy chủ đã có thể kết nối với các nguồn dữ liệu của chúng tôi và đã tải bộ công cụ và các công cụ. Dưới đây là kết quả mẫu:
./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!"
Theo mặc định, Máy chủ Hộp công cụ MCP chạy trên cổng 5000. Hãy sử dụng Cloud Shell để kiểm thử điều này.
Nhấp vào Web Preview (Xem trước trang web) trong Cloud Shell như minh hoạ bên dưới:
Nhấp vào Thay đổi cổng rồi đặt cổng thành 5000 như minh hoạ bên dưới rồi nhấp vào Thay đổi và Xem trước.
Thao tác này sẽ trả về kết quả sau:
Trong URL của trình duyệt, hãy thêm nội dung sau vào cuối URL:
/api/toolset
Thao tác này sẽ hiển thị các công cụ hiện đang được định cấu hình. Dưới đây là kết quả mẫu:
{
"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": []
}
]
}
}
}
Bộ công cụ MCP cho cơ sở dữ liệu mô tả cách thức Pythonic để bạn xác thực và kiểm thử các công cụ. Thông tin này được ghi lại tại đây. Chúng ta sẽ bỏ qua phần đó và chuyển thẳng đến Bộ phát triển tác nhân (ADK) trong phần tiếp theo để sử dụng các công cụ này.
6. Viết tác nhân bằng Agent Development Kit (ADK)
Cài đặt Bộ phát triển tác nhân (ADK)
Mở một thẻ dòng lệnh mới trong Cloud Shell và tạo một thư mục có tên my-agents như sau. Chuyển đến thư mục my-agents.
mkdir my-agents
cd my-agents
Bây giờ, hãy tạo một môi trường Python ảo bằng venv như sau:
python -m venv .venv
Kích hoạt môi trường ảo như sau:
source .venv/bin/activate
Cài đặt các gói ADK và MCP Toolbox for Databases như sau:
pip install google-adk toolbox-core
Giờ đây, bạn có thể gọi tiện ích adk như sau.
adk
Bạn sẽ thấy danh sách các lệnh.
$ 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.
Tạo ứng dụng Agent đầu tiên
Bây giờ, chúng ta sẽ sử dụng adk để tạo một khung cho Ứng dụng đại lý khách sạn thông qua lệnh adk create với tên ứng dụng **(hotel-agent-app)**như dưới đây.
adk create hotel-agent-app
Làm theo các bước và chọn những mục sau:
- Mô hình Gemini để chọn mô hình cho tác nhân gốc.
- Chọn Vertex AI cho phần phụ trợ.
- Mã dự án và khu vực mặc định của Google sẽ xuất hiện. Chọn chính giá trị mặc định.
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
Quan sát thư mục chứa mẫu mặc định và các tệp bắt buộc cho Tác nhân.
Đầu tiên là tệp .env. Nội dung của tệp này được trình bày bên dưới:
GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=YOUR_GOOGLE_PROJECT_ID
GOOGLE_CLOUD_LOCATION=YOUR_GOOGLE_PROJECT_REGION
Các giá trị này cho biết chúng ta sẽ sử dụng Gemini thông qua Vertex AI cùng với các giá trị tương ứng cho mã dự án và vị trí trên Google Cloud.
Sau đó, chúng ta có tệp __init__.py đánh dấu thư mục này là một mô-đun và có một câu lệnh duy nhất để nhập tác nhân từ tệp agent.py.
from . import agent
Cuối cùng, hãy cùng xem tệp agent.py. Nội dung được hiển thị bên dưới:
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',
)
Đây là Tác nhân đơn giản nhất mà bạn có thể viết bằng ADK. Theo trang tài liệu ADK, Tác nhân là một đơn vị thực thi độc lập được thiết kế để hoạt động tự động nhằm đạt được các mục tiêu cụ thể. Tác nhân có thể thực hiện các tác vụ, tương tác với người dùng, sử dụng các công cụ bên ngoài và điều phối với các tác nhân khác.
Cụ thể, LLMAgent (thường được gọi là Agent) sử dụng Mô hình ngôn ngữ lớn (LLM) làm công cụ cốt lõi để hiểu ngôn ngữ tự nhiên, lý luận, lập kế hoạch, tạo phản hồi và linh động quyết định cách tiếp tục hoặc công cụ nào cần sử dụng, giúp các Agent này lý tưởng cho các tác vụ linh hoạt, tập trung vào ngôn ngữ. Tìm hiểu thêm về Tác nhân LLM tại đây.
Hãy sửa đổi mã cho agent.py như sau:
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.',
)
Kiểm thử Ứng dụng tác nhân cục bộ
Từ cửa sổ dòng lệnh hiện có, hãy nhập lệnh sau. Đảm bảo rằng bạn đang ở thư mục mẹ (my-agents) chứa thư mục hotel-agent-app.
adk web
Dưới đây là một ví dụ về quá trình thực thi mẫu:
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)
Nhấp vào đường liên kết cuối cùng để mở một bảng điều khiển web nhằm kiểm thử Tác nhân. Bạn sẽ thấy nội dung sau được chạy trong trình duyệt như minh hoạ dưới đây:
Lưu ý rằng ở trên cùng bên trái, ứng dụng hotel-agent-app đã được xác định. Giờ đây, bạn có thể bắt đầu trò chuyện với Nhân viên hỗ trợ. Cung cấp một vài câu lệnh yêu cầu thông tin về thành phố. Dưới đây là ví dụ về cuộc trò chuyện:
Bạn có thể tắt quy trình đang chạy trong dòng lệnh Cloud Shell (Ctrl-C).
Một cách khác để kiểm thử Tác nhân là thông qua lệnh adk run như được cung cấp bên dưới từ thư mục my-agents.
adk run hotel-agent-app
Hãy thử lệnh này và bạn có thể trò chuyện với Trợ lý qua dòng lệnh (cửa sổ dòng lệnh). Nhập exit để đóng cuộc trò chuyện.
7. Kết nối Nhân viên hỗ trợ của chúng tôi với các công cụ
Bây giờ, chúng ta đã biết cách viết một Tác nhân và kiểm thử tác nhân đó trên máy. Chúng ta sẽ kết nối Tác nhân này với Công cụ. Trong ngữ cảnh của ADK, Công cụ đại diện cho một chức năng cụ thể được cung cấp cho tác nhân AI, cho phép tác nhân này thực hiện các hành động và tương tác với thế giới ngoài khả năng lập luận và tạo văn bản cốt lõi.
Trong trường hợp này, chúng ta sẽ trang bị cho Tác nhân của mình các Công cụ mà chúng ta đã định cấu hình trong Hộp công cụ MCP cho Cơ sở dữ liệu.
Sửa đổi tệp agent.py bằng mã sau:
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,
)
Bây giờ, chúng ta có thể kiểm thử Trình đại diện sẽ tìm nạp dữ liệu thực từ cơ sở dữ liệu PostgreSQL đã được định cấu hình bằng Hộp công cụ MCP cho Cơ sở dữ liệu.
Để thực hiện việc này, hãy làm theo trình tự sau:
Trong một cửa sổ dòng lệnh của Cloud Shell, hãy khởi chạy Hộp công cụ MCP cho Cơ sở dữ liệu. Bạn có thể đã chạy ứng dụng này cục bộ trên cổng 5000 như chúng ta đã kiểm thử trước đó. Nếu không, hãy chạy lệnh sau (từ thư mục mcp-toolbox) để khởi động máy chủ:
./toolbox --tools_file "tools.yaml"
Tốt nhất là bạn sẽ thấy kết quả cho biết Máy chủ đã có thể kết nối với các nguồn dữ liệu của chúng tôi và đã tải bộ công cụ và các công cụ. Dưới đây là kết quả mẫu:
./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!"
Sau khi máy chủ MCP khởi động thành công, trong một thiết bị đầu cuối khác, hãy chạy Trình đại diện như chúng ta đã thực hiện trước đó thông qua lệnh adk run (từ thư mục my-agents) như minh hoạ bên dưới. Bạn cũng có thể sử dụng lệnh adk web nếu muốn.
$ 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.
Lưu ý rằng Trình đại diện hiện đang sử dụng hai công cụ mà chúng ta đã định cấu hình trong Hộp công cụ MCP cho Cơ sở dữ liệu (search-hotels-by-name và search-hotels-by-location) và cung cấp các tuỳ chọn chính xác cho chúng ta. Sau đó, ứng dụng có thể truy xuất liền mạch dữ liệu từ cơ sở dữ liệu thực thể PostgreSQL và định dạng phản hồi cho phù hợp.
Như vậy, chúng ta đã hoàn tất quá trình phát triển và kiểm thử cục bộ của Trình đại diện khách sạn mà chúng ta đã tạo bằng Bộ phát triển tác nhân (ADK) và được cung cấp bởi các công cụ mà chúng ta đã định cấu hình trong Hộp công cụ MCP cho cơ sở dữ liệu.
8. (Không bắt buộc) Triển khai Hộp công cụ MCP cho cơ sở dữ liệu và tác nhân cho Cloud Run
Trong phần trước, chúng ta đã sử dụng thiết bị đầu cuối Cloud Shell để khởi chạy máy chủ Bộ công cụ MCP và kiểm thử các công cụ bằng Trình tác nhân. Quá trình này đang chạy cục bộ trong môi trường Cloud Shell.
Bạn có thể triển khai cả máy chủ MCP Toolbox và Tác nhân cho các dịch vụ của Google Cloud có thể lưu trữ các ứng dụng này cho chúng tôi.
Lưu trữ máy chủ Hộp công cụ MCP trên Cloud Run
Trước tiên, chúng ta có thể bắt đầu với máy chủ Hộp công cụ MCP và lưu trữ máy chủ đó trên Cloud Run. Sau đó, chúng ta sẽ có một điểm cuối công khai mà chúng ta có thể tích hợp với bất kỳ ứng dụng nào khác và/hoặc các ứng dụng của Agent. Bạn có thể xem hướng dẫn lưu trữ ứng dụng này trên Cloud Run tại đây. Bây giờ, chúng ta sẽ tìm hiểu các bước chính.
Chạy một Cửa sổ dòng lệnh Cloud Shell mới hoặc sử dụng một Cửa sổ dòng lệnh Cloud Shell hiện có. Chuyển đến thư mục mcp-toolbox, trong đó có tệp nhị phân toolbox và tools.yaml.
Chạy các lệnh sau (có nội dung giải thích cho từng lệnh):
Đặt biến PROJECT_ID trỏ đến Mã dự án Google Cloud của bạn.
export PROJECT_ID="YOUR_GOOGLE_CLOUD_PROJECT_ID"
Tiếp theo, hãy xác minh rằng các dịch vụ sau của Google Cloud đã được bật trong dự án.
gcloud services enable run.googleapis.com \
cloudbuild.googleapis.com \
artifactregistry.googleapis.com \
iam.googleapis.com \
secretmanager.googleapis.com
Hãy tạo một tài khoản dịch vụ riêng biệt sẽ đóng vai trò là danh tính cho dịch vụ Hộp công cụ mà chúng ta sẽ triển khai trên Google Cloud Run. Chúng tôi cũng đảm bảo rằng tài khoản dịch vụ này có các vai trò chính xác, tức là có thể truy cập vào Secret Manager và giao tiếp với 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
Chúng ta sẽ tải tệp tools.yaml lên dưới dạng một tệp bảo mật và vì phải cài đặt Hộp công cụ trong Cloud Run, nên chúng ta sẽ sử dụng hình ảnh Vùng chứa mới nhất cho hộp công cụ và đặt hình ảnh đó trong biến IMAGE.
gcloud secrets create tools --data-file=tools.yaml
export IMAGE=us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest
Bước cuối cùng trong lệnh triển khai quen thuộc cho 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
Thao tác này sẽ bắt đầu quá trình triển khai Máy chủ hộp công cụ bằng tools.yaml đã định cấu hình của chúng tôi cho Cloud Run. Khi triển khai thành công, bạn sẽ thấy một thông báo tương tự như sau:
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
Giờ đây, bạn có thể truy cập vào Service URL được liệt kê ở trên trong trình duyệt. Ứng dụng sẽ hiển thị thông báo "Hello World" (Xin chào thế giới) mà chúng ta đã thấy trước đó. Ngoài ra, bạn cũng có thể truy cập vào URL sau để xem các công cụ có sẵn:
SERVICE URL/api/toolset
Bạn cũng có thể truy cập vào Cloud Run từ bảng điều khiển Google Cloud và sẽ thấy dịch vụ Hộp công cụ trong danh sách dịch vụ trong Cloud Run.
Lưu ý: Nếu vẫn muốn chạy Trình đại diện khách sạn trên máy và kết nối với dịch vụ Cloud Run mới triển khai, bạn chỉ cần thực hiện một thay đổi trong tệp my-agents/hotel-agent-app/agent.py.
Thay vì nội dung sau:
toolbox = ToolboxSyncClient("http://127.0.0.1:5000")
Thay đổi thành URL dịch vụ của dịch vụ Cloud Run như bên dưới:
toolbox = ToolboxSyncClient("CLOUD_RUN_SERVICE_URL")
Kiểm thử Ứng dụng tác nhân bằng adk run hoặc adk web như chúng ta đã thấy trước đó.
Triển khai ứng dụng Hotel Agent trên Cloud Run
Bước đầu tiên là đảm bảo rằng bạn đã thực hiện thay đổi trong my-agents/hotel-agent-app/agent.py theo hướng dẫn ở trên để trỏ đến URL dịch vụ Hộp công cụ đang chạy trên Cloud Run chứ không phải máy chủ cục bộ.
Trong một Cloud Shell Terminal mới hoặc phiên Terminal hiện có, hãy đảm bảo rằng bạn đang ở đúng môi trường ảo Python mà chúng ta đã thiết lập trước đó.
Trước tiên, hãy tạo tệp requirements.txt trong thư mục my-agents/hotel-agent-app như minh hoạ bên dưới:
google-adk
toolbox-core
Chuyển đến thư mục my-agents và trước tiên, hãy thiết lập các biến môi trường sau:
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
Cuối cùng, hãy triển khai Ứng dụng tác nhân cho Cloud Run thông qua lệnh cloud_run adk deploy như bên dưới. Nếu bạn được yêu cầu cho phép các lệnh gọi chưa xác thực đến dịch vụ, vui lòng cung cấp giá trị "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
Thao tác này sẽ bắt đầu quá trình triển khai Ứng dụng đại lý khách sạn lên Cloud Run. Công cụ này sẽ tải các nguồn lên, đóng gói các nguồn đó vào một Vùng chứa Docker, đẩy vùng chứa đó vào Cấu phần phần mềm lưu trữ, sau đó triển khai dịch vụ trên Cloud Run. Quá trình này có thể mất vài phút. Vui lòng kiên nhẫn chờ đợi.
Bạn sẽ thấy một thông báo tương tự như sau:
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
Sau khi triển khai thành công, bạn sẽ được cung cấp một giá trị cho URL dịch vụ. Sau đó, bạn có thể truy cập vào URL này trong trình duyệt để xem cùng một Ứng dụng web cho phép bạn trò chuyện với Trợ lý khách sạn, như chúng ta đã thấy trước đó trong phần thiết lập cục bộ.
9. Xin chúc mừng
Xin chúc mừng! Bạn đã tạo thành công một tác nhân bằng cách sử dụng Bộ phát triển tác nhân (ADK) sử dụng Hộp công cụ MCP cho cơ sở dữ liệu.