قاعدة البيانات كأداة: التوليد المعزّز بالاسترجاع المستند إلى الوكيل باستخدام "حزمة تطوير التطبيقات" و"مجموعة أدوات MCP" وCloud SQL

1. مقدمة

تعتمد فائدة وكلاء الذكاء الاصطناعي على البيانات التي يمكنهم الوصول إليها. تتوفّر معظم البيانات الواقعية في قواعد البيانات، وعادةً ما يعني ربط الوكلاء بقواعد البيانات كتابة إدارة الاتصال ومنطق طلب البحث وتضمين خطوط الأنابيب داخل رمز الوكيل. ويكرّر كل وكيل يحتاج إلى الوصول إلى قاعدة البيانات هذه العملية، ويتطلّب كل تغيير في طلب البحث إعادة نشر الوكيل.

يوضّح هذا الدرس التطبيقي العملي أسلوبًا مختلفًا. يمكنك تحديد أدوات قاعدة البيانات في ملف YAML، مثل طلبات بحث SQL العادية، وبحث التشابه المتّجهي، وحتى إنشاء عمليات التضمين التلقائية، وتتولّى أداة MCP لقواعد البيانات جميع عمليات قاعدة البيانات كخادم MCP. يبقى رمز الوكيل بسيطًا: حمِّل الأدوات، ودَع Gemini يقرّر الأداة التي سيستخدمها.

ما ستنشئه

مساعد لوحة وظائف ذكية لـ "TechJobs": هو وكيل ADK يستند إلى Gemini ويساعد المطوّرين في تصفّح قوائم الوظائف في مجال التكنولوجيا باستخدام الفلاتر العادية (الدور، مجموعة التكنولوجيا) واكتشاف الوظائف من خلال أوصاف مكتوبة بلغة طبيعية، مثل "أريد وظيفة عن بُعد في مجال تطوير برامج الدردشة المستندة إلى الذكاء الاصطناعي". يقرأ الوكيل من قاعدة بيانات Cloud SQL PostgreSQL ويكتب فيها بالكامل من خلال MCP Toolbox for Databases، الذي يتعامل مع جميع عمليات الوصول إلى قاعدة البيانات، بما في ذلك إنشاء عمليات التضمين التلقائية للبحث المتّجه. في النهاية، سيتم تشغيل كلّ من "مجموعة الأدوات" و"الوكيل" على Cloud Run.

ما ستتعلمه

كيف يوحّد بروتوكول MCP (Model Context Protocol) إمكانية الوصول إلى الأدوات لوكلاء الذكاء الاصطناعي، وكيف تطبّق أداة MCP Toolbox لقواعد البيانات ذلك على عمليات قواعد البيانات
إعداد "مجموعة أدوات MCP لقواعد البيانات" كبرنامج وسيط بين وكيل ADK وCloud SQL PostgreSQL
تحديد أدوات قاعدة البيانات بشكل تعريفي في tools.yaml، بدون رمز قاعدة بيانات في الوكيل
إنشاء وكيل ADK يحمّل الأدوات من خادم Toolbox قيد التشغيل باستخدام ToolboxToolset
إنشاء تضمينات متجهة باستخدام الدالة المضمّنة embedding() في Cloud SQL وتفعيل البحث الدلالي باستخدام pgvector
استخدِم ميزة valueFromParam لإدخال المتجهات تلقائيًا في عمليات الكتابة
نشر كلّ من خادم Toolbox ووكيل ADK على Cloud Run

المتطلبات الأساسية

حساب Google Cloud يتضمّن حساب فوترة تجريبيًا
معرفة أساسية بلغة Python وSQL
لا يُشترط توفّر خبرة سابقة في "حزمة تطوير التطبيقات على Android" أو "مجموعة أدوات MCP" أو pgvector

2. إعداد البيئة

ملاحظات مهمة:

يتطلّب هذا البرنامج التعليمي مشروعًا على Google Cloud مع حساب فوترة نشط. إذا لم يكن لديك حساب بعد، يُرجى اتّباع الخطوات التالية للحصول على حساب فوترة تجريبي يمكن استخدامه في هذا البرنامج التعليمي:

فتح نافذة التصفُّح المتخفي
إذا كنت ستنضم إلى جلسة ورشة عمل، سيتم عادةً تقديم عنوان URL لبوابة الاسترداد في الجلسة، وإلا يمكنك الانتقال إلى بوابة استرداد حساب الفوترة التجريبي.
سجِّل الدخول باستخدام حسابك الشخصي على Gmail ( لن تعمل حسابات Google Workspace أو عناوين البريد الإلكتروني الأخرى). )
اتّبِع تعليمات الاسترداد خطوة بخطوة من أجل إنشاء مشروع جديد على Google Cloud مرتبط بحساب فوترة تجريبي تمّت المطالبة به سابقًا لهذا الفيديو التعليمي.

