Trang này được dịch bởi Cloud Translation API.

Tạo Trợ lý AI cho nhân viên cửa hàng thể thao bằng ADK, Hộp công cụ MCP và AlloyDB

1. Giới thiệu

Sản phẩm bạn sẽ tạo ra

Trong lớp học lập trình này, bạn sẽ tìm hiểu cách tạo trợ lý AI Sports Shop Agent. Ứng dụng AI Agent thế hệ tiếp theo này, được hỗ trợ bởi ADK, MCP Toolbox và AlloyDB, sẽ hỗ trợ người dùng thực hiện nhiều việc, bao gồm:

Tìm kiếm sản phẩm bằng ngôn ngữ tự nhiên.
Tìm các cửa hàng gần đó để mua sản phẩm được đề xuất.
Đặt đơn đặt hàng mới.
Kiểm tra trạng thái đơn đặt hàng hiện tại.
Cập nhật đơn đặt hàng bằng phương thức giao hàng ưu tiên.

Kiến thức bạn sẽ học được

Cung cấp và điền sẵn cơ sở dữ liệu AlloyDB cho PostgreSQL.
Thiết lập MCP Toolbox for Databases bằng phiên bản AlloyDB cho PostgreSQL.
Thiết kế và phát triển một Đặc vụ AI bằng Bộ công cụ phát triển đặc vụ (ADK) để hỗ trợ các câu hỏi về cửa hàng thể thao.
Kiểm thử Agent và MCP Toolbox cho Cơ sở dữ liệu trong môi trường đám mây.
Khai thác các khả năng truy vấn nâng cao của AlloyDB để có được câu trả lời thông minh từ tác nhân.

Bạn cần có

Để hoàn tất lớp học lập trình này, bạn cần:

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 dành cho nhà phát triển ở mọi cấp độ, kể cả người mới bắt đầu.

2. Trước khi bắt đầu

Phần này hướng dẫn bạn thực hiện quy trình thiết lập ban đầu bắt buộc trong Dự án trên Google Cloud trước khi bạn có thể bắt đầu xây dựng trợ lý AI của Cửa hàng đồ thể thao.

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 rằng 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 .
Kích hoạt Cloud Shell bằng cách nhấp vào đường liên kết này. Bạn có thể chuyển đổi giữa Cloud Shell Terminal (để chạy các lệnh trên đám mây) và Trình chỉnh sửa (để tạo dự án) bằng cách nhấp vào nút tương ứng trong Cloud Shell.

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

Đặt biến PROJECT_ID, dùng lệnh sau để đặt biến này:

export PROJECT_ID=[YOUR_PROJECT_ID]

gcloud config set project $PROJECT_ID

Bật các API sau bằng cách chạy các lệnh sau:

gcloud services enable alloydb.googleapis.com \
                       compute.googleapis.com \
                       cloudresourcemanager.googleapis.com \
                       servicenetworking.googleapis.com \
                       vpcaccess.googleapis.com \
                       aiplatform.googleapis.com

3. Tạo phiên bản AlloyDB

Trong phần này, bạn sẽ thiết lập cụm cơ sở dữ liệu và phiên bản AlloyDB, đồng thời định cấu hình các quyền và hoạt động kết nối mạng cần thiết cho AI Agent.

Trước tiên, hãy chạy lệnh sau trong thiết bị đầu cuối Cloud Shell để tạo Cụm AlloyDB:

gcloud alloydb clusters create alloydb-cluster \
    --password=alloydb\
    --network=default \
    --region=us-central1 \
    --database-version=POSTGRES_16

AlloyDB dựa vào khả năng kết nối IP riêng tư để truy cập an toàn và hiệu suất cao. Bạn cần phân bổ một dải IP riêng tư trong VPC để Google sử dụng cho kết nối ngang hàng dịch vụ với cơ sở hạ tầng mạng của dịch vụ do Google quản lý. Chạy lệnh sau:

gcloud compute addresses create peering-range-for-alloydb \
    --global \
    --purpose=VPC_PEERING \
    --prefix-length=16 \
    --description="Automatically allocated IP range for service networking" \
    --network=default

Tiếp theo, hãy tạo kết nối VPC Service Peering. Điều này cho phép mạng Đám mây riêng ảo (VPC) của Google Cloud giao tiếp một cách an toàn và riêng tư với các dịch vụ được quản lý của Google, bao gồm cả AlloyDB. Chạy lệnh sau:

gcloud services vpc-peerings connect \
--service=servicenetworking.googleapis.com \
--ranges=peering-range-for-alloydb \
--network=default

Bây giờ, hãy tạo phiên bản chính trong cụm AlloyDB. Đây là điểm cuối cơ sở dữ liệu thực tế mà các ứng dụng của bạn sẽ kết nối. Chạy lệnh sau để tạo một phiên bản AlloyDB:

gcloud alloydb instances create alloydb-inst \
     --instance-type=PRIMARY \
     --cpu-count=2 \
     --region=us-central1 \
     --cluster=alloydb-cluster \
     --availability-type=ZONAL \
     --ssl-mode=ALLOW_UNENCRYPTED_AND_ENCRYPTED

