التخطيط للسفر باستخدام وكيل مستند إلى الذكاء الاصطناعي يمكن الوصول إليه في جميع تطبيقات Google Workspace

مستوى الترميز: متقدّم
المدة: 45 دقيقة
نوع المشروع: إضافة Google Workspace توسّع نطاق Chat وGmail وتقويم Google وDrive ومستندات Google وجداول بيانات Google والعروض التقديمية من Google

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

نظرة عامة

في هذا البرنامج التعليمي، ستنشئ نموذج Travel Concierge من حزمة تطوير الوكلاء (ADK). ‫Travel Concierge هو ذكاء اصطناعي حواري متعدد الوكلاء يستخدم أدوات مثل Places API من Google Maps Platform، وGoogle Search Grounding، وخادم Model Context Protocol (MCP).

توفّر حزمة تطوير التطبيقات (ADK) واجهات للدردشة والنصوص للمطوّرين تلقائيًا. في هذا الدليل التعليمي، ستضيف واجهة مستخدم تصويرية (GUI) إلى تطبيقات Google Workspace يمكن للمستخدمين الوصول إليها مباشرةً في Chat وGmail و"تقويم Google" وDrive و"مستندات Google" و"جداول بيانات Google" و"العروض التقديمية من Google".

• 

  الشكل 1. استخدام وكيل الذكاء الاصطناعي من Chat لاستلهام أفكار حول السفر

• 

  الشكل 2. استخدام وكيل الذكاء الاصطناعي من Gmail لتخطيط رحلة من السياق الوارد في الرسالة الإلكترونية المحدّدة

الأهداف

• إعداد البيئة
• انشر وكيل الذكاء الاصطناعي.
• إعداد المشروع
• يمكن نشرها في Gmail و"تقويم Google" وDrive و"مستندات Google" و"جداول بيانات Google" و"العروض التقديمية من Google".
• نشر التطبيق في Chat
• اختبِر الحلّ.

لمحة عن هذا الحلّ

يعتمد هذا الحلّ على التقنيات الأساسية التالية: حزمة تطوير التطبيقات (ADK) وGoogle Cloud وواجهات برمجة التطبيقات في Google Workspace وVertex AI Agent Engine وإطار عمل البطاقات.

تم تصميم واجهات المستخدم الرسومية بشكل مختلف لتطبيقات Chat والتطبيقات الأخرى (Gmail و"تقويم Google" وDrive و"مستندات Google" و"جداول بيانات Google" و"العروض التقديمية من Google") لمراعاة ميزاتها وقيودها المحدّدة.

الميزات

تتوفّر ميزات تطبيق "مساعد السفر" التالية في جميع تطبيقات Google Workspace:

• جلسات المستخدمين الدائمة: تدير Vertex AI الجلسات لضمان استمرارها. يشارك كل مستخدم جلسة واحدة في جميع تطبيقات Workspace. يمكن للمستخدمين إعادة ضبط الجلسة يدويًا لبدء محادثة جديدة.

• المراسلة التفاعلية: يرسل المستخدمون رسائل نصية ويتلقّون ردودًا تتضمّن نصوصًا تفاعلية وأدوات على شكل بطاقات.

• التعامل مع الأخطاء: يتم التعامل مع الأخطاء غير المتوقّعة بشكل سليم باستخدام عمليات إعادة المحاولة والحالات القابلة للضبط في الردود.

يتضمّن تطبيق Chat الميزات الإضافية التالية:

• مراسلة المستخدمين باستخدام وسائط متعددة: يمكن للمستخدمين إرسال رسائل تتضمّن مرفقات، بما في ذلك الصوت والفيديو المسجّلان مباشرةً من مساحة Chat.

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

تتضمّن التطبيقات الأخرى الميزات الإضافية التالية:

• سياق الملف الشخصي في حساب Google: يمكن للمستخدمين إرسال رسائل تتضمّن معلومات ملفهم الشخصي (تقتصر على أعياد الميلاد في هذا المثال).

• سياق Gmail: يمكن للمستخدمين إرسال رسائل مع رسائل إلكترونية (يقتصر ذلك على موضوع واحد ونص واحد في هذا المثال).

• إمكانية وصول الوكيل إلى مساحة Chat: يمكن للمستخدمين فتح مساحة الرسائل المباشرة في تطبيق Chat في علامة تبويب جديدة بنقرة زر واحدة.

الهندسة المعمارية

يتلقّى تطبيق Travel Concierge أحداث التفاعل مع إضافة Google Workspace ويعالجها من تطبيقات Google Workspace، ويستخدم Vertex AI لطلب المساعدة من وكيل الذكاء الاصطناعي في ADK وإدارة جلسات المستخدمين، ويعتمد على واجهات برمجة التطبيقات في Google Cloud وGoogle Workspace لجمع السياق وعرض الردود.

تعرض المخططات التالية تدفق المستخدم الرئيسي: إرسال رسالة إلى وكيل الذكاء الاصطناعي.

HTTP

• 

  الشكل 3. يكمل تطبيق Chat السياق بالمرفقات من رسالة المستخدم، ويرسل مجموعة من الرسائل تتضمّن سجلّ تفاعلات الوكيل الفرعي والإجابة النهائية الشاملة بترتيب زمني.

• 

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

برمجة التطبيقات

