Xây dựng một Đại lý du lịch bằng MCP Toolbox 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ẽ tạo một tác nhân bằng cách sử dụng Bộ công cụ phát triển tác nhân (ADK). Bộ công cụ này sử dụng MCP Toolbox for Databases.
Trong lớp học lập trình này, bạn sẽ sử dụng phương pháp từng bước như sau:
- Cung cấp một cơ sở dữ liệu Cloud SQL cho PostgreSQL sẽ có cơ sở dữ liệu khách sạn và dữ liệu mẫu.
- Thiết lập MCP Toolbox 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 cách sử dụng Bộ công cụ phát triển tác nhân (ADK) để sử dụng Bộ công cụ MCP nhằm trả lời các truy vấn của người dùng.
- Khám phá các lựa chọn để kiểm thử Agent và MCP Toolbox for Databases tại chỗ 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 Đặc vụ có thể trả lời các câu hỏi của người dùng về khách sạn ở một vị trí hoặc tìm kiế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 MCP Toolbox for Databases cho phiên bản cơ sở dữ liệu Cloud SQL for PostgreSQL.
- Thiết kế và phát triển một Agent bằng Agent Development Kit (ADK) để trả lời các truy vấn của người dùng.
- Kiểm thử Agent và MCP Toolbox for Databases trong môi trường cục bộ.
- (Không bắt buộc) Triển khai Agent và MCP Toolbox 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 đám mây đã bật tính năng thanh toán
Lớp học lập trình này được thiết kế cho 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 có kiến thức về Python và chỉ cần có khả năng đọc mã cơ bản là đủ để 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 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 một 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 biểu tượng 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, bạn có thể kiểm tra để đảm bảo rằng 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 bạn chưa đặt dự án, hãy dùng lệnh sau để đặt:
gcloud config set project <YOUR_PROJECT_ID>
- Bật các API bắt buộc thông qua lệnh bên dưới. Quá trình này có thể mất vài phút, vì vậy, 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 lệnh thành công, 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ể thay thế lệnh gcloud bằng cách tìm kiếm từng sản phẩm trên bảng điều khiển hoặc sử dụng đường liên kết này.
Nếu bỏ lỡ 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 một 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 Nền tảng đám mây của Google.
Chạy lệnh sau trong Cloud Shell để tạo phiên bản:
gcloud sql instances create hoteldb-instance \
--database-version=POSTGRES_15 \
--tier db-g1-small \
--region=us-central1 \
--edition=ENTERPRISE \
--root-password=postgres
Lệnh này mất khoảng 3 đến 5 phút để thực thi. Sau khi thực hiện thành công lệnh này, bạn sẽ thấy một 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 của bạn, chẳng hạn như TÊN, DATABASE_VERSION, VỊ TRÍ, v.v.
4. Chuẩn bị cơ sở dữ liệu Khách sạn
Bây giờ, nhiệm vụ của chúng ta là tạo một số dữ liệu mẫu cho Hotel Agent.
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 lựa chọn trình đơn Cloud SQL Studio như minh hoạ dưới đây:
Thao tác này sẽ yêu cầu bạn đăng nhập vào Cloud SQL Studio. Thông qua Cloud SQL Studio, chúng ta sẽ đưa ra một vài lệnh SQL. Chọn postgres cho mục Cơ sở dữ liệu và cho cả mụ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 đồ bên dưới. 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-20', '2024-04-22', 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-05', '2024-04-24', B'0'),
(5, 'Best Western Bern', 'Bern', 'Upper Midscale', '2024-04-01', '2024-04-23', B'0'),
(6, 'InterContinental Geneva', 'Geneva', 'Luxury', '2024-04-23', '2024-04-28', B'0'),
(7, 'Sheraton Zurich', 'Zurich', 'Upper Upscale', '2024-04-02', '2024-04-27', B'0'),
(8, 'Holiday Inn Basel', 'Basel', 'Upper Midscale', '2024-04-09', '2024-04-24', 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 SQL SELECT như minh hoạ 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ạ bên dưới:
Chúng tôi đã 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 MCP Toolbox 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 là một máy chủ MCP nguồn mở dành cho cơ sở dữ liệu. Máy chủ này được thiết kế để đáp ứng chất lượng sản xuất và cấp doanh nghiệp. Nhờ đó, bạn có thể 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 điểm phức tạp như nhóm kết nối, xác thực và nhiều điểm khác.
Toolbox giúp bạn tạo các công cụ AI tạo sinh cho phép nhân viên 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 chỉ bằng chưa đến 10 dòng mã, tái sử dụng 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ư nhóm 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: Xác thực tích hợp để 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à hoạt động theo dõi có sẵn với sự hỗ trợ tích hợp cho OpenTelemetry.
Toolbox nằm giữa khung điều phối của ứng dụng và cơ sở dữ liệu của bạn, cung cấp một mặt phẳng điều khiển được dùng để sửa đổi, phân phối hoặc gọi các công cụ. Nó đơ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 thiết phải triển khai lại ứng dụng của mình.
Bạn có thể thấy rằng một trong những cơ sở dữ liệu được MCP Toolbox for Databases hỗ trợ là Cloud SQL và chúng tôi đã cung cấp cơ sở dữ liệu đó trong phần trước.
Cài đặt Hộp công cụ
Mở Cloud Shell Terminal rồi tạo một thư mục có tên là mcp-toolbox.
mkdir mcp-toolbox
Chuyển đến thư mục mcp-toolbox thông qua lệnh bên dưới:
cd mcp-toolbox
Cài đặt phiên bản nhị phân của MCP Toolbox for Databases thông qua tập lệnh bên dưới. Lệnh dưới đây dành cho Linux, nhưng nếu bạn đang dùng Mac hoặc Windows, hãy đảm bảo rằng bạn đang tải đúng tệp nhị phân. Xem trang phát hành cho Hệ điều hành và Cấu trúc của bạn rồi tải tệp nhị phân phù hợp xuống.
export VERSION=0.8.0
curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox
Giờ đây, chúng ta đã có phiên bản nhị phân của hộp công cụ để sử dụng. Bước tiếp theo là định cấu hình bộ 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 Toolbox là thông qua tệp tools.yaml. Tạo một tệp có tên là tools.yaml trong cùng một thư mục, tức là mcp-toolbox. Nội dung của tệp này được trình bày 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 có dạng 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. Result is sorted by price from least to most expensive.
parameters:
- name: location
type: string
description: The location of the hotel.
statement: |
SELECT *
FROM hotels
WHERE location ILIKE '%' || $1 || '%'
ORDER BY
CASE price_tier
WHEN 'Midscale' THEN 1
WHEN 'Upper Midscale' THEN 2
WHEN 'Upscale' THEN 3
WHEN 'Upper Upscale' THEN 4
WHEN 'Luxury' THEN 5
ELSE 99 -- Handle any unexpected values, place them at the end
END;
toolsets:
my_first_toolset:
- search-hotels-by-name
- search-hotels-by-location
Hãy cùng tìm hiểu sơ lược về tệp này:
Sourcesđại diện cho các nguồn dữ liệu khác nhau mà một công cụ có thể tương tác. Nguồn đạ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 tôi đã đị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 đăng nhập. Để 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 những hành động mà một 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ẽ cần một nguồn để hoạt động. Trong trường hợp này, chúng ta đang xác định 2 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 phần 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 có thể 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 đó có 2 công cụ mà chúng ta đã xác định.
Chạy MCP Toolbox 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 nên thấy một đầu ra 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ụ cũng như các công cụ. Dưới đây là một 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, MCP Toolbox Server chạy trên cổng 5000. Nếu thấy cổng 5000 đã được sử dụng, bạn có thể sử dụng một cổng khác (ví dụ: 7000) theo lệnh bên dưới. Vui lòng sử dụng 7000 thay vì cổng 5000 trong các lệnh tiếp theo.
./toolbox --tools-file "tools.yaml" --port 7000
Hãy dùng Cloud Shell để kiểm thử.
Nhấp vào Web Preview (Xem trước trên web) trong Cloud Shell như minh hoạ dưới đây:
Nhấp vào Change port (Thay đổi cổng) rồi đặt cổng thành 5000 như minh hoạ bên dưới, sau đó nhấp vào Change and Preview (Thay đổi và xem trước).
Thao tác này sẽ cho ra 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 được định cấu hình. Dưới đây là một ví dụ về kết quả đầu ra:
{
"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 Toolkit for Databases (Bộ công cụ MCP cho cơ sở dữ liệu) mô tả một cách thức theo kiểu Python để bạn xác thực và kiểm thử các công cụ, được ghi lại tại đây. Chúng ta sẽ bỏ qua phần đó và chuyển thẳng đến Bộ công cụ 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 Agent bằng Agent Development Kit (ADK)
Cài đặt Agent Development Kit (ADK)
Mở một thẻ thiết bị đầu cuối mới trong Cloud Shell và tạo một thư mục có tên là 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 cách sử dụ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 ADK và các gói MCP Toolbox for Databases cùng với phần phụ thuộc langchain như sau:
pip install google-adk toolbox-core
Giờ đây, bạn có thể gọi tiện ích adk như sau.
adk
Thao tác này sẽ cho bạn 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 nhân viên hỗ trợ đầu tiên
Giờ đây, chúng ta sẽ sử dụng adk để tạo một cấu trúc cho Ứng dụng đại lý khách sạn thông qua lệnh adk create với tên ứng dụng là **(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 bạn trên Google sẽ xuất hiện. Chọn chính chế độ 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 mà một mẫu mặc định và các tệp bắt buộc cho Agent đã được tạo.
Đầ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 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 xem tệp agent.py. Nội dung được trình bày 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à Agent đơn giản nhất mà bạn có thể viết bằng ADK. Theo tài liệu về ADK page, Agent là một đơn vị thực thi độc lập được thiết kế để hoạt động độc lập nhằm đạt được các mục tiêu cụ thể. Agent 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à phối hợp với các Agent 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, suy luận, lập kế hoạch, tạo câu trả lời và quyết định một cách linh hoạt cách tiếp tục hoặc công cụ cần sử dụng, khiến chúng trở nên lý tưởng cho các tác vụ linh hoạt, lấy ngôn ngữ làm trung tâm. Tìm hiểu thêm về Trợ lý ảo dựa trê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 dành cho nhân viên hỗ trợ tại chỗ
Từ cửa sổ dòng lệnh hiện có, hãy đưa ra lệnh sau. Đảm bảo rằng bạn đang ở trong 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:
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. Đường liên kết này sẽ mở ra một bảng điều khiển trên web để kiểm thử Trợ lý. Bạn sẽ thấy nội dung sau đây xuất hiện 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 đại lý khách sạn đã được xác định. Giờ đây, bạn có thể bắt đầu trò chuyện với Trợ lý. Đưa ra một vài câu lệnh hỏi về các thành phố. Sau đây là ví dụ về một cuộc trò chuyện:
Bạn có thể tắt quy trình đang chạy trong thiết bị đầu cuối Cloud Shell (Ctrl-C).
Một cách khác để kiểm thử Agent là thông qua lệnh adk run như được cung cấp bên dưới trong 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 (thiết bị đầu cuối). Nhập exit để đóng cuộc trò chuyện.
7. Kết nối Agent với các công cụ
Giờ đây, chúng ta đã biết cách viết một Agent và kiểm thử cục bộ. Chúng ta sẽ kết nối Agent này với Tools. Trong bối cảnh ADK, Công cụ đại diện cho một chức năng cụ thể được cung cấp cho một tác nhân AI, cho phép tác nhân đó thực hiện các hành động và tương tác với thế giới bên ngoài khả năng tạo văn bản và suy luận cốt lõi.
Trong trường hợp này, chúng ta sẽ trang bị cho Agent những Công cụ mà chúng ta đã định cấu hình trong MCP Toolbox for Databases.
Sửa đổi tệp agent.py bằng đoạn mã sau. Xin lưu ý rằng chúng ta đang sử dụng cổng mặc định 5000 trong mã. Tuy nhiên, nếu bạn đang sử dụng một số cổng thay thế, vui lòng sử dụng số cổng đó.
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,
)
Giờ đây, chúng ta có thể kiểm thử Agent 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 MCP Toolbox for Databases.
Để thực hiện việc này, hãy làm theo trình tự sau:
Trong một cửa sổ lệnh của Cloud Shell, hãy khởi chạy MCP Toolbox for Databases. Bạn có thể đã chạy ứng dụng này cục bộ trên cổng 5000 như chúng ta đã thử nghiệm 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 nên thấy một đầu ra 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ụ cũng như các công cụ. Dưới đây là một 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 Agent như chúng ta đã làm 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 hiện tại, Agent đang sử dụng hai công cụ mà chúng ta đã định cấu hình trong MCP Toolbox for Databases (search-hotels-by-name và search-hotels-by-location) và cung cấp cho chúng ta các lựa chọn chính xác. Sau đó, ứng dụng có thể truy xuất dữ liệu một cách liền mạch từ cơ sở dữ liệu của phiên bản PostgreSQL và định dạng phản hồi cho phù hợp.
Thao tác này hoàn tất quá trình phát triển và kiểm thử cục bộ của Hotel Agent mà chúng tôi đã tạo bằng Agent Development Kit (ADK) và được hỗ trợ bởi các công cụ mà chúng tôi đã định cấu hình trong MCP Toolbox for Databases.
8. (Không bắt buộc) Triển khai MCP Toolbox for Databases và Agent cho Cloud Run
Trong phần trước, chúng ta đã sử dụng thiết bị đầu cuối Cloud Shell để chạy máy chủ MCP Toolbox và kiểm thử các công cụ bằng Agent. Thao tác 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à Agent cho các dịch vụ của Google Cloud có thể lưu trữ những ứ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ủ này trên Cloud Run. Sau đó, việc này sẽ cung cấp cho chúng ta 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ả ứng dụng Agent. Hướng dẫn về cách lưu trữ ứng dụng này trên Cloud Run có tại đây. Bây giờ, chúng ta sẽ xem xét các bước chính.
Khởi 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 (mỗi lệnh đều có phần giải thích):
Đặt biến PROJECT_ID để trỏ đến mã dự án trên Google Cloud.
export PROJECT_ID="YOUR_GOOGLE_CLOUD_PROJECT_ID"
Tiếp theo, hãy xác minh rằng các dịch vụ sau đây 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 đó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ó đúng vai trò, tức là có khả năng 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 bí mật. Vì phải cài đặt Toolbox trong Cloud Run, nên chúng ta sẽ dùng Container image mới nhất cho Toolbox và đặt tệp đó 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 đối với 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 quy trình triển khai Toolbox Server 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. Thao tác này sẽ hiển thị thông báo "Hello World" 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ụ hiện có:
SERVICE URL/api/toolset
Bạn cũng có thể truy cập vào Cloud Run trong bảng điều khiển Google Cloud và sẽ thấy dịch vụ Toolbox trong danh sách dịch vụ của Cloud Run.
Lưu ý: Nếu vẫn muốn chạy Hotel Agent cục bộ 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 = ToolboxTool("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 = ToolboxTool("CLOUD_RUN_SERVICE_URL")
Hãy thử Ứng dụng đại lý bằng cách sử dụng adk run hoặc adk web như chúng ta đã thấy trước đó.
Triển khai Ứng dụng đại lý khách sạn trên Cloud Run
Bước đầu tiên là đảm bảo bạn đã thực hiện thay đổi trong my-agents/hotel-agent-app/agent.py như hướng dẫn ở trên để trỏ đến URL dịch vụ Toolbox đang chạy trên Cloud Run chứ không phải máy chủ lưu trữ cục bộ.
Trong một phiên Cloud Shell Terminal mới hoặc phiên Terminal hiện có, hãy đảm bảo rằng bạn đang ở trong môi trường ảo Python chính xác mà chúng ta đã thiết lập trước đó.
Trước tiên, hãy tạo một 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 rồi thiết lập các biến môi trường sau đây trước:
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 Agent lên Cloud Run thông qua lệnh adk deploy cloud_run 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 được xác thực đến dịch vụ, vui lòng cung cấp "y" làm giá trị hiện tại.
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 vào Cloud Run. Công cụ này sẽ tải các nguồn lên, đóng gói thành một vùng chứa Docker, đẩy vùng chứa đó vào Artifact Registry rồi triển khai dịch vụ trên Cloud Run. Quá trình này có thể mất vài phút, vì vậy, vui lòng kiên nhẫn chờ đợi.
Bạn sẽ thấy một thông báo tương tự như thông báo bên dưới:
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
Khi triển khai thành công, bạn sẽ nhận được một giá trị cho URL dịch vụ. Sau đó, bạn có thể truy cập vào giá trị 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 Nhân viên khách sạn, như chúng ta đã thấy trước đó trong quá trình thiết lập cục bộ.
9. Dọn dẹp
Để tránh bị tính phí liên tục cho tài khoản Google Cloud của bạn, bạn cần xoá các tài nguyên mà chúng tôi đã tạo trong hội thảo này. Chúng tôi sẽ xoá phiên bản Cloud SQL và các dịch vụ đó (nếu bạn đã triển khai Toolbox và Ứng dụng Khách sạn vào Cloud Run).
Đảm bảo rằng bạn đã thiết lập chính xác các biến môi trường sau, theo dự án và khu vực của bạn:
export PROJECT_ID="YOUR_PROJECT_ID"
export REGION="YOUR_REGION"
Hai lệnh sau đây sẽ xoá các dịch vụ Cloud Run mà chúng ta đã triển khai:
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
Lệnh sau đây sẽ xoá phiên bản Cloud SQL:
gcloud sql instances delete hoteldb-instance
10. Xin chúc mừng
Chúc mừng bạn đã tạo thành công một tác nhân bằng Bộ công cụ phát triển tác nhân (ADK) sử dụng MCP Toolbox cho Cơ sở dữ liệu.