Lưu ý: Quá trình tạo phiên bản có thể mất khoảng 10 phút để hoàn tất. Vui lòng đợi thao tác này hoàn tất rồi mới tiếp tục.

Bật tính năng tích hợp Vertex AI

Để cho phép phiên bản AlloyDB của bạn thực hiện các truy vấn tìm kiếm vectơ (rất cần thiết cho các chức năng AI như tìm kiếm ngữ nghĩa) và gọi các mô hình được triển khai trong Vertex AI, bạn cần cấp quyền Vertex AI cho Đặc vụ dịch vụ AlloyDB.

Trước tiên, hãy truy xuất Số dự án trên Google Cloud vì đây là thông tin bắt buộc đối với việc liên kết IAM.

PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
gcloud projects describe $PROJECT_ID --format="value(projectNumber)"

Sau đó, cấp cho Vertex AI quyền truy cập vào Tác nhân dịch vụ AlloyDB:

gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:service-$PROJECT_NUMBER@gcp-sa-alloydb.iam.gserviceaccount.com" \
--role="roles/aiplatform.user"

Bật IP công khai

Để chuẩn bị cho các bước tiếp theo, chúng ta sẽ bật tính năng Kết nối IP công khai trong phiên bản AlloyDB.

Trong Bảng điều khiển, hãy chuyển đến trường tìm kiếm ở giữa trên cùng của màn hình rồi nhập "alloydb", sau đó chỉnh sửa và chuyển đến phần Kết nối IP công khai. Đánh dấu vào hộp "Bật IP công khai" rồi nhập địa chỉ IP của máy Cloud Shell.

Để lấy IP của máy Cloud Shell, hãy chuyển đến Cloud Shell Terminal rồi nhập lệnh "ifconfig | grep -A 1 eth0". Từ kết quả, hãy thay thế 2 chữ số cuối cùng bằng 0.0 với kích thước mặt nạ "/16". Ví dụ: "XX.XX.0.0/16" trong đó XX là các số.

Dán địa chỉ IP này vào hộp văn bản "Mạng" của Mạng bên ngoài được uỷ quyền trên trang chỉnh sửa phiên bản.

Lưu ý: Thao tác cập nhật có thể mất đến 3 phút

4. Tải cơ sở dữ liệu

Tạo cơ sở dữ liệu cửa hàng

Bây giờ là lúc bạn tạo cơ sở dữ liệu và tải dữ liệu ban đầu cho Cửa hàng đồ thể thao.

Để cho phép psql kết nối với phiên bản AlloyDB riêng tư của bạn từ Cloud Shell, bạn sẽ sử dụng AlloyDB Auth Proxy. Tiện ích này sẽ tạo đường hầm bảo mật cho kết nối của bạn với cơ sở dữ liệu. (Tham khảo Proxy xác thực AlloyDB)

Tải AlloyDB Auth Proxy xuống bằng lệnh sau:

wget https://storage.googleapis.com/alloydb-auth-proxy/v1.13.6/alloydb-auth-proxy.linux.amd64 -O alloydb-auth-proxy

Biến tệp thành tệp thực thi:

chmod +x alloydb-auth-proxy

Chạy lệnh này trong cửa sổ dòng lệnh Cloud Shell đầu tiên. Proxy sẽ chạy ở chế độ nền và chuyển tiếp các kết nối.

nohup ./alloydb-auth-proxy "projects/$PROJECT_ID/locations/us-central1/clusters/alloydb-cluster/instances/alloydb-inst" --public-ip &

Kết nối với phiên bản AlloyDB bằng psql:

psql -h 127.0.0.1 -U postgres

Lưu ý: Khi được nhắc, hãy nhập mật khẩu mà bạn đã đặt cho người dùng postgres trong quá trình tạo cụm (nếu bạn đang làm theo tài liệu trực tiếp, mật khẩu là alloydb).

Và tạo cơ sở dữ liệu cửa hàng cho ứng dụng của chúng ta (chạy từng lệnh một):

CREATE DATABASE store;
\c store
exit

Mã nguồn

Bây giờ, hãy sao chép kho lưu trữ mã nguồn của lớp học lập trình. Đảm bảo bạn đang ở thư mục chính hoặc một vị trí phù hợp trước khi sao chép và chạy lệnh sau:

git clone https://github.com/mtoscano84/sports-agent-adk-mcp-alloydb.git

Điền dữ liệu vào cơ sở dữ liệu

Chuyển đến thư mục data của dự án đã sao chép để truy cập vào tệp kết xuất cơ sở dữ liệu.

cd sports-agent-adk-mcp-alloydb/data

Sau đó, hãy nhập tập dữ liệu mẫu vào cơ sở dữ liệu store bằng cách sử dụng tệp store_backup.sql trong kho lưu trữ.

psql -h 127.0.0.1 -U postgres -d store -f store_backup.sql