• 

  الشكل 3. يكمل تطبيق Chat السياق بالمرفقات من رسالة المستخدم، ويرسل مجموعة من الرسائل تتضمّن سجلّ تفاعلات الوكيل الفرعي والإجابة النهائية الشاملة بترتيب زمني.

• 

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

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

• حساب Google Workspace تابع لـ Business أو Enterprise مع إمكانية الوصول إلى Google Chat

• متصفّح ويب يمكنه الوصول إلى الإنترنت

• المتطلبات الأساسية الخاصة بوكيل الذكاء الاصطناعي في حزمة تطوير التطبيقات (ADK) الخاصة بخدمة Travel Concierge

  • ‫Python 3.10 والإصدارات الأحدث: لتثبيت هذه اللغة، اتّبِع التعليمات الواردة على موقع Python الإلكتروني الرسمي.
  • uv: لتثبيت التطبيق، اتّبِع التعليمات الواردة على موقع uv الإلكتروني الرسمي.
  • ‫Google Cloud CLI: لتثبيت هذه الأداة، اتّبِع التعليمات الواردة على موقع Google Cloud الإلكتروني الرسمي.

تجهيز البيئة

يوضّح هذا القسم كيفية إنشاء مشروع على Google Cloud وإعداده.

إنشاء مشروع على Google Cloud

وحدة تحكّم Google API

1. في Google API Console، انتقِل إلى "القائمة" > إدارة الهوية وإمكانية الوصول (IAM) والمشرف > إنشاء مشروع.

   الانتقال إلى صفحة "إنشاء مشروع"

2. في حقل اسم المشروع، أدخِل اسمًا وصفيًا لمشروعك.

   اختياري: لتعديل رقم تعريف المشروع، انقر على تعديل. لا يمكن تغيير رقم تعريف المشروع بعد إنشائه، لذا اختَر رقم تعريف يلبي احتياجاتك طوال مدة المشروع.

3. في حقل الموقع الجغرافي، انقر على تصفّح لعرض المواقع الجغرافية المحتملة لمشروعك. بعد ذلك، انقر على اختيار.
   تنبيه: يتعذّر العثور على مؤسستك على Google Workspace؟
   هذا يعني أنّك لست مسجّلاً الدخول إلى حساب Google Workspace. لا تتوفّر بعض الميزات الموضّحة في مستندات مطوّري Google Workspace إلا للمشاريع المرتبطة بمؤسسة.
4. انقر على إنشاء. ستنتقل وحدة تحكّم Google API إلى صفحة "لوحة البيانات"، وسيتم إنشاء مشروعك في غضون بضع دقائق.

gcloud CLI

في إحدى بيئات التطوير التالية، يمكنك الوصول إلى واجهة سطر الأوامر (CLI) في Google Cloud (gcloud):

• Cloud Shell: لتفعيل Cloud Shell واستخدام وحدة طرفية على الإنترنت مع إعداد واجهة سطر الأوامر gcloud مسبقًا
  تفعيل Cloud Shell
• Local Shell: لاستخدام بيئة تطوير على الجهاز، عليك تثبيت وإعداد gcloud CLI.
  لإنشاء مشروع على السحابة الإلكترونية، استخدِم الأمر gcloud projects create:

  gcloud projects create PROJECT_ID

  استبدِل PROJECT_ID بضبط رقم تعريف المشروع الذي تريد إنشاءه.

تفعيل الفوترة لمشروع على السحابة الإلكترونية

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

وحدة تحكّم Google API

1. في Google API Console، انتقِل إلى الفوترة. انقر على القائمة > الفوترة > مشاريعي.

   الانتقال إلى "الفوترة لمشاريعي"

2. في اختيار مؤسسة، اختَر المؤسسة المرتبطة بمشروعك على Google Cloud.
3. في صف المشروع، افتح قائمة الإجراءات ()، ثم انقر على تغيير الفوترة واختَر حساب Cloud Billing.
4. انقر على ضبط الحساب.

gcloud CLI

1. لعرض قائمة بحسابات الفوترة المتاحة، نفِّذ الأمر التالي:

   gcloud billing accounts list

2. ربط حساب فوترة بمشروع على Google Cloud:

   gcloud billing projects link PROJECT_ID --billing-account=BILLING_ACCOUNT_ID

   غيِّر القيم في السلسلة على الشكل التالي:

   • PROJECT_ID هو رقم تعريف المشروع لمشروع على السحابة الإلكترونية الذي تريد تفعيل الفوترة فيه.
   • BILLING_ACCOUNT_ID هو رقم تعريف حساب الفوترة الذي سيتم ربطه بمشروع Google Cloud.

تفعيل واجهات Google Cloud APIs

HTTP

1. في Google API Console، فعِّل واجهات برمجة التطبيقات Vertex AI وPlaces وPeople وGoogle Chat وGmail وCloud Build وCloud Functions وCloud Pub/Sub وCloud Logging وArtifact Registry وCloud Run وإضافات Google Workspace وCloud Resource Manager.

   تفعيل واجهات برمجة التطبيقات

2. تأكَّد من أنّك بصدد تفعيل واجهات برمجة التطبيقات في مشروع على السحابة الإلكترونية الصحيح، ثم انقر على التالي.

3. تأكَّد من تفعيل واجهات برمجة التطبيقات الصحيحة، ثم انقر على تفعيل.

برمجة التطبيقات

