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

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

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

نظرة عامة

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

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

  • استخدام وكيل الذكاء الاصطناعي من Chat لطرح أفكار حول السفر
    الشكل 1. استخدام وكيل الذكاء الاصطناعي من Chat لاستلهام أفكار حول السفر
  • استخدام وكيل الذكاء الاصطناعي من Gmail للتخطيط لرحلة من السياق الوارد في الرسالة الإلكترونية المحدّدة
    الشكل 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") لمراعاة ميزاتها وقيودها المحدّدة.

الميزات

تتوفّر ميزات تطبيق Travel Concierge التالية في جميع تطبيقات 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

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

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

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

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

تجهيز البيئة

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

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

Google Cloud Console

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

    الانتقال إلى "إنشاء مشروع"

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

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

  3. في حقل الموقع الجغرافي، انقر على تصفّح لعرض المواقع الجغرافية المحتملة لمشروعك. بعد ذلك، انقر على اختيار.
  4. انقر على إنشاء. تنتقل وحدة تحكّم Google Cloud إلى صفحة "لوحة البيانات" ويتم إنشاء مشروعك في غضون بضع دقائق.

gcloud CLI

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

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

تفعيل الفوترة لمشروع Cloud

Google Cloud Console

  1. في Google Cloud 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 Cloud Console، فعِّل واجهات برمجة التطبيقات Vertex AI وPlaces وPeople وGoogle Chat وGmail وCloud Build وCloud Functions وCloud Pub/Sub وCloud Logging وArtifact Registry وCloud Run وإضافات Google Workspace.

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

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

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

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

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

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

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

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

الحصول على مفتاح Places API في Google Maps Platform

  1. في وحدة تحكّم Google Cloud، انتقِل إلى صفحة Google Maps Platform > المفاتيح وبيانات الاعتماد.

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

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

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

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

Google Cloud Console

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

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

  2. انقر على إنشاء حساب خدمة.
  3. املأ تفاصيل حساب الخدمة، ثم انقر على إنشاء ومتابعة.
  4. اختياري: يمكنك إسناد أدوار إلى حساب الخدمة لمنح إذن الوصول إلى موارد مشروعك على Google Cloud. لمزيد من التفاصيل، يُرجى الرجوع إلى منح إذن الوصول إلى الموارد وتغييره وإبطاله.
  5. انقر على متابعة.
  6. اختياري: أدخِل المستخدمين أو المجموعات التي يمكنها إدارة حساب الخدمة هذا وتنفيذ إجراءات فيه. لمزيد من التفاصيل، يُرجى الاطّلاع على إدارة انتحال هوية حساب الخدمة.
  7. انقر على تم. دوِّن عنوان البريد الإلكتروني لحساب الخدمة.