تجهّز هذه الخطوة بيئة Cloud Shell وتضبط مشروعك على Google Cloud وتستنسخ مستودع الرموز المرجعي.

فتح Cloud Shell

افتح Cloud Shell في المتصفّح. توفّر Cloud Shell بيئة مُعدّة مسبقًا تتضمّن جميع الأدوات التي تحتاج إليها في هذا الدرس العملي. انقر على تفويض عندما يُطلب منك ذلك

بعد ذلك، انقر على "عرض" -> "وحدة طرفية" لفتح الوحدة الطرفية.يجب أن تبدو واجهتك مشابهة لما يلي

ستكون هذه واجهتنا الرئيسية، مع وضع بيئة التطوير المتكاملة في الأعلى والوحدة الطرفية في الأسفل.

إعداد دليل العمل

أنشئ دليل العمل. يتم تخزين كل الرموز البرمجية التي تكتبها في هذا الدرس التطبيقي حول الترميز هنا:

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

إعداد مشروعك على Google Cloud

أنشئ ملف .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

Vertex AI API (aiplatform.googleapis.com): يستخدم الوكيل نماذج Gemini، وتستخدم "مجموعة الأدوات" واجهة برمجة التطبيقات الخاصة بالتضمين للبحث المتّجه.
واجهة برمجة التطبيقات Cloud SQL Admin (sqladmin.googleapis.com): يمكنك توفير مثيل PostgreSQL وإدارته.
Compute Engine API (compute.googleapis.com): مطلوب لإنشاء مثيلات Cloud SQL.
‫Cloud Run وCloud Build وArtifact Registry: يتم استخدامها في خطوة النشر لاحقًا في هذا الدرس التطبيقي حول الترميز

3- إنشاء مثيل قاعدة البيانات

تؤدي هذه الخطوة إلى إعداد عملية إنشاء مثيل 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 (وحدة معالجة مركزية افتراضية واحدة، وذاكرة وصول عشوائي سعتها 3.75 غيغابايت) في إصدار 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 الثنائي. يمكنك إجراء ذلك في نافذة الوحدة الطرفية نفسها.

تنزيل ملف Toolbox الثنائي

سنستخدم MCP Toolbox في هذا البرنامج التعليمي، ولحسن الحظ، يتضمّن ثنائيًا مسبق الإنشاء وجاهزًا للاستخدام في بيئة Linux. لننزّله في الخلفية لأنّ العملية تستغرق وقتًا طويلاً

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

السماح بتشغيل هذه العملية في علامة التبويب الحالية (نحن نشغّلها في الخلفية، ولكن سيظل يتم عرض الناتج). لنفتح علامة تبويب جديدة في نافذة Terminal في Cloud Shell (انقر على الرمز +) حتى نتمكّن من التركيز بشكل أكبر.

انتقِل إلى دليل العمل مرة أخرى وفعِّل المشروع باستخدام نص الإعداد البرمجي السابق.

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

تُعدّ هذه الخطوة مشروع Python وتثبّت التبعيات وتنشئ بنية دليل وكيل ADK.

4. إعداد "مشروع الوكيل"

إعداد مشروع Python

‫uv هو مدير حِزم ومشاريع سريع للغة Python مكتوب بلغة Rust ( مستندات uv). يستخدم هذا الدرس التطبيقي حول الترميز هذه الحزمة لتحقيق السرعة والبساطة.

ابدأ مشروع Python وأضِف التبعيات المطلوبة:

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

google-adk: حزمة تطوير الوكلاء من Google، بما في ذلك حزمة تطوير البرامج (SDK) الخاصة بـ Gemini
‫toolbox-adk: دمج ADK مع "مجموعة أدوات بروتوكول سياق النموذج لقواعد البيانات"

إنشاء بنية دليل الوكيل

يتوقّع 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/

5- تعبئة قاعدة بيانات بيانات الوظائف

تكتب هذه الخطوة البيانات الأولية، وتنتظر إلى أن تنتهي عملية توفير آلة Cloud SQL الافتراضية، وتحمّل الجدول jobs بـ 15 إعلانًا عن وظائف وتضمين أوصافها.

كتابة 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.');

يُثبِّت النص البرمجي الأوّلي إضافتَين إلى PostgreSQL:

‫google_ml_integration: توفّر دالة SQL embedding() التي تستدعي نماذج التضمين في Vertex AI مباشرةً من 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 بشكل مستمر. لنفتح علامة تبويب جديدة في نافذة Terminal في Cloud Shell (انقر على الرمز +) حتى نتمكّن من التركيز بشكل أكبر.

انتقِل إلى دليل العمل مرة أخرى وفعِّل المشروع باستخدام نص الإعداد البرمجي السابق.

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