1. في Google API Console، فعِّل واجهات برمجة التطبيقات Vertex AI وPlaces وPeople وGoogle Chat وCloud Resource Manager.

   تفعيل واجهات برمجة التطبيقات

2. تأكَّد من أنّك بصدد تفعيل واجهات برمجة التطبيقات في مشروع على السحابة الإلكترونية الصحيح، ثم انقر على التالي.

3. تأكَّد من تفعيل واجهات برمجة التطبيقات الصحيحة، ثم انقر على تفعيل.

الحصول على مفتاح واجهة برمجة التطبيقات لـ Places API في "منصة خرائط Google"

1. في Google API Console، انتقِل إلى صفحة منصة خرائط Google > المفاتيح وبيانات الاعتماد.

   الانتقال إلى المفاتيح وبيانات الاعتماد

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

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

إنشاء حساب خدمة في Google Cloud Console

أنشئ حساب خدمة جديدًا بالدور Vertex AI User باتّباع الخطوات التالية:

Google Cloud Console

1. في Google Cloud Console، انتقِل إلى "القائمة" > المشرف وإدارة الهوية وإمكانية الوصول > حسابات الخدمة.

   الانتقال إلى "حسابات الخدمة"

   تظهر الخطوات المتبقية في Google Cloud Console.

2. اختَر مشروعًا على Google Cloud.
3. انقر على إنشاء حساب خدمة.
4. أدخِل اسم حساب خدمة ليتم عرضه في Google Cloud Console.
   ملاحظة: تنشئ Google تلقائيًا معرّفًا فريدًا لحساب الخدمة استنادًا إلى اسم حساب الخدمة. يمكنك تعديل المعرّف في حقل معرّف حساب الخدمة. لا يمكنك تغيير المعرّف لاحقًا.
5. إذا كنت لا تريد ضبط عناصر التحكّم في الوصول الآن، انقر على تم لإنهاء عملية إنشاء حساب الخدمة. لضبط عناصر التحكّم في الوصول الآن، انقر على إنشاء ومتابعة وانتقِل إلى الخطوة التالية.
   ملاحظة: لا يؤثّر منح إذن التحكّم في الوصول هنا إلا في موارد Google Cloud. تتم مشاركة موارد Google Workspace (مثل "جداول بيانات Google" وGoogle Drive) وإعدادها بشكل منفصل.
6. اختياري: يمكنك منح أدوار لحساب الخدمة من أجل السماح بالوصول إلى موارد مشروع على السحابة الإلكترونية على Google Cloud بالإضافة إلى موارد Google Workspace. لمزيد من التفاصيل، يُرجى الاطّلاع على إدارة الوصول إلى المشاريع والمجلدات والمؤسسات.
7. انقر على متابعة.
8. اختياري: أدخِل المستخدمين أو المجموعات التي يمكنها إدارة حساب الخدمة هذا وتنفيذ إجراءات فيه. لمزيد من التفاصيل، يُرجى الاطّلاع على انتحال هوية حساب الخدمة.
9. انقر على تم للانتهاء من إنشاء حساب الخدمة.

   دوِّن عنوان البريد الإلكتروني لحساب الخدمة.

gcloud CLI

1. أنشئ حساب الخدمة:

   gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
     --display-name="SERVICE_ACCOUNT_NAME"

2. اختياري: يمكنك منح أدوار لحساب الخدمة من أجل السماح بالوصول إلى موارد مشروع على السحابة الإلكترونية على Google Cloud بالإضافة إلى موارد Google Workspace. لمزيد من التفاصيل، يُرجى الاطّلاع على إدارة الوصول إلى المشاريع والمجلدات والمؤسسات.

يظهر حساب الخدمة في صفحة حساب الخدمة. بعد ذلك، أنشئ مفتاحًا خاصًا لحساب الخدمة.

إنشاء مفتاح خاص

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

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

لإنشاء مفتاح خاص لحساب الخدمة وتنزيله، اتّبِع الخطوات التالية:

1. في Google Cloud Console، انتقِل إلى "القائمة" > المشرف وإدارة الهوية وإمكانية الوصول > حسابات الخدمة.

   الانتقال إلى "حسابات الخدمة"

   تظهر الخطوات المتبقية في Google Cloud Console.

2. اختَر مشروعًا على Google Cloud.
3. انقر على عنوان البريد الإلكتروني لحساب الخدمة الذي تريد إنشاء مفتاح له.
4. انقر على علامة التبويب المفاتيح.
5. انقر على القائمة المنسدلة إضافة مفتاح، ثمّ اختَر إنشاء مفتاح جديد.
6. اختَر JSON كـ نوع المفتاح وانقر على إنشاء.

   يتم إنشاء زوج المفتاح العام/الخاص وتنزيله على جهازك كملف مفتاح لحساب الخدمة. احفظ ملف JSON الذي تم تنزيله باسم credentials.json في دليل العمل. هذا الملف هو النسخة الوحيدة من هذا المفتاح. بعد تنزيل ملف المفتاح، لا يمكنك تنزيله مرة أخرى. للحصول على معلومات حول كيفية تخزين المفتاح بشكل آمن، يُرجى الاطّلاع على أفضل الممارسات لإدارة مفاتيح حسابات الخدمة.

لمزيد من المعلومات حول حسابات الخدمة، يُرجى الاطّلاع على حسابات الخدمة في مستندات Cloud IAM في Google Cloud.

ضبط شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth

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

