إنشاء مساعد ذكاء اصطناعي لموظف دعم في متجر رياضي باستخدام ADK وMCP Toolbox وAlloyDB

1. مقدمة

ما ستنشئه

في هذا الدرس التطبيقي حول الترميز، ستتعرّف على كيفية إنشاء مساعد مستند إلى الذكاء الاصطناعي لمتجر لوازم الرياضة. سيساعد هذا التطبيق المستند إلى الذكاء الاصطناعي الوكيل من الجيل التالي، والذي يستند إلى ADK وMCP Toolbox وAlloyDB، المستخدمين في تنفيذ مهام مختلفة، بما في ذلك:

البحث عن المنتجات باستخدام اللغة الطبيعية
العثور على متاجر قريبة لشراء المنتجات المقترَحة
تقديم طلبات جديدة
التحقّق من حالات الطلبات الحالية
تعديل الطلبات باستخدام طرق التسليم المفضّلة

ما ستتعلمه

توفير قاعدة بيانات AlloyDB for PostgreSQL وتعبئتها
إعداد MCP Toolbox for Databases باستخدام مثيل AlloyDB for PostgreSQL
تصميم وكيل ذكاء اصطناعي وتطويره باستخدام "حزمة تطوير الوكلاء" (ADK) للمساعدة في الردّ على طلبات البحث في متجر لوازم رياضية
اختبار الوكيل وMCP Toolbox for Databases في بيئة سحابية
الاستفادة من إمكانات طلبات البحث المتقدّمة في AlloyDB للحصول على ردود ذكية من الوكيل

المتطلبات

لإكمال هذا الدرس التطبيقي حول الترميز، ستحتاج إلى:

متصفّح الويب Chrome
حساب Gmail
مشروع Google Cloud تم تفعيل الفوترة فيه

تم تصميم هذا الدرس التطبيقي حول الترميز للمطوّرين من جميع المستويات، بما في ذلك المبتدئين.

2. قبل البدء

يرشدك هذا القسم إلى عملية الإعداد الأوّلي المطلوبة في مشروعك على Google Cloud قبل أن تتمكّن من بدء إنشاء مساعد الذكاء الاصطناعي Sports Shop Agent.

إنشاء مشروع

في Google Cloud Console، ضمن صفحة اختيار المشروع، اختَر مشروعًا على Google Cloud أو أنشِئه.
تأكَّد من تفعيل الفوترة لمشروعك على السحابة الإلكترونية. تعرَّف على كيفية التحقّق مما إذا كانت الفوترة مفعَّلة في مشروع .
فعِّل Cloud Shell من خلال النقر على هذا الرابط. يمكنك التبديل بين Cloud Shell Terminal (لتنفيذ أوامر السحابة الإلكترونية) والمحرّر (لإنشاء المشاريع) من خلال النقر على الزر المناسب من Cloud Shell.

بعد الاتصال بـ Cloud Shell، يمكنك التأكّد من أنّك قد أثبتّ هويتك وأنّ المشروع مضبوط على رقم تعريف مشروعك باستخدام الأمر التالي:

gcloud auth list

نفِّذ الأمر التالي في Cloud Shell للتأكّد من أنّ أمر gcloud يعرف مشروعك.

gcloud config list project

اضبط المتغيّر PROJECT_ID باستخدام الأمر التالي:

export PROJECT_ID=[YOUR_PROJECT_ID]

gcloud config set project $PROJECT_ID

فعِّل واجهات برمجة التطبيقات التالية من خلال تنفيذ الأوامر التالية:

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

3- إنشاء مثيل AlloyDB

في هذا القسم، ستُعدّ مجموعة ومثيل قاعدة بيانات AlloyDB، وستضبط إعدادات الشبكات والأذونات اللازمة لـ "وكيل الذكاء الاصطناعي".

أولاً، نفِّذ الأمر التالي في وحدة Cloud Shell الطرفية لإنشاء مجموعة AlloyDB:

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

تعتمد AlloyDB على الاتصال عبر عناوين IP خاصة لتوفير وصول آمن وعالي الأداء. عليك تخصيص نطاق عناوين IP خاصة ضمن شبكتك VPC لتستخدمه Google في اتصال ربط الخدمة ببنية شبكة الخدمة التي تديرها Google. نفِّذ الأمر التالي:

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

بعد ذلك، أنشئ اتصال "تبادل معلومات بين شبكات VPC". يتيح ذلك لشبكة السحابة الإلكترونية الافتراضية الخاصة (VPC) في Google Cloud التواصل بأمان وخصوصية مع خدمات Google المُدارة، بما في ذلك AlloyDB. نفِّذ الأمر التالي:

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