Lưu ý: Bạn có thể thấy một số thông báo CẢNH BÁO và LỖI trong quá trình nhập này. Bạn có thể yên tâm bỏ qua các thông báo này trong lớp học lập trình này. Những cảnh báo này thường liên quan đến các quyền hoặc đối tượng đã tồn tại nếu tệp kết xuất chứa lược đồ đầy đủ.Bạn sẽ thấy một số CẢNH BÁO và LỖI mà bạn có thể bỏ qua

5. Thiết lập dịch vụ uỷ quyền

Trong phần này, bạn sẽ thiết lập Dịch vụ uỷ quyền cho ứng dụng của mình. Dịch vụ này đóng vai trò quan trọng trong việc bảo mật quyền truy cập và bảo vệ khỏi các lỗ hổng tấn công bằng câu lệnh trong AI Agent của bạn.

Trước tiên, bạn sẽ thêm một người dùng mẫu vào bảng users trong cơ sở dữ liệu store. Người dùng này sẽ được dùng để xác thực trong ứng dụng của bạn.

Chuyển đến bảng điều khiển và chuyển đến AlloyDB, chọn phiên bản chính rồi chọn AlloyDB Studio:

Khi được nhắc, hãy đăng nhập vào AlloyDB Studio bằng thông tin đăng nhập mà bạn đã tạo khi thiết lập cụm:

Tên người dùng: "postgres"
Cơ sở dữ liệu: "store"
Mật khẩu: "alloydb"

Trong Trình chỉnh sửa SQL, hãy thực thi câu lệnh INSERT để thêm người dùng vào cơ sở dữ liệu. Thay đổi tên, họ và địa chỉ email.

Quan trọng:

Giữ nguyên VỊ TRÍ như trong ví dụ
Sử dụng cùng địa chỉ email mà bạn dùng để đăng ký trong Google Cloud Console

INSERT INTO users (user_id, first_name, last_name, Address, city, postal_code, location, email)
VALUES (10,'John', 'Doe', 'Carrer Muntaner 39', 'Barcelona', '08019', '0101000020E61000008AAE0B3F38B144401FBB0B9414780140', 'john.doe@example.com');

Tiếp theo, bạn cần định cấu hình Màn hình đồng ý OAuth cho dự án của mình. Màn hình này xuất hiện với người dùng khi ứng dụng của bạn yêu cầu quyền truy cập vào Tài khoản Google của họ và xác định thương hiệu của ứng dụng.

Trong Bảng điều khiển, hãy chuyển đến phần "API và dịch vụ", "Sự đồng ý của Google OAuth":

Cung cấp thông tin sau để tạo thương hiệu cho ứng dụng của bạn:

Tên ứng dụng: "Sports Shopping Agent AI"
Email hỗ trợ người dùng: "YOUR_EMAIL"
Đối tượng: "Bên ngoài"
Thông tin liên hệ: "YOUR_EMAIL"

Giờ đây, bạn sẽ tạo Mã ứng dụng OAuth mà ứng dụng giao diện người dùng sẽ dùng để xác thực danh tính người dùng bằng Google.

Trước tiên, hãy đảm bảo bạn có Số dự án trên Google Cloud. Bạn cần phải làm việc này để định cấu hình URI chuyển hướng một cách chính xác. Chạy lệnh sau trong một Cloud Shell Terminal:

Trong trường hợp biến PROJECT_ID chưa được đặt trong cửa sổ Cloud Shell Terminal này, hãy thực thi:

export PROJECT_ID=[YOUR_PROJECT_ID]

Sau đó, hãy lấy PROJECT_NUMBER bằng lệnh sau:

gcloud projects describe $PROJECT_ID --format="value(projectNumber)"

Sau đó, chuyển đến phần "API và Dịch vụ" -> "Thông tin xác thực" -> "Tạo thông tin xác thực" -> "Mã ứng dụng OAuth"

Hãy sử dụng thông tin sau để tạo thông tin đăng nhập:

Loại ứng dụng: "Ứng dụng web"
Tên: "Sports Shopping Agent AI App" (Ứng dụng AI Sports Shopping Agent)

Nguồn gốc JavaScript được phép:

URL1: https://finn-frontend-[YOUR_PROJECT_NUMBER].us-central1.run.app

URI chuyển hướng được uỷ quyền:

URL1: https://finn-frontend-[YOUR_PROJECT_NUMBER].us-central1.run.app

Lưu ý: URL https://finn-frontend-[YOUR_PROJECT_NUMBER].us-central1.run.app là URL triển khai dự kiến cho ứng dụng giao diện người dùng của bạn. URL này sẽ được thiết lập sau trong lớp học lập trình này. Đảm bảo bạn thay thế [YOUR_PROJECT_NUMBER] bằng số thực tế mà bạn đã sao chép.

Lưu ý quan trọng: Sau khi bạn tạo, một cửa sổ bật lên sẽ hiển thị Mã ứng dụng OAuth và đôi khi là Khoá bí mật của ứng dụng. Lưu trữ mã ứng dụng OAuth ở một nơi an toàn vì bạn sẽ cần mã này trong một bước sau khi định cấu hình giao diện người dùng.