1. في Google API Console، انتقِل إلى القائمة > منصة Google Auth > العلامة التجارية.

   الانتقال إلى "هوية العلامة التجارية"

2. إذا سبق لك ضبط منصة Google Auth، يمكنك ضبط إعدادات شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth التالية في العلامة التجارية والجمهور والوصول إلى البيانات. إذا ظهرت لك رسالة لم يتم إعداد منصة Google Auth بعد، انقر على البدء:
1. ضمن معلومات التطبيق، في اسم التطبيق، أدخِل اسمًا للتطبيق.
2. في حقل البريد الإلكتروني لدعم المستخدمين، اختَر عنوان بريد إلكتروني مخصّصًا للدعم يمكن للمستخدمين التواصل معك من خلاله إذا كانت لديهم أسئلة حول موافقتهم.
3. انقر على التالي.
4. ضمن الجمهور، اختَر داخلي.
5. انقر على التالي.
6. ضمن معلومات الاتصال، أدخِل عنوان بريد إلكتروني يمكنك تلقّي إشعارات عليه بشأن أي تغييرات في مشروعك.
7. انقر على التالي.
8. ضمن إنهاء، راجِع سياسة بيانات المستخدمين في خدمات Google API، وإذا كنت موافقًا عليها، ضَع علامة في المربّع أوافق على "سياسة بيانات المستخدمين في خدمات Google API".
9. انقر على متابعة.
10. انقر على إنشاء.
3. يمكنك حاليًا تخطّي إضافة النطاقات. في المستقبل، عند إنشاء تطبيق للاستخدام خارج مؤسسة Google Workspace، عليك تغيير نوع المستخدم إلى خارجي. بعد ذلك، أضِف نطاقات التفويض التي يتطلّبها تطبيقك. لمزيد من المعلومات، يُرجى الاطّلاع على دليل ضبط موافقة OAuth الكامل.

نشر وكيل الذكاء الاصطناعي Travel Concierge ADK

1. إذا لم يسبق لك إجراء ذلك، عليك مصادقة حسابك على Google Cloud وإعداد Google Cloud CLI لاستخدام مشروعك على السحابة الإلكترونية.

   gcloud auth application-default login
   gcloud config set project PROJECT_ID
   gcloud auth application-default set-quota-project PROJECT_ID

   استبدِل PROJECT_ID بمعرّف مشروع على السحابة الإلكترونية الذي أنشأته.

2. تنزيل مستودع GitHub هذا

   تنزيل

3. في بيئة التطوير المحلية المفضّلة لديك، استخرِج ملف الأرشيف الذي تم تنزيله وافتح الدليل adk-samples/python/agents/travel-concierge.

   unzip adk-samples-main.zip
   cd adk-samples-main/python/agents/travel-concierge

4. أنشِئ حزمة جديدة في Cloud Storage مخصّصة لوكيل الذكاء الاصطناعي في "حزمة تطوير التطبيقات".

   gcloud storage buckets create gs://CLOUD_STORAGE_BUCKET_NAME --project=PROJECT_ID --location=PROJECT_LOCATION

   غيِّر القيم في السلسلة على الشكل التالي:

   1. استبدِل CLOUD_STORAGE_BUCKET_NAME باسم حزمة فريد تريد استخدامه.
   2. استبدِل PROJECT_ID بمعرّف مشروع Cloud الذي أنشأته.
   3. استبدِل PROJECT_LOCATION بموقع مشروع Cloud الذي أنشأته.

5. اضبط متغيرات البيئة التالية:

   export GOOGLE_GENAI_USE_VERTEXAI=1
   export GOOGLE_CLOUD_PROJECT=PROJECT_ID
   export GOOGLE_CLOUD_LOCATION=PROJECT_LOCATION
   export GOOGLE_PLACES_API_KEY=PLACES_API_KEY
   export GOOGLE_CLOUD_STORAGE_BUCKET=CLOUD_STORAGE_BUCKET_NAME
   export TRAVEL_CONCIERGE_SCENARIO=travel_concierge/profiles/itinerary_empty_default.json

   غيِّر القيم في السلسلة على الشكل التالي:

   1. استبدِل PROJECT_ID بمعرّف مشروع Cloud الذي أنشأته.
   2. استبدِل PROJECT_LOCATION بموقع مشروع Cloud الذي أنشأته.
   3. PLACES_API_KEY مع سلسلة مفتاح واجهة برمجة التطبيقات الذي أنشأته.
   4. استبدِل CLOUD_STORAGE_BUCKET_NAME باسم الحزمة التي أنشأتها.

6. تثبيت وكيل الذكاء الاصطناعي ADK ونشره

   uv sync --group deployment
   uv run python deployment/deploy.py --create

7. استرجِع رقم المشروع ومعرّف المحرّك من آخر سجلّ مطبوع على النحو PROJECT_NUMBER وENGINE_ID على التوالي، وستحتاج إلى كليهما لاحقًا لإعداد مشروعك.

   Created remote agent: projects/PROJECT_NUMBER/locations/us-central1/reasoningEngines/ENGINE_ID

مراجعة الرمز النموذجي

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

Python

عرض على GitHub

برمجة التطبيقات

عرض على GitHub

إنشاء المشروع وإعداده

Python

1. تنزيل مستودع GitHub هذا

   تنزيل