الآن، أنشئ الآلة الافتراضية الأساسية ضمن مجموعة AlloyDB. هذه هي نقطة نهاية قاعدة البيانات الفعلية التي ستربط بها تطبيقاتك. نفِّذ الأمر التالي لإنشاء مثيل AlloyDB:

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

ملاحظة: قد يستغرق إنشاء الآلة الافتراضية حوالي 10 دقائق. يُرجى الانتظار حتى تنتهي هذه العملية قبل المتابعة.

تفعيل عملية الدمج مع Vertex AI

للسماح لآلة AlloyDB الافتراضية بتنفيذ طلبات البحث عن المتجهات (وهي ضرورية لوظائف الذكاء الاصطناعي، مثل البحث الدلالي) واستدعاء النماذج التي تم نشرها في Vertex AI، عليك منح أذونات Vertex AI إلى "وكيل خدمة AlloyDB".

أولاً، استردِد رقم مشروعك على Google Cloud، لأنّه مطلوب لربط إدارة الهوية وإمكانية الوصول (IAM).

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

بعد ذلك، امنح Vertex AI الإذن بالوصول إلى AlloyDB Service Agent:

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

تفعيل عنوان IP العلني

استعدادًا للخطوات التالية، سنفعّل ميزة "الاتصال عبر عنوان IP العام" في مثيل AlloyDB.

في "وحدة التحكّم"، انتقِل إلى حقل البحث في أعلى منتصف الشاشة وأدخِل "alloydb"، ثم عدِّل وانتقِل إلى قسم "الاتصال عبر عنوان IP العام". ضَع علامة في مربّع الاختيار "تفعيل عنوان IP العام" (Enable Public IP) وأدخِل عنوان IP لجهاز Cloud Shell.

للحصول على عنوان IP لجهاز Cloud Shell، انتقِل إلى "وحدة طرفية Cloud Shell" وأدخِل الأمر "ifconfig | grep -A 1 eth0". من النتيجة، استبدِل آخر رقمَين بالرقم 0.0 مع حجم قناع "‎/16". على سبيل المثال، سيبدو على النحو التالي: "XX.XX.0.0/16" حيث XX هي أرقام.

ألصِق عنوان IP هذا في مربّع النص "الشبكات" ضمن "الشبكات الخارجية المسموح بها" في صفحة تعديل المثيل.

ملاحظة: يمكن أن تستغرق عملية التعديل مدة تصل إلى 3 دقائق.

4. تحميل قاعدة البيانات

إنشاء قاعدة بيانات المتجر

حان الوقت الآن لإنشاء قاعدة البيانات وتحميل البيانات الأولية لمتجر Sports Shop.

لإتاحة اتصال psql بمثيل AlloyDB الخاص من Cloud Shell، عليك استخدام AlloyDB Auth Proxy. تتيح هذه الأداة إنشاء نفق آمن للاتصال بقاعدة البيانات. (يُرجى الرجوع إلى AlloyDB Auth Proxy)

نزِّل AlloyDB Auth Proxy باستخدام الأمر التالي:

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

أن تكون قابلة للتنفيذ:

chmod +x alloydb-auth-proxy

نفِّذ الأمر التالي في نافذة الوحدة الطرفية الأولى في Cloud Shell. سيتم تشغيل الخادم الوكيل في الخلفية وإعادة توجيه الاتصالات.

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

اتّبِع الخطوات التالية للاتصال بمثيل AlloyDB باستخدام psql:

psql -h 127.0.0.1 -U postgres

ملاحظة: عند المطالبة بذلك، أدخِل كلمة المرور التي ضبطتها للمستخدم postgres أثناء إنشاء المجموعة (إذا كنت تتّبع المستندات مباشرةً، تكون كلمة المرور alloydb).

وأنشئ قاعدة بيانات المتجر لتطبيقنا (نفِّذ الأوامر واحدًا تلو الآخر):

CREATE DATABASE store;
\c store
exit

Source Code

الآن، استنسِخ مستودع رمز المصدر الخاص بالتجربة العملية. تأكَّد من أنّك في دليل المنزل أو في موقع مناسب قبل استنساخ المستودع، ثم نفِّذ الأمر التالي:

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

ملء قاعدة البيانات

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

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

بعد ذلك، استورِد مجموعة البيانات النموذجية إلى قاعدة بيانات store باستخدام ملف store_backup.sql من المستودع.

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

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

5- إعداد خدمة التفويض

في هذا القسم، عليك إعداد خدمة التفويض لتطبيقك. هذه الخدمة ضرورية لتأمين الوصول وتوفير الحماية من ثغرات حقن التعليمات في "وكيل الذكاء الاصطناعي".