6. MCP ToolBox cho chế độ thiết lập cơ sở dữ liệu

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ụ của bạn 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.

Vì một trong các cơ sở dữ liệu được MCP Toolbox for Databases hỗ trợ là AlloyDB và chúng ta đã cung cấp cơ sở dữ liệu đó trong phần trước, nên hãy tiếp tục thiết lập Toolbox.

Trước tiên, bạn sẽ thiết lập máy chủ MCP Toolbox cục bộ trong môi trường Cloud Shell để xác minh chức năng của máy chủ này.

Trong Cloud Shell Terminal, hãy chuyển đến thư mục toolbox nằm trong kho lưu trữ dự án đã sao chép:"

cd sports-agent-adk-mcp-alloydb/src/toolbox

Chạy các lệnh sau để tải tệp nhị phân Toolbox xuống và cấp cho tệp này quyền thực thi:

# see releases page for other versions
export VERSION=0.16.0

curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox

chmod +x toolbox

Lưu ý: Phiên bản 0.16.0 được chỉ định ở đây. Đối với môi trường phát hành công khai, hãy luôn xác minh và sử dụng bản phát hành ổn định mới nhất trên trang phát hành Hộp công cụ.

Chuyển đến Cloud Shell Editor (bạn có thể chuyển đổi từ Terminal bằng cách nhấp vào biểu tượng Editor).

Trong cùng thư mục sports-agent-adk-mcp-alloydb/src/toolbox, bạn sẽ thấy một tệp có tên tools.yaml. Mở tệp này rồi cập nhật các phần giữ chỗ bằng mã ứng dụng OAuth và mã dự án trên Google Cloud ở các bước trước.

Hãy tìm hiểu về tools.yaml

Nguồn đạ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 định Nguồn dưới dạng 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.

Công cụ xá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ụ là 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 định Công cụ dướ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.

Để biết thêm thông tin chi tiết về cách định cấu hình tools.yaml, hãy tham khảo tài liệu này.

Hãy 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"

Giờ đây, nếu mở máy chủ ở chế độ xem trước trên web trên đám mây, bạn sẽ thấy máy chủ Toolbox đang chạy với tất cả các công cụ của ứng dụng.

Theo mặc định, MCP Toolbox Server chạy trên cổng 5000. 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:

MCP Toolkit for Databases (Bộ công cụ MCP cho cơ sở dữ liệu) mô tả một SDK Python để bạn xác thực và thử nghiệm các công cụ. Bạn có thể xem tài liệu về bộ công cụ này 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 (ADK) trong phần tiếp theo để sử dụng những công cụ này.

Hãy triển khai Hộp công cụ của chúng ta lên Cloud Run

Để máy chủ Toolbox của bạn có thể truy cập được dưới dạng một điểm cuối công khai có thể tích hợp với các ứng dụng khác và AI Agent của bạn, bạn sẽ triển khai máy chủ đó vào Cloud Run. Hướng dẫn chi tiết về cách lưu trữ Hộp công cụ trên Cloud Run có tại đây.

Quay lại thiết bị đầu cuối Cloud Shell rồi chuyển đến thư mục toolbox:

cd sports-agent-adk-mcp-alloydb/src/toolbox

Đảm bảo rằng biến môi trường PROJECT_ID được đặt thành mã dự án trên Google Cloud.

export PROJECT_ID=$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à tương tác với AlloyDB.

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/alloydb.client'


gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member='serviceAccount:toolbox-identity@'$PROJECT_ID'.iam.gserviceaccount.com' \
    --role='roles/serviceusage.serviceUsageConsumer'

Sau đó, bạn 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 hộp công cụ và đặt giá trị đó trong biến IMAGE.

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

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

Cuối cùng, hãy triển khai máy chủ Toolbox lên Cloud Run bằng lệnh sau. Lệnh này sẽ tạo vùng chứa cho ứng dụng của bạn, định cấu hình tài khoản dịch vụ, chèn bí mật và công khai bí mật đó:

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 vào 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 [sports-store-agent-ai] region [us-central1]
OK Deploying... Done.
  OK Creating Revision...
  OK Routing traffic...
  OK Setting IAM Policy...
Done.
Service [toolbox] revision [toolbox-00002-dn2] has been deployed and is serving 100 percent of traffic.
Service URL: https://toolbox-[YOUR_PROJECT_NUMBER].us-central1.run.app

Giờ đây, bạn có thể truy cập vào URL dịch vụ nêu 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ó:

https://toolbox-[YOUR_PROJECT_NUMBER].us-central1.run.app/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à bạn sẽ thấy dịch vụ Toolbox có trong danh sách dịch vụ trong Cloud Run.

7. Nhân viên hỗ trợ được tạo trên ADK

Trong phần này, bạn sẽ triển khai AI Agent (Đại lý AI) được tạo bằng Agent Development Kit (ADK) (Bộ công cụ phát triển đại lý) cho Cloud Run.

