Cơ sở dữ liệu như một công cụ: RAG dựa trên tác nhân bằng ADK, MCP Toolbox và Cloud SQL

1. Giới thiệu

Độ hữu ích của các tác nhân AI phụ thuộc vào dữ liệu mà chúng có thể truy cập. Hầu hết dữ liệu thực tế đều nằm trong cơ sở dữ liệu và việc kết nối các tác nhân với cơ sở dữ liệu thường có nghĩa là bạn phải viết quy trình quản lý kết nối, logic truy vấn và nhúng trong mã tác nhân của mình. Mọi tác nhân cần truy cập vào cơ sở dữ liệu đều lặp lại công việc này và mọi thay đổi về truy vấn đều yêu cầu triển khai lại tác nhân.

Lớp học lập trình này trình bày một phương pháp khác. Bạn khai báo các công cụ cơ sở dữ liệu của mình trong một tệp YAML (truy vấn SQL chuẩn, tìm kiếm tương tự theo vectơ, thậm chí là tạo mục nhúng tự động) và MCP Toolbox for Databases sẽ xử lý tất cả các thao tác cơ sở dữ liệu dưới dạng một máy chủ MCP. Mã tác nhân của bạn vẫn ở mức tối thiểu: tải các công cụ, để Gemini quyết định gọi công cụ nào.

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

Trợ lý thông minh cho bảng tin tuyển dụng cho "TechJobs" – một tác nhân ADK dựa trên Gemini, giúp nhà phát triển duyệt xem danh sách việc làm trong ngành công nghệ bằng các bộ lọc tiêu chuẩn (vai trò, bộ công cụ công nghệ) và khám phá việc làm thông qua nội dung mô tả bằng ngôn ngữ tự nhiên như "Tôi muốn làm việc từ xa trong lĩnh vực chatbot AI". Tác nhân đọc và ghi vào cơ sở dữ liệu Cloud SQL PostgreSQL hoàn toàn thông qua MCP Toolbox for Databases. Công cụ này xử lý mọi hoạt động truy cập vào cơ sở dữ liệu, bao gồm cả việc tự động tạo mục nhúng để tìm kiếm vectơ. Đến cuối cùng, cả Hộp công cụ và tác nhân đều chạy trên Cloud Run.

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

Cách MCP (Giao thức ngữ cảnh mô hình) chuẩn hoá quyền truy cập vào công cụ cho các tác nhân AI và cách MCP Toolbox for Databases áp dụng điều này cho các hoạt động trên cơ sở dữ liệu
Thiết lập MCP Toolbox for Databases làm phần mềm trung gian giữa một tác nhân ADK và Cloud SQL PostgreSQL
Xác định các công cụ cơ sở dữ liệu một cách khai báo trong tools.yaml – không có mã cơ sở dữ liệu trong tác nhân của bạn
Tạo một tác nhân ADK tải các công cụ từ một máy chủ Toolbox đang chạy bằng cách sử dụng ToolboxToolset
Tạo các mục nhúng vectơ bằng hàm embedding() tích hợp của Cloud SQL và bật tính năng tìm kiếm ngữ nghĩa bằng pgvector
Sử dụng tính năng valueFromParam để tự động nhập vectơ trong các thao tác ghi
Triển khai cả máy chủ Toolbox và tác nhân ADK lên Cloud Run

Điều kiện tiên quyết

Tài khoản Google Cloud có tài khoản thanh toán dùng thử
Hiểu biết cơ bản về Python và SQL
Không cần có kinh nghiệm sử dụng ADK, MCP Toolbox hoặc pgvector

2. Thiết lập môi trường

LƯU Ý QUAN TRỌNG:

Hướng dẫn này yêu cầu bạn phải có một Dự án trên Google Cloud có tài khoản thanh toán đang hoạt động. Nếu bạn chưa có tài khoản thanh toán, vui lòng làm theo các bước bên dưới để tạo một tài khoản thanh toán dùng thử có thể dùng cho hướng dẫn này:

Mở cửa sổ ẩn danh
Nếu tham gia một buổi hội thảo, bạn thường sẽ nhận được URL của cổng đổi quà trong buổi hội thảo đó. Nếu không, bạn có thể truy cập vào cổng đổi quà của tài khoản thanh toán dùng thử này
Đăng nhập bằng tài khoản Gmail cá nhân của bạn ( Google Workspace / các email khác sẽ không hoạt động! )
Làm theo hướng dẫn từng bước về cách sử dụng để tạo thành công một dự án mới trên Google Cloud được liên kết với tài khoản thanh toán dùng thử mà bạn đã yêu cầu trong hướng dẫn này

Bước này chuẩn bị môi trường Cloud Shell, định cấu hình dự án Google Cloud và sao chép kho lưu trữ tham chiếu.

Mở Cloud Shell

Mở Cloud Shell trong trình duyệt. Cloud Shell cung cấp một môi trường được định cấu hình sẵn với tất cả các công cụ bạn cần cho lớp học lập trình này. Nhấp vào Uỷ quyền khi được nhắc

Sau đó, nhấp vào "View" (Xem) -> "Terminal" (Thiết bị đầu cuối) để mở thiết bị đầu cuối.Giao diện của bạn sẽ trông tương tự như thế này

Đây sẽ là giao diện chính của chúng ta, IDE ở trên cùng, thiết bị đầu cuối ở dưới cùng

Thiết lập thư mục làm việc

Tạo thư mục làm việc. Tất cả mã bạn viết trong lớp học lập trình này đều nằm ở đây:

mkdir -p ~/build-agent-adk-toolbox-cloudsql
cloudshell workspace ~/build-agent-adk-toolbox-cloudsql && cd ~/build-agent-adk-toolbox-cloudsql

Thiết lập dự án của bạn trên Google Cloud

Tạo tệp .env bằng các biến vị trí:

# For Vertex AI / Gemini API calls
echo "GOOGLE_CLOUD_LOCATION=global" > .env
# For Cloud SQL, Cloud Run, Artifact Registry
echo "REGION=us-central1" >> .env

Tải tập lệnh thiết lập dự án xuống thư mục làm việc của bạn:

curl -sL https://raw.githubusercontent.com/alphinside/cloud-trial-project-setup/main/setup_verify_trial_project.sh -o setup_verify_trial_project.sh

Chạy tập lệnh. Lệnh này xác minh tài khoản thanh toán dùng thử của bạn, tạo một dự án mới (hoặc xác thực một dự án hiện có), lưu mã dự án vào một tệp .env trong thư mục hiện tại và đặt dự án đang hoạt động trong gcloud.

bash setup_verify_trial_project.sh && source .env

Tập lệnh sẽ:

Xác minh rằng bạn có một tài khoản thanh toán dùng thử đang hoạt động
Kiểm tra xem có dự án nào trong .env hay không (nếu có)
Tạo dự án mới hoặc sử dụng lại dự án hiện có
Liên kết tài khoản thanh toán dùng thử với dự án của bạn
Lưu mã dự án vào .env
Đặt dự án làm dự án gcloud đang hoạt động

Xác minh rằng dự án được thiết lập đúng cách bằng cách kiểm tra văn bản màu vàng bên cạnh thư mục làm việc của bạn trong dấu nhắc của thiết bị đầu cuối Cloud Shell. Thẻ này sẽ hiển thị mã dự án của bạn.