أولاً، ستضيف مستخدمًا نموذجيًا إلى جدول users في قاعدة بيانات store. سيتم استخدام هذا المستخدم للمصادقة في تطبيقك.

انتقِل إلى وحدة التحكّم وانتقِل إلى AlloyDB، واختَر الآلة الافتراضية الأساسية ثم AlloyDB Studio:

عندما يُطلب منك ذلك، سجِّل الدخول إلى AlloyDB Studio باستخدام بيانات الاعتماد التي أنشأتها عند إعداد المجموعة:

اسم المستخدم: "postgres"
قاعدة البيانات: "store"
كلمة المرور: "alloydb"

في "محرّر SQL"، نفِّذ عبارة INSERT لإضافة المستخدم إلى قاعدة البيانات. غيِّر الاسم واسم العائلة وعنوان البريد الإلكتروني.

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

اترك LOCATION كما هو في المثال
استخدِم عنوان البريد الإلكتروني نفسه الذي تستخدمه للتسجيل في Google Cloud Console.

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

بعد ذلك، عليك ضبط "شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth" لمشروعك. تظهر هذه الشاشة للمستخدمين عندما يطلب تطبيقك الوصول إلى حساب Google الخاص بهم، وتحدّد العلامة التجارية لتطبيقك.

في "وحدة التحكّم"، انتقِل إلى "واجهات برمجة التطبيقات والخدمات"، ثمّ إلى "موافقة Google OAuth":

قدِّم المعلومات التالية لإنشاء العلامة التجارية لتطبيقك:

اسم التطبيق: "Sports Shopping Agent AI"
البريد الإلكتروني المخصّص لدعم المستخدمين: "YOUR_EMAIL"
الجمهور: "خارجي"
معلومات الاتصال: "YOUR_EMAIL"

الآن، عليك إنشاء معرّف عميل OAuth الذي سيستخدمه تطبيق الواجهة الأمامية للتحقّق من هوية المستخدم مع Google.

أولاً، تأكَّد من توفّر رقم مشروع Google Cloud. هذا الإجراء مطلوب لإعداد معرّفات الموارد المنتظمة (URI) الخاصة بإعادة التوجيه بشكلٍ صحيح. نفِّذ الأمر التالي في "وحدة طرفية Cloud Shell":

في حال لم يتم ضبط المتغيّر PROJECT_ID في نافذة Cloud Shell Terminal هذه، نفِّذ ما يلي:

export PROJECT_ID=[YOUR_PROJECT_ID]

بعد ذلك، احصل على PROJECT_NUMBER باستخدام الأمر التالي:

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

بعد ذلك، انتقِل إلى "واجهات برمجة التطبيقات والخدمات" (APIs and Services) -> "بيانات الاعتماد" (Credentials) -> "إنشاء بيانات اعتماد" (Create Credentials) -> "معرّف عميل OAuth" (OAuth Client ID).

استخدِم المعلومات التالية لإنشاء بيانات الاعتماد:

نوع التطبيق: "تطبيق ويب"
الاسم: "تطبيق وكيل التسوّق الرياضي المستند إلى الذكاء الاصطناعي"

مصادر JavaScript المعتمَدة:

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

معرّفات الموارد المنتظمة (URI) المعتمَدة لإعادة التوجيه:

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

ملاحظة: عنوان URL https://finn-frontend-[YOUR_PROJECT_NUMBER].us-central1.run.app هو عنوان URL المتوقّع لعملية التفعيل لتطبيق الواجهة الأمامية، وسيتم إعداده لاحقًا في هذا الدرس التطبيقي حول الترميز. تأكَّد من استبدال [YOUR_PROJECT_NUMBER] بالرقم الفعلي الذي نسخته.

ملاحظة مهمة: بعد الإنشاء، ستظهر نافذة منبثقة تعرض معرّف عميل OAuth، وفي بعض الأحيان، سر العميل. احفظ معرّف عميل OAuth في مكان آمن، لأنّك ستحتاج إليه في خطوة لاحقة عند إعداد الواجهة الأمامية.

6. إعداد MCP ToolBox for Databases

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

بما أنّ AlloyDB هي إحدى قواعد البيانات المتوافقة مع MCP Toolbox for Databases، وقد سبق أن وفّرناها في القسم السابق، لننتقل الآن إلى إعداد Toolbox.

أولاً، عليك إعداد خادم MCP Toolbox محليًا في بيئة Cloud Shell للتحقّق من وظائفه.

في "وحدة Cloud Shell الطرفية"، انتقِل إلى المجلد toolbox ضِمن مستودع المشروع المستنسَخ:

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