Trước tiên, hãy bật các API cần thiết trong dự án của bạn để tạo và triển khai Agent trên Cloud Run, cũng như để tương tác với Artifact Registry và Cloud Storage. Chạy lệnh sau trong Cloud Shell Terminal:

gcloud services enable artifactregistry.googleapis.com \
                       cloudbuild.googleapis.com \
                       run.googleapis.com \
                       storage.googleapis.com

Sau đó, chúng tôi sẽ chỉ định các quyền cần thiết cho Tài khoản dịch vụ mặc định của Compute Engine trong dự án của mình. Trước tiên, hãy chạy lệnh sau trong cửa sổ dòng lệnh Cloud Shell để lấy PROJECT_NUMBER:

PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")

Chỉ định quyền cho Tài khoản dịch vụ mặc định của Compute Engine:

# Grant Cloud Run service account access to GCS
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
--role="roles/storage.admin"

gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
--role="roles/run.admin"

gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
--role="roles/artifactregistry.writer"

gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$PROJECT_NUMBER@cloudbuild.gserviceaccount.com" \
--role="roles/artifactregistry.repoAdmin"

# Grant Vertex AI User role to the service account
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
--role="roles/aiplatform.user"

# Grant Vertex AI Model User role to the service account
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
--role="roles/aiplatform.modelUser"

Kết nối Agent của chúng tôi với các công cụ

Chúng ta sẽ kết nối Agent với Tools. Trong bối cảnh ADK, Công cụ là 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.

Bằng Cloud Shell Editor, hãy chuyển đến sports-agent-adk-mcp-alloydb/src/backend/ rồi chỉnh sửa tệp "finn_agent.py" bằng mã sau. Xin lưu ý rằng chúng ta đang sử dụng URL dịch vụ Cloud Run từ MCP ToolBox Server được triển khai ở bước trước:

Triển khai Agent trên Cloud Run

Cuối cùng, bạn sẽ triển khai AI Agent đã định cấu hình vào Cloud Run, giúp AI Agent có thể truy cập được thông qua một điểm cuối HTTP.

Trước tiên, hãy tạo một kho lưu trữ Docker trong Artifact Registry để lưu trữ hình ảnh vùng chứa của Agent. Chạy lệnh sau trong Cloud Shell:

gcloud artifacts repositories create finn-agent-images \
    --repository-format=docker \
    --location=us-central1 \
    --project=$PROJECT_ID \
    --description="Repository for finn-agent images"

Tiếp theo, hãy tạo hình ảnh Docker cho Agent bằng Cloud Build. Chạy lệnh này từ thư mục gốc của dự án đã sao chép (sports-agent-adk-mcp-alloydb/):

gcloud builds submit src/backend/ --tag us-central1-docker.pkg.dev/$PROJECT_ID/finn-agent-images/finn-agent

Bây giờ, hãy triển khai dịch vụ Agent. Lệnh này sẽ tạo một dịch vụ Cloud Run, kéo hình ảnh từ Artifact Registry và định cấu hình các biến môi trường

gcloud run deploy finn-agent \
    --image us-central1-docker.pkg.dev/$PROJECT_ID/finn-agent-images/finn-agent \
    --platform managed \
    --allow-unauthenticated \
    --region us-central1 \
    --project $PROJECT_ID --set-env-vars="GOOGLE_CLOUD_PROJECT=$PROJECT_ID,GOOGLE_CLOUD_LOCATION=us-central1,GOOGLE_GENAI_USE_VERTEXAI=TRUE"

Lưu ý: Chúng tôi đang thiết lập các biến môi trường một cách linh hoạt, bao gồm cả GOOGLE_CLOUD_PROJECT (bằng cách sử dụng biến shell $PROJECT_ID)

Bạn sẽ nhận được kết quả tương tự như sau, cho biết rằng bạn đã triển khai thành công Agent:

Deploying container to Cloud Run service [finn-agent] in project [sports-store-agent-ai] region [us-central1]
OK Deploying... Done.
  OK Creating Revision...
  OK Routing traffic...
  OK Setting IAM Policy...
Done.
Service [finn-agent] revision [finn-agent-00005-476] has been deployed and is serving 100 percent of traffic.
Service URL: https://finn-agent-359225437509.us-central1.run.app

Cuối cùng, hãy kiểm thử nhân viên hỗ trợ bằng cách thực thi lệnh curl này từ Cửa sổ dòng lệnh Cloud Shell:

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"message":"Hello"}' \
  https://finn-agent-[YOUR_PROJECT_NUMBER].us-central1.run.app/chat

Bạn sẽ nhận được kết quả tương tự như sau:

"Xin chào! Tôi là Finn, trợ lý mua sắm thể thao dựa trên AI. Tôi có thể giúp bạn tìm các sản phẩm, dụng cụ và thiết bị thể thao. Hôm nay tôi có thể hỗ trợ gì cho bạn?"