2. في بيئة التطوير المحلية المفضّلة لديك، استخرِج ملف الأرشيف الذي تم تنزيله وافتح الدليل add-ons-samples/python/travel-adk-ai-agent.

   unzip add-ons-samples-main.zip
   cd add-ons-samples-main/python/travel-adk-ai-agent

3. انقِل ملف مفتاح JSON credentials.json من حساب الخدمة الذي تم تنزيله في الخطوات السابقة إلى دليل المشروع.

4. في Google API Console، انتقِل إلى Cloud Run:

   الانتقال إلى Cloud Run

5. انقر على كتابة دالة.

6. في صفحة إنشاء خدمة، يمكنك إعداد الدالة باتّباع الخطوات التالية:

   1. في حقل اسم الخدمة، أدخِل travel-concierge-app.
   2. في قائمة المنطقة، اختَر موقع مشروع على السحابة الإلكترونية الذي أنشأته PROJECT_LOCATION.
   3. ضمن عنوان URL لنقطة النهاية، انقر على .
   4. في قائمة وقت التشغيل، اختَر أحدث إصدار من Python.
   5. في قسم المصادقة، اختَر السماح بالوصول العام.
   6. في قسم الحاويات ووحدات التخزين والشبكات والأمان، ضمن الموارد:
      1. في حقل الذاكرة، اختَر 1 غيغابايت.
      2. في حقل وحدة المعالجة المركزية، اختَر 2.
   7. انقر على إنشاء وانتظِر إلى أن تنتهي خدمة Cloud Run من إنشاء الخدمة. تعيد وحدة التحكّم توجيهك إلى علامة التبويب المصدر.

7. في بيئة التطوير المحلية المفضّلة لديك، نفِّذ مصدر المشروع:

   gcloud run deploy travel-concierge-app --quiet --source . \
       --region PROJECT_LOCATION  \
       --function adk_ai_agent  \
       --set-env-vars LOCATION=LOCATION,PROJECT_NUMBER=PROJECT_NUMBER,ENGINE_ID=ENGINE_ID,BASE_URL=BASE_URL

   غيِّر القيم في السلسلة على الشكل التالي:

   1. استبدِل PROJECT_LOCATION بموقع وظيفة Cloud Run التي أنشأتها سابقًا.
   2. استبدِل LOCATION بموقع مشروع على السحابة الإلكترونية من Google Cloud الذي تم إنشاؤه في الخطوات السابقة، PROJECT_LOCATION.
   3. PROJECT_NUMBER مع رقم مشروع وكيل الذكاء الاصطناعي Travel Concierge ADK الذي تم نشره في الخطوات السابقة.
   4. استبدِل ENGINE_ID برقم تعريف محرّك وكيل الذكاء الاصطناعي في Travel Concierge ADK الذي تم نشره في الخطوات السابقة.
   5. BASE_URL بعنوان عنوان URL لنقطة النهاية الذي نسخته سابقًا.

برمجة التطبيقات

لإنشاء مشروع برمجة تطبيقات وإعداده لاستخدام وكيل الذكاء الاصطناعي الخاص بـ Travel Concierge ADK الذي تم نشره، اتّبِع الخطوات التالية:

1. انقر على الزر التالي لفتح مشروع وكيل الذكاء الاصطناعي في حزمة تطوير التطبيقات الخاصة بـ "خدمة الاستشارة بشأن السفر" في Apps Script.
   افتح المشروع

2. انقر على نظرة عامة، ثم على إنشاء نسخة.

3. أدخِل اسمًا لنسخة مشروع "برمجة تطبيقات Google":

   1. انقر على نسخة من وكيل الذكاء الاصطناعي في حزمة تطوير التطبيقات Travel Concierge.
   2. في عنوان المشروع، اكتب Travel Concierge ADK AI Agent.
   3. انقر على إعادة تسمية.

4. في مشروع برمجة تطبيقات، انقر على المحرّر، ثم حرِّك الملف VertexAi.gs للأعلى إلى أن يصبح فوق الملف AgentHandler.gs باستخدام إجراء الملف نقل الملف للأعلى.

5. في مشروع برمجة تطبيقات، انقر على إعدادات المشروع، ثم انقر على تعديل خصائص النص البرمجي، ثم على إضافة خاصية نص برمجي لإضافة خصائص النص البرمجي التالية:

6. استبدِل ENGINE_ID برقم تعريف المحرّك الخاص بـ "وكيل الذكاء الاصطناعي" في Travel Concierge ADK الذي تم نشره في الخطوات السابقة، ENGINE_ID.

7. استبدِل LOCATION بموقع مشروع على السحابة الإلكترونية من Google Cloud الذي تم إنشاؤه في الخطوات السابقة، PROJECT_LOCATION.

8. استبدِل PROJECT_NUMBER برقم مشروع وكيل الذكاء الاصطناعي Travel Concierge ADK الذي تم نشره في الخطوات السابقة، PROJECT_NUMBER.

9. استبدِل SERVICE_ACCOUNT_KEY بمفتاح JSON من حساب الخدمة الذي تم تنزيله في الخطوات السابقة، مثل { ... }.

10. انقر على حفظ خصائص النص البرمجي.

11. في مشروعك على "برمجة تطبيقات Google"، انقر على إعدادات المشروع.

12. ضمن مشروع Google Cloud Platform (GCP)، انقر على تغيير المشروع.

13. في رقم مشروع Google Cloud Platform، ألصِق رقم مشروع Travel Concierge ADK وكيل الذكاء الاصطناعي الذي تم نشره في الخطوات السابقة، PROJECT_NUMBER.