نفِّذ الأوامر التالية لتنزيل ملف Toolbox الثنائي ومنحه أذونات التنفيذ:

# see releases page for other versions
export VERSION=0.16.0

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

chmod +x toolbox

ملاحظة: تم تحديد الإصدار 0.16.0 هنا. بالنسبة إلى بيئات الإنتاج، يُرجى التحقّق دائمًا من أحدث إصدار ثابت واستخدامه من صفحة إصدارات "مجموعة الأدوات".

انتقِل إلى "محرّر Cloud Shell" (يمكنك التبديل من "الوحدة الطرفية" من خلال النقر على رمز "المحرّر").

في دليل sports-agent-adk-mcp-alloydb/src/toolbox نفسه، ستعثر على ملف باسم tools.yaml. افتح هذا الملف وعدِّل العناصر النائبة باستخدام معرّف عميل OAuth ورقم تعريف مشروع Google Cloud من الخطوات السابقة.

لنتعرّف على ملف tools.yaml

تمثّل المصادر مصادر البيانات المختلفة التي يمكن أن تتفاعل معها إحدى الأدوات. يمثّل "المصدر" مصدر بيانات يمكن أن تتفاعل معه إحدى الأدوات. يمكنك تعريف المصادر كخريطة في قسم المصادر ضمن ملف tools.yaml. عادةً، سيحتوي إعداد المصدر على أي معلومات مطلوبة للاتصال بقاعدة البيانات والتفاعل معها.

تحدّد الأدوات الإجراءات التي يمكن أن يتّخذها الوكيل، مثل القراءة والكتابة في مصدر معيّن. تمثّل الأداة إجراءً يمكن أن يتّخذه الوكيل، مثل تنفيذ عبارة SQL. يمكنك تعريف "الأدوات" كخريطة في قسم الأدوات في ملف tools.yaml. عادةً، تتطلّب الأداة مصدرًا لتنفيذ الإجراءات.

لمزيد من التفاصيل حول ضبط ملف tools.yaml، يُرجى الرجوع إلى هذه المستندات.

تشغيل خادم MCP Toolbox لقواعد البيانات

نفِّذ الأمر التالي (من مجلد mcp-toolbox) لبدء الخادم:

./toolbox --tools-file "tools.yaml"

الآن، إذا فتحت الخادم في وضع معاينة الويب على السحابة الإلكترونية، من المفترض أن تتمكّن من رؤية خادم Toolbox يعمل ويتضمّن جميع أدوات تطبيقنا.

يتم تشغيل خادم MCP Toolbox تلقائيًا على المنفذ 5000. لنستخدم Cloud Shell لاختبار ذلك.

انقر على "معاينة الويب" في Cloud Shell كما هو موضّح أدناه:

انقر على "تغيير المنفذ" (Change port) واضبط المنفذ على 5000 كما هو موضّح أدناه، ثم انقر على "تغيير ومعاينة" (Change and Preview).

من المفترض أن يؤدي ذلك إلى ظهور الناتج التالي:

تصف "مجموعة أدوات MCP لقواعد البيانات" حزمة تطوير برامج (SDK) بلغة Python تتيح لك التحقّق من الأدوات واختبارها، ويمكنك الاطّلاع على مستنداتها هنا. سنتخطّى ذلك وسننتقل مباشرةً إلى "حزمة تطوير الوكلاء" (ADK) في القسم التالي الذي سيستخدم هذه الأدوات.

لنشر Toolbox على Cloud Run

لإتاحة الوصول إلى خادم Toolbox كنقطة نهاية عامة يمكن دمجها مع تطبيقات أخرى و"وكيل الذكاء الاصطناعي"، عليك نشره على Cloud Run. تتوفّر هنا تعليمات مفصّلة حول استضافة "مجموعة الأدوات" على Cloud Run.

ارجع إلى نافذة Cloud Shell وانتقِل إلى مجلد الأدوات:

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

تأكَّد من ضبط متغيّر البيئة PROJECT_ID على رقم تعريف مشروعك على Google Cloud.

export PROJECT_ID=$PROJECT_ID

بعد ذلك، تأكَّد من تفعيل خدمات Google Cloud التالية في المشروع.

gcloud services enable run.googleapis.com \
                       cloudbuild.googleapis.com \
                       artifactregistry.googleapis.com \
                       iam.googleapis.com \
                       secretmanager.googleapis.com

لننشئ حساب خدمة منفصلاً سيعمل كمعرّف لخدمة Toolbox التي سننشرها على Google Cloud Run. نحرص أيضًا على أن يكون لحساب الخدمة هذا الأدوار الصحيحة، أي القدرة على الوصول إلى Secret Manager والتواصل مع AlloyDB.