Nếu phiên Cloud Shell của bạn được đặt lại vào bất kỳ thời điểm nào trong lớp học lập trình này, hãy chuyển về thư mục làm việc rồi chạy lại bash setup_verify_trial_project.sh && source .env để khôi phục cấu hình dự án. Xác nhận rằng văn bản mã dự án màu vàng xuất hiện lại trong lời nhắc của thiết bị đầu cuối.

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

Vertex AI API (aiplatform.googleapis.com) – tác nhân của bạn sử dụng các mô hình Gemini và Toolbox sử dụng API nhúng để tìm kiếm vectơ.
Cloud SQL Admin API (sqladmin.googleapis.com) – bạn cung cấp và quản lý một phiên bản PostgreSQL.
Compute Engine API (compute.googleapis.com) – bắt buộc để tạo phiên bản Cloud SQL.
Cloud Run, Cloud Build, Artifact Registry – được dùng trong bước triển khai sau này trong lớp học lập trình này

3. Tạo thực thể cơ sở dữ liệu

Bước này thiết lập quá trình tạo phiên bản Cloud SQL ở chế độ nền – quá trình này sẽ cung cấp trong khi bạn tiếp tục hướng dẫn.

Bắt đầu tạo phiên bản

Thêm mật khẩu cơ sở dữ liệu vào tệp .env rồi tải lại tệp đó:

echo "DB_PASSWORD=techjobs-pwd-2025" >> .env
source .env

Bắt đầu tạo phiên bản Cloud SQL. Thao tác này chạy ở chế độ nền để bạn có thể tiếp tục làm việc:

gcloud sql instances create jobs-instance \
  --database-version=POSTGRES_17 \
  --tier=db-custom-1-3840 \
  --edition=ENTERPRISE \
  --region=$REGION \
  --root-password=$DB_PASSWORD \
  --enable-google-ml-integration \
  --database-flags cloudsql.enable_google_ml_integration=on \
  --quiet &

db-custom-1-3840 là cấp Cloud SQL nhỏ nhất có lõi chuyên dụng (1 vCPU, RAM 3,75 GB) trong phiên bản ENTERPRISE. Bạn có thể đọc thêm thông tin chi tiết tại đây. Bạn cần có một lõi chuyên dụng để tích hợp Vertex AI ML – các cấp lõi dùng chung (db-f1-micro, db-g1-small) không hỗ trợ tính năng này.
--root-password đặt mật khẩu cho người dùng postgres mặc định.
--enable-google-ml-integration cho phép tích hợp sẵn Cloud SQL với Vertex AI, giúp bạn gọi các mô hình nhúng trực tiếp từ SQL bằng hàm embedding().
& chạy lệnh ở chế độ nền.

Thao tác này sẽ chạy ở chế độ nền, tiếp theo, hãy tải tệp nhị phân MCP Toolbox xuống. Bạn có thể thực hiện việc này trong cùng một thiết bị đầu cuối

Tải tệp nhị phân của Hộp công cụ xuống

Chúng ta sẽ sử dụng MCP Toolbox trong hướng dẫn này. May mắn là công cụ này đi kèm với một tệp nhị phân được tạo sẵn và sẵn sàng sử dụng trong môi trường Linux. Hãy tải tệp này xuống ở chế độ nền vì quá trình này sẽ mất khá nhiều thời gian

cd ~/build-agent-adk-toolbox-cloudsql
curl -O https://storage.googleapis.com/genai-toolbox/v0.27.0/linux/amd64/toolbox &

Cho phép quy trình này chạy trong thẻ hiện tại (chúng tôi đã chạy quy trình này ở chế độ nền, tuy nhiên, kết quả vẫn sẽ hiển thị). Hãy mở một thẻ dòng lệnh mới trong Cloud Shell (nhấp vào biểu tượng +) để chúng ta có thể tập trung hơn.

Chuyển đến thư mục làm việc của bạn một lần nữa và kích hoạt dự án bằng tập lệnh thiết lập trước đó.

cd ~/build-agent-adk-toolbox-cloudsql
bash setup_verify_trial_project.sh && source .env

Bước này thiết lập dự án Python, cài đặt các phần phụ thuộc và tạo cấu trúc thư mục tác nhân ADK

4. Khởi chạy Dự án tác nhân

Thiết lập dự án Python

uv là một trình quản lý dự án và gói Python nhanh chóng được viết bằng Rust ( tài liệu uv ). Lớp học lập trình này sử dụng uv để tăng tốc độ và đơn giản hoá.

Khởi chạy một dự án Python và thêm các phần phụ thuộc bắt buộc:

uv init
uv add google-adk==1.25.0 toolbox-adk==0.6.0

google-adk – Bộ công cụ phát triển tác nhân của Google, bao gồm cả Gemini SDK
toolbox-adk – Tích hợp ADK cho MCP Toolbox for Databases.

Tạo cấu trúc thư mục của tác nhân

ADK yêu cầu một bố cục thư mục cụ thể: một thư mục được đặt tên theo tác nhân của bạn, chứa __init__.py, agent.py và .env. Để giúp giải quyết vấn đề này, công cụ này có sẵn lệnh để nhanh chóng thiết lập cấu trúc:

uv run adk create jobs_agent \
    --model gemini-2.5-flash \
    --project ${GOOGLE_CLOUD_PROJECT} \
    --region ${GOOGLE_CLOUD_LOCATION}

Thư mục của bạn hiện sẽ có dạng như sau:

build-agent-adk-toolbox-cloudsql/
├── jobs_agent/
│   ├── __init__.py
│   ├── agent.py
│   └── .env
├── pyproject.toml
├── .env              (project setup — already exists)
└── .venv/

5. Tạo cơ sở dữ liệu trang thông tin việc làm

Bước này ghi dữ liệu ban đầu, chờ phiên bản Cloud SQL hoàn tất việc cung cấp và tải bảng jobs với 15 tin tuyển dụng và phần nhúng nội dung mô tả của các tin tuyển dụng đó

Viết SQL ban đầu

Chúng ta sẽ tạo một tệp có tên là seed.sql trong Cloud Shell Editor với nội dung liệt kê các công việc. Thao tác này sẽ tạo bảng jobs có chế độ hỗ trợ pgvector và chèn 15 tin tuyển dụng tại các công ty công nghệ.

Trước tiên, hãy tạo tệp seed.sql bằng lệnh sau:

cloudshell edit seed.sql

Sau đó, sao chép các tập lệnh này vào tệp

-- seed.sql
-- DISCLAIMER: These job listings are entirely fictional and created for tutorial
-- purposes only. Company names are used for illustrative context — the positions,
-- salaries, and descriptions do not reflect real openings.

CREATE EXTENSION IF NOT EXISTS google_ml_integration;
CREATE EXTENSION IF NOT EXISTS vector;

CREATE TABLE IF NOT EXISTS jobs (
    id SERIAL PRIMARY KEY,
    title VARCHAR NOT NULL,
    company VARCHAR NOT NULL,
    role VARCHAR NOT NULL,
    tech_stack VARCHAR NOT NULL,
    salary_range VARCHAR NOT NULL,
    location VARCHAR NOT NULL,
    openings INTEGER NOT NULL,
    description TEXT NOT NULL,
    description_embedding vector(3072)
);

INSERT INTO jobs (title, company, role, tech_stack, salary_range, location, openings, description) VALUES
('Senior Backend Engineer', 'Stripe', 'Backend', 'Go, PostgreSQL, gRPC, Kubernetes', '$180-250K/year', 'San Francisco, Hybrid', 3,
 'Design and build high-throughput microservices powering payment infrastructure for millions of businesses. Optimize Go services for sub-100ms latency at scale, work with PostgreSQL and Redis for data persistence, and deploy on Kubernetes clusters handling billions of API calls.'),