14. انقر على ضبط المشروع. تم ربط مشروع على السحابة الإلكترونية بمشروع "برمجة التطبيقات".

النشر في Gmail و"تقويم Google" وDrive و"مستندات Google" و"جداول بيانات Google" و"العروض التقديمية من Google"

Python

استخدِم عملية نشر لإضافة Google Workspace من أجل تثبيت نموذج المشروع على جميع تطبيقات Google Workspace (باستثناء Google Chat) لتفعيل الاختبار.

1. في بيئة التطوير المحلية المفضّلة لديك، افتح الملف deployment.json من مصدر الرمز البرمجي للمشروع واستبدِل كل مثيلات $BASE_URL بقيمة BASE_URL، أي عنوان URL لنقطة النهاية الذي نسخته في الخطوات السابقة.

2. أنشئ عملية نشر لإضافة Google Workspace باسم travel-concierge-addon:

   gcloud workspace-add-ons deployments create travel-concierge-addon \
       --deployment-file=deployment.json

3. ثبِّت عملية نشر إضافة Google Workspace باتّباع الخطوات التالية:

   gcloud workspace-add-ons deployments install travel-concierge-addon

برمجة التطبيقات

ثبِّت مشروع "برمجة تطبيقات Google" على جميع تطبيقات Google Workspace (باستثناء Google Chat) لتفعيل الاختبار.

1. في مشروع برمجة تطبيقات، انقر على تفعيل > عمليات النشر التجريبية، ثم ثبّت.

يمكن الآن الوصول إلى الإضافة من الأشرطة الجانبية لتطبيق Google Workspace.

نشر التطبيق في Chat

Python

ثبِّت المشروع النموذجي في Chat باستخدام عنوان URL لنقطة النهاية لتفعيل الاختبار.

1. في وحدة تحكّم API، ابحث عن Google Chat API، ثم انقر على Google Chat API، ثم على إدارة، ثم على الإعدادات.

   الانتقال إلى صفحة "إعدادات واجهة برمجة تطبيقات Google Chat"

2. إعداد تطبيق Chat:

   1. في حقل اسم التطبيق، أدخِل Travel ADK AI Agent.
   2. في حقل عنوان URL للأفاتار، أدخِل https://goo.gle/3SfMkjb.
   3. في حقل الوصف، أدخِل Travel ADK AI Agent.
   4. ضمن إعدادات الاتصال، اختَر عنوان URL لنقطة نهاية HTTP.
   5. ضمن عوامل التفعيل، اختَر استخدام عنوان URL مشترك لنقطة نهاية HTTP لجميع عوامل التفعيل.
   6. في الحقل عنوان URL لنقطة نهاية HTTP، الصِق عنوان URL لنقطة النهاية الذي نسخته سابقًا BASE_URL.
   7. سجِّل طلبًا سريعًا يستخدمه تطبيق Chat الذي تم تنفيذه بالكامل:
      1. ضمن الأوامر، انقر على إضافة أمر.
      2. في معرّف الأمر، اكتب 1.
      3. في حقل الوصف، اكتب Reset session.
      4. ضمن نوع الأمر، اختَر أمر سريع.
      5. في حقل الاسم، اكتب Reset session.
      6. انقر على تم. يتم تسجيل الأمر السريع وإدراجه.
   8. ضمن إمكانية الوصول، اختَر إتاحة تطبيق Chat هذا لأشخاص ومجموعات محدّدة في نطاق Workspace وأدخِل عنوان بريدك الإلكتروني.
   9. ضمن السجلات، اختَر تسجيل الأخطاء في خدمة "التسجيل".
   10. انقر على حفظ.

برمجة التطبيقات

ثبِّت مشروع برمجة تطبيقات في Chat باستخدام معرّف عملية النشر الرئيسية لتفعيل الاختبار.

1. في مشروع برمجة تطبيقات، انقر على نشر > اختبار عمليات النشر، ثم على نسخ ضمن معرّف عملية النشر الرئيسية.

2. في وحدة تحكّم API، ابحث عن Google Chat API، ثم انقر على Google Chat API، ثم على إدارة، ثم على الإعدادات.

   الانتقال إلى صفحة "إعدادات واجهة برمجة تطبيقات Google Chat"

3. إعداد تطبيق Chat:

   1. في حقل اسم التطبيق، أدخِل Travel ADK AI Agent.
   2. في حقل عنوان URL للأفاتار، أدخِل https://goo.gle/3SfMkjb.
   3. في حقل الوصف، أدخِل Travel ADK AI Agent.
   4. ضِمن إعدادات الربط، اختَر Apps Script.
   5. في حقل رقم تعريف النشر، ألصِق رقم تعريف النشر الرئيسي الذي نسخته سابقًا.
   6. سجِّل طلبًا سريعًا يستخدمه تطبيق Chat الذي تم تنفيذه بالكامل:
      1. ضمن الأوامر، انقر على إضافة أمر.
      2. في معرّف الأمر، اكتب 1.
      3. في حقل الوصف، اكتب Reset session.
      4. ضمن نوع الأمر، اختَر أمر سريع.
      5. في حقل الاسم، اكتب Reset session.
      6. انقر على تم. يتم تسجيل الأمر السريع وإدراجه.
   7. ضمن إمكانية الوصول، اختَر إتاحة تطبيق Chat هذا لأشخاص ومجموعات محدّدة في نطاق Workspace وأدخِل عنوان بريدك الإلكتروني.
   8. ضمن السجلات، اختَر تسجيل الأخطاء في خدمة "التسجيل".
   9. انقر على حفظ.

