این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

پایگاه داده به عنوان یک ابزار: Agentic RAG با ADK، جعبه ابزار MCP و Cloud SQL

۱. مقدمه

عامل‌های هوش مصنوعی فقط به اندازه داده‌هایی که می‌توانند به آنها دسترسی داشته باشند، مفید هستند. بیشتر داده‌های دنیای واقعی در پایگاه‌های داده قرار دارند - و اتصال عامل‌ها به پایگاه‌های داده معمولاً به معنای نوشتن مدیریت اتصال، منطق پرس‌وجو و تعبیه خطوط لوله در داخل کد عامل شماست. هر عاملی که به دسترسی به پایگاه داده نیاز دارد، این کار را تکرار می‌کند و هر تغییر پرس‌وجو نیاز به استقرار مجدد عامل دارد.

این آزمایشگاه کد رویکرد متفاوتی را نشان می‌دهد. شما ابزارهای پایگاه داده خود را در یک فایل YAML تعریف می‌کنید - کوئری‌های استاندارد SQL، جستجوی شباهت برداری، حتی تولید خودکار جاسازی - و MCP Toolbox for Databases تمام عملیات پایگاه داده را به عنوان یک سرور MCP مدیریت می‌کند. کد عامل شما مینیمال باقی می‌ماند: ابزارها را بارگذاری کنید، بگذارید Gemini تصمیم بگیرد کدام یک را فراخوانی کند.

آنچه خواهید ساخت

یک دستیار هوشمند برای تابلوی مشاغل برای "TechJobs" - یک عامل ADK که توسط Gemini پشتیبانی می‌شود و به توسعه‌دهندگان کمک می‌کند تا با استفاده از فیلترهای استاندارد (نقش، پشته فناوری) فهرست مشاغل فنی را مرور کنند و از طریق توضیحات زبان طبیعی مانند "من یک کار از راه دور با کار بر روی ربات‌های چت هوش مصنوعی می‌خواهم" مشاغل را کشف کنند. این عامل از طریق MCP Toolbox for Databases، که تمام دسترسی به پایگاه داده - از جمله تولید خودکار جاسازی برای جستجوی برداری - را مدیریت می‌کند، از یک پایگاه داده Cloud SQL PostgreSQL می‌خواند و در آن می‌نویسد. در نهایت، هم Toolbox و هم عامل بر روی Cloud Run اجرا می‌شوند.

آنچه یاد خواهید گرفت

چگونه MCP (پروتکل زمینه مدل) دسترسی به ابزار را برای عوامل هوش مصنوعی استاندارد می‌کند، و چگونه MCP Toolbox for Databases این را در عملیات پایگاه داده اعمال می‌کند
جعبه ابزار MCP برای پایگاه‌های داده را به عنوان میان‌افزار بین یک عامل ADK و Cloud SQL PostgreSQL تنظیم کنید.
ابزارهای پایگاه داده را به صورت اعلانی در tools.yaml تعریف کنید - هیچ کد پایگاه داده‌ای در عامل شما وجود ندارد
با استفاده از ToolboxToolset یک عامل ADK بسازید که ابزارها را از یک سرور Toolbox در حال اجرا بارگیری کند.
با استفاده از embedding() داخلی Cloud SQL، جاسازی‌های برداری ایجاد کنید و جستجوی معنایی را با pgvector فعال کنید.
از ویژگی valueFromParam برای دریافت خودکار بردار در عملیات نوشتن استفاده کنید
سرور Toolbox و ADK agent را روی Cloud Run مستقر کنید.

پیش‌نیازها

یک حساب Google Cloud با یک حساب پرداخت آزمایشی
آشنایی اولیه با پایتون و SQL
هیچ تجربه قبلی با ADK، MCP Toolbox یا pgvector لازم نیست

۲. محیط خود را آماده کنید

نکات مهم:

این آموزش به یک پروژه گوگل کلود با یک حساب پرداخت فعال نیاز دارد. اگر هنوز حساب ندارید، لطفاً مراحل زیر را برای دریافت یک حساب پرداخت آزمایشی که می‌توانید برای این آموزش استفاده کنید، دنبال کنید:

باز کردن پنجره ناشناس
اگر در حال پیوستن به یک جلسه کارگاه هستید، معمولاً آدرس اینترنتی پورتال بازخرید در جلسه ارائه می‌شود، در غیر این صورت می‌توانید به این پورتال بازخرید حساب صورتحساب آزمایشی بروید
با استفاده از حساب جیمیل شخصی خود وارد شوید (Google Workspace / سایر ایمیل‌ها کار نخواهند کرد!)
دستورالعمل‌های بازخرید را گام به گام دنبال کنید تا با موفقیت یک پروژه جدید Google Cloud ایجاد کنید که به حساب پرداخت آزمایشی قبلاً ادعا شده برای این آموزش مرتبط باشد .

این مرحله محیط Cloud Shell شما را آماده می‌کند، پروژه Google Cloud شما را پیکربندی می‌کند و مخزن مرجع را کلون می‌کند.

پوسته ابری را باز کنید

Cloud Shell را در مرورگر خود باز کنید. Cloud Shell یک محیط از پیش پیکربندی شده با تمام ابزارهای مورد نیاز برای این آزمایشگاه کد را فراهم می‌کند. در صورت درخواست، روی تأیید (Authorize) کلیک کنید.

سپس روی « مشاهده » -> « ترمینال » کلیک کنید تا ترمینال باز شود. رابط کاربری شما باید شبیه به این باشد.

۸۶۳۰۷fac5da2f077.png

این رابط اصلی ما خواهد بود، IDE در بالا، ترمینال در پایین

دایرکتوری کاری خود را تنظیم کنید

دایرکتوری کاری خود را ایجاد کنید. تمام کدهایی که در این آزمایشگاه کد می‌نویسید، در اینجا قرار دارند:

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

پروژه گوگل کلود خود را راه‌اندازی کنید

فایل .env را با متغیرهای مکان ایجاد کنید:

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

اسکریپت راه‌اندازی پروژه را در دایرکتوری کاری خود دانلود کنید:

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

اسکریپت را اجرا کنید. این اسکریپت حساب کاربری آزمایشی شما را تأیید می‌کند، یک پروژه جدید ایجاد می‌کند (یا یک پروژه موجود را تأیید می‌کند)، شناسه پروژه شما را در یک فایل .env در دایرکتوری فعلی ذخیره می‌کند و پروژه فعال را در gcloud تنظیم می‌کند.

bash setup_verify_trial_project.sh && source .env

اسکریپت:

تأیید کنید که یک حساب پرداخت آزمایشی فعال دارید
بررسی وجود یک پروژه موجود در .env (در صورت وجود)
یک پروژه جدید ایجاد کنید یا از پروژه موجود دوباره استفاده کنید
حساب پرداخت آزمایشی را به پروژه خود پیوند دهید
شناسه پروژه را در .env ذخیره کنید
پروژه را به عنوان پروژه فعال gcloud تنظیم کنید

با بررسی متن زرد رنگ کنار دایرکتوری کاری خود در اعلان ترمینال Cloud Shell، مطمئن شوید که پروژه به درستی تنظیم شده است. باید شناسه پروژه شما نمایش داده شود.

اگر جلسه Cloud Shell شما در هر مرحله از این آزمایش کد بازنشانی شد، به دایرکتوری کاری خود برگردید و دستور bash setup_verify_trial_project.sh && source .env را دوباره اجرا کنید تا پیکربندی پروژه شما بازیابی شود. تأیید کنید که متن زرد رنگ شناسه پروژه دوباره در اعلان ترمینال ظاهر می‌شود.

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

رابط برنامه‌نویسی کاربردی هوش مصنوعی ورتکس ( aiplatform.googleapis.com ) — عامل شما از مدل‌های Gemini استفاده می‌کند و تول‌باکس از رابط برنامه‌نویسی کاربردی جاسازی برای جستجوی برداری استفاده می‌کند.
رابط برنامه‌نویسی کاربردی مدیریت SQL ابری ( sqladmin.googleapis.com ) - شما یک نمونه PostgreSQL را تهیه و مدیریت می‌کنید.
رابط برنامه‌نویسی کاربردی موتور محاسبات (compute Engine API ) ( compute.googleapis.com ) — برای ایجاد نمونه‌های Cloud SQL مورد نیاز است.
Cloud Run، Cloud Build، Artifact Registry - که در مرحله استقرار بعداً در این آزمایشگاه کد استفاده می‌شود

۳. ایجاد نمونه پایگاه داده

این مرحله، ایجاد نمونه Cloud SQL را در پس‌زمینه تنظیم می‌کند - این نمونه در حین ادامه آموزش، آماده‌سازی می‌شود.

شروع ایجاد نمونه