('Machine Learning Engineer', 'Spotify', 'Data/AI', 'Python, TensorFlow, BigQuery, Vertex AI', '$170-230K/year', 'Stockholm, Remote', 2,
 'Build and deploy ML models for music recommendation and personalization systems serving hundreds of millions of listeners. Design feature pipelines in BigQuery, train models using distributed computing, and serve predictions through real-time APIs processing thousands of requests per second.'),

('Frontend Engineer', 'Vercel', 'Frontend', 'React, TypeScript, Next.js', '$140-190K/year', 'Remote', 4,
 'Build developer-facing dashboard interfaces and deployment tools used by millions of developers worldwide. Create responsive, accessible React components for project management, analytics, and real-time deployment monitoring with a focus on developer experience.'),

('DevOps Engineer', 'Datadog', 'DevOps', 'Terraform, GCP, Docker, Kubernetes, ArgoCD', '$160-220K/year', 'New York, Hybrid', 2,
 'Manage cloud infrastructure powering an observability platform used by thousands of engineering teams. Automate deployment pipelines with ArgoCD, manage multi-cloud Kubernetes clusters, and implement infrastructure-as-code with Terraform across production environments.'),

('Mobile Engineer (Android)', 'Grab', 'Mobile', 'Kotlin, Jetpack Compose, GraphQL', '$120-170K/year', 'Singapore, Hybrid', 3,
 'Develop features for a super-app serving millions of users across Southeast Asia. Build modern Android UIs with Jetpack Compose, integrate GraphQL APIs, and optimize app performance for diverse device capabilities and network conditions.'),

('Data Engineer', 'Airbnb', 'Data', 'Python, Apache Spark, Airflow, BigQuery', '$160-210K/year', 'San Francisco, Hybrid', 2,
 'Build data pipelines that process booking, search, and pricing data for a global travel marketplace. Design ETL workflows with Apache Spark and Airflow, maintain data warehouses in BigQuery, and ensure data quality for analytics and machine learning teams.'),

('Full Stack Engineer', 'Revolut', 'Full Stack', 'TypeScript, Node.js, React, PostgreSQL', '$130-180K/year', 'London, Remote', 5,
 'Build the next generation of financial products making banking accessible to millions of users across 35 countries. Develop real-time trading interfaces with React and WebSockets, build Node.js APIs handling market data streams, and design PostgreSQL schemas for financial transactions.'),

('Site Reliability Engineer', 'Cloudflare', 'SRE', 'Go, Prometheus, Grafana, GCP, Terraform', '$170-230K/year', 'Austin, Hybrid', 2,
 'Ensure 99.99% uptime for a global network handling millions of requests per second. Define SLOs, build monitoring dashboards with Prometheus and Grafana, manage incident response, and automate infrastructure scaling across 300+ data centers worldwide.'),

('Cloud Architect', 'Google Cloud', 'Cloud', 'GCP, Terraform, Kubernetes, Python', '$200-280K/year', 'Seattle, Hybrid', 1,
 'Help enterprises modernize their infrastructure on Google Cloud. Design multi-region architectures, lead migration projects from on-premises to GKE, and build reference implementations using Terraform and Cloud Foundation Toolkit.'),

('Backend Engineer (Payments)', 'Square', 'Backend', 'Java, Spring Boot, PostgreSQL, Kafka', '$160-220K/year', 'San Francisco, Hybrid', 3,
 'Build payment processing systems handling millions of transactions for businesses of all sizes. Design event-driven architectures using Kafka, implement idempotent payment flows with Spring Boot, and ensure PCI-DSS compliance across all services.'),

('AI Engineer', 'Hugging Face', 'Data/AI', 'Python, LangChain, Vertex AI, FastAPI, PostgreSQL', '$150-210K/year', 'Paris, Remote', 2,
 'Build AI-powered tools for the largest open-source ML community. Develop RAG pipelines that index and search model documentation, create conversational agents using LangChain, and deploy AI services with FastAPI on cloud infrastructure.'),

('Platform Engineer', 'Coinbase', 'Platform', 'Rust, Kubernetes, AWS, Terraform', '$180-250K/year', 'Remote', 0,
 'Build the infrastructure platform for a leading cryptocurrency exchange. Develop high-performance matching engines in Rust, manage Kubernetes clusters for microservices, and design CI/CD pipelines that enable rapid feature deployment with zero downtime.'),

('QA Automation Engineer', 'Shopify', 'QA', 'Python, Selenium, Cypress, Jenkins', '$110-160K/year', 'Toronto, Hybrid', 3,
 'Design and maintain automated test suites for a commerce platform powering millions of merchants. Build end-to-end test frameworks with Cypress and Selenium, integrate tests into Jenkins CI pipelines, and establish quality gates that prevent regressions in checkout and payment flows.'),

('Security Engineer', 'CrowdStrike', 'Security', 'Python, SIEM, Kubernetes, Penetration Testing', '$170-240K/year', 'Austin, On-site', 1,
 'Protect enterprise customers from cyber threats on a leading endpoint security platform. Conduct penetration testing, design security monitoring with SIEM tools, implement zero-trust networking in Kubernetes environments, and lead incident response for security events.'),

('Product Engineer', 'GitLab', 'Full Stack', 'Go, React, PostgreSQL, Redis, GCP', '$140-200K/year', 'Remote', 4,
 'Own features end-to-end for an all-in-one DevSecOps platform used by millions of developers. Build Go microservices for CI/CD pipelines, create React frontends for code review and project management, and collaborate with product managers to iterate on user-facing features using data-driven development.');

Tập lệnh ban đầu cài đặt 2 tiện ích PostgreSQL:

google_ml_integration – cung cấp hàm SQL embedding(), gọi các mô hình nhúng Vertex AI trực tiếp từ SQL. Đây là một tiện ích ở cấp cơ sở dữ liệu giúp các hàm ML có sẵn trong jobs_db. Cờ cấp phiên bản (--enable-google-ml-integration) mà bạn đặt trong quá trình tạo phiên bản cho phép VM Cloud SQL truy cập vào Vertex AI – tiện ích này cung cấp các hàm SQL trong cơ sở dữ liệu cụ thể này.
vector (pgvector) – thêm kiểu dữ liệu vector và các toán tử khoảng cách để lưu trữ và truy vấn các mục nhúng.

Cột description_embedding là vector(3072) – một cột pgvector lưu trữ các vectơ 3072 chiều. Hiện tại, giá trị này là NULL; bạn sẽ tạo và điền các mục nhúng ở bước tiếp theo bằng hàm embedding().

Hoàn tất quá trình thiết lập cơ sở dữ liệu

Phiên bản Cloud SQL mà bạn đã bắt đầu tạo ở bước trước có thể vẫn đang chạy và chưa hoàn tất. Xác minh rằng phiên bản đã sẵn sàng:

gcloud sql instances describe jobs-instance --format="value(state)"

Bạn sẽ thấy kết quả sau

RUNNABLE

Tiếp theo, cấp cho tài khoản dịch vụ của phiên bản Cloud SQL quyền gọi Vertex AI. Đây là yêu cầu bắt buộc đối với hàm embedding() tích hợp sẵn mà bạn sẽ dùng trong bước tiếp theo:

SERVICE_ACCOUNT=$(gcloud sql instances describe jobs-instance --format="value(serviceAccountEmailAddress)")

gcloud projects add-iam-policy-binding $GOOGLE_CLOUD_PROJECT \
  --member="serviceAccount:$SERVICE_ACCOUNT" \
  --role="roles/aiplatform.user" \
  --quiet