يمكن الآن الوصول إلى التطبيق من Google Chat.

1. افتح Google Chat.

   الانتقال إلى Google Chat

2. إنشاء مساحة الرسائل المباشرة في Chat:

   1. انقر على محادثة جديدة.
   2. اكتب اسم التطبيق Travel ADK AI Agent في شريط البحث واختَره.
   3. في مربّع الحوار Install app، انقر على تثبيت التطبيق.
   4. يتم إغلاق مربّع الحوار Install app ويتم اختيار مساحة الرسائل المباشرة الجديدة في Chat.

تطبيق Chat جاهز للردّ على الرسائل.

اختبار الوكيل

1. افتح Gmail.

   الانتقال إلى Gmail

2. أرسِل الرسالة الإلكترونية التالية إلى نفسك:

   • الموضوع: You need to travel to Paris
   • نص الرسالة: Please be there between 11/25/2025 and 11/30/2025!

3. افتح إضافة الوكيل المستنِد إلى الذكاء الاصطناعي في Travel ADK من الشريط الجانبي.

4. انقر على منح الأذونات لإكمال عملية إعداد الوظيفة الإضافية.

5. انقر على إرسال بعد ضبط الطلب التالي إلى الوكيل:

   • الرسالة: Please help me plan this travel!
   • السياق: اختَر البريد الإلكتروني الحالي

   يتم تعديل الشريط الجانبي ليتضمّن ردّ الوكيل.

   

6. انقر على فتح Chat لإعادة توجيهك إلى مساحة الرسائل المباشرة في Chat.

7. انقر على + > إعادة ضبط الجلسة.

   ستتلقّى رسالة جديدة تؤكّد إتمام العملية: OK, let's start from the beginning, what can I help you with?

8. أرسِل الرسالة Give me ideas.

   تتلقّى رسائل جديدة تتضمّن ردّ الموظف.

   

9. أرسِل الرسالة I want to go there! بعد تحميل صورة لأي مكان، مثل برج إيفل.

   تتلقّى رسائل جديدة تتضمّن ردّ الموظف.

   

ملاحظة: يمكن أيضًا فتح إضافة وكيل الذكاء الاصطناعي في Travel ADK من الشريط الجانبي في "تقويم Google" وDrive و"مستندات Google" و"جداول بيانات Google" و"العروض التقديمية من Google"، تمامًا كما يتم ذلك في Gmail.

القيود

HTTP

في تطبيقات Google Workspace غير Chat، يخضع وكيل الذكاء الاصطناعي للقيود التالية:

• التزامن: لا يمكن تعديل الأشرطة الجانبية إلا استجابةً لتفاعلات المستخدم، لذا لا يتم عرض ردود وكيل الذكاء الاصطناعي إلا بعد اكتمالها بالكامل (بدون عرض تدريجي).

• انتهاء المهلة: تنتهي مهلة تعديلات الشريط الجانبي عندما يستغرق إكمالها أكثر من بضع دقائق.

لا تنطبق هذه القيود على Chat.

برمجة التطبيقات

في جميع تطبيقات Google Workspace، يستدعي وكيل الذكاء الاصطناعي واجهات برمجة تطبيقات REST في Vertex AI باستخدام UrlFetchApp، ما يؤدي إلى القيود التالية:

• متزامن: لا يتم عرض ردود وكيل الذكاء الاصطناعي بشكل تدريجي، بل يتم عرضها بعد اكتمالها.

• انتهاء المهلة: تنتهي مهلة طلب وكيل الذكاء الاصطناعي عندما يستغرق إكماله أكثر من دقيقة واحدة تقريبًا.

التخصيص

يتيح هذا الحلّ وكلاء الذكاء الاصطناعي في "حزمة تطوير التطبيقات" (ADK) المستضافين في Vertex AI Agent Engine، وهي مجموعة فرعية من واجهات مستخدم تطبيقات Google Workspace، وعمليات عرض الاستجابات الخاصة باستجابات نموذج Travel Concierge. يستخدم الحل إطارًا قابلاً للتوسيع، لذا يمكنك تخصيصه عن طريق تعديل الملفات التالية:

Python

• main.py: يحدّد واجهات المستخدم الرئيسية ومنطق تفاعلات المستخدمين (معالجات أحداث Google Workspace). من الأمثلة على الإضافات الشائعة إتاحة مستندات Drive كميزة سياقية لتطبيق Drive، على غرار ما يتم تنفيذه مع رسائل Gmail لتطبيق Gmail.

• ‫vertex_ai.py: يدير جلسات وكيل الذكاء الاصطناعي وردوده وأخطائه، ويحدّد واجهات خاصة بـ Vertex AI يجب تنفيذها لدعم تفاعلات الوكيل وعرض الردود. تشمل الإضافات النموذجية إتاحة جلسات متعدّدة لمحادثات المستخدمين المنفصلة، ومنصات إدارة وكلاء الذكاء الاصطناعي الأخرى.

• agent_handler.py: تنفّذ هذه السمة واجهات خاصة بـ Vertex AI تم تحديدها في vertex_ai.py في حالات معيّنة من تطبيقات Chat والتطبيقات الأخرى. يمكن إضافة أزرار تتيح للمستخدمين إرسال ملاحظات حول ردود وكيل الذكاء الاصطناعي.

• ‫google_workspace.py: تنفّذ عمليات التفاعل بين المنصة وإدارة الوكلاء غير المستندة إلى وكيل الذكاء الاصطناعي باستخدام طلبات البيانات من واجهة برمجة التطبيقات. يتم استخدام واجهات برمجة تطبيقات Google Workspace فقط في هذا المثال لجمع تفاصيل السياق واتّخاذ الإجراءات. من الأمثلة الشائعة على الإضافات، إضافة وظائف لاسترداد بيانات النشاط الإعلاني من "تقويم Google" أو نظام إدارة علاقات العملاء (CRM).

• travel_agent_ui_render.gs: تنفّذ عمليات عرض الاستجابات الخاصة بـ "مساعد السفر" لوكلاء الخدمة الفرعية وتطبيقات Workspace. وتتمثّل الإضافات النموذجية في توفير دعم لعرض الردود الجديدة بشكل رسومي لعرض خيارات الرحلات الجوية وغيرها من وكلاء الذكاء الاصطناعي.

برمجة التطبيقات

• Code.gs: يحدّد واجهات المستخدم الرئيسية ومنطق تفاعلات المستخدمين (معالجات أحداث Google Workspace). من الإضافات النموذجية إتاحة مستندات Drive كميزة سياقية لتطبيق Drive، على غرار ما يتم إجراؤه مع رسائل Gmail لتطبيق Gmail.

• ‫VertexAi.gs: يدير جلسات وكيل الذكاء الاصطناعي والردود والأخطاء، ويحدّد واجهات خاصة بـ Vertex AI يجب تنفيذها لدعم تفاعلات الوكيل وعرض الردود. تشمل الإضافات النموذجية إتاحة جلسات متعدّدة لمحادثات المستخدمين المنفصلة، ومنصات إدارة وكلاء الذكاء الاصطناعي الأخرى.

• ‫AgentHandler.gs: تنفّذ هذه السمة واجهات خاصة بـ Vertex AI تم تحديدها في VertexAi.gs في حالات محدّدة من تطبيقات Chat وغير Chat. يمكن إضافة أزرار تتيح للمستخدمين إرسال ملاحظات حول ردود وكيل الذكاء الاصطناعي.

• ‫GoogleWorkspace.gs: تنفّذ هذه السمة تفاعلات منصة إدارة وكلاء الذكاء الاصطناعي غير المستندة إلى الذكاء الاصطناعي باستخدام طلبات البيانات من واجهة برمجة التطبيقات. يتم استخدام واجهات برمجة تطبيقات Google Workspace فقط في هذا المثال لجمع تفاصيل السياق واتّخاذ الإجراءات. من الأمثلة الشائعة على الإضافات، إضافة وظائف لاسترداد بيانات النشاط الإعلاني من "تقويم Google" أو نظام إدارة علاقات العملاء (CRM).

• TravelAgentUiRender.gs: تنفّذ هذه السمة عمليات عرض الاستجابات الخاصة بـ "مساعد السفر" للوكلاء الفرعيين وتطبيقات Workspace. وتتمثّل الإضافات النموذجية في توفير دعم لعرض الردود الجديدة بشكل رسومي لعرض خيارات الرحلات الجوية وغيرها من وكلاء الذكاء الاصطناعي.

تَنظيم

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

تنبيه: يؤدي حذف مشروع إلى ما يلي:

• يتم حذف كل المحتوى في المشروع. إذا كنت قد استخدمت مشروعًا حاليًا لهذا البرنامج التعليمي، سيؤدي حذفه إلى حذف أي عمل آخر أنجزته في المشروع.
• فقدان أرقام تعريف المشاريع المخصّصة: عند إنشاء هذا المشروع، ربما أنشأت رقم تعريف مشروع مخصّصًا تريد استخدامه في المستقبل. للحفاظ على عناوين URL التي تستخدم رقم تعريف المشروع، مثل عنوان URL على appspot.com، احذف الموارد المحدّدة داخل المشروع بدلاً من حذف المشروع بأكمله.

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

1. في Google API Console، انتقِل إلى صفحة إدارة الموارد. انقر على القائمة > إدارة الهوية وإمكانية الوصول والمشرف > إدارة الموارد.

   الانتقال إلى "إدارة الموارد"

2. في قائمة المشاريع، اختَر المشروع الذي تريد حذفه، ثم انقر على حذف .
3. في مربّع الحوار، اكتب رقم تعريف المشروع، ثم انقر على إيقاف لحذف المشروع.

المواضيع ذات الصلة

• التحقّق من صحة البيانات باستخدام وكيل الذكاء الاصطناعي في حزمة ADK ونموذج Gemini
• دمج مفاهيم الذكاء الاصطناعي الأساسية في تطبيقات Chat
• الإجابة عن الأسئلة استنادًا إلى محادثات Chat باستخدام تطبيق Gemini AI Chat
• الاستجابة للحوادث باستخدام Google Chat وVertex AI وApps Script ومصادقة المستخدم
• إدارة المشاريع باستخدام Google Chat وVertex AI وFirestore
• إنشاء تطبيق Chat كإضافة على Google Workspace باستخدام "برمجة تطبيقات Google"