بعد ذلك، شغِّل النص البرمجي الأوّلي.

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

من المفترض أن تظهر لك 15 إعلانًا وظيفيًا في أدوار متعددة:

             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، بدون الحاجة إلى نص برمجي بلغة Python أو حزمة 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): تستدعي نموذج تضمين Gemini في Vertex AI مباشرةً من SQL، مع تمرير نص description لكل وظيفة. هذه هي الإضافة google_ml_integration التي ثبَّتها في النص البرمجي الأوّلي.
::vector: تحويل مصفوفة الأرقام العشرية التي تم إرجاعها إلى نوع vector في pgvector حتى يمكن تخزينها والاستعلام عنها باستخدام عوامل تشغيل المسافة
يتم تشغيل UPDATE على جميع الصفوف الـ 15، ما يؤدي إلى إنشاء تضمين واحد ذي 3072 بُعدًا لكل وصف وظيفي.
ينفّذ الأمر & في الخلفية، ما يتيح لك مواصلة العمل أثناء معالجة Vertex AI لعمليات التضمين.

وكما هو الحال مع تنفيذ العمليات السابقة في الخلفية، ستعرض الوحدة الطرفية الحالية سجلّ العملية. لنفتح علامة تبويب جديدة في نافذة Terminal في Cloud Shell (انقر على الرمز +) حتى نتمكّن من التركيز بشكل أكبر.

انتقِل إلى دليل العمل مرة أخرى وفعِّل المشروع باستخدام نص الإعداد البرمجي السابق.

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

بعد ذلك، يمكننا الانتقال إلى العملية التالية.

6. ضبط إعدادات "مجموعة أدوات MCP" لقواعد البيانات

تقدّم هذه الخطوة "مجموعة أدوات MCP لقواعد البيانات"، وتضبطها للاتصال بمثيل Cloud SQL، وتحدّد أداتَين عاديتَين للاستعلام عن SQL.

ما هي "برنامج الشركاء المتعدّدين القنوات" (MCP) ولماذا يجب استخدام "صندوق الأدوات"؟

بروتوكول Model Context Protocol (MCP) هو بروتوكول مفتوح يوحّد طريقة عثور وكلاء الذكاء الاصطناعي على الأدوات الخارجية والتفاعل معها. يحدّد هذا البروتوكول نموذجًا للعميل والخادم: يستضيف الوكيل عميل MCP، وتوفّر خوادم MCP الأدوات. يمكن لأي برنامج متوافق مع MCP استخدام أي خادم متوافق مع MCP، ولا يحتاج البرنامج إلى رمز دمج مخصّص لكل أداة.

مجموعة أدوات MCP لقواعد البيانات هي خادم MCP مفتوح المصدر مصمَّم خصيصًا للوصول إلى قواعد البيانات. وبدونها، ستكتب دوال Python التي تفتح اتصالات بقاعدة البيانات، وتدير مجموعات الاتصالات، وتنشئ طلبات بحث ذات معلَمات لمنع اختراق SQL، وتعالج الأخطاء، وتضمّن كل هذا الرمز البرمجي داخل برنامجك. ويكرّر كل وكيل يحتاج إلى الوصول إلى قاعدة البيانات هذه العملية. يعني تغيير الاستعلام إعادة نشر الوكيل.

باستخدام Toolbox، يمكنك كتابة ملف YAML. ترتبط كل أداة بعبارة SQL ذات معلَمات. تتعامل "مجموعة الأدوات" مع تجميع الاتصالات، والاستعلامات التي تتضمّن مَعلمات، والمصادقة، وإمكانية المراقبة. الأدوات منفصلة عن الوكيل، ويمكنك تعديل طلب بحث من خلال تعديل tools.yaml وإعادة تشغيل Toolbox بدون تعديل رمز الوكيل. تعمل الأدوات نفسها على جميع إطارات العمل المتوافقة مع MCP، مثل ADK أو LangGraph أو LlamaIndex.

كتابة إعدادات الأدوات

الآن، علينا إنشاء ملف باسم tools.yaml في "محرّر Cloud Shell" لإعداد ضبط الأدوات.

cloudshell edit tools.yaml

يستخدم الملف YAML متعدد المستندات، وكلّ كتلة مفصولة بـ --- هي مورد مستقل. يحتوي كل مصدر على kind يوضّح نوعه (sources لعمليات ربط قواعد البيانات، وtools للإجراءات التي يمكن أن يستدعيها الوكيل) وtype يحدّد الخلفية (cloud-sql-postgres للمصدر، وpostgres-sql للأدوات المستندة إلى SQL). تشير الأداة إلى مصدرها باستخدام name، وهي الطريقة التي تعرف بها "مجموعة الأدوات" مجموعة الاتصال التي سيتم تنفيذها. تستخدم متغيرات البيئة بنية ${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}

---