توضّح هذه الصفحة كيفية إنشاء إضافة Google Workspace تعمل في Google Chat وتتفاعل مع وكيل ذكاء اصطناعي يستخدم بروتوكول Agent2Agent (A2A). يمكنك تطوير الوكيل باستخدام حزمة تطوير الوكيل (ADK) واستضافته في محرك وكلاء Vertex AI.
تستطيع وكلاء الذكاء الاصطناعي إدراك البيئة المحيطة بهم بشكل مستقل، والاستدلال المنطقي، وتنفيذ إجراءات معقّدة ومتعددة الخطوات لتحقيق هدف محدّد. في هذا البرنامج التعليمي، ستنفّذ نموذج LLM Auditor متعدد الوكلاء الذي يقيّم الحقائق ويراجعها باستخدام Gemini وتحديد المصدر من خلال "بحث Google".

يوضّح المخطّط التالي بنية النظام ونمط المراسلة:
في المخطّط، يتفاعل المستخدم مع تطبيق دردشة تم تنفيذه باستخدام وكيل A2A، ويكون تدفّق المعلومات على النحو التالي:
- يرسل مستخدم رسالة إلى تطبيق Chat، إما في رسالة مباشرة أو في مساحة Chat.
- تتلقّى منطق تطبيق Chat الذي يتم تنفيذه إما في Apps Script أو كخادم ويب مع نقاط نهاية HTTP الرسالة وتعالجها.
- يتلقّى الوكيل A2A المستضاف على "محرك وكلاء Vertex AI" التفاعل ويعالجه.
- يمكن للتطبيق Chat أو وكيل الذكاء الاصطناعي أن يتكامل مع خدمات Google Workspace، مثل "تقويم Google" أو "جداول بيانات Google"، أو خدمات Google الأخرى، مثل "خرائط Google" أو YouTube.
- يرسل تطبيق Chat الردود بشكل غير متزامن، ويستخدم واجهة برمجة التطبيقات Google Chat API لإعلامك بمدى تقدّم وكيل الذكاء الاصطناعي.
- يتم تسليم الردود إلى المستخدم.
الأهداف
- إعداد البيئة
- نشر وكيل A2A
- نشر تطبيق Chat
- ضبط إعدادات تطبيق Chat
- اختبِر تطبيق Chat.
المتطلبات الأساسية
- حساب Google Workspace Business أو Enterprise مع إمكانية الوصول إلى Google Chat
- مشروع Google Cloud تم تفعيل الفوترة فيه للتأكّد من تفعيل الفوترة في مشروع حالي، يُرجى الاطّلاع على التأكّد من حالة الفوترة في مشاريعك. لإنشاء مشروع وإعداد الفوترة، راجِع مقالة إنشاء مشروع على Google Cloud.
- المتطلبات الأساسية لوكيل LLM Auditor ADK
- Python 3.11 والإصدارات الأحدث: لتثبيت هذا الإصدار، اتّبِع التعليمات الواردة على موقع Python الإلكتروني الرسمي.
- Python Poetry: لتثبيت هذه الأداة، اتّبِع التعليمات الواردة على موقع Poetry الإلكتروني الرسمي.
- Google Cloud CLI: للتثبيت، اتّبِع التعليمات الواردة على موقع Google Cloud الإلكتروني الرسمي.
إعداد البيئة
تفعيل واجهات Google Cloud APIs
قبل استخدام واجهات Google APIs، عليك تفعيلها في مشروع على Google Cloud. يمكنك تفعيل واجهة برمجة تطبيق واحدة أو أكثر في مشروع واحد على Google Cloud.في Google Cloud Console، فعِّل واجهات برمجة التطبيقات Google Chat وVertex AI وCloud Resource Manager.
إعداد شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth
تتطلّب جميع التطبيقات التي تستخدم OAuth 2.0 إعداد شاشة موافقة. يؤدي ضبط شاشة موافقة OAuth في تطبيقك إلى تحديد ما سيظهر للمستخدمين ومراجعي التطبيق، كما يؤدي إلى تسجيل تطبيقك حتى تتمكّن من نشره لاحقًا.
- في "وحدة تحكّم Google Cloud"، انتقِل إلى "القائمة" > Google Auth platform > العلامة التجارية.
- إذا سبق لك ضبط Google Auth platform، يمكنك ضبط إعدادات "شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth" التالية في العلامة التجارية والجمهور والوصول إلى البيانات. إذا ظهرت لك الرسالة Google Auth platform لم يتم ضبطه بعد، انقر على البدء:
- ضمن معلومات التطبيق، في اسم التطبيق، أدخِل اسمًا للتطبيق.
- في حقل البريد الإلكتروني لدعم المستخدمين، اختَر عنوان بريد إلكتروني للدعم يمكن للمستخدمين التواصل معك من خلاله إذا كانت لديهم أسئلة حول موافقتهم.
- انقر على التالي.
- ضمن الجمهور، اختَر داخلي.
- انقر على التالي.
- ضمن معلومات الاتصال، أدخِل عنوان بريد إلكتروني يمكنك تلقّي إشعارات فيه بشأن أي تغييرات تطرأ على مشروعك.
- انقر على التالي.
- ضمن إنهاء، راجِع سياسة بيانات المستخدمين في خدمات Google API، وإذا كنت توافق عليها، ضَع علامة في المربّع أوافق على "سياسة بيانات المستخدمين في خدمات Google API".
- انقر على متابعة.
- انقر على إنشاء.
- يمكنك حاليًا تخطّي إضافة النطاقات. في المستقبل، عند إنشاء تطبيق لاستخدامه خارج مؤسسة Google Workspace، عليك تغيير نوع المستخدم إلى خارجي. بعد ذلك، أضِف نطاقات التفويض التي يتطلّبها تطبيقك. لمزيد من المعلومات، يُرجى الاطّلاع على الدليل الكامل حول ضبط موافقة OAuth.
إنشاء حساب خدمة في Google Cloud Console
أنشِئ حساب خدمة جديدًا بالدور Vertex AI User باتّباع الخطوات التالية:
Google Cloud Console
- في Google Cloud Console، انتقِل إلى "القائمة" > المشرف وإدارة الهوية وإمكانية الوصول > حسابات الخدمة.
- انقر على إنشاء حساب خدمة.
- املأ تفاصيل حساب الخدمة، ثم انقر على إنشاء ومتابعة.
- اختياري: يمكنك إسناد أدوار إلى حساب الخدمة لمنحه إذن الوصول إلى موارد مشروعك على Google Cloud. لمزيد من التفاصيل، يُرجى الرجوع إلى منح إذن الوصول إلى الموارد وتغييره وإبطاله.
- انقر على متابعة.
- اختياري: أدخِل المستخدمين أو المجموعات التي يمكنها إدارة حساب الخدمة هذا وتنفيذ إجراءات فيه. لمزيد من التفاصيل، يُرجى الاطّلاع على إدارة انتحال هوية حساب الخدمة.
- انقر على تم. دوِّن عنوان البريد الإلكتروني لحساب الخدمة.
gcloud CLI
- أنشئ حساب الخدمة:
gcloud iam service-accounts createSERVICE_ACCOUNT_NAME\ --display-name="SERVICE_ACCOUNT_NAME" - اختياري: يمكنك إسناد أدوار إلى حساب الخدمة لمنحه إذن الوصول إلى موارد مشروعك على Google Cloud. لمزيد من التفاصيل، يُرجى الرجوع إلى منح إذن الوصول إلى الموارد وتغييره وإبطاله.
يظهر حساب الخدمة في صفحة حساب الخدمة.
إنشاء مفتاح خاص
لإنشاء مفتاح خاص لحساب الخدمة وتنزيله، اتّبِع الخطوات التالية:
- في Google Cloud Console، انتقِل إلى "القائمة" > المشرف وإدارة الهوية وإمكانية الوصول > حسابات الخدمة.
- اختَر حساب الخدمة.
- انقر على المفاتيح > إضافة مفتاح > إنشاء مفتاح جديد.
- اختَر JSON، ثمّ انقر على إنشاء.
يتم إنشاء زوج المفتاح العام/الخاص وتنزيله على جهازك كملف جديد. احفظ ملف JSON الذي تم تنزيله باسم
credentials.jsonفي دليل العمل. هذا الملف هو النسخة الوحيدة من هذا المفتاح. للحصول على معلومات عن طريقة التخزين الآمن للمفتاح، راجِع إدارة مفاتيح حساب الخدمة. - انقر على إغلاق (Close).
لمزيد من المعلومات عن حسابات الخدمة، يُرجى الاطّلاع على حسابات الخدمة في مستندات "إدارة الهوية وإمكانية الوصول" في Google Cloud.
نشر وكيل A2A
إذا لم يسبق لك إجراء ذلك، عليك إثبات ملكية حسابك على Google Cloud وإعداد Google Cloud CLI لاستخدام مشروعك على Google Cloud.
gcloud auth application-default logingcloud config set project PROJECT_IDgcloud auth application-default set-quota-project PROJECT_IDاستبدِل PROJECT_ID بمعرّف مشروعك على Cloud.
نزِّل مستودع GitHub لعيّنات ADK باستخدام هذا الزر:
في بيئة التطوير المحلية المفضّلة لديك، استخرِج ملف الأرشيف الذي تم تنزيله وافتح الدليل
adk-samples/python/agents/llm-auditor.unzip adk-samples-main.zipcd adk-samples-main/python/agents/llm-auditorعدِّل عملية التنفيذ لنشر وكيل ADK كوكيل A2A بعيد:
pyproject.toml: أضِف عناصر اعتماد حزمة تطوير البرامج (SDK) الخاصة بـ "حزمة تطوير تطبيقات Android" و"التطبيق إلى التطبيق" في مجموعة النشر.
deployment/deploy.py: استبدِل عملية نشر تطبيق ADK بعميل A2A وبطاقة.
أنشِئ حزمة جديدة في Cloud Storage مخصَّصة لعامل ADK.
gcloud storage buckets create gs://CLOUD_STORAGE_BUCKET_NAME --project=PROJECT_ID --location=PROJECT_LOCATIONغيِّر القيم في السلسلة على الشكل التالي:
- استبدِل CLOUD_STORAGE_BUCKET_NAME باسم حزمة فريد تريد استخدامه.
- استبدِل PROJECT_ID بمعرّف مشروعك على السحابة الإلكترونية.
- استبدِل PROJECT_LOCATION بموقع مشروعك على السحابة الإلكترونية.
اضبط متغيرات البيئة التالية:
export GOOGLE_GENAI_USE_VERTEXAI=trueexport GOOGLE_CLOUD_PROJECT=PROJECT_IDexport GOOGLE_CLOUD_LOCATION=PROJECT_LOCATIONexport GOOGLE_CLOUD_STORAGE_BUCKET=CLOUD_STORAGE_BUCKET_NAMEغيِّر القيم في السلسلة على الشكل التالي:
- استبدِل CLOUD_STORAGE_BUCKET_NAME باسم الحزمة التي أنشأتها.
- استبدِل PROJECT_ID بمعرّف مشروعك على السحابة الإلكترونية.
- PROJECT_LOCATION مع الموقع الجغرافي لمشروعك على السحابة الإلكترونية.
تثبيت وكيل ADK ونشره من بيئة افتراضية
python3 -m venv myenvsource myenv/bin/activatepoetry install --with deploymentpython3 deployment/deploy.py --createاسترداد معرّف الوكيل ستحتاج إليه لاحقًا عند إعداد تطبيق Chat.
python3 deployment/deploy.py --list
إنشاء مشروع تطبيق Chat وإعداده
انقر على الزر التالي لفتح مشروع A2A AI Agent Quickstart في Apps Script.
انقر على نظرة عامة >
إنشاء نسخة.
في مشروع Apps Script، انقر على
إعدادات المشروع > تعديل خصائص النص البرمجي > إضافة خاصية نص برمجي لإضافة خصائص النص البرمجي التالية:
- استبدِل
REASONING_ENGINE_RESOURCE_NAMEباسم مورد وكيل Vertex AI الذي نسخته في الخطوات السابقة. - استبدِل
SERVICE_ACCOUNT_KEYبمفتاح JSON من حساب الخدمة الذي تم تنزيله في الخطوات السابقة، مثل{ ... }.
- استبدِل
انقر على حفظ مواقع النص البرمجي.
في وحدة تحكّم Google Cloud، انتقِل إلى "القائمة" > إدارة الهوية وإمكانية الوصول > الإعدادات.
في حقل رقم المشروع، انسخ القيمة.
في مشروع "برمجة التطبيقات"، انقر على
إعدادات المشروع.
ضمن مشروع Google Cloud Platform (GCP)، انقر على تغيير المشروع.
في رقم مشروع Google Cloud Platform، ألصِق رقم مشروع Google Cloud الذي نسخته في الخطوات السابقة.
انقر على تحديد المشروع. تم ربط مشروع Cloud بمشروع "برمجة التطبيقات".
إنشاء عملية نشر اختبارية
تحتاج إلى معرّف نشر لمشروع "برمجة تطبيقات Google" هذا، حتى تتمكّن من استخدامه في الخطوة التالية.
للحصول على رقم تعريف عملية نشر العنوان، اتّبِع الخطوات التالية:
- في مشروع "برمجة التطبيقات" لتطبيق Chat، انقر على نشر > اختبار عمليات النشر.
- ضمن رقم تعريف عملية نشر العنوان، انقر على
نسخ.
- انقر على تم.
ضبط إعدادات تطبيق Chat
باستخدام عملية نشر Apps Script، اتّبِع الخطوات التالية لنشر تطبيق Google Chat بغرض الاختبار:
- في
وحدة التحكّم،
ابحث عن
Google Chat API، ثم انقر على Google Chat API. - انقر على إدارة.
انقر على الإعداد وأعِدّ تطبيق Chat على النحو التالي:
- في حقل اسم التطبيق، أدخِل
A2A Quickstart. - في الحقل عنوان URL للصورة الرمزية، أدخِل
https://developers.google.com/workspace/add-ons/images/quickstart-app-avatar.png. - في حقل الوصف، أدخِل
A2A Quickstart. - ضمن الوظائف، اختَر الانضمام إلى المساحات والمحادثات الجماعية.
- ضِمن "إعدادات الربط"، اختَر مشروع "برمجة التطبيقات".
- في حقل رقم تعريف عملية النشر، ألصِق رقم تعريف عملية النشر الرئيسي الذي نسخته سابقًا.
- ضمن "إذن الوصول"، اختَر مستخدمون ومجموعات محدّدة في نطاقك، ثم أدخِل عنوان بريدك الإلكتروني.
- في حقل اسم التطبيق، أدخِل
انقر على حفظ.
تطبيق Chat جاهز للردّ على الرسائل.
اختبار تطبيق Chat
لاختبار تطبيق Chat، افتح مساحة رسالة مباشرة باستخدام تطبيق Chat وأرسِل رسالة:
افتح Google Chat باستخدام حساب Google Workspace الذي قدّمته عند إضافة نفسك كمختبِر موثوق به.
- انقر على محادثة جديدة.
- في حقل إضافة مستخدم واحد أو أكثر، اكتب اسم تطبيق Chat.
اختَر تطبيق Chat من النتائج. سيتم فتح رسالة مباشرة.
في الرسالة المباشرة الجديدة مع التطبيق، اكتب
The Eiffel Tower was completed in 1900واضغط علىenter.يردّ تطبيق Chat باستخدام ردود الوكيلَين الفرعيَين الناقد والمراجع.
لإضافة مختبِرين موثوق بهم والتعرّف على مزيد من المعلومات حول اختبار الميزات التفاعلية، يُرجى الاطّلاع على مقالة اختبار الميزات التفاعلية لتطبيقات Google Chat.
تحديد المشاكل وحلّها
عندما يعرض تطبيق أو بطاقة في Google Chat خطأً، تعرض واجهة Chat رسالة تفيد بحدوث خطأ. أو "لم نتمكّن من معالجة طلبك". في بعض الأحيان، لا تعرض واجهة مستخدم Chat أي رسالة خطأ، ولكن ينتج تطبيق Chat أو البطاقة نتيجة غير متوقّعة، مثلاً، قد لا تظهر رسالة البطاقة.
على الرغم من أنّه قد لا تظهر رسالة خطأ في واجهة مستخدم Chat، تتوفّر رسائل خطأ وصفية وبيانات سجلّات لمساعدتك في إصلاح الأخطاء عند تفعيل تسجيل الأخطاء لتطبيقات Chat. للحصول على مساعدة في عرض الأخطاء وتصحيحها وتحديد المشاكل فيها، يُرجى الاطّلاع على تحديد مشاكل Google Chat وحلّها.
تَنظيم
لتجنُّب تحمّل رسوم في حسابك على Google Cloud مقابل الموارد المستخدَمة في هذا البرنامج التعليمي، ننصحك بحذف مشروع Cloud.
- في Google Cloud Console، انتقِل إلى صفحة إدارة الموارد. انقر على القائمة > إدارة الهوية وإمكانية الوصول والمشرف > إدارة الموارد.
- في قائمة المشاريع، اختَر المشروع الذي تريد حذفه، ثم انقر على حذف .
- في مربّع الحوار، اكتب معرّف المشروع، ثم انقر على إيقاف لحذف المشروع.
مواضيع ذات صلة
- إنشاء تطبيق Google Chat باستخدام وكيل الذكاء الاصطناعي في "حزمة تطوير الوكلاء"
- التأكّد من صحة البيانات باستخدام وكيل الذكاء الاصطناعي في "حزمة تطوير التطبيقات" ونموذج Gemini
- تخطيط الرحلات باستخدام وكيل مستنِد إلى الذكاء الاصطناعي يمكن الوصول إليه في مختلف منتجات Google Workspace
- دمج المفاهيم الأساسية للذكاء الاصطناعي في تطبيقات Chat
- الإجابة عن الأسئلة استنادًا إلى محادثات Chat باستخدام تطبيق Gemini AI Chat
- الاستجابة للحوادث باستخدام Google Chat وVertex AI و"برمجة تطبيقات Google" ومصادقة المستخدم
- إدارة المشاريع باستخدام Google Chat وVertex AI وFirestore