gcloud iam service-accounts create toolbox-identity

gcloud projects add-iam-policy-binding $PROJECT_ID \
   --member serviceAccount:toolbox-identity@$PROJECT_ID.iam.gserviceaccount.com \
   --role roles/secretmanager.secretAccessor


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


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

بعد ذلك، ستحمّل ملف tools.yaml كبيانات سرية، وبما أنّه علينا تثبيت Toolbox في Cloud Run، سنستخدم أحدث صورة حاوية لـ Toolbox ونضبطها في المتغيّر IMAGE.

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

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

أخيرًا، يمكنك نشر خادم Toolbox على Cloud Run باستخدام الأمر التالي. سيؤدي هذا الأمر إلى إنشاء حاوية لتطبيقك، وإعداد حساب الخدمة، وإدخال كلمة المرور، وإتاحتها للجميع:

gcloud run deploy toolbox \
--image $IMAGE \
--service-account toolbox-identity \
--region us-central1 \
--set-secrets "/app/tools.yaml=tools:latest" \
--args="--tools_file=/app/tools.yaml","--address=0.0.0.0","--port=8080" \
--allow-unauthenticated

من المفترض أن تبدأ هذه الخطوة عملية نشر Toolbox Server باستخدام ملف tools.yaml الذي تم إعداده على Cloud Run. عند اكتمال عملية النشر بنجاح، من المفترض أن تظهر لك رسالة مشابهة لما يلي:

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

يمكنك الآن الانتقال إلى عنوان URL الخاص بالخدمة والمدرَج أعلاه في المتصفّح. من المفترض أن يتم عرض الرسالة "Hello World" التي رأيناها سابقًا. بالإضافة إلى ذلك، يمكنك أيضًا الانتقال إلى عنوان URL التالي للاطّلاع على الأدوات المتاحة:

https://toolbox-[YOUR_PROJECT_NUMBER].us-central1.run.app/api/toolset

يمكنك أيضًا الانتقال إلى Cloud Run من وحدة تحكّم Google Cloud، وستظهر لك خدمة Toolbox ضِمن قائمة الخدمات في Cloud Run.

7. وكيل تم إنشاؤه باستخدام حزمة تطوير الوكلاء (ADK)

في هذا القسم، ستفعّل وكيل الذكاء الاصطناعي الذي تم إنشاؤه باستخدام "حزمة تطوير الوكلاء" (ADK) على Cloud Run.

أولاً، فعِّل واجهات برمجة التطبيقات اللازمة في مشروعك لإنشاء "الوكيل" ونشره على Cloud Run، وللتفاعل مع Artifact Registry وCloud Storage. نفِّذ الأمر التالي في "وحدة Cloud Shell الطرفية":

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

بعد ذلك، سنمنح الأذونات اللازمة إلى حساب خدمة Compute Engine التلقائي في مشروعنا. أولاً، نفِّذ الأمر التالي في وحدة Cloud Shell الطرفية للحصول على PROJECT_NUMBER:

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

منح أذونات لحساب خدمة Compute Engine التلقائي:

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

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

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

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

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

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

ربط الوكيل بالأدوات

سنربط الآن "الوكيل" بالأدوات. في سياق "مجموعة أدوات الذكاء الاصطناعي"، تمثّل الأداة إمكانية محدّدة يتم توفيرها لوكيل الذكاء الاصطناعي، ما يتيح له تنفيذ الإجراءات والتفاعل مع العالم الخارجي بما يتجاوز قدراته الأساسية في إنشاء النصوص والاستدلال.

في حالتنا، سنزوّد الوكيل الآن بالأدوات التي أعددناها في MCP Toolbox for Databases.

باستخدام "محرِّر Cloud Shell"، انتقِل إلى sports-agent-adk-mcp-alloydb/src/backend/ وعدِّل الملف "finn_agent.py" باستخدام الرمز التالي. يُرجى العِلم أنّنا نستخدم عنوان URL لخدمة Cloud Run من خادم MCP ToolBox الذي تم نشره في الخطوة السابقة:

نشر الوكيل على Cloud Run

أخيرًا، ستنشر وكيل الذكاء الاصطناعي الذي تم إعداده على Cloud Run، ما يتيح الوصول إليه من خلال نقطة نهاية HTTP.

أولاً، أنشئ مستودع Docker في Artifact Registry لتخزين صور حاويات الوكيل. نفِّذ الأمر التالي في Cloud Shell:

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

بعد ذلك، أنشئ صورة Docker للوكيل باستخدام Cloud Build. نفِّذ الأمر التالي من دليل الجذر للمشروع الذي نسخته (sports-agent-adk-mcp-alloydb/):

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