Đến đây, bạn đã xác thực thành công việc triển khai AlloyDB, MCP Toolbox và Agent được tạo bằng ADK.

8. Triển khai Giao diện người dùng

Trong phần này, bạn sẽ triển khai giao diện người dùng đàm thoại cho trợ lý AI của mình trên Cloud Run. Giao diện người dùng này được tạo bằng React và JavaScript.

Trước khi triển khai, bạn cần cập nhật mã nguồn của giao diện người dùng bằng URL của Nhân viên hỗ trợ đã triển khai và Mã ứng dụng OAuth.

Sử dụng Cloud Shell Editor, chuyển đến sports-agent-adk-mcp-alloydb/src/frontend/src/pages/ rồi mở tệp Home.jsx. Bạn sẽ cần cập nhật phần giữ chỗ cho URL Dịch vụ Cloud Run của Nhân viên hỗ trợ. Sau đó, hãy thay thế bằng URL Dịch vụ Cloud Run của Agent từ bước trước (ví dụ: https://finn-agent-[YOUR_PROJECT_NUMBER].us-central1.run.app).

Tiếp theo, hãy chuyển đến sports-agent-adk-mcp-alloydb/src/frontend/src/components/ rồi mở tệp GoogleSignInButton.jsx. Bạn sẽ cập nhật tệp này bằng Mã ứng dụng OAuth mà bạn đã nhận được trong phần "Thiết lập dịch vụ uỷ quyền":

Triển khai giao diện người dùng trên Cloud Run

Giờ đây, ứng dụng giao diện người dùng của bạn đã được định cấu hình, bạn có thể triển khai ứng dụng đó lên Cloud Run.

Chạy lệnh sau trong một Cửa sổ dòng lệnh Cloud Shell từ thư mục gốc (sports-agent-adk-mcp-alloydb/) để tạo một kho lưu trữ Docker trong Artifact Registry cho các hình ảnh giao diện người dùng của bạn.

gcloud artifacts repositories create finn-frontend-images \
    --repository-format=docker \
    --location=us-central1 \
    --project=$PROJECT_ID \
    --description="Repository for finn-frontend images"

Tiếp theo, hãy tạo hình ảnh Docker cho ứng dụng giao diện người dùng bằng Cloud Build. Chạy lệnh này từ thư mục gốc của dự án:

gcloud builds submit src/frontend/ --tag us-central1-docker.pkg.dev/$PROJECT_ID/finn-frontend-images/finn-frontend

Cuối cùng, chúng ta sẽ triển khai giao diện người dùng trên Cloud Run bằng lệnh sau:

gcloud run deploy finn-frontend \
    --image us-central1-docker.pkg.dev/$PROJECT_ID/finn-frontend-images/finn-frontend \
    --platform managed \
    --allow-unauthenticated \
    --region us-central1 \
    --project $PROJECT_ID

Bạn sẽ nhận được kết quả tương tự như sau, cho biết quá trình triển khai giao diện người dùng đã thành công:

Deploying container to Cloud Run service [finn-frontend] in project [sport-store-agent-ai] region [us-central1]
OK Deploying... Done.
  OK Creating Revision...
  OK Routing traffic...
  OK Setting IAM Policy...
Done.
Service [finn-frontend] revision [finn-frontend-00002-mwc] has been deployed and is serving 100 percent of traffic.
Service URL: https://finn-frontend-535807247199.us-central1.run.app

Mở trình duyệt web và sử dụng URL dịch vụ ở bước trước để mở ứng dụng mới triển khai, được hỗ trợ bởi AI Agent!

9. Chạy Agent của chúng tôi

Trợ lý AI Finn của Cửa hàng đồ thể thao hiện đã được triển khai đầy đủ và sẵn sàng hỗ trợ bạn mua hàng!

Mở trình duyệt web rồi chuyển đến URL dịch vụ của ứng dụng giao diện người dùng ở bước trước. URL có định dạng như sau: https://finn-frontend-[YOUR_PROJECT_NUMBER].us-central1.run.app

Sau khi giao diện người dùng tải xong, hãy nhấp vào nút trên cùng bên phải (thường có nhãn "Đăng nhập" hoặc một lời nhắc tương tự) để xác thực bằng thông tin đăng nhập Google của bạn. Thao tác này sẽ tận dụng cấu hình OAuth mà bạn đã thiết lập trước đó.

Sau khi xác thực thành công, bạn có thể tương tác với Finn! Nhấp vào nút "Mua sắm ngay" để bắt đầu trải nghiệm mua sắm đàm thoại.

Sử dụng tập lệnh sau để kiểm thử các chức năng của AI Agent. Sao chép và dán từng câu lệnh này vào giao diện trò chuyện:

Chào Finn!
Tôi đang tìm giày chạy bộ cho đường mòn siêu dài
Cho tôi biết thêm chi tiết về Ultra Glide
Thêm Ultra Glide, cỡ 40, màu Đỏ/Xám vào danh sách mua sắm của tôi
Cho tôi xem danh sách mua sắm của tôi
Tìm cửa hàng gần tôi
Vui lòng đặt hàng theo danh sách mua sắm của tôi cho cửa hàng Sports Diagonal Mar
Kiểm tra trạng thái đơn đặt hàng
Vui lòng liệt kê các phương thức giao hàng cho cửa hàng Sports Diagonal Mar
Cập nhật phương thức giao hàng thành Giao hàng nhanh cho đơn đặt hàng [YOUR_ORDER_NUMBER]
Kiểm tra trạng thái đơn đặt hàng
Cảm ơn Finn!

Để xem minh hoạ trực quan về Finn Agent đã triển khai và các chức năng của công cụ này, hãy xem video bên dưới:

Bản minh hoạ Trợ lý AI dành cho người đại diện thể thao dựa trên AlloyDB

10. Kết quả

Sau khi thực thi tập lệnh trước đó, bạn đã xác thực thành công toàn bộ quá trình tích hợp ADK Agent, kết nối với AlloyDB và sử dụng MCP Toolbox. Phần này nêu bật các chức năng cốt lõi mà bạn đã triển khai.

Dịch vụ uỷ quyền

MCP Toolbox for Databases cung cấp khả năng liên kết một Dịch vụ uỷ quyền (cụ thể là Đăng nhập bằng Google trong lớp học lập trình này) để xác thực người dùng trong ứng dụng của bạn. Với MCP Toolbox, Mã ứng dụng OAuth của bạn được dùng để xác thực danh tính người dùng khi một công cụ được gọi.

Cơ chế xác thực mạnh mẽ này mang đến một giải pháp tuyệt vời để bảo vệ ứng dụng dựa trên tác nhân của bạn khỏi tấn công bằng cách chèn câu lệnh, một loại tấn công trong đó đầu vào độc hại cố gắng vượt qua hoặc thao túng hành vi dự kiến của tác nhân. Để biết thêm thông tin chi tiết, bạn có thể tham khảo bài viết trên Wikipedia về Tấn công bằng cách chèn câu lệnh

Trong ứng dụng này, kỹ thuật này được sử dụng khi người dùng yêu cầu "kiểm tra trạng thái đơn đặt hàng của chúng tôi" hoặc "hiện danh sách mua sắm của tôi". Đại lý được thiết kế để chỉ hiển thị những đơn đặt hàng thuộc về người dùng đã xác thực, ngăn chặn hành vi truy cập trái phép vào thông tin đơn đặt hàng.

Tìm kiếm vectơ

Ứng dụng dựa trên tác nhân của bạn tận dụng AlloyDB cho PostgreSQL để cung cấp các khả năng truy vấn nâng cao, đặc biệt là thông qua tính năng tìm kiếm vectơ. AlloyDB hỗ trợ việc tạo mục nhúng trực tuyến ngay trong cơ sở dữ liệu bằng cách sử dụng các hàm SQL.

Tính năng mạnh mẽ này cho phép tác nhân dịch nội dung đầu vào bằng ngôn ngữ tự nhiên của người dùng thành một biểu diễn nhúng bằng số. Sau đó, mô hình này có thể thực hiện tìm kiếm tương tự dựa trên các vectơ nhúng này trong danh mục sản phẩm của bạn (hoặc dữ liệu liên quan khác), từ đó mang lại kết quả tìm kiếm có mức độ liên quan cao.

Trong ứng dụng của bạn, bạn sẽ trải nghiệm kỹ thuật này khi hỏi Finn: "Tôi đang tìm giày chạy bộ cho một đường chạy siêu dài".

Khả năng không gian địa lý (PostGis)

AlloyDB cho PostgreSQL duy trì khả năng tương thích 100% với các tính năng tiêu chuẩn của PostgreSQL. Trong ứng dụng này, chúng tôi sử dụng tiện ích PostgreSQL phổ biến PostGIS để cung cấp các chức năng vị trí không gian địa lý cho tác nhân.

Khi bạn yêu cầu tác nhân: "Tìm cửa hàng gần tôi", tác nhân sẽ thực thi một công cụ tận dụng chỉ mục PostGIS trong cơ sở dữ liệu để xác định hiệu quả các cửa hàng gần nhất với vị trí được chỉ định hoặc suy luận của người dùng.

11. (Không bắt buộc) Kiểm thử tính năng AI tự nhiên của AlloyDB để chuyển đổi ngôn ngữ sang SQL

Phần này giới thiệu một tính năng nâng cao, trước khi phát hành công khai của AlloyDB cho PostgreSQL: Ngôn ngữ tự nhiên sang SQL. Tính năng này cho phép bạn tạo truy vấn SQL trực tiếp từ câu lệnh bằng ngôn ngữ tự nhiên, tận dụng sức mạnh của AI trong cơ sở dữ liệu.

Lưu ý quan trọng: Vì đây là một tính năng Pre-GA, nên bạn cần đăng ký và được cấp quyền truy cập cho Dự án trên Google Cloud, Cụm AlloyDB và cơ sở dữ liệu của mình.

Đăng ký quyền truy cập: Vui lòng điền vào biểu mẫu này để yêu cầu cấp quyền truy cập cho dự án của bạn
Tài liệu: Bạn có thể tìm hiểu thêm về cách tận dụng Ngôn ngữ tự nhiên của AI AlloyDB để chuyển đổi thành SQL trong tài liệu chính thức

Sau khi bạn đăng ký và xác nhận quyền truy cập cho dự án của mình, hãy tiếp tục thực hiện các bước sau trong AlloyDB Studio.

Đăng nhập vào AlloyDB bằng thông tin đăng nhập mà bạn đã tạo khi tạo cụm:

Tên người dùng: "postgres"
Cơ sở dữ liệu: "store"
Mật khẩu: "alloydb"

1- Tạo tiện ích alloydb_ai_nl. Tiện ích này cung cấp các chức năng cần thiết cho các tính năng Ngôn ngữ tự nhiên của AI trên AlloyDB.

CREATE EXTENSION alloydb_ai_nl cascade;

2. Tạo cấu hình cho ứng dụng của bạn. Cấu hình xác định ngữ cảnh giản đồ mà mô hình AI sẽ dùng để hiểu cơ sở dữ liệu của bạn.

SELECT
 alloydb_ai_nl.g_create_configuration(
   'finn_app_config'        -- configuration_id
 );

3 – Đăng ký giản đồ / bảng bằng cấu hình. Thêm các bảng và giản đồ cụ thể mà tác nhân của ứng dụng sẽ tương tác vào cấu hình.

SELECT alloydb_ai_nl.g_manage_configuration(
   operation => 'register_table_view',
   configuration_id_in => 'finn_app_config',
   table_views_in=>'{public.products, public.products_variants, public.orders, public.orders_items, public.users, public.inventory, public.stores}'
);

4. Tạo ngữ cảnh cho giản đồ / bảng. Bước này xử lý các bảng đã đăng ký để tạo ngữ cảnh cần thiết cho mô hình AI. Quá trình này có thể mất khoảng 2 đến 3 phút.

SELECT alloydb_ai_nl.generate_schema_context(
 'finn_app_config',
 TRUE
);

5. Kiểm tra ngữ cảnh được tạo tự động cho các bảng và cột cụ thể (không bắt buộc). Bạn có thể kiểm tra ngữ cảnh được tạo để hiểu cách mô hình AI diễn giải giản đồ của bạn.

SELECT object_context
FROM alloydb_ai_nl.generated_schema_context_view
WHERE schema_object = 'public.inventory';


SELECT object_context
FROM alloydb_ai_nl.generated_schema_context_view
WHERE schema_object = 'public.products.name';


SELECT object_context
FROM alloydb_ai_nl.generated_schema_context_view
WHERE schema_object = 'public.products.popularity_score';

Bạn sẽ tìm thấy một công cụ có tên là "check-inventory-by-store-brand-category" trong "tools.yaml" của Agent. Công cụ này sử dụng tính năng Ngôn ngữ tự nhiên sang SQL của AlloyDB:

Mở một trình duyệt web rồi dùng URL dịch vụ để mở ứng dụng: "https://finn-frontend-[YOUR_PROJECT_NUMBER].us-central1.run.app"

Sau đó, hãy sử dụng tập lệnh sau trong giao diện trò chuyện để kiểm thử tính năng mới này:

Chào Finn!
Tổng số lượng sản phẩm thuộc danh mục Chạy bộ của Salomon có tại cửa hàng "Sports Diagonal Mar" là bao nhiêu?

Để xem truy vấn SQL thực tế mà AlloyDB AI đã tạo từ câu lệnh sử dụng ngôn ngữ tự nhiên của bạn, hãy quay lại AlloyDB Studio rồi thực thi truy vấn sau:

SELECT
   alloydb_ai_nl.get_sql(
       'finn_app_config',
       'What is the total quantity of category Running products of Salomon in stock at the "Sports Diagonal Mar" store?'
   ) ->> 'sql';

Thao tác này sẽ hiển thị câu lệnh SQL do AI AlloyDB tạo.

12. Dọn dẹp

Để tránh bị tính phí vào tài khoản Google Cloud cho các tài nguyên được dùng trong phòng thí nghiệm này, hãy làm theo các bước sau:

Trong Google Cloud Console, hãy chuyển đến trang Quản lý tài nguyên.
Trong danh sách dự án, hãy chọn dự án mà bạn muốn xoá, rồi nhấp vào Xoá.
Trong hộp thoại, hãy nhập mã dự án rồi nhấp vào Tắt để xoá dự án.

13. Xin chúc mừng

Xin chúc mừng! Bạn đã tạo thành công một ứng dụng AI dựa trên dữ liệu bằng ADK, MCP Toolbox for Databases và AlloyDB for PostgreSQL

Để biết thêm thông tin, hãy tham khảo tài liệu về sản phẩm: Bộ công cụ phát triển tác nhân, Bộ công cụ MCP cho cơ sở dữ liệu và AlloyDB cho PostgreSQL