رمز عبور پایگاه داده را به فایل .env خود اضافه کنید و آن را مجدداً بارگذاری کنید:

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

ایجاد نمونه Cloud SQL را شروع کنید. این در پس‌زمینه اجرا می‌شود تا بتوانید به کار خود ادامه دهید:

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 کوچکترین لایه اختصاصی Cloud SQL با هسته اختصاصی (1 vCPU، 3.75 GB RAM) در نسخه ENTERPRISE است. می‌توانید جزئیات بیشتر را اینجا بخوانید. برای ادغام Vertex AI ML به یک هسته اختصاصی نیاز است - لایه‌های مشترک هسته ( db-f1-micro ، db-g1-small ) از آن پشتیبانی نمی‌کنند.
--root-password ‎ رمز عبور را برای کاربر پیش‌فرض postgres تنظیم می‌کند.
--enable-google-ml-integration امکان ادغام داخلی Cloud SQL با Vertex AI را فراهم می‌کند، که به شما امکان می‌دهد مدل‌های جاسازی را مستقیماً از SQL با استفاده از تابع embedding() فراخوانی کنید.
& دستور را در پس‌زمینه اجرا می‌کند.

این در پس‌زمینه اجرا می‌شود، سپس بیایید فایل باینری MCP Toolbox را دانلود کنیم. می‌توانید این کار را در همان ترمینال انجام دهید.

دانلود فایل باینری جعبه ابزار

ما در این آموزش از MCP Toolbox استفاده خواهیم کرد، خوشبختانه این ابزار با یک فایل باینری از پیش ساخته شده ارائه می‌شود که آماده استفاده در محیط لینوکس است. بیایید آن را در پس‌زمینه دانلود کنیم زیرا مدتی طول می‌کشد.

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

بگذارید این فرآیند در تب فعلی اجرا شود (ما قبلاً آن را در پس‌زمینه اجرا کرده‌ایم، با این حال خروجی همچنان نمایش داده می‌شود). بیایید یک تب ترمینال جدید در Cloud Shell باز کنیم (روی نماد + کلیک کنید) تا بتوانیم بیشتر متمرکز شویم.

دوباره به دایرکتوری کاری خود بروید و پروژه را با استفاده از اسکریپت راه‌اندازی قبلی فعال کنید.

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

این مرحله پروژه پایتون را راه‌اندازی می‌کند، وابستگی‌ها را نصب می‌کند و دایرکتوری عامل ADK را چارچوب‌بندی می‌کند.

۴. پروژه عامل را مقداردهی اولیه کنید

پروژه پایتون را تنظیم کنید

uv یک پکیج سریع پایتون و مدیر پروژه است که با Rust نوشته شده است ( مستندات uv ). این codelab از آن برای سرعت و سادگی استفاده می‌کند.

یک پروژه پایتون را راه‌اندازی کنید و وابستگی‌های مورد نیاز را اضافه کنید:

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

google-adk — کیت توسعه عامل گوگل، شامل Gemini SDK
toolbox-adk — یکپارچه‌سازی ADK برای جعبه ابزار MCP برای پایگاه‌های داده.

ساختار دایرکتوری عامل را ایجاد کنید

ADK انتظار یک طرح پوشه خاص را دارد: یک پوشه به نام عامل شما که شامل __init__.py ، agent.py و .env باشد. برای کمک به این امر، دستوری را برای ایجاد سریع ساختار تعبیه کرده است:

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

اکنون دایرکتوری شما باید به این شکل باشد:

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

۵. پایگاه داده فهرست مشاغل را راه‌اندازی کنید

این مرحله داده‌های اولیه را می‌نویسد، منتظر می‌ماند تا نمونه Cloud SQL آماده‌سازی را تمام کند و جدول jobs را با ۱۵ لیست شغل و توضیحات جاسازی‌شده آنها بارگذاری می‌کند.

SQL اولیه را بنویسید

ما فایلی به نام seed.sql در ویرایشگر Cloud Shell با محتوای فهرست مشاغل ایجاد خواهیم کرد. این کار جدول jobs را با پشتیبانی pgvector ایجاد می‌کند و 15 فهرست شغلی در شرکت‌های فناوری را درج می‌کند.

ابتدا، فایل seed.sql را با استفاده از دستور زیر ایجاد کنید:

cloudshell edit seed.sql

سپس، این اسکریپت‌ها را در فایل کپی کنید

-- 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.');

اسکریپت seed دو افزونه PostgreSQL را نصب می‌کند:

google_ml_integration — تابع embedding() SQL را فراهم می‌کند که مدل‌های تعبیه هوش مصنوعی Vertex را مستقیماً از SQL فراخوانی می‌کند. این یک افزونه در سطح پایگاه داده است که توابع یادگیری ماشین را در jobs_db در دسترس قرار می‌دهد. پرچم سطح نمونه ( --enable-google-ml-integration ) که هنگام ایجاد نمونه تنظیم می‌کنید، به ماشین مجازی Cloud SQL اجازه می‌دهد تا به Vertex AI دسترسی پیدا کند — این افزونه توابع SQL را در این پایگاه داده خاص در دسترس قرار می‌دهد.
vector ( pgvector ) - نوع داده vector و عملگرهای فاصله را برای ذخیره و جستجوی جاسازی‌ها اضافه می‌کند.

ستون description_embedding vector(3072) است - یک ستون pgvector که بردارهای 3072 بعدی را ذخیره می‌کند. فعلاً مقدار آن NULL است؛ شما در مرحله بعدی با استفاده از تابع embedding() جاسازی‌ها را ایجاد و پر می‌کنید.

پایان تنظیمات پایگاه داده

ممکن است ایجاد نمونه Cloud SQL که در مرحله قبل شروع کرده‌اید هنوز در حال اجرا باشد و تکمیل نشده باشد. تأیید کنید که نمونه آماده است:

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

باید خروجی زیر را مشاهده کنید

RUNNABLE

در مرحله بعد، به حساب کاربری سرویس نمونه Cloud SQL اجازه دهید تا Vertex AI را فراخوانی کند. این برای تابع داخلی embedding() که در مرحله بعدی استفاده خواهید کرد، لازم است:

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

پس از آن، یک پایگاه داده اختصاصی برای لیست مشاغل ایجاد کنید:

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

شما باید خروجی را مشاهده کنید که ایجاد پایگاه داده را تأیید می‌کند:

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

اتصال و ایجاد پایگاه داده

پروکسی احراز هویت Cloud SQL را اجرا کنید ( cloud-sql-proxy از قبل در Cloud Shell نصب شده است). این یک اتصال امن و احراز هویت شده از Cloud Shell به نمونه Cloud SQL شما فراهم می‌کند:

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

اگر پروکسی شروع به کار کند، باید این خروجی را در ترمینال مشاهده کنید:

... 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!

اکنون ترمینال فعلی به طور مداوم گزارش پروکسی cloud sql را ارائه می‌دهد. بیایید یک تب ترمینال جدید در Cloud Shell باز کنیم (روی نماد + کلیک کنیم) تا بتوانیم بیشتر متمرکز شویم.

دوباره به دایرکتوری کاری خود بروید و پروژه را با استفاده از اسکریپت راه‌اندازی قبلی فعال کنید.

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

سپس، اسکریپت seed را اجرا کنید

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

خروجی ترمینال مانند این را خواهید دید

CREATE EXTENSION
CREATE EXTENSION
CREATE TABLE
INSERT 0 15

بیایید داده‌ها را تأیید کنیم

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;"

شما باید ۱۵ لیست شغلی را در چندین نقش مشاهده کنید:

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

ایجاد جاسازی برای شرح شغل‌ها

ستون description_embedding در جدول jobs در حال حاضر NULL است. افزونه google_ml_integration داخلی Cloud SQL یک تابع embedding() ارائه می‌دهد که Vertex AI را مستقیماً از SQL فراخوانی می‌کند - بدون نیاز به اسکریپت پایتون یا SDK خارجی.

تولید جاسازی را در پس‌زمینه شروع کنید. این کار Vertex AI را برای تولید یک بردار 3072 بعدی با استفاده از مدل gemini-embedding-001 برای هر یک از 15 شرح شغل فراخوانی می‌کند:

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;" &

این کاری است که اسکریپت انجام می‌دهد:

embedding('gemini-embedding-001', description) — مدل embedding Gemini مربوط به Vertex AI را مستقیماً از SQL فراخوانی می‌کند و متن description هر کار را ارسال می‌کند. این افزونه google_ml_integration است که شما در اسکریپت seed نصب کرده‌اید.
::vector — آرایه اعشاری برگشتی را به نوع vector pgvector تبدیل می‌کند تا بتوان آن را ذخیره و با عملگرهای فاصله پرس‌وجو کرد.
UPDATE در هر ۱۵ ردیف اجرا می‌شود و به ازای هر شرح شغل، یک جاسازی ۳۰۷۲ بعدی ایجاد می‌کند.
& دستور را در پس‌زمینه اجرا می‌کند تا بتوانید در حالی که Vertex AI در حال پردازش جاسازی‌ها است، به کار خود ادامه دهید.