Sau đó, hãy tạo một cơ sở dữ liệu riêng cho danh sách việc làm:

gcloud sql databases create jobs_db --instance=jobs-instance

Bạn sẽ thấy kết quả xác nhận rằng cơ sở dữ liệu đã được tạo:

Creating Cloud SQL database...done.                                                                         
Created database [jobs_db].
instance: jobs-instance
name: jobs_db
project: workshop-xxxxxxx

Kết nối và gieo hạt cơ sở dữ liệu

Khởi động Cloud SQL Auth Proxy (cloud-sql-proxy được cài đặt sẵn trong Cloud Shell). Điều này giúp thiết lập một kết nối an toàn, đã xác thực từ Cloud Shell đến phiên bản Cloud SQL của bạn:

cloud-sql-proxy ${GOOGLE_CLOUD_PROJECT}:${REGION}:jobs-instance --port 5432 &

Nếu proxy khởi động, bạn sẽ thấy kết quả sau trong thiết bị đầu cuối:

... Authorizing with Application Default Credentials
... [workshop-xxxxxx:your-location:jobs-instance] Listening on 127.0.0.1:5432
... The proxy has started successfully and is ready for new connections!

Giờ đây, thiết bị đầu cuối hiện tại sẽ liên tục xuất nhật ký của proxy Cloud SQL. Hãy mở một thẻ dòng lệnh mới trong Cloud Shell (nhấp vào biểu tượng +) để chúng ta có thể tập trung hơn.

Chuyển đến thư mục làm việc của bạn một lần nữa và kích hoạt dự án bằng tập lệnh thiết lập trước đó.

cd ~/build-agent-adk-toolbox-cloudsql
bash setup_verify_trial_project.sh && source .env

Sau đó, hãy chạy tập lệnh khởi động

psql "host=127.0.0.1 port=5432 dbname=jobs_db user=postgres password=$DB_PASSWORD" -f seed.sql

Bạn sẽ thấy kết quả đầu ra của thiết bị đầu cuối như sau

CREATE EXTENSION
CREATE EXTENSION
CREATE TABLE
INSERT 0 15

Hãy xác minh dữ liệu

psql "host=127.0.0.1 port=5432 dbname=jobs_db user=postgres password=$DB_PASSWORD" \
  -c "SELECT title, company, role, openings FROM jobs ORDER BY role, title;"

Bạn sẽ thấy 15 tin tuyển dụng cho nhiều vai trò:

             title              |    company     |   role    | openings
---------------------------------+----------------+-----------+----------
 Senior Backend Engineer         | Stripe         | Backend   |        3
 Backend Engineer (Payments)     | Square         | Backend   |        3
 Cloud Architect                 | Google Cloud   | Cloud     |        1
 ...
(15 rows)

Tạo các vectơ nhúng cho nội dung mô tả công việc

Cột description_embedding trong bảng jobs hiện có giá trị NULL. Tiện ích google_ml_integration tích hợp của Cloud SQL cung cấp một hàm embedding() gọi Vertex AI trực tiếp từ SQL mà không cần tập lệnh Python hoặc SDK bên ngoài.

Bắt đầu tạo quá trình nhúng trong nền. Thao tác này gọi Vertex AI để tạo một vectơ 3072 chiều bằng cách sử dụng mô hình gemini-embedding-001 cho mỗi nội dung mô tả trong số 15 công việc:

psql "host=127.0.0.1 port=5432 dbname=jobs_db user=postgres password=$DB_PASSWORD" \
  -c "UPDATE jobs SET description_embedding = embedding('gemini-embedding-001', description)::vector;" &

Đây là những việc mà tập lệnh này thực hiện:

embedding('gemini-embedding-001', description) – gọi mô hình nhúng Gemini của Vertex AI trực tiếp từ SQL, truyền văn bản description của từng công việc. Đây là tiện ích google_ml_integration mà bạn đã cài đặt trong tập lệnh ban đầu.
::vector – truyền mảng số thực được trả về sang kiểu vector của pgvector để có thể lưu trữ và truy vấn bằng các toán tử khoảng cách.
UPDATE chạy trên cả 15 hàng, tạo ra một vectơ nhúng 3072 chiều cho mỗi nội dung mô tả công việc.
& sẽ chạy lệnh trong nền để bạn có thể tiếp tục làm việc trong khi Vertex AI xử lý các mục nhúng.

Giống như quá trình thực thi quy trình nền trước đây, thiết bị đầu cuối hiện tại sẽ xuất nhật ký của quy trình. Hãy mở một thẻ dòng lệnh mới trong Cloud Shell (nhấp vào biểu tượng +) để chúng ta có thể tập trung hơn.

Chuyển đến thư mục làm việc của bạn một lần nữa và kích hoạt dự án bằng tập lệnh thiết lập trước đó.

cd ~/build-agent-adk-toolbox-cloudsql
bash setup_verify_trial_project.sh && source .env

Sau đó, chúng ta có thể tiếp tục quy trình tiếp theo

6. Định cấu hình MCP Toolbox cho Cơ sở dữ liệu

Bước này giới thiệu MCP Toolbox for Databases, định cấu hình công cụ này để kết nối với phiên bản Cloud SQL của bạn và xác định 2 công cụ truy vấn SQL chuẩn.

MCP là gì và tại sao nên sử dụng Toolbox?

MCP (Giao thức ngữ cảnh mô hình) là một giao thức mở giúp chuẩn hoá cách các tác nhân AI khám phá và tương tác với các công cụ bên ngoài. Nó xác định một mô hình ứng dụng-máy chủ: tác nhân lưu trữ một ứng dụng MCP và các công cụ được máy chủ MCP hiển thị. Mọi ứng dụng tương thích với MCP đều có thể sử dụng mọi máy chủ tương thích với MCP – tác nhân không cần mã tích hợp tuỳ chỉnh cho từng công cụ.

MCP Toolbox for Databases là một máy chủ MCP nguồn mở được xây dựng dành riêng cho quyền truy cập vào cơ sở dữ liệu. Nếu không có công cụ này, bạn sẽ viết các hàm Python để mở kết nối cơ sở dữ liệu, quản lý nhóm kết nối, tạo truy vấn được tham số hoá để ngăn chặn việc chèn mã SQL, xử lý lỗi và nhúng tất cả mã đó vào trong tác nhân của bạn. Mọi tác nhân cần truy cập vào cơ sở dữ liệu đều lặp lại công việc này. Việc thay đổi một truy vấn có nghĩa là bạn phải triển khai lại tác nhân.

Với Toolbox, bạn sẽ viết một tệp YAML. Mỗi công cụ sẽ liên kết đến một câu lệnh SQL có tham số. Hộp công cụ xử lý việc gộp kết nối, truy vấn theo tham số, xác thực và khả năng quan sát. Các công cụ được tách biệt khỏi tác nhân – cập nhật một truy vấn bằng cách chỉnh sửa tools.yaml và khởi động lại Toolbox mà không cần chỉnh sửa mã tác nhân. Các công cụ này hoạt động trên ADK, LangGraph, LlamaIndex hoặc bất kỳ khung tương thích nào với MCP.

Viết cấu hình công cụ

Bây giờ, chúng ta cần tạo một tệp có tên là tools.yaml trong Cloud Shell Editor để thiết lập cấu hình công cụ

cloudshell edit tools.yaml

