تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

1. مقدمة

ما ستنشئه

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

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

ما ستتعلمه

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

المتطلبات

لإكمال هذا الدرس العملي، ستحتاج إلى ما يلي:

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

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

2. قبل البدء

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

إنشاء مشروع

في Google Cloud Console، ضمن صفحة اختيار المشروع، اختَر أو أنشِئ مشروعًا على Google Cloud.
تأكَّد من تفعيل الفوترة لمشروعك على Cloud. تعرَّف على كيفية التحقّق مما إذا كانت الفوترة مفعَّلة في مشروع .
فعِّل Cloud Shell من خلال النقر على هذا الرابط. يمكنك التبديل بين "نافذة Cloud Shell" (لتنفيذ أوامر السحابة الإلكترونية) و"المحرّر" (لإنشاء المشاريع) من خلال النقر على الزر المناسب من 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 Service Peering. يتيح ذلك لشبكة السحابة الإلكترونية الافتراضية الخاصة (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، لأنّه مطلوب لربط "إدارة الهوية وإمكانية الوصول".

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

بعد ذلك، امنح Vertex AI الإذن بالوصول إلى "وكيل خدمة AlloyDB" باتّباع الخطوات التالية:

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.

في "وحدة التحكّم" (Console)، انتقِل إلى حقل البحث في أعلى منتصف الشاشة وأدخِل "alloydb"، ثم عدِّل وانتقِل إلى قسم "الاتصال عبر عنوان IP العام" (Public IP connectivity). ضَع علامة في مربّع الاختيار "تفعيل عنوان 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

الرمز المصدر

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

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"
قاعدة البيانات: "المتجر"
كلمة المرور: "alloydb"

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

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

احتفِظ بالموقع الجغرافي كما هو في المثال
استخدِم عنوان البريد الإلكتروني نفسه الذي تستخدمه للتسجيل في 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 Setup

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

بما أنّ إحدى قواعد البيانات المتوافقة مع MCP Toolbox for Databases هي AlloyDB، وقد سبق أن وفّرنا هذه القاعدة في القسم السابق، لننتقل الآن إلى إعداد 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) في القسم التالي الذي سيستخدم هذه الأدوات.

لنبدأ بنشر "مجموعة الأدوات" على 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" لقواعد البيانات.

باستخدام "محرِّر 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 لتخزين صور حاويات Agent. نفِّذ الأمر التالي في 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، مساعدك للتسوّق من Google المستند إلى الذكاء الاصطناعي. يمكنني مساعدتك في العثور على المنتجات والمعدات الرياضية. كيف يمكننا مساعدتك اليوم؟"

في هذه المرحلة، تكون قد تحقّقت بنجاح من نشر AlloyDB وMCP Toolbox وAgent الذي تم إنشاؤه باستخدام 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 Agent، ومن اتصاله بـ 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"
قاعدة البيانات: "المتجر"
كلمة المرور: "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. تهانينا

تهانينا! لقد أنشأت بنجاح تطبيق ذكاء اصطناعي مستند إلى البيانات باستخدام "حزمة تطوير التطبيقات" و"مجموعة أدوات MCP لقواعد البيانات" وAlloyDB for PostgreSQL

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