الآن، يمكنك نشر خدمة "الوكيل". سيؤدي هذا الأمر إلى إنشاء خدمة Cloud Run وسحب الصورة من Artifact Registry وإعداد متغيّرات البيئة.

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

ملاحظة: نعمل على ضبط متغيّرات البيئة بشكلٍ ديناميكي، بما في ذلك GOOGLE_CLOUD_PROJECT (باستخدام متغيّر shell $PROJECT_ID)

من المفترض أن تظهر لك نتيجة مشابهة لما يلي، ما يشير إلى أنّ عملية نشر الوكيل تمت بنجاح:

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

أخيرًا، اختبِر الوكيل من خلال تنفيذ الأمر curl التالي من "وحدة Cloud Shell الطرفية":

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

ستظهر لك نتيجة مشابهة لما يلي:

"مرحبًا. أنا Finn، مساعدك للتسوق الرياضي المستند إلى الذكاء الاصطناعي. يمكنني مساعدتك في العثور على المنتجات والمعدّات الرياضية. كيف يمكنني مساعدتك اليوم؟"

في هذه المرحلة، تكون قد تحقّقت بنجاح من عملية نشر AlloyDB وMCP Toolbox والوكيل الذي تم إنشاؤه باستخدام ADK.

8. نشر الواجهة الأمامية

في هذا القسم، ستنشر واجهة المستخدم الحوارية لمساعدك المستند إلى الذكاء الاصطناعي على Cloud Run. تم إنشاء هذه الواجهة الأمامية باستخدام React وJavaScript.

قبل النشر، عليك تعديل الرمز المصدر للواجهة الأمامية باستخدام عناوين URL الخاصة بالوكيل الذي تم نشره ورقم تعريف عميل OAuth.