Tệp này sử dụng YAML nhiều tài liệu – mỗi khối được phân tách bằng --- là một tài nguyên độc lập. Mỗi tài nguyên đều có một kind khai báo tài nguyên đó là gì (sources cho các kết nối cơ sở dữ liệu, tools cho các thao tác có thể gọi của tác nhân) và một type chỉ định phần phụ trợ (cloud-sql-postgres cho nguồn, postgres-sql cho các công cụ dựa trên SQL). Một công cụ tham chiếu nguồn của nó bằng name. Đây là cách Toolbox biết nên thực thi nhóm kết nối nào. Các biến môi trường sử dụng cú pháp ${VAR_NAME} và được phân giải khi khởi động.

Bây giờ, trước tiên hãy sao chép các tập lệnh sau vào tệp tools.yaml

# tools.yaml

# --- Data Source ---
kind: sources
name: jobs-db
type: cloud-sql-postgres
project: ${GOOGLE_CLOUD_PROJECT}
region: ${REGION}
instance: jobs-instance
database: jobs_db
user: postgres
password: ${DB_PASSWORD}

---

Tập lệnh này xác định tài nguyên sau:

Nguồn (jobs-db) – cho biết cách Toolbox kết nối với phiên bản Cloud SQL PostgreSQL của bạn. Loại cloud-sql-postgres sử dụng trình kết nối Cloud SQL nội bộ, tự động xử lý việc xác thực và các kết nối an toàn. Các phần giữ chỗ ${GOOGLE_CLOUD_PROJECT} , ${REGION} và ${DB_PASSWORD} được phân giải từ các biến môi trường khi khởi động.

Tiếp theo, hãy thêm tập lệnh sau vào dưới biểu tượng --- trong tools.yaml

# --- Tool 1: Search jobs by role and/or tech stack ---
kind: tools
name: search-jobs
type: postgres-sql
source: jobs-db
description: >-
  Search for job listings by role category and/or tech stack.
  Use this tool when the developer wants to browse listings
  by role (e.g., Backend, Frontend, Data) or find jobs
  using a specific technology. Both parameters accept an
  empty string to match all values.
statement: |
  SELECT title, company, role, tech_stack, salary_range, location, openings
  FROM jobs
  WHERE ($1 = '' OR LOWER(role) = LOWER($1))
  AND ($2 = '' OR LOWER(tech_stack) LIKE '%' || LOWER($2) || '%')
  ORDER BY title
  LIMIT 10
parameters:
  - name: role
    type: string
    description: "The role category to filter by (e.g., 'Backend', 'Frontend', 'Data/AI', 'DevOps'). Use empty string for all roles."
  - name: tech_stack
    type: string
    description: "A technology to search for in the tech stack (partial match, e.g., 'Python', 'Kubernetes'). Use empty string for all tech stacks."

---

# --- Tool 2: Get full details for a specific job ---
kind: tools
name: get-job-details
type: postgres-sql
source: jobs-db
description: >-
  Get full details for a specific job listing including its description,
  salary range, location, and number of openings. Use this tool when the
  developer asks about a particular job by title or company.
statement: |
  SELECT title, company, role, tech_stack, salary_range, location, openings, description
  FROM jobs
  WHERE LOWER(title) LIKE '%' || LOWER($1) || '%'
  OR LOWER(company) LIKE '%' || LOWER($1) || '%'
parameters:
  - name: search_term
    type: string
    description: "The job title or company name to look up (partial match supported)."

---

Tập lệnh này xác định tài nguyên sau:

Công cụ 1 và 2 (search-jobs, get-job-details) – công cụ truy vấn SQL chuẩn. Mỗi mục ánh xạ một tên công cụ (những gì mà tác nhân nhìn thấy) với một câu lệnh SQL được tham số hoá (những gì mà cơ sở dữ liệu thực thi). Các tham số sử dụng trình giữ chỗ vị trí $1, $2. Hộp công cụ thực thi các câu lệnh này dưới dạng câu lệnh đã chuẩn bị, giúp ngăn chặn việc chèn SQL.

Hãy tiếp tục, thêm tập lệnh sau vào biểu tượng --- trong tools.yaml

# --- Embedding Model ---
kind: embeddingModels
name: gemini-embedding
type: gemini
model: gemini-embedding-001
dimension: 3072

---

Tập lệnh này xác định tài nguyên sau:

Mô hình nhúng (gemini-embedding) – định cấu hình Toolbox để gọi mô hình gemini-embedding-001 của Gemini nhằm tạo các mục nhúng văn bản 3072 chiều. Toolbox sử dụng Thông tin đăng nhập mặc định của ứng dụng (ADC) để xác thực – không cần khoá API trong Cloud Shell hoặc Cloud Run. Lưu ý rằng dimension được định cấu hình ở đây phải giống với dimension mà chúng ta đã định cấu hình trước đó để gieo dữ liệu vào cơ sở dữ liệu

Hãy tiếp tục, thêm tập lệnh sau vào biểu tượng --- trong tools.yaml

# --- Tool 3: Semantic search by description ---
kind: tools
name: search-jobs-by-description
type: postgres-sql
source: jobs-db
description: >-
  Find jobs that match a natural language description of what the developer
  is looking for. Use this tool when the developer describes their ideal job
  using interests, work style, career goals, or project type rather than a
  specific role or tech stack. Examples: "I want to work on AI chatbots,"
  "a remote job at a fintech startup," "something involving infrastructure
  and reliability."
statement: |
  SELECT title, company, role, tech_stack, salary_range, location, description
  FROM jobs
  WHERE description_embedding IS NOT NULL
  ORDER BY description_embedding <=> $1
  LIMIT 5
parameters:
  - name: search_query
    type: string
    description: "A natural language description of the kind of job the developer is looking for."
    embeddedBy: gemini-embedding

---

Tập lệnh này xác định tài nguyên sau:

Công cụ 3 (search-jobs-by-description) – một công cụ tìm kiếm vectơ. Tham số search_query có embeddedBy: gemini-embedding, cho biết Toolbox sẽ chặn văn bản thô, gửi văn bản đó đến mô hình nhúng và sử dụng vectơ kết quả trong câu lệnh SQL. Toán tử <=> là khoảng cách cosin của pgvector – giá trị càng nhỏ thì nội dung mô tả càng giống nhau.

Cuối cùng, hãy thêm công cụ cuối cùng vào biểu tượng --- trong tools.yaml

# --- Tool 4: Add a new job listing with automatic embedding ---
kind: tools
name: add-job
type: postgres-sql
source: jobs-db
description: >-
  Add a new job listing to the platform. Use this tool when a user asks
  to post a job that is not currently listed.
statement: |
  INSERT INTO jobs (title, company, role, tech_stack, salary_range, location, openings, description, description_embedding)
  VALUES ($1, $2, $3, $4, $5, $6, CAST($7 AS INTEGER), $8, $9)
  RETURNING title, company
parameters:
  - name: title
    type: string
    description: "The job title (e.g., 'Senior Backend Engineer')."
  - name: company
    type: string
    description: "The company name (e.g., 'Stripe', 'Spotify')."
  - name: role
    type: string
    description: "The role category (e.g., 'Backend', 'Frontend', 'Data/AI', 'DevOps')."
  - name: tech_stack
    type: string
    description: "Comma-separated list of technologies (e.g., 'Python, FastAPI, GCP')."
  - name: salary_range
    type: string
    description: "The salary range (e.g., '$150-200K/year')."
  - name: location
    type: string
    description: "Work location and arrangement (e.g., 'Remote')."
  - name: openings
    type: string
    description: "The number of open positions."
  - name: description
    type: string
    description: "A short description of the job (2-3 sentences)."
  - name: description_vector
    type: string
    description: "Auto-generated embedding vector for the job description."
    valueFromParam: description
    embeddedBy: gemini-embedding