مانند اجرای قبلی فرآیند در پس‌زمینه، ترمینال فعلی گزارش فرآیند را نمایش می‌دهد. بیایید یک تب ترمینال جدید در Cloud Shell باز کنیم (روی آیکون + کلیک کنیم) تا بتوانیم بیشتر تمرکز کنیم.

دوباره به دایرکتوری کاری خود بروید و پروژه را با استفاده از اسکریپت راه‌اندازی قبلی فعال کنید.

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

سپس، می‌توانیم به فرآیند بعدی ادامه دهیم

۶. پیکربندی جعبه ابزار MCP برای پایگاه‌های داده

این مرحله جعبه ابزار MCP برای پایگاه‌های داده را معرفی می‌کند، آن را برای اتصال به نمونه Cloud SQL شما پیکربندی می‌کند و دو ابزار استاندارد پرس‌وجوی SQL را تعریف می‌کند.

MCP چیست و چرا از جعبه ابزار استفاده کنیم؟

MCP (پروتکل زمینه مدل) یک پروتکل باز است که نحوه کشف و تعامل عامل‌های هوش مصنوعی با ابزارهای خارجی را استاندارد می‌کند. این پروتکل یک مدل کلاینت-سرور را تعریف می‌کند: عامل میزبان یک کلاینت MCP است و ابزارها توسط سرورهای MCP در معرض دید قرار می‌گیرند. هر کلاینت سازگار با MCP می‌تواند از هر سرور سازگار با MCP استفاده کند - عامل برای هر ابزار به کد یکپارچه‌سازی سفارشی نیاز ندارد.

جعبه ابزار MCP برای پایگاه‌های داده، یک سرور MCP متن‌باز است که به‌طور خاص برای دسترسی به پایگاه داده ساخته شده است. بدون آن، شما باید توابع پایتونی بنویسید که اتصالات پایگاه داده را باز می‌کنند، مجموعه‌های اتصال را مدیریت می‌کنند، کوئری‌های پارامتری برای جلوگیری از تزریق SQL می‌سازند، خطاها را مدیریت می‌کنند و تمام آن کد را درون عامل خود جاسازی می‌کنند. هر عاملی که به دسترسی به پایگاه داده نیاز دارد، این کار را تکرار می‌کند. تغییر یک کوئری به معنای استقرار مجدد عامل است.

با Toolbox، شما یک فایل YAML می‌نویسید. هر ابزار به یک دستور SQL پارامتری نگاشت می‌شود. Toolbox ادغام اتصال، پرس‌وجوهای پارامتری، احراز هویت و مشاهده‌پذیری را مدیریت می‌کند. ابزارها از عامل جدا شده‌اند - یک پرس‌وجو را با ویرایش tools.yaml و راه‌اندازی مجدد Toolbox، بدون دست زدن به کد عامل، به‌روزرسانی کنید. همین ابزارها در ADK، LangGraph، LlamaIndex یا هر چارچوب سازگار با MCP کار می‌کنند.

پیکربندی ابزارها را بنویسید

حالا، باید فایلی به نام tools.yaml در ویرایشگر Cloud Shell ایجاد کنیم تا پیکربندی ابزارهایمان را تنظیم کنیم.

cloudshell edit tools.yaml

این فایل از YAML چند سندی استفاده می‌کند - هر بلوک جدا شده با --- یک منبع مستقل است. هر منبع یک kind دارد که ماهیت آن را اعلام می‌کند ( sources برای اتصالات پایگاه داده، tools برای اقدامات قابل فراخوانی توسط عامل) و یک type که backend را مشخص می‌کند ( cloud-sql-postgres برای منبع، postgres-sql برای ابزارهای مبتنی بر SQL). یک ابزار منبع خود را با name ارجاع می‌دهد، به این ترتیب Toolbox می‌داند که در کدام مخزن اتصال اجرا شود. متغیرهای محیطی از سینتکس ${VAR_NAME} استفاده می‌کنند و در هنگام راه‌اندازی حل می‌شوند.

حالا، بیایید اسکریپت‌های زیر را ابتدا در فایل 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}

---