gcloud CLI

  1. أنشئ حساب الخدمة: 
    gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
  --display-name="SERVICE_ACCOUNT_NAME"
  2. اختياري: يمكنك إسناد أدوار إلى حساب الخدمة لمنح إذن الوصول إلى موارد مشروعك على Google Cloud. لمزيد من التفاصيل، يُرجى الرجوع إلى منح إذن الوصول إلى الموارد وتغييره وإبطاله.

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

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

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

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

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

  2. اختَر حساب الخدمة.
  3. انقر على المفاتيح > إضافة مفتاح > إنشاء مفتاح جديد.
  4. اختَر JSON، ثمّ انقر على إنشاء.

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

  5. انقر على إغلاق (Close).

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

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

  1. في "وحدة تحكّم Google Cloud"، انتقِل إلى "القائمة" > Google Auth platform > العلامة التجارية.

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

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

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

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

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

    استبدِل PROJECT_ID بمعرّف مشروع Cloud الذي أنشأته.

  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 مخصَّصة لبرنامج ADK AI.

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

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

    1. استبدِل CLOUD_STORAGE_BUCKET_NAME باسم حزمة فريد تريد استخدامه.
    2. PROJECT_ID مع رقم تعريف مشروع السحابة الإلكترونية الذي أنشأته.
    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 مع رقم تعريف مشروع السحابة الإلكترونية الذي أنشأته.
    2. استبدِل PROJECT_LOCATION بموقع مشروع Cloud الذي أنشأته.
    3. PLACES_API_KEY مع سلسلة مفتاح واجهة برمجة التطبيقات الذي أنشأته.
    4. استبدِل CLOUD_STORAGE_BUCKET_NAME باسم الحزمة التي أنشأتها.

  6. ثبِّت وكيل الذكاء الاصطناعي في "حزمة تطوير التطبيقات" ونفِّذه.

    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 Cloud Console، انتقِل إلى Cloud Run:

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

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

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

    1. في حقل اسم الخدمة، أدخِل travel-concierge-app.
    2. في قائمة المنطقة، اختَر موقع مشروع Cloud الذي أنشأته، 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 AI Agent الذي تم نشره في الخطوات السابقة.
    4. ENGINE_ID مع رقم تعريف محرّك Travel Concierge ADK AI Agent الذي تم نشره في الخطوات السابقة.
    5. BASE_URL بعنوان عنوان URL لنقطة النهاية الذي نسخته سابقًا.

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

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

  1. انقر فوق الزر التالي لفتح مشروع Apps Script Travel Concierge ADK AI Agent.
    فتح المشروع

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

  3. قم بتسمية نسختك من مشروع Apps Script:

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

  4. في مشروع Apps Script، انقر على رمز إعدادات المشروع المحرر وانقل الملف VertexAi.gs لأعلى حتى يصبح أعلى الملف AgentHandler.gs باستخدام إجراء الملف نقل الملف لأعلى.

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

  6. ENGINE_ID مع معرف محرك وكيل Travel Concierge ADK AI الذي تم نشره في الخطوات السابقة، ENGINE_ID.

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

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

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

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

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

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

  13. في رقم مشروع GCP، الصق رقم مشروع وكيل Travel Concierge ADK AI الذي تم نشره في الخطوات السابقة، PROJECT_NUMBER.

  14. انقر على تحديد المشروع. تم الآن ربط مشروع Cloud بمشروع "برمجة التطبيقات".

النشر في 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

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

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

  1. في مشروع Apps Script، انقر على نشر > اختبار عمليات النشر، ثم تثبيت.

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

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

Python

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

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

    الانتقال إلى صفحة إعدادات Google Chat API

  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. انقر على حفظ.

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

قم بتثبيت مشروع Apps Script على Chat باستخدام معرف النشر الرئيسي لتمكين الاختبار.

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

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

    الانتقال إلى صفحة إعدادات Google Chat API

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

    1. في حقل اسم التطبيق، أدخِل Travel ADK AI Agent.
    2. في الحقل عنوان URL للصورة الرمزية، أدخِل https://goo.gle/3SfMkjb.
    3. في حقل الوصف، أدخِل Travel ADK AI Agent.
    4. ضمن إعدادات الاتصال، اختَر Apps Script.
    5. في حقل رقم تعريف النشر، ألصِق رقم تعريف النشر الرئيسي الذي نسخته سابقًا.
    6. سجل أمرًا سريعًا يستخدمه تطبيق الدردشة الذي تم تنفيذه بالكامل:
      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 جاهز للردّ على الرسائل.

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

  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!
    • السياق: اختَر البريد الإلكتروني الحالي

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

    تخطيط رحلة من Gmail

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

  7. انقر فوق + > إعادة تعيين الجلسة.

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

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

    ستتلقى رسائل جديدة مع استجابة الوكيل.

    تبادل الأفكار من Chat

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

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

    الحصول على تفاصيل الموقع الجغرافي من مرفق في Chat

القيود

HTTP

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

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

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

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

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

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

  • إنه متزامن: يتم إرجاع استجابات وكيل الذكاء الاصطناعي فقط بعد الانتهاء الكامل (لا يوجد بث).

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

التخصيص

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

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 مقابل الموارد المستخدَمة في هذا البرنامج التعليمي، ننصحك بحذف مشروع Cloud.

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

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

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