Tập lệnh này xác định tài nguyên sau:

Công cụ 4 (add-job) – minh hoạ việc sử dụng vectơ. Tham số description_vector có 2 trường đặc biệt:
valueFromParam: description – Hộp công cụ sao chép giá trị từ tham số description vào tham số này. LLM không bao giờ thấy tham số này.
embeddedBy: gemini-embedding – Toolbox nhúng văn bản đã sao chép vào một vectơ trước khi chuyển văn bản đó đến SQL.

Kết quả: một lệnh gọi công cụ lưu trữ cả văn bản mô tả thô và vectơ nhúng của văn bản đó, mà không cần tác nhân biết bất kỳ thông tin nào về các vectơ nhúng.

Định dạng YAML nhiều tài liệu phân tách từng tài nguyên bằng ---. Mỗi tài liệu có các trường kind, name và type xác định nội dung của tài liệu. Tóm lại, chúng ta đã định cấu hình tất cả những điều sau:

Xác định cơ sở dữ liệu nguồn
Xác định các công cụ ( công cụ 1 và 2) để truy vấn cơ sở dữ liệu bằng bộ lọc tiêu chuẩn
Xác định mô hình nhúng
Xác định công cụ để thực hiện tìm kiếm vectơ ( công cụ 3 ) cho cơ sở dữ liệu
Xác định công cụ để thực hiện quá trình nhập dữ liệu vectơ ( công cụ 4) vào cơ sở dữ liệu

Xác minh các thành phần được nhúng

Trước khi bắt đầu Toolbox, hãy xác nhận rằng quá trình tạo mục nhúng ở chế độ nền đã hoàn tất. Kiểm tra để đảm bảo tất cả các công việc hiện đều có các mục nhúng:

psql "host=127.0.0.1 port=5432 dbname=jobs_db user=postgres password=$DB_PASSWORD" \
  -c "SELECT title, (description_embedding IS NOT NULL) AS has_embedding FROM jobs ORDER BY title;"

Mỗi hàng phải cho thấy t (true) trong cột has_embedding. Nếu không, bạn có thể chọn đợi cho đến khi hoàn tất toàn bộ quy trình tạo tính năng nhúng hàng

           title            | has_embedding 
-----------------------------+---------------
 AI Engineer                 | t
 Backend Engineer (Payments) | t
 Cloud Architect             | t
 Data Engineer               | t
 DevOps Engineer             | t
 Frontend Engineer           | t
 Full Stack Engineer         | t

Khởi động máy chủ Hộp công cụ

Trong bước thiết lập, chúng ta đã tải tệp thực thi toolbox xuống. Đảm bảo rằng tệp nhị phân này tồn tại và đã tải xuống thành công. Nếu chưa, hãy tải tệp xuống và đợi cho đến khi hoàn tất

cd ~/build-agent-adk-toolbox-cloudsql
if [ ! -f toolbox ]; then
  curl -O https://storage.googleapis.com/genai-toolbox/v0.27.0/linux/amd64/toolbox
fi
chmod +x toolbox

Xuất các biến môi trường cần thiết và khởi động Toolbox. Bạn cần có các biến GOOGLE_CLOUD_LOCATION và GOOGLE_GENAI_USE_VERTEXAI vì cấu hình này bao gồm một mô hình nhúng – GOOGLE_GENAI_USE_VERTEXAI cho biết Gemini SDK sẽ định tuyến thông qua Vertex AI (thay vì Gemini API dành cho người tiêu dùng) và GOOGLE_CLOUD_LOCATION cho biết Gemini SDK sẽ dùng điểm cuối theo khu vực nào.

export GOOGLE_CLOUD_PROJECT=$GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=$GOOGLE_CLOUD_LOCATION
export GOOGLE_GENAI_USE_VERTEXAI=true
export DB_PASSWORD=$DB_PASSWORD
export REGION=$REGION
./toolbox --tools-file tools.yaml &

Bạn sẽ thấy kết quả xác nhận rằng máy chủ đã sẵn sàng như minh hoạ dưới đây:

... INFO "Initialized 0 authServices: " 
... INFO "Initialized 1 embeddingModels: gemini-embedding" 
... INFO "Initialized 4 tools: add-job, search-jobs, get-job-details, search-jobs-by-description" 
...
... INFO "Server ready to serve!"

Giống như bước trước, bước này sẽ tạo ra một quy trình khác và xuất ra các kết quả. Hãy mở một thẻ dòng lệnh mới trong Cloud Shell (nhấp vào biểu tượng +) để chúng ta có thể tập trung hơn.

Chuyển đến thư mục làm việc của bạn một lần nữa và kích hoạt dự án bằng tập lệnh thiết lập trước đó.

cd ~/build-agent-adk-toolbox-cloudsql
bash setup_verify_trial_project.sh && source .env

Xác minh các công cụ

Truy vấn Toolbox API để liệt kê tất cả các công cụ đã đăng ký:

curl -s http://localhost:5000/api/toolset | python3 -m json.tool

Bạn sẽ thấy các công cụ cùng với nội dung mô tả và tham số của chúng. Như minh hoạ bên dưới

...

"search-jobs-by-description": {
            "description": "Find jobs that match a natural language description of what the developer is looking for. Use this tool when the developer describes their ideal job using interests, work style, career goals, or project type rather than a specific role or tech stack. Examples: \"I want to work on AI chatbots,\" \"a remote job at a fintech startup,\" \"something involving infrastructure and reliability.\"",
            "parameters": [
                {
                    "name": "search_query",
                    "type": "string",
                    "required": true,
                    "description": "A natural language description of the kind of job the developer is looking for.",
                    "authSources": []
                }
            ],
            "authRequired": []
        }
...

Kiểm thử trực tiếp công cụ search-jobs:

curl -s -X POST http://localhost:5000/api/tool/search-jobs/invoke \
  -H "Content-Type: application/json" \
  -d '{"role": "Backend", "tech_stack": ""}' | jq '.result | fromjson'

Phản hồi phải chứa 2 công việc kỹ thuật phụ trợ trong dữ liệu ban đầu của bạn.

[
  {
    "title": "Backend Engineer (Payments)",
    "company": "Square",
    "role": "Backend",
    "tech_stack": "Java, Spring Boot, PostgreSQL, Kafka",
    "salary_range": "$160-220K/year",
    "location": "San Francisco, Hybrid",
    "openings": 3
  },
  {
    "title": "Senior Backend Engineer",
    "company": "Stripe",
    "role": "Backend",
    "tech_stack": "Go, PostgreSQL, gRPC, Kubernetes",
    "salary_range": "$180-250K/year",
    "location": "San Francisco, Hybrid",
    "openings": 3
  }
]

7. Tạo ADK Agent

Bước này kết nối tác nhân ADK với máy chủ Toolbox đang chạy và kiểm thử cả 4 công cụ: truy vấn chuẩn, tìm kiếm ngữ nghĩa và truyền vectơ. Mã tác nhân là tối thiểu: mọi logic cơ sở dữ liệu đều nằm trong tools.yaml.

Định cấu hình môi trường của tác nhân

ADK đọc GOOGLE_GENAI_USE_VERTEXAI, GOOGLE_CLOUD_PROJECT và GOOGLE_CLOUD_LOCATION từ môi trường shell mà bạn đã thiết lập ở bước trước. Biến duy nhất dành riêng cho nhân viên hỗ trợ là TOOLBOX_URL – hãy thêm biến này vào tệp .env của nhân viên hỗ trợ:

echo -e "\nTOOLBOX_URL=http://127.0.0.1:5000" >> jobs_agent/.env

Cập nhật mô-đun tác nhân

Mở jobs_agent/agent.py trong Trình chỉnh sửa Cloud Shell

cloudshell edit jobs_agent/agent.py

và ghi đè nội dung bằng mã sau:

# jobs_agent/agent.py
import os

from google.adk.agents import LlmAgent
from toolbox_adk import ToolboxToolset

TOOLBOX_URL = os.environ.get("TOOLBOX_URL", "http://127.0.0.1:5000")

toolbox = ToolboxToolset(TOOLBOX_URL)

root_agent = LlmAgent(
    name="jobs_agent",
    model="gemini-2.5-flash",
    instruction="""You are a helpful assistant at "TechJobs," a tech job listing platform.

Your job:
- Help developers browse job listings by role or tech stack.
- Provide full details about specific positions, including salary range and number of openings.
- Recommend jobs based on natural language descriptions of what the developer is looking for.
- Add new job listings to the platform when asked.

When a developer asks about a specific job by title or company, use the get-job-details tool.
When a developer asks for a specific role category or tech stack, use the search-jobs tool.
When a developer describes what kind of job they want — by interest area, work style,
career goals, or project type — use the search-jobs-by-description tool for semantic search.
When in doubt between search-jobs and search-jobs-by-description, prefer
search-jobs-by-description — it searches job descriptions and finds more relevant matches.

If a position has no openings (openings is 0), let the developer know
and suggest similar alternatives from the search results.

Be conversational, knowledgeable, and concise.""",
    tools=[toolbox],
)

Xin lưu ý rằng không có mã cơ sở dữ liệu nào ở đây – ToolboxToolset kết nối với máy chủ Toolbox khi khởi động và tải tất cả các công cụ có sẵn. Tên của các công cụ được gọi bởi tác nhân; Toolbox sẽ dịch những lệnh gọi đó thành các truy vấn SQL đối với Cloud SQL.

Biến môi trường TOOLBOX_URL mặc định là http://127.0.0.1:5000 cho quá trình phát triển cục bộ. Khi triển khai lên Cloud Run sau này, bạn sẽ ghi đè URL này bằng URL Cloud Run của dịch vụ Toolbox mà không cần thay đổi mã.

Hướng dẫn này hiện chỉ đề cập đến 2 công cụ tiêu chuẩn (search-jobs và get-job-details). Bạn sẽ mở rộng hướng dẫn này ở bước tiếp theo khi thêm các công cụ tìm kiếm và nhập dữ liệu ngữ nghĩa.

Kiểm thử tác nhân

Khởi động giao diện người dùng dành cho nhà phát triển ADK:

cd ~/build-agent-adk-toolbox-cloudsql
uv run adk web