باستخدام "محرِّر Cloud Shell"، انتقِل إلى sports-agent-adk-mcp-alloydb/src/frontend/src/pages/ وافتح الملف Home.jsx. عليك تعديل العنصر النائب لعنوان URL الخاص بخدمة Cloud Run للوكيل. بعد ذلك، استبدِلها بعنوان URL لخدمة Cloud Run الخاصة بالوكيل من الخطوة السابقة (على سبيل المثال، https://finn-agent-[YOUR_PROJECT_NUMBER].us-central1.run.app).

الآن، انتقِل إلى sports-agent-adk-mcp-alloydb/src/frontend/src/components/ وافتح الملف GoogleSignInButton.jsx. ستعدّل هذا الملف باستخدام معرّف عميل OAuth الذي حصلت عليه في قسم "إعداد خدمة التفويض" على النحو التالي:

نشر الواجهة الأمامية على Cloud Run

بعد إعداد تطبيق الواجهة الأمامية، يمكنك نشره على Cloud Run.

نفِّذ الأمر التالي في "وحدة طرفية Cloud Shell" من الدليل الجذر (sports-agent-adk-mcp-alloydb/) لإنشاء مستودع Docker في Artifact Registry لصور الواجهة الأمامية.

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

بعد ذلك، أنشئ صورة Docker لتطبيق الواجهة الأمامية باستخدام Cloud Build. نفِّذ الأمر التالي من دليل الجذر الخاص بمشروعك:

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

أخيرًا، سننفذ الواجهة الأمامية على Cloud Run باستخدام الأمر التالي:

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

من المفترض أن تظهر لك نتيجة مشابهة لما يلي، ما يشير إلى أنّ عملية نشر الواجهة الأمامية تمت بنجاح:

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

افتح متصفّح الويب واستخدِم عنوان URL الخاص بالخدمة من الخطوة السابقة لفتح التطبيق الذي تم نشره حديثًا، والذي يعمل بواسطة "وكيل الذكاء الاصطناعي".

9- تشغيل الوكيل

تم الآن نشر مساعد الذكاء الاصطناعي "فين" في "متجر الرياضة" وأصبح جاهزًا للمساعدة في عمليات الشراء.

افتح متصفّح الويب وانتقِل إلى عنوان URL الخاص بالخدمة لتطبيق الواجهة الأمامية من الخطوة السابقة. يتّبع عنوان URL التنسيق التالي: https://finn-frontend-[YOUR_PROJECT_NUMBER].us-central1.run.app

بعد تحميل الواجهة الأمامية، انقر على الزر في أعلى يسار الصفحة (عادةً ما يكون مصنّفًا على أنّه "تسجيل الدخول" أو طلب مشابه) للمصادقة باستخدام بيانات اعتماد Google. سيستفيد هذا الإجراء من إعدادات OAuth التي سبق لك إعدادها.

بعد إكمال عملية المصادقة بنجاح، يمكنك بدء التفاعل مع Finn. انقر على الزر "التسوّق الآن" لبدء تجربة التسوّق الحواري.

استخدِم النص البرمجي التالي لاختبار الوظائف المختلفة لـ "وكيل الذكاء الاصطناعي". انسخ هذه الطلبات والصقها في واجهة المحادثة واحدًا تلو الآخر:

مرحبًا "فين"!
أبحث عن أحذية جري مناسبة للمسارات الطويلة جدًا
أريد المزيد من التفاصيل حول Ultra Glide
أريد إضافة حذاء Ultra Glide، المقاس 40، اللون أحمر/رمادي إلى قائمة التسوّق
عرض قائمة التسوّق
البحث عن متاجر بالقرب مني
يُرجى تقديم طلب باستخدام قائمة التسوّق الخاصة بي من متجر Sports Diagonal Mar
التحقّق من حالة طلباتي
يُرجى إدراج طرق التسليم لمتجر Sports Diagonal Mar
تعديل طريقة التسليم إلى "التسليم السريع" للطلب [YOUR_ORDER_NUMBER]
التحقّق من حالة طلباتي
شكرًا "فين".

للحصول على عرض مرئي لوكيل Finn Agent الذي تم نشره وإمكاناته، يمكنك مشاهدة الفيديو أدناه:

عرض توضيحي لمساعد مستند إلى الذكاء الاصطناعي لوكيل رياضي يستخدِم AlloyDB

10. النتائج

بعد تنفيذ النص البرمجي السابق، تكون قد تحقّقت بنجاح من عملية الدمج الكاملة لـ "وكيل ADK"، ومن إمكانية اتصاله بـ AlloyDB، ومن استخدامه لـ MCP Toolbox. يسلّط هذا القسم الضوء على الإمكانات الأساسية التي نفّذتها.

خدمة التفويض

توفّر أداة MCP لقواعد البيانات إمكانية ربط خدمة مصادقة (تحديدًا، "تسجيل الدخول باستخدام حساب Google" في هذا الدرس التطبيقي حول الترميز) لمصادقة المستخدمين داخل تطبيقك. باستخدام MCP Toolbox، يتم استخدام معرّف عميل OAuth للتحقّق من هوية المستخدم عند استدعاء إحدى الأدوات.

تقدّم آلية المصادقة القوية هذه حلاً ممتازًا لحماية تطبيقك المستند إلى وكيل من هجمات حقن الطلبات، وهي نوع من الهجمات التي تحاول فيها الإدخالات الضارة تجاوز السلوك المقصود للوكيل أو التلاعب به. لمزيد من التفاصيل، يمكنك الرجوع إلى مقالة ويكيبيديا حول هجمات حقن التعليمات .

في هذا التطبيق، يتم استخدام هذه التقنية عندما يطلب المستخدم "التحقّق من حالة طلباتنا" أو "عرض قائمة التسوّق". تم تصميم الوكيل لعرض الطلبات التي تخص المستخدم الذي تمّت المصادقة عليه فقط، ما يمنع الوصول غير المصرَّح به إلى معلومات الطلبات.

البحث عن المتّجهات

يستفيد تطبيقك المستند إلى الوكلاء من AlloyDB for PostgreSQL لتوفير إمكانات طلبات بحث متقدّمة، لا سيما من خلال البحث المتّجه. تتيح AlloyDB إنشاء عمليات التضمين على الإنترنت مباشرةً داخل قاعدة البيانات باستخدام دوال SQL.

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

في تطبيقك، يمكنك تجربة هذه التقنية عندما تسأل Finn: "أبحث عن أحذية رياضية للجري في مسار طويل جدًا".

إمكانات البيانات الجغرافية المكانية (PostGis)

تحافظ خدمة AlloyDB for PostgreSQL على توافق بنسبة% 100 مع ميزات PostgreSQL العادية. في هذا التطبيق، نستخدم إضافة PostgreSQL الشائعة PostGIS لتوفير إمكانات الموقع الجغرافي المكاني للوكيل.

عندما تطلب من الوكيل: "العثور على متاجر بالقرب مني"، ينفّذ الوكيل أداة تستفيد من فهارس PostGIS داخل قاعدة البيانات لتحديد المتاجر الأقرب إلى الموقع الجغرافي المحدّد أو المستنتَج للمستخدم بكفاءة.

11. (اختياري) اختبار ميزة "اللغة الطبيعية إلى SQL" في AlloyDB AI

يعرض هذا القسم ميزة متقدّمة في مرحلة ما قبل التوفّر للجمهور العام من AlloyDB for PostgreSQL، وهي تحويل اللغة الطبيعية إلى لغة الاستعلامات البنيوية (SQL). تتيح لك هذه الميزة إنشاء طلبات بحث SQL مباشرةً من طلبات اللغة الطبيعية، ما يتيح لك الاستفادة من إمكانات الذكاء الاصطناعي داخل قاعدة البيانات.

ملاحظة مهمة: بما أنّ هذه الميزة في مرحلة ما قبل التوفّر للجمهور العام، يجب الاشتراك فيها وتفعيل إمكانية الوصول إليها لمشروعك على Google Cloud ومجموعة AlloyDB وقاعدة البيانات.

التسجيل للحصول على إذن الوصول: يُرجى اتّباع هذا النموذج لطلب إذن الوصول إلى مشروعك.
المستندات: يمكنك الاطّلاع على مزيد من المعلومات حول الاستفادة من ميزة "اللغة الطبيعية إلى SQL" في AlloyDB AI في المستندات الرسمية.

بعد الاشتراك وتأكيد إمكانية الوصول إلى مشروعك، اتّبِع الخطوات التالية في AlloyDB Studio.

سجِّل الدخول إلى AlloyDB باستخدام بيانات الاعتماد التي أنشأتها عند إنشاء المجموعة:

اسم المستخدم: "postgres"
قاعدة البيانات: "store"
كلمة المرور: "alloydb"

‫1- أنشئ إضافة alloydb_ai_nl. توفّر هذه الإضافة الوظائف اللازمة لإمكانات اللغة الطبيعية في AlloyDB AI.

CREATE EXTENSION alloydb_ai_nl cascade;

‫2- أنشئ إعدادًا لتطبيقك. يحدّد الإعداد سياق المخطط الذي سيستخدمه نموذج الذكاء الاصطناعي لفهم قاعدة البيانات.

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

‫3- سجِّل المخطّط أو الجداول باستخدام الإعدادات. أضِف الجداول والمخططات المحدّدة التي سيتفاعل معها وكيل تطبيقك إلى الإعدادات.

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

‫4- إنشاء سياق للمخطط / الجداول تعالج هذه الخطوة الجداول المسجّلة لإنشاء السياق اللازم لنموذج الذكاء الاصطناعي. قد تستغرق هذه العملية دقيقتَين أو ثلاث دقائق تقريبًا.

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

‫5- راجِع السياق الذي تمّ إنشاؤه تلقائيًا لجداول وأعمدة معيّنة (اختياري). يمكنك فحص السياق الذي تم إنشاؤه لفهم الطريقة التي يفسّر بها نموذج الذكاء الاصطناعي المخطط الخاص بك.

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


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


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

ستجد أداة باسم "check-inventory-by-store-brand-category" في ملف "tools.yaml" الخاص ببرنامج Agent. تستخدم هذه الأداة ميزة "اللغة الطبيعية إلى SQL" في AlloyDB:

افتح متصفّح ويب، واستخدِم عنوان URL للخدمة لفتح التطبيق: "https://finn-frontend-[YOUR_PROJECT_NUMBER].us-central1.run.app"

بعد ذلك، استخدِم النص البرمجي التالي في واجهة المحادثة لاختبار هذه الإمكانية الجديدة:

مرحبًا "فين"!
ما هو إجمالي كمية منتجات فئة "الركض" من Salomon المتوفّرة في المتجر "Sports Diagonal Mar"؟

للاطّلاع على استعلام SQL الفعلي الذي أنشأته AlloyDB AI من إدخالك باللغة الطبيعية، ارجع إلى AlloyDB Studio ونفِّذ الاستعلام التالي:

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

سيؤدي ذلك إلى عرض عبارة SQL التي أنشأتها AlloyDB AI.

12. تنظيف

لتجنُّب تحمّل رسوم في حسابك على Google Cloud مقابل الموارد المستخدَمة في هذا الدرس التطبيقي، اتّبِع الخطوات التالية:

في Google Cloud Console، انتقِل إلى صفحة إدارة الموارد.
في قائمة المشاريع، اختَر المشروع الذي تريد حذفه، ثم انقر على "حذف".
في مربّع الحوار، اكتب رقم تعريف المشروع، ثم انقر على "إيقاف" لحذف المشروع.

13. تهانينا

تهانينا! لقد أنشأت بنجاح تطبيقًا مستندًا إلى الذكاء الاصطناعي الوكيل ومستندًا إلى البيانات باستخدام ADK وMCP Toolbox for Databases وAlloyDB for PostgreSQL

لمزيد من المعلومات، يُرجى الرجوع إلى مستندات المنتج: Agent Development Kit و MCP Toolbox for Databases و AlloyDB for PostgreSQL.