التخطيط للسفر باستخدام وكيل مستند إلى الذكاء الاصطناعي يمكن الوصول إليه في جميع تطبيقات 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".

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

الميزات

تتوفّر ميزات تطبيق "مساعد السفر" التالية في جميع تطبيقات 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. تكمل التطبيقات غير التابعة للمحادثة السياق باستخدام الملف الشخصي في حساب Google للمستخدم واختيار العناصر، وتعرض مجموعة من الأقسام تتضمّن سجلّ تفاعلات الوكيل الفرعي والإجابة النهائية الشاملة بترتيب زمني عكسي.

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

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

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

تجهيز البيئة

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

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

وحدة تحكّم Google API

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

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

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

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

  3. في حقل الموقع الجغرافي، انقر على تصفّح لعرض المواقع الجغرافية المحتملة لمشروعك. بعد ذلك، انقر على اختيار.
  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 Cloud Console

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

Google Cloud Console

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

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

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

  2. اختَر مشروعًا على Google Cloud.
  3. انقر على إنشاء حساب خدمة.
  4. أدخِل اسم حساب خدمة ليتم عرضه في Google Cloud Console.
  5. إذا كنت لا تريد ضبط عناصر التحكّم في الوصول الآن، انقر على تم لإنهاء عملية إنشاء حساب الخدمة. لضبط عناصر التحكّم في الوصول الآن، انقر على إنشاء ومتابعة وانتقِل إلى الخطوة التالية.
  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.

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

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

    تخطيط السفر من Gmail

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

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

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

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

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