Mở URL xuất hiện trong thiết bị đầu cuối (thường là http://localhost:8000) bằng tính năng Xem trước trên web của Cloud Shell hoặc nhấn ctrl + nhấp vào URL xuất hiện trong thiết bị đầu cuối. Chọn jobs_agent trong trình đơn thả xuống của tác nhân ở góc trên bên trái.

Kiểm thử các truy vấn tiêu chuẩn

Hãy thử những câu lệnh sau để xác minh các công cụ SQL chuẩn:

What backend engineering jobs do you have?

Any jobs using Kubernetes?

Tell me about the Cloud Architect position

Kiểm thử tính năng tìm kiếm ngữ nghĩa

Hãy thử nội dung mô tả bằng ngôn ngữ tự nhiên không liên kết với một vai trò hoặc bộ công nghệ cụ thể:

I want a remote job where I can work on AI and machine learning

Find me something in fintech with good work-life balance

I'm interested in infrastructure and reliability engineering

Trợ lý sẽ cố gắng chọn công cụ phù hợp dựa trên loại truy vấn: bộ lọc có cấu trúc sẽ đi qua search-jobs, nội dung mô tả bằng ngôn ngữ tự nhiên sẽ đi qua search-jobs-by-description.

Kiểm thử việc truyền dẫn vectơ

Yêu cầu trợ lý ảo thêm một công việc mới:

Add a new job: 'Robotics Software Engineer' at Boston Dynamics, role Robotics, tech stack: Python, C++, ROS, Computer Vision, salary $160-230K/year, location Waltham MA, Hybrid, 2 openings. Description: Design and implement autonomous navigation and manipulation algorithms for next-generation robots. Work on perception pipelines using computer vision and lidar, develop motion planning software in C++ and Python, and test systems on real hardware in warehouse and logistics environments.

Bây giờ, hãy thử tìm kiếm:

Find me jobs involving autonomous systems and working with physical hardware

Hoạt động nhúng được tạo tự động trong quá trình INSERT – không cần thực hiện bước riêng biệt.

Giờ đây, bạn đã có một ứng dụng RAG dựa trên tác nhân hoạt động đầy đủ, sử dụng ADK, MCP Toolbox và CloudSQL. Xin chúc mừng! Hãy tiến thêm một bước nữa để triển khai các ứng dụng này lên Cloud Run!

Bây giờ, hãy dừng giao diện người dùng dành cho nhà phát triển bằng cách kết thúc quy trình này bằng cách nhấn tổ hợp phím Ctrl+C hai lần trước khi tiếp tục.

8. Triển khai lên Cloud Run

Trợ lý và Hộp công cụ hoạt động cục bộ. Bước này triển khai cả hai dưới dạng các dịch vụ Cloud Run để có thể truy cập qua Internet. Dịch vụ Toolbox chạy dưới dạng máy chủ MCP trên Cloud Run và dịch vụ tác nhân kết nối với dịch vụ này.

Chuẩn bị Hộp công cụ để triển khai

Tạo một thư mục triển khai cho dịch vụ Toolbox:

cd ~/build-agent-adk-toolbox-cloudsql
mkdir -p deploy-toolbox
cp toolbox tools.yaml deploy-toolbox/

Tạo Dockerfile cho Toolbox. Mở deploy-toolbox/Dockerfile trong Trình chỉnh sửa Cloud Shell:

cloudshell edit deploy-toolbox/Dockerfile

Sao chép tập lệnh sau vào đó

# deploy-toolbox/Dockerfile
FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y ca-certificates && rm -rf /var/lib/apt/lists/*
WORKDIR /app
COPY toolbox tools.yaml ./
RUN chmod +x toolbox
EXPOSE 8080
CMD ["./toolbox", "--tools-file", "tools.yaml", "--address", "0.0.0.0", "--port", "8080"]

Tệp nhị phân Toolbox và tools.yaml được đóng gói thành một hình ảnh Debian tối thiểu. Cloud Run định tuyến lưu lượng truy cập đến cổng 8080.

Triển khai dịch vụ Hộp công cụ

cd ~/build-agent-adk-toolbox-cloudsql
gcloud run deploy toolbox-service \
  --source deploy-toolbox/ \
  --region $REGION \
  --set-env-vars "DB_PASSWORD=$DB_PASSWORD,GOOGLE_CLOUD_PROJECT=$GOOGLE_CLOUD_PROJECT,REGION=$REGION,GOOGLE_CLOUD_LOCATION=$GOOGLE_CLOUD_LOCATION,GOOGLE_GENAI_USE_VERTEXAI=true" \
  --allow-unauthenticated \
  --quiet

Lệnh này gửi nguồn đến Cloud Build, tạo một hình ảnh vùng chứa, đẩy hình ảnh đó vào Artifact Registry và triển khai hình ảnh đó vào Cloud Run. Việc này mất vài phút. Hãy mở một thẻ thiết bị đầu cuối mới trong Cloud Shell (nhấp vào biểu tượng +) để chúng ta có thể tập trung hơn.

Chuyển đến thư mục làm việc của bạn một lần nữa và kích hoạt dự án bằng tập lệnh thiết lập trước đó.

cd ~/build-agent-adk-toolbox-cloudsql
bash setup_verify_trial_project.sh && source .env

Chuẩn bị tác nhân để triển khai

Trong khi Toolbox đang tạo, hãy thiết lập các tệp triển khai của nhân viên hỗ trợ.

Tạo một Dockerfile trong thư mục gốc của dự án. Mở Dockerfile trong Trình chỉnh sửa Cloud Shell:

cloudshell edit Dockerfile

Sau đó, hãy sao chép nội dung sau

# Dockerfile
FROM ghcr.io/astral-sh/uv:python3.12-trixie-slim
WORKDIR /app
COPY pyproject.toml ./
COPY uv.lock ./
RUN uv sync --no-dev
COPY jobs_agent/ jobs_agent/
EXPOSE 8080
CMD ["uv", "run", "adk", "web", "--host", "0.0.0.0", "--port", "8080"]

Dockerfile này sử dụng ghcr.io/astral-sh/uv làm hình ảnh cơ sở, bao gồm cả Python và uv được cài đặt sẵn – không cần cài đặt uv riêng biệt thông qua pip.

Tạo tệp .dockerignore để loại trừ các tệp không cần thiết khỏi hình ảnh vùng chứa:

cloudshell edit .dockerignore

Sau đó, sao chép tập lệnh sau vào đó

# .dockerignore
.venv/
__pycache__/
*.pyc
.env
jobs_agent/.env
toolbox
tools.yaml
seed.sql
deploy-toolbox/

Triển khai dịch vụ tác nhân

Chờ quá trình triển khai Toolbox hoàn tất. Truy xuất URL Cloud Run của ứng dụng bằng lệnh sau

TOOLBOX_URL=$(gcloud run services describe toolbox-service \
  --region=$REGION \
  --format='value(status.url)')
echo "Toolbox URL: $TOOLBOX_URL"

Bạn sẽ thấy kết quả tương tự như sau

Toolbox URL: https://toolbox-service-xxxxxx-xx.a.run.app

Sau đó, hãy xác minh rằng Toolbox đã triển khai đang hoạt động:

curl -s "$TOOLBOX_URL/api/toolset" | python3 -m json.tool | head -5

Nếu kết quả đầu ra hiển thị như ví dụ này, thì quá trình triển khai đã thành công

{
    "serverVersion": "0.27.0+binary.linux.amd64.c5524d3",
    "tools": {
        "add-job": {
            "description": "Add a new job listing to the platform. Use this tool when a user asks to post a job that is not currently listed.",

Tiếp theo, hãy triển khai tác nhân bằng cách truyền URL của Hộp công cụ dưới dạng một biến môi trường:

cd ~/build-agent-adk-toolbox-cloudsql
gcloud run deploy jobs-agent \
  --source . \
  --region $REGION \
  --set-env-vars "TOOLBOX_URL=$TOOLBOX_URL,GOOGLE_CLOUD_PROJECT=$GOOGLE_CLOUD_PROJECT,GOOGLE_CLOUD_LOCATION=$GOOGLE_CLOUD_LOCATION,GOOGLE_GENAI_USE_VERTEXAI=TRUE" \
  --allow-unauthenticated \
  --quiet

Mã tác nhân đọc TOOLBOX_URL từ môi trường (bạn đã thiết lập mã này trước đó). Trên máy cục bộ, tham số này trỏ đến http://127.0.0.1:5000; trên Cloud Run, tham số này trỏ đến URL dịch vụ Toolbox. Bạn không cần thay đổi mã.

Kiểm thử nhân viên hỗ trợ đã triển khai

Truy xuất URL Cloud Run của nhân viên hỗ trợ:

AGENT_URL=$(gcloud run services describe jobs-agent \
  --region=$REGION \
  --format='value(status.url)')
echo "Agent URL: $AGENT_URL"

Mở URL trong trình duyệt. Giao diện người dùng dành cho nhà phát triển ADK sẽ tải – cùng một giao diện mà bạn đã sử dụng cục bộ, hiện đang chạy trên Cloud Run.

Chọn jobs_agent trong trình đơn thả xuống rồi kiểm thử:

What backend engineering jobs do you have?

I want a remote job working on AI and machine learning

Cả hai truy vấn đều hoạt động thông qua các dịch vụ đã triển khai: tác nhân trên Cloud Run gọi Toolbox trên Cloud Run, truy vấn Cloud SQL.

9. Chúc mừng / Dọn dẹp

Bạn đã tạo và triển khai một trợ lý bảng thông báo việc làm thông minh sử dụng MCP Toolbox for Databases để kết nối một tác nhân ADK và Cloud SQL PostgreSQL – bằng cả truy vấn SQL tiêu chuẩn và tìm kiếm vectơ ngữ nghĩa.

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

Cách MCP chuẩn hoá quyền truy cập vào công cụ cho các tác nhân AI và cách MCP Toolbox for Databases áp dụng điều này cụ thể cho các hoạt động trên cơ sở dữ liệu – thay thế mã cơ sở dữ liệu tuỳ chỉnh bằng cấu hình YAML khai báo
Cách định cấu hình Cloud SQL PostgreSQL làm nguồn dữ liệu Toolbox bằng loại nguồn cloud-sql-postgres
Cách xác định các công cụ truy vấn SQL chuẩn bằng các câu lệnh có tham số giúp ngăn chặn việc chèn SQL
Cách bật tính năng tìm kiếm vectơ bằng pgvector và gemini-embedding-001, với tham số embeddedBy để tự động nhúng truy vấn
Cách valueFromParam cho phép tự động thu nạp vectơ – LLM cung cấp nội dung mô tả bằng văn bản và Toolbox sẽ sao chép, nhúng và lưu trữ vectơ cùng với văn bản một cách âm thầm
Cách ToolboxToolset của ADK tải các công cụ từ một máy chủ Toolbox đang chạy, giúp mã tác nhân ở mức tối thiểu và logic cơ sở dữ liệu hoàn toàn tách biệt
Cách triển khai cả máy chủ MCP của Toolbox và tác nhân ADK vào Cloud Run dưới dạng các dịch vụ riêng biệt

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 tạo trong lớp học lập trình này, bạn có thể xoá từng tài nguyên hoặc xoá toàn bộ dự án.

Cách 1: Xoá dự án (nên dùng)

Cách dọn dẹp dễ nhất là xoá dự án. Thao tác này sẽ xoá tất cả tài nguyên liên kết với dự án.

gcloud projects delete $GOOGLE_CLOUD_PROJECT

Cách 2: Xoá từng tài nguyên

Nếu bạn muốn giữ lại dự án nhưng chỉ xoá các tài nguyên được tạo trong lớp học lập trình này, hãy làm như sau:

gcloud run services delete jobs-agent --region=$REGION --quiet
gcloud run services delete toolbox-service --region=$REGION --quiet
gcloud sql instances delete jobs-instance --quiet
gcloud artifacts repositories delete cloud-run-source-deploy --location=$REGION --quiet 2>/dev/null