دمج "وكلاء Gemini Enterprise" مع Google Workspace

1. قبل البدء

ما هو Gemini Enterprise؟

‫Gemini Enterprise هي منصة متقدّمة تستند إلى الذكاء الاصطناعي الوكيل، وتتيح لكل موظف استغلال قوة ذكاء Google الاصطناعي في جميع مهام سير العمل. تُمكّن هذه المنصة الفِرق من اكتشاف وكلاء الذكاء الاصطناعي وإنشائهم ومشاركتهم وتشغيلهم في بيئة آمنة واحدة.

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

ما هو Google Workspace؟

‫Google Workspace هي مجموعة من حلول الإنتاجية والتعاون المستندة إلى السحابة الإلكترونية والمصمّمة للأفراد والمدارس والأنشطة التجارية:

التواصل: خدمات البريد الإلكتروني الاحترافية (Gmail) واجتماعات الفيديو (Meet) ومراسلة الفريق (Chat)
صناعة المحتوى: أدوات لكتابة المستندات ("مستندات Google") وإنشاء جداول البيانات ("جداول بيانات Google") وتصميم العروض التقديمية ("العروض التقديمية من Google")
التنظيم: التقاويم المشتركة (تقويم Google) وتدوين الملاحظات الرقمية (Keep)
مساحة التخزين: مساحة مركزية في السحابة الإلكترونية لحفظ الملفات ومشاركتها بأمان (Drive)
الإدارة: عناصر تحكّم إدارية لإدارة المستخدمين وإعدادات الأمان (وحدة تحكّم المشرف في Workspace)

ما هي أنواع عمليات الدمج المخصّصة؟

تنشئ Google Workspace وGemini Enterprise حلقة ملاحظات فعّالة حيث يوفّر Workspace بيانات في الوقت الفعلي وسياقًا للتعاون، بينما يوفّر Gemini Enterprise النماذج والاستدلال الوكيلي والتنسيق اللازم لأتمتة مهام سير العمل الذكية.

الاتصال الذكي: تتيح مخازن البيانات وواجهات برمجة التطبيقات وخوادم MCP (التي تديرها Google والمخصّصة) التي تديرها Google للموظفين الوصول إلى بيانات Workspace بأمان وسلاسة واتخاذ إجراءات نيابةً عن المستخدمين.
الوكلاء المخصّصون: باستخدام أدوات تصميم بدون رموز أو أُطر عمل احترافية، يمكن للفرق إنشاء وكلاء متخصصين يستندون إلى بيانات وإجراءات Workspace التي يديرها المشرف.
التكامل الأصلي: تعمل إضافات Workspace على سد الفجوة بين أنظمة الذكاء الاصطناعي والتطبيقات، مثل Chat وGmail، سواء من خلال مكوّنات واجهة المستخدم المخصّصة أو العمليات التي تتم في الخلفية. يتيح ذلك للوكلاء مقابلة المستخدمين في المكان الذي يتواجدون فيه بالضبط لتقديم مساعدة فورية ومراعية للسياق.

من خلال الجمع بين منظومة الإنتاجية المتكاملة في Google Workspace وقدرات الذكاء الاصطناعي الوكيل المتقدّمة في Gemini Enterprise، يمكن للمؤسسات تغيير عملياتها من خلال وكلاء الذكاء الاصطناعي المخصّصين المستندين إلى البيانات والذين يؤتمتون مهام سير العمل المعقّدة مباشرةً في الأدوات التي تستخدمها فِرقها يوميًا.

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

إذا أردت اتّباع جميع الخطوات في بيئتك الخاصة، ستحتاج إلى ما يلي:

معرفة أساسية بمنصة Google Cloud ولغة Python
مشروع على Google Cloud تملكه ويتضمّن الفوترة للتأكّد من تفعيل الفوترة في مشروع حالي، اطّلِع على التأكّد من حالة الفوترة في مشاريعك. لإنشاء مشروع وإعداد الفوترة، يُرجى الاطّلاع على إنشاء مشروع على Google Cloud. لتغيير مالك المشروع، يُرجى الاطّلاع على إدارة أعضاء المشروع أو تغيير مالك المشروع.
تم تفعيل إصدارات Gemini Enterprise Standard أو Plus. للمقارنة بين إصدارات Gemini Enterprise، يُرجى الاطّلاع على المقارنة بين إصدارات Gemini Enterprise. إذا لم يكن لديك ترخيص Gemini Enterprise، سيتوفّر لك خيار إنشاء ترخيص تجريبي في الخطوة التالية.
حساب Google Workspace من إصدار Business أو Enterprise مع إمكانية الوصول إلى Google Chat وتفعيل الميزات الذكية
يجب أن تكون واجهة سطر الأوامر (CLI) في Google Cloud مثبّتة ومهيأة لمشروعك على Google Cloud.
يجب تثبيت الإصدار 3.11 من Python أو إصدار أحدث، ويمكنك الاطّلاع على التعليمات على موقع Python الإلكتروني الرسمي.

ما ستنشئه

في هذا الدرس العملي، سننشئ ثلاثة حلول باستخدام وكلاء الذكاء الاصطناعي في Gemini Enterprise المدمجين بإحكام مع Google Workspace. ستعرض هذه الجلسات أنماطًا معمارية يمكن استخدامها للتفاعل مع البيانات والإجراءات وواجهات المستخدم.

وكيل مخصّص بدون استخدام رمز

يتيح هذا الوكيل للمستخدمين البحث عن البيانات وتنفيذ الإجراءات في Workspace بلغتهم الطبيعية. ويعتمد على العناصر التالية:

النموذج: Gemini
البيانات والإجراءات: تخزّن خدمة Gemini Enterprise البيانات في Google Workspace (تقويم Google وGmail وDrive وNotebookLM) وبحث Google.
أدوات إنشاء الوكلاء: "مصمّم وكيل Gemini Enterprise"
مضيف الوكيل: Gemini Enterprise
واجهة المستخدم: تطبيق Gemini Enterprise للويب

وكيل مخصّص باستخدام رمز

تتيح هذه الأداة للمستخدمين البحث عن البيانات واتّخاذ إجراءات في Workspace بلغتهم الطبيعية باستخدام أدوات وقواعد مخصّصة. ويعتمد على العناصر التالية:

النموذج: Gemini
البيانات والإجراءات: مخازن بيانات Gemini Enterprise في Google Workspace (تقويم Google وGmail وDrive وNotebookLM)، وبحث Google، وخادم بروتوكول سياق نموذج البحث (MCP) في Vertex AI الذي تديره Google، ووظيفة أداة مخصّصة لإرسال رسائل Google Chat (عبر Google Chat API).
أدوات إنشاء الوكلاء: "حزمة تطوير الوكلاء" (ADK)
مضيف الوكيل: محرك وكلاء Vertex AI
واجهة المستخدم: تطبيق Gemini Enterprise للويب

الوكيل التلقائي كإضافة على Google Workspace

يتيح هذا الوكيل للمستخدمين البحث عن بيانات Workspace بلغتهم الطبيعية ضمن سياق واجهات مستخدم تطبيقات Workspace. ويعتمد على العناصر التالية:

النموذج: Gemini
البيانات: مخازن بيانات Gemini Enterprise في Google Workspace (تقويم Google وGmail وDrive وNotebookLM) وبحث Google
مضيف الوكيل: Gemini Enterprise
واجهة المستخدم: إضافة Google Workspace إلى Chat وGmail (يمكن توسيعها بسهولة لتشمل "تقويم Google" وDrive و"مستندات Google" و"جداول بيانات Google" و"العروض التقديمية من Google")
إضافة Google Workspace: خدمة "برمجة التطبيقات" وGemini Enterprise وواجهات برمجة التطبيقات Vertex AI والسياقية (بيانات وصفية للمستخدم ورسالة Gmail المحدّدة)

ما ستتعلمه

نقاط التكامل بين Gemini Enterprise وGoogle Workspace التي تتيح البيانات والإجراءات
خيارات البرمجة البسيطة والاحترافية لإنشاء وكلاء مخصّصين مستضافين في Gemini Enterprise
طرق وصول المستخدمين إلى الوكلاء من تطبيق Gemini Enterprise للويب وتطبيقات Google Workspace

2. طريقة الإعداد

مراجعة المفاهيم

تطبيق Gemini Enterprise

يوفّر تطبيق Gemini Enterprise للمستخدمين النهائيين نتائج البحث والإجراءات والوكلاء. يمكن استخدام مصطلح "تطبيق" بالتبادل مع مصطلح "محرك" في سياق واجهات برمجة التطبيقات. يجب ربط التطبيق بمخزن بيانات لاستخدام البيانات منه في عرض نتائج البحث أو الإجابات أو الإجراءات.

تطبيق Gemini Enterprise للويب

يرتبط تطبيق Gemini Enterprise على الويب بتطبيق Gemini Enterprise، ويعمل كقاعدة مركزية للذكاء الاصطناعي حيث يستخدم الموظفون واجهة محادثة واحدة للبحث في بيانات الشركة المنعزلة، وتشغيل وكلاء الذكاء الاصطناعي المتخصّصين لسير العمل المعقّد، وإنشاء محتوى احترافي مع الحفاظ على الخصوصية على مستوى المؤسسة.

تهيئة الموارد والوصول إليها

في هذا القسم، يمكنك الوصول إلى الموارد التالية وضبطها من متصفّح الويب المفضّل لديك.

تطبيق Gemini Enterprise

افتح وحدة تحكّم Google Cloud في علامة تبويب جديدة، ثم اتّبِع الخطوات التالية:

اختَر مشروعك.
في حقل البحث في Google Cloud، ابحث عن Gemini Enterprise واختَره، ثم انقر على علامة الإضافة إنشاء تطبيق. إذا لم يكن لديك ترخيص لاستخدام Gemini Enterprise، سيُطلب منك تفعيل ترخيص تجريبي مجاني لمدة 30 يومًا.

اضبط اسم التطبيق على codelab.
يتم إنشاء معرّف استنادًا إلى الاسم ويظهر تحت الحقل، لذا انسَخه.
اضبط المنطقة المتعدّدة على global (Global).
انقر على إنشاء.

يتم إنشاء التطبيق وتتم إعادة توجيهك تلقائيًا إلى Gemini Enterprise > نظرة عامة.
ضمن الحصول على إذن الوصول الكامل، انقر على إعداد الهوية.
في الشاشة الجديدة، اختَر استخدام هوية Google وانقر على تأكيد هوية الموظف.

يتم حفظ الإعدادات وتتم إعادة توجيهك تلقائيًا إلى Gemini Enterprise > نظرة عامة.
انتقِل إلى الإعدادات.
في علامة التبويب إدارة الميزات، فعِّل تفعيل مصمّم البرامج الوكيلة، ثم انقر على حفظ.

تطبيق Gemini Enterprise للويب

افتح Gemini Enterprise من Cloud Console في علامة تبويب جديدة، ثم اتّبِع الخطوات التالية:

انقر على التطبيق الذي يحمل الاسم codelab.
انسخ عنوان URL الذي يظهر لأنّنا سنستخدمه للانتقال إلى تطبيق Gemini Enterprise على الويب في الخطوات التالية.

3- وكيل مخصّص بدون استخدام رمز

النموذج: Gemini
البيانات والإجراءات: تخزّن خدمة Gemini Enterprise البيانات في Google Workspace (تقويم Google وGmail وDrive وNotebookLM) وبحث Google.
أدوات إنشاء الوكلاء: "مصمّم وكيل Gemini Enterprise"
مضيف الوكيل: Gemini Enterprise
واجهة المستخدم: تطبيق Gemini Enterprise للويب

مراجعة المفاهيم

Gemini

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

مستودع بيانات Gemini Enterprise

مخزن بيانات Gemini Enterprise هو كيان يحتوي على البيانات التي تم استيعابها من مصدر بيانات تابع لجهة أولى، مثل Google Workspace أو تطبيقات تابعة لجهات خارجية، مثل Jira أو Salesforce. تُعرف مخازن البيانات التي تحتوي على بيانات من تطبيقات تابعة لجهات خارجية أيضًا باسم أدوات ربط البيانات.

أداة تصميم وكيل Gemini Enterprise

Gemini Enterprise Agent Designer هي منصة تفاعلية لا تتطلّب ترميزًا أو تتطلّب ترميزًا بسيطًا لإنشاء وكلاء أحاديي الخطوة ومتعدّدي الخطوات وإدارتهم وإطلاقهم في Gemini Enterprise.

مراجعة بنية الحل

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

تتطلّب مخازن بيانات Gemini Enterprise Workspace تفعيل واجهات برمجة التطبيقات التالية:

في وحدة تحكّم Google Cloud، فعِّل واجهات برمجة التطبيقات Calendar وGmail وPeople:

انقر على القائمة ☰ > واجهات برمجة التطبيقات والخدمات > واجهات برمجة التطبيقات والخدمات المفعَّلة، ثم تأكَّد من أنّ Google Calendar API وGmail API وPeople API مدرَجة في القائمة.

تتطلّب إجراءات "تقويم Workspace" وGmail في Gemini Enterprise إعداد شاشة موافقة:

في وحدة تحكّم Google Cloud، انقر على القائمة ☰ > منصة Google Auth > العلامة التجارية.

انقر على البدء.
ضمن معلومات التطبيق، اضبط اسم التطبيق على Codelab .
في حقل البريد الإلكتروني لدعم المستخدمين، اختَر عنوان بريد إلكتروني للدعم يمكن للمستخدمين التواصل معك من خلاله إذا كانت لديهم أسئلة حول موافقتهم.
انقر على التالي.
ضمن الجمهور، اختَر داخلي.
انقر على التالي.
ضمن معلومات الاتصال، أدخِل عنوان بريد إلكتروني يمكنك تلقّي إشعارات فيه بشأن أي تغييرات تطرأ على مشروعك.
انقر على التالي.
ضمن إنهاء، راجِع سياسة بيانات المستخدمين في خدمات Google API، وإذا كنت توافق عليها، ضَع علامة في المربّع أوافق على "سياسة بيانات المستخدمين في خدمات Google API".
انقر على متابعة ثم على إنشاء.

يتم حفظ الإعدادات ويتمّ إعادة توجيهك تلقائيًا إلى منصّة Google Auth > نظرة عامة.
انتقِل إلى الوصول إلى البيانات.
انقر على إضافة نطاقات أو إزالتها.
انسخ النطاقات التالية وألصِقها في حقل إضافة نطاقات يدويًا.

https://www.googleapis.com/auth/calendar.readonly
https://www.googleapis.com/auth/calendar.events
https://www.googleapis.com/auth/calendar.calendars
https://www.googleapis.com/auth/gmail.send
https://www.googleapis.com/auth/gmail.readonly

انقر على إضافة إلى الجدول، ثم على تعديل، ثم على حفظ.

لمزيد من المعلومات، يُرجى الاطّلاع على الدليل الكامل ضبط موافقة OAuth.

إنشاء بيانات اعتماد عميل OAuth

أنشئ عميل OAuth جديدًا لخدمة Gemini Enterprise من أجل مصادقة المستخدمين:

في وحدة تحكّم Google Cloud، انقر على القائمة ☰ > منصة Google Auth > العملاء.

انقر على + إنشاء عميل.
بالنسبة إلى نوع التطبيق، اختَر تطبيق الويب.
اضبط الاسم على codelab.
تخطَّ مصادر JavaScript المعتمَدة.
في قسم معرّفات الموارد المنتظمة (URI) المسموح بها لإعادة التوجيه، انقر على إضافة معرّف الموارد المنتظمة (URI) وأدخِل https://vertexaisearch.cloud.google.com/oauth-redirect.
انقر على إنشاء.
سيظهر مربّع حوار يتضمّن معرّف عميل OAuth وسرّه اللذين تم إنشاؤهما حديثًا. احفظ هذه المعلومات في مكان آمن.

إنشاء مخازن بيانات

افتح Gemini Enterprise من Cloud Console في علامة تبويب جديدة، ثم اتّبِع الخطوات التالية:

انقر على التطبيق الذي يحمل الاسم codelab.
في قائمة التنقّل، انقر على مخازن البيانات المرتبطة.
انقر على + مستودع بيانات جديد.
في المصدر، ابحث عن تقويم Google وانقر على اختيار.
في قسم الإجراءات، أدخِل معرّف العميل وسر العميل المحفوظَين من الخطوات السابقة، ثم انقر على التحقّق من صحة التفويض واتّبِع الخطوات لمصادقة عميل OAuth ومنحه الإذن.
فعِّل الإجراءَين إنشاء حدث في التقويم وتعديل حدث في التقويم.
انقر على متابعة.

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

أنشئ مستودع بيانات Google Gmail باتّباع الخطوات التالية:

انقر على + مستودع بيانات جديد.
في المصدر، ابحث عن Google Gmail، ثم انقر على اختيار.
في قسم الإجراءات، أدخِل معرّف العميل والرمز السري للعميل المحفوظَين من الخطوات السابقة، ثم انقر على التحقّق من التفويض.
فعِّل الإجراء إرسال رسالة إلكترونية.
انقر على متابعة.
في قسم الإعداد، اضبط اسم أداة ربط البيانات على gmail.
انقر على إنشاء.
ستتم إعادة توجيهك تلقائيًا إلى متاجر البيانات المرتبطة حيث يمكنك الاطّلاع على متجر البيانات الذي تمت إضافته حديثًا.

أنشئ مستودع بيانات Google Drive باتّباع الخطوات التالية:

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

إنشاء مستودع بيانات NotebookLM:

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

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

مخازن البيانات الاختبارية

افتح عنوان URL لتطبيق Gemini Enterprise على الويب الذي نسخناه سابقًا:

انقر على القائمة ☰ > محادثة جديدة.
في تذييل حقل رسالة المحادثة الجديدة، انقر على رمز الموصلات وفعِّل جميع الموصلات.
يمكنك الآن تجربة طلبات مرتبطة بالموصّلات. على سبيل المثال، في المحادثة، اكتب Do I have any meetings today? واضغط على enter.
بعد ذلك، حاوِل كتابة How many emails did I receive today? واضغط على enter.
أخيرًا، اكتب Give me the title of the last Drive file I created واضغط على enter.

إنشاء وكيل مخصّص

في تطبيق Gemini Enterprise للويب، أنشئ وكيلاً جديدًا باستخدام "مصمّم الوكلاء" باتّباع الخطوات التالية:

انقر على القائمة ☰ > + وكيل جديد.
في المحادثة، اكتب An agent that always sends pirate-themed emails but use normal English otherwise واضغط على enter.

تصمّم "أداة تصميم الوكيل" الوكيل استنادًا إلى الطلب وتفتحه في المحرِّر.
انقر على إنشاء

تجربة وكيل مخصّص

في تطبيق Gemini Enterprise للويب، يمكنك الدردشة مع الوكيل الذي تم إنشاؤه حديثًا باتّباع الخطوات التالية:
انقر على القائمة ☰ > المشرفون.
اختَر الوكيل ضمن برامج الوكلاء.
في تذييل حقل رسالة المحادثة الجديدة، انقر على رمز الموصلات، ثم انقر على تفعيل الإجراءات لـ البريد واتّبِع التعليمات لتفويض الوكيل
في المحادثة، اكتب Send an email to someone@example.com saying I'll see them at Cloud Next, generate some subject and body yourself واضغط على enter. يمكنك استبدال نموذج عنوان البريد الإلكتروني بعنوان بريدك الإلكتروني.
انقر على ✔️ لإرسال الرسالة الإلكترونية.

4. وكيل مخصّص باستخدام رموز برمجية

النموذج: Gemini
البيانات والإجراءات: مخازن بيانات Gemini Enterprise في Google Workspace (تقويم Google وGmail وDrive وNotebookLM)، وبحث Google، وخادم بروتوكول سياق نموذج البحث (MCP) في Vertex AI الذي تديره Google، ووظيفة أداة مخصّصة لإرسال رسائل Google Chat (عبر Google Chat API).
أدوات إنشاء الوكلاء: "حزمة تطوير الوكلاء" (ADK)
مضيف الوكيل: محرك وكلاء Vertex AI
واجهة المستخدم: تطبيق Gemini Enterprise للويب

سيتم دمجها في Gemini Enterprise باستخدام ميزة "استخدام نموذجك الخاص"، لذا علينا اتّباع خطوات النشر والتسجيل والإعداد.

مراجعة المفاهيم

Vertex AI

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

مجموعة أدوات تطوير الوكلاء (ADK)

حزمة تطوير الوكيل (ADK) هي مجموعة متخصّصة من الأدوات وأُطر العمل المصمَّمة لتبسيط عملية إنشاء وكلاء الذكاء الاصطناعي المستقلين من خلال توفير وحدات مُعدّة مسبقًا للاستدلال وإدارة الذاكرة ودمج الأدوات.

بروتوكول سياق النموذج (MCP)

بروتوكول سياق النموذج (MCP) هو معيار مفتوح مصمّم لإتاحة دمج سلس وآمن بين تطبيقات الذكاء الاصطناعي ومصادر البيانات أو الأدوات المختلفة من خلال واجهة عالمية "جاهزة للاستخدام".

أداة الدوال

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

مراجعة بنية الحل

مراجعة رمز المصدر

agent.py

...
MODEL = "gemini-2.5-flash"

# Gemini Enterprise authentication injects a bearer token into the ToolContext state.
# The key pattern is "GE_AUTH_NAME_<random_digits>".
# We dynamically parse this token to authenticate our MCP and API calls.
GE_AUTH_NAME = "enterprise-ai"

VERTEXAI_SEARCH_TIMEOUT = 15.0

def get_project_id():
    """Fetches the consumer project ID from the environment natively."""
    _, project = google.auth.default()
    if project:
        return project
    raise Exception(f"Failed to resolve GCP Project ID from environment.")

def find_serving_config_path():
    """Dynamically finds the default serving config in the engine."""
    project_id = get_project_id()
    engines = discoveryengine_v1.EngineServiceClient().list_engines(
        parent=f"projects/{project_id}/locations/global/collections/default_collection"
    )
    for engine in engines:
        # engine.name natively contains the numeric Project Number
        return f"{engine.name}/servingConfigs/default_serving_config"
    raise Exception(f"No Discovery Engines found in project {project_id}")

def _get_access_token_from_context(tool_context: ToolContext) -> str:
    """Helper method to dynamically parse the intercepted bearer token from the context state."""
    escaped_name = re.escape(GE_AUTH_NAME)
    pattern = re.compile(fr"^{escaped_name}_\d+$")
    # Handle ADK varying state object types (Raw Dict vs ADK State)
    state_dict = tool_context.state.to_dict() if hasattr(tool_context.state, 'to_dict') else tool_context.state
    matching_keys = [k for k in state_dict.keys() if pattern.match(k)]
    if matching_keys:
        return state_dict.get(matching_keys[0])
    raise Exception(f"No bearer token found in ToolContext state matching pattern {pattern.pattern}")

def auth_header_provider(tool_context: ToolContext) -> dict[str, str]:
    token = _get_access_token_from_context(tool_context)
    return {"Authorization": f"Bearer {token}"}

def send_direct_message(email: str, message: str, tool_context: ToolContext) -> dict:
    """Sends a Google Chat Direct Message (DM) to a specific user by email address."""
    chat_client = chat_v1.ChatServiceClient(
        credentials=Credentials(token=_get_access_token_from_context(tool_context))
    )

    # 1. Setup the DM space or find existing one
    person = chat_v1.User(
        name=f"users/{email}",
        type_=chat_v1.User.Type.HUMAN
    )
    membership = chat_v1.Membership(member=person)
    space_req = chat_v1.Space(space_type=chat_v1.Space.SpaceType.DIRECT_MESSAGE)
    setup_request = chat_v1.SetUpSpaceRequest(
        space=space_req,
        memberships=[membership]
    )
    space_response = chat_client.set_up_space(request=setup_request)
    space_name = space_response.name
    
    # 2. Send the message
    msg = chat_v1.Message(text=message)
    message_request = chat_v1.CreateMessageRequest(
        parent=space_name,
        message=msg
    )
    message_response = chat_client.create_message(request=message_request)
    
    return {"status": "success", "message_id": message_response.name, "space": space_name}

vertexai_mcp = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://discoveryengine.googleapis.com/mcp",
        timeout=VERTEXAI_SEARCH_TIMEOUT,
        sse_read_timeout=VERTEXAI_SEARCH_TIMEOUT
    ),
    tool_filter=['search'],
    # The auth_header_provider dynamically injects the bearer token from the ToolContext
    # into the MCP call for authentication.
    header_provider=auth_header_provider
)

# Answer nicely the following user queries:
#  - Please find my meetings for today, I need their titles and links
#  - What is the latest Drive file I created?
#  - What is the latest Gmail message I received?
#  - Please send the following message to someone@example.com: Hello, this is a test message.

root_agent = LlmAgent(
    model=MODEL,
    name='enterprise_ai',
    instruction=f"""
        You are a helpful assistant that always uses the Vertex AI MCP search tool to answer the user's message, unless the user asks you to send a message to someone.
        If the user asks you to send a message to someone, use the send_direct_message tool to send the message.
        You MUST unconditionally use the Vertex AI MCP search tool to find answer, even if you believe you already know the answer or believe the Vertex AI MCP search tool does not contain the data.
        The Vertex AI MCP search tool accesses the user's data through datastores including Google Drive, Google Calendar, and Gmail.
        Only use the Vertex AI MCP search tool with servingConfig and query parameters, do not use any other parameters.
        Always use the servingConfig {find_serving_config_path()} while using the Vertex AI MCP search tool.
    """,
    tools=[vertexai_mcp, FunctionTool(send_direct_message)]
)

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

يتطلّب الحلّ تفعيل واجهات برمجة تطبيقات إضافية:

في وحدة تحكّم Google Cloud، فعِّل واجهات برمجة التطبيقات Vertex AI وCloud Resource Manager وGoogle Chat:

انقر على القائمة ☰ > واجهات برمجة التطبيقات والخدمات > واجهات برمجة التطبيقات والخدمات المفعَّلة، ثم تأكَّد من أنّ Vertex AI API وCloud Resource Manager API وGoogle Chat API مدرَجة في القائمة.

يتطلّب الحلّ إذن وصول إضافي إلى البيانات:

في وحدة تحكّم Google Cloud، انقر على القائمة ☰ > منصة Google Auth > الوصول إلى البيانات.

انقر على إضافة نطاقات أو إزالتها.
انسخ النطاقات التالية وألصِقها في حقل إضافة نطاقات يدويًا.
انقر على إضافة إلى الجدول، ثم على تعديل، ثم على حفظ.

https://www.googleapis.com/auth/cloud-platform
https://www.googleapis.com/auth/chat.messages.create
https://www.googleapis.com/auth/chat.spaces.create

انقر على إضافة إلى الجدول، ثم على تعديل، ثم على حفظ.

تعديل بيانات اعتماد عميل OAuth

يتطلّب الحلّ معرّف موارد منتظم (URI) إضافيًا معتمَدًا لإعادة التوجيه:

في وحدة تحكّم Google Cloud، انقر على القائمة ☰ > منصة Google Auth > العملاء.

انقر على اسم العميل codelab.
في قسم معرّفات الموارد المنتظمة (URI) المسموح بها لإعادة التوجيه، انقر على إضافة معرّف الموارد المنتظمة (URI) وأدخِل https://vertexaisearch.cloud.google.com/static/oauth/oauth.html.
انقر على حفظ.

تفعيل Vertex AI Search MCP

في الوحدة الطرفية، نفِّذ ما يلي:

gcloud beta services mcp enable discoveryengine.googleapis.com \
     --project=$(gcloud config get-value project)

ضبط تطبيق Chat

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

اضبط اسم التطبيق والوصف على Gemini Enterprise.
اضبط عنوان URL للأفاتار على https://developers.google.com/workspace/add-ons/images/quickstart-app-avatar.png.
أزِل العلامة من المربّع تفعيل الميزات التفاعلية، ثم انقر على إيقاف في مربّع الحوار المشروط الذي يظهر.
اختَر تسجيل الأخطاء في خدمة Logging.
انقر على حفظ.

نشر وكيل في "محرك وكلاء Vertex AI"

نزِّل مستودع GitHub هذا.

في الوحدة الطرفية، افتح الدليل solutions/enterprise-ai-agent ثم نفِّذ ما يلي:

# 1. Create and activate a new virtual environment
python3 -m venv .venv
source .venv/bin/activate

# 2. Install poetry and project dependencies
pip install poetry
poetry install

# 3. Deploy the agent
adk deploy agent_engine \
  --project=$(gcloud config get-value project) \
  --region=us-central1 \
  --display_name="Enterprise AI" \
  enterprise_ai

عندما يظهر السطر Deploying to agent engine...‎ في السجلات، افتح وحدة طرفية جديدة ونفِّذ الأمر التالي لإضافة الأذونات المطلوبة إلى Vertex AI Reasoning Engine Service Agent:

# 1. Get the current Project ID
PROJECT_ID=$(gcloud config get-value project)

# 2. Extract the Project Number for that ID
PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format='value(projectNumber)')

# 3. Construct the Service Account name
SERVICE_ACCOUNT="service-${PROJECT_NUMBER}@gcp-sa-aiplatform-re.iam.gserviceaccount.com"

# 4. Apply the IAM policy binding
gcloud projects add-iam-policy-binding $PROJECT_ID \
     --member="serviceAccount:$SERVICE_ACCOUNT" \
     --role="roles/discoveryengine.viewer"

انتظِر إلى أن يكتمل تنفيذ الأمر adk deploy، ثم انسخ اسم المورد الخاص بالوكيل الذي تم نشره حديثًا من ناتج الأمر باللون الأخضر.

تسجيل وكيل في Gemini Enterprise

افتح Gemini Enterprise من Cloud Console في علامة تبويب جديدة، ثم اتّبِع الخطوات التالية:

انقر على التطبيق الذي يحمل الاسم codelab.
في قائمة التنقّل، انقر على الوكلاء.
انقر على + إضافة وكيل.
انقر على إضافة وكيل مخصّص من خلال Agent Engine. يظهر قسم التفويضات.
انقر على إضافة تفويض.
اضبط اسم التفويض على enterprise-ai. يتم إنشاء معرّف استنادًا إلى الاسم ويظهر تحت الحقل، لذا انسَخه.
اضبط معرّف العميل على القيمة نفسها التي تم ضبطها لمعرّف عميل OAuth الذي تم إنشاؤه وتعديله في الخطوات السابقة.
اضبط سر العميل على القيمة نفسها التي تم ضبطها لعميل OAuth الذي تم إنشاؤه وتعديله في الخطوات السابقة.
اضبط معرّف الموارد المنتظم (URI) للرمز المميز على https://oauth2.googleapis.com/token.
اضبط عنوان URI للتفويض على القيمة التالية بعد استبدال <CLIENT_ID> بمعرّف عميل OAuth الذي تم إنشاؤه وتعديله في الخطوات السابقة.

https://accounts.google.com/o/oauth2/v2/auth?client_id=<CLIENT_ID>&redirect_uri=https%3A%2F%2Fvertexaisearch.cloud.google.com%2Fstatic%2Foauth%2Foauth.html&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fcalendar.readonly%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fcalendar.calendars%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fcalendar.events%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fcloud-platform%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fgmail.send%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fgmail.readonly%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fchat.messages.create%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fchat.spaces.create&include_granted_scopes=true&response_type=code&access_type=offline&prompt=consent

انقر على تم ثم على التالي. يظهر قسم الإعداد.
اضبط اسم الوكيل ووصف الوكيل على Enterprise AI.
اضبط محرك الاستدلال الخاص بـ Agent Engine على اسم مورد محرك الاستدلال الذي تم نسخه في الخطوات السابقة. ويكون بالتنسيق التالي:

projects/<PROJECT_ID>/locations/<LOCATION>/reasoningEngines/<REASONING_ENGINE_ID>

انقر على إنشاء. يظهر الموظف الذي تمت إضافته حديثًا الآن ضمن موظفو الدعم.

تجربة وكيل

في تطبيق Gemini Enterprise للويب، يمكنك الدردشة مع الوكيل المسجَّل حديثًا باتّباع الخطوات التالية:
انقر على القائمة ☰ > المشرفون.
اختَر الوكيل ضمن من مؤسستك.
في المحادثة، اكتب Please find my meetings for today, I need their titles and links واضغط على enter.
انقر على تفويض، ثم اتّبِع خطوات التفويض.

يجيب الوكيل بقائمة أحداث التقويم (حسب حساب المستخدم).
في المحادثة، اكتب Please send a Chat message to someone@example.com with the following text: Hello! واضغط على enter.
يجيب الوكيل برسالة تأكيد.

5- الوكيل التلقائي كإضافة على Google Workspace

تتيح هذه الأداة للمستخدمين البحث عن بيانات في Workspace بلغتهم الطبيعية في سياق واجهات مستخدم تطبيقات Workspace. ويعتمد على العناصر التالية:

النموذج: Gemini
البيانات: مخازن بيانات Gemini Enterprise في Google Workspace (تقويم Google وGmail وDrive وNotebookLM) وبحث Google
مضيف الوكيل: Gemini Enterprise
واجهة المستخدم: إضافة Google Workspace إلى Chat وGmail (يمكن توسيعها بسهولة لتشمل "تقويم Google" وDrive و"مستندات Google" و"جداول بيانات Google" و"العروض التقديمية من Google")
إضافة Google Workspace: خدمة "برمجة التطبيقات" وGemini Enterprise وواجهات برمجة التطبيقات Vertex AI والسياقية (بيانات وصفية للمستخدم ورسالة Gmail المحدّدة)

سيتم ربط إضافة Google Workspace بـ Gemini Enterprise باستخدام StreamAssist API.

مراجعة المفاهيم

إضافة Google Workspace

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

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

برمجة تطبيقات Google هي منصة مستندة إلى السحابة الإلكترونية تستخدم JavaScript وتعمل من خلال Google Drive، وتتيح لك التكامل مع المهام وتشغيلها تلقائيًا في جميع منتجات Google.

إطار عمل بطاقة Google Workspace

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

مراجعة بنية الحلّ

مراجعة رمز المصدر

appsscript.json

...
"addOns": {
    "common": {
      "name": "Enterprise AI",
      "logoUrl": "https://developers.google.com/workspace/add-ons/images/quickstart-app-avatar.png"
    },
    "chat": {},
    "gmail": {
      "contextualTriggers": [
        {
          "unconditional": {},
          "onTriggerFunction": "onAddonEvent"
        }
      ]
    }
  },
  "oauthScopes": [
    "https://www.googleapis.com/auth/script.external_request",
    "https://www.googleapis.com/auth/discoveryengine.assist.readwrite",
    "https://www.googleapis.com/auth/gmail.addons.execute",
    "https://www.googleapis.com/auth/gmail.addons.current.message.readonly"
  ]
...

Chat.gs

...
// Service that handles Google Chat operations.

// Handle incoming Google Chat message events, actions will be taken via Google Chat API calls
function onMessage(event) {
  if (isInDebugMode()) {
    console.log(`MESSAGE event received (Chat): ${JSON.stringify(event)}`);
  }
  // Extract data from the event.
  const chatEvent = event.chat;
  setChatConfig(chatEvent.messagePayload.space.name);

  // Request AI agent to answer the message
  requestAgent(chatEvent.messagePayload.message);
  // Respond with an empty response to the Google Chat platform to acknowledge execution
  return null; 
}

// --- Utility functions ---

// The Chat direct message (DM) space associated with the user
const SPACE_NAME_PROPERTY = "DM_SPACE_NAME"

// Sets the Chat DM space name for subsequent operations.
function setChatConfig(spaceName) {
  const userProperties = PropertiesService.getUserProperties();
  userProperties.setProperty(SPACE_NAME_PROPERTY, spaceName);
  console.log(`Space is set to ${spaceName}`);
}

// Retrieved the Chat DM space name to sent messages to.
function getConfiguredChat() {
  const userProperties = PropertiesService.getUserProperties();
  return userProperties.getProperty(SPACE_NAME_PROPERTY);
}

// Finds the Chat DM space name between the Chat app and the given user.
function findChatAppDm(userName) {
  return Chat.Spaces.findDirectMessage(
    { 'name': userName },
    {'Authorization': `Bearer ${getAddonCredentials().getAccessToken()}`}
  ).name;
}

// Creates a Chat message in the configured space.
function createMessage(message) {
  const spaceName = getConfiguredChat();
  console.log(`Creating message in space ${spaceName}...`);
  return Chat.Spaces.Messages.create(
    message,
    spaceName,
    {},
    {'Authorization': `Bearer ${getAddonCredentials().getAccessToken()}`}
  ).name;
}

...
// Service that handles Gmail operations.

// Triggered when the user opens the Gmail Add-on or selects an email.
function onAddonEvent(event) {
  // If this was triggered by a button click, handle it
  if (event.parameters && event.parameters.action === 'send') {
    return handleSendMessage(event);
  }

  // Otherwise, just render the default initial sidebar
  return createSidebarCard();
}

// Creates the standard Gmail sidebar card consisting of a text input and send button.
// Optionally includes an answer section if a response was generated.
function createSidebarCard(optionalAnswerSection) {
  const card = CardService.newCardBuilder();
  const actionSection = CardService.newCardSection();

  // Create text input for the user's message
  const messageInput = CardService.newTextInput()
    .setFieldName("message")
    .setTitle("Message")
    .setMultiline(true);

  // Create action for sending the message
  const sendAction = CardService.newAction()
    .setFunctionName('onAddonEvent')
    .setParameters({ 'action': 'send' });

  const sendButton = CardService.newTextButton()
    .setText("Send message")
    .setTextButtonStyle(CardService.TextButtonStyle.FILLED)
    .setOnClickAction(sendAction);

  actionSection.addWidget(messageInput);
  actionSection.addWidget(CardService.newButtonSet().addButton(sendButton));

  card.addSection(actionSection);

  // Attach the response at the bottom if we have one
  if (optionalAnswerSection) {
    card.addSection(optionalAnswerSection);
  }

  return card.build();
}

// Handles clicks from the Send message button.
function handleSendMessage(event) {
  const commonEventObject = event.commonEventObject || {};
  const formInputs = commonEventObject.formInputs || {};
  const messageInput = formInputs.message;

  let userMessage = "";
  if (messageInput && messageInput.stringInputs && messageInput.stringInputs.value.length > 0) {
    userMessage = messageInput.stringInputs.value[0];
  }

  if (!userMessage || userMessage.trim().length === 0) {
    return CardService.newActionResponseBuilder()
      .setNotification(CardService.newNotification().setText("Please enter a message."))
      .build();
  }

  let finalQueryText = `USER MESSAGE TO ANSWER: ${userMessage}`;

  // If we have an email selected in Gmail, append its content as context
  if (event.gmail && event.gmail.messageId) {
    try {
      GmailApp.setCurrentMessageAccessToken(event.gmail.accessToken);
      const message = GmailApp.getMessageById(event.gmail.messageId);

      const subject = message.getSubject();
      const bodyText = message.getPlainBody() || message.getBody();

      finalQueryText += `\n\nEMAIL THE USER HAS OPENED ON SCREEN:\nSubject: ${subject}\nBody:\n---\n${bodyText}\n---`;
    } catch (e) {
      console.error("Could not fetch Gmail context: " + e);
      // Invalidate the token explicitly so the next prompt requests the missing scopes
      ScriptApp.invalidateAuth();

      CardService.newAuthorizationException()
        .setResourceDisplayName("Enterprise AI")
        .setAuthorizationUrl(ScriptApp.getAuthorizationUrl())
        .throwException();
    }
  }

  try {
    const responseText = queryAgent({ text: finalQueryText, forceNewSession: true });

    // We leverage the 'showdown' library to parse the LLM's Markdown output into HTML
    // We also substitute markdown listings with arrows and adjust newlines for clearer rendering in the sidebar
    let displayedText = substituteListingsFromMarkdown(responseText);
    displayedText = new showdown.Converter().makeHtml(displayedText).replace(/\n/g, '\n\n');

    const textParagraph = CardService.newTextParagraph();
    textParagraph.setText(displayedText);

    const answerSection = CardService.newCardSection()
      .addWidget(textParagraph);

    const updatedCard = createSidebarCard(answerSection);

    return CardService.newActionResponseBuilder()
      .setNavigation(CardService.newNavigation().updateCard(updatedCard))
      .build();

  } catch (err) {
    return CardService.newActionResponseBuilder()
      .setNotification(CardService.newNotification().setText("Error fetching response: " + err.message))
      .build();
  }
}
...

AgentHandler.gs

...
// Service that handles Gemini Enterprise AI Agent operations.

// Submits a query to the AI agent and returns the response string synchronously
function queryAgent(input) {
  const isNewSession = input.forceNewSession || !PropertiesService.getUserProperties().getProperty(AGENT_SESSION_NAME);
  const sessionName = input.forceNewSession ? createAgentSession() : getOrCreateAgentSession();

  let systemPrompt = "SYSTEM PROMPT START Do not respond with tables but use bullet points instead.";
  if (input.forceNewSession) {
    systemPrompt += " Do not ask the user follow-up questions or converse with them as history is not kept in this interface.";
  }
  systemPrompt += " SYSTEM PROMPT END\n\n";

  const queryText = isNewSession ? systemPrompt + input.text : input.text;

  const requestPayload = {
    "session": sessionName,
    "userMetadata": { "timeZone": Session.getScriptTimeZone() },
    "query": { "text": queryText },
    "toolsSpec": { "vertexAiSearchSpec": { "dataStoreSpecs": getAgentDataStores().map(ds => { dataStore: ds }) } },
    "agentsSpec": { "agentSpecs": [{ "agentId": getAgentId() }] }
  };

  const responseContentText = UrlFetchApp.fetch(
    `https://${getLocation()}-discoveryengine.googleapis.com/v1alpha/${getReasoningEngine()}/assistants/default_assistant:streamAssist?alt=sse`,
    {
      method: 'post',
      headers: { 'Authorization': `Bearer ${ScriptApp.getOAuthToken()}` },
      contentType: 'application/json',
      payload: JSON.stringify(requestPayload),
      muteHttpExceptions: true
    }
  ).getContentText();

  if (isInDebugMode()) {
    console.log(`Response: ${responseContentText}`);
  }

  const events = responseContentText.split('\n').map(s => s.replace(/^data:\s*/, '')).filter(s => s.trim().length > 0);
  console.log(`Received ${events.length} agent events.`);

  let answerText = "";
  for (const eventJson of events) {
    if (isInDebugMode()) {
      console.log("Event: " + eventJson);
    }
    const event = JSON.parse(eventJson);

    // Ignore internal events
    if (!event.answer) {
      console.log(`Ignored: internal event`);
      continue;
    }

    // Handle text replies
    const replies = event.answer.replies || [];
    for (const reply of replies) {
      const content = reply.groundedContent.content;
      if (content) {
        if (isInDebugMode()) {
          console.log(`Processing content: ${JSON.stringify(content)}`);
        }
        if (content.thought) {
          console.log(`Ignored: thought event`);
          continue;
        }
        answerText += content.text;
      }
    }

    if (event.answer.state === "SUCCEEDED") {
      console.log(`Answer text: ${answerText}`);
      return answerText;
    } else if (event.answer.state !== "IN_PROGRESS") {
      throw new Error("Something went wrong, check the Apps Script logs for more info.");
    }
  }
  return answerText;
}

// Gets the list of data stores configured for the agent to include in the request.
function getAgentDataStores() {
  const responseContentText = UrlFetchApp.fetch(
    `https://${getLocation()}-discoveryengine.googleapis.com/v1/${getReasoningEngine().split('/').slice(0, 6).join('/')}/dataStores`,
    {
      method: 'get',
      // Use the add on service account credentials for data store listing access
      headers: { 'Authorization': `Bearer ${getAddonCredentials().getAccessToken()}` },
      contentType: 'application/json',
      muteHttpExceptions: true
    }
  ).getContentText();
  if (isInDebugMode()) {
    console.log(`Response: ${responseContentText}`);
  }
  const dataStores = JSON.parse(responseContentText).dataStores.map(ds => ds.name);
  if (isInDebugMode()) {
    console.log(`Data stores: ${dataStores}`);
  }
  return dataStores;
}
...

بدء حساب الخدمة

في وحدة تحكّم Google Cloud، اتّبِع الخطوات التالية:

انقر على القائمة ☰ > إدارة الهوية وإمكانية الوصول والمشرف > حسابات الخدمة > + إنشاء حساب خدمة.

اضبط اسم حساب الخدمة على ge-add-on.

انقر على إنشاء ومتابعة.
أضِف الدور مشاهد "محرك البحث أثناء التصفّح" في الأذونات.

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

اختَر حساب الخدمة الذي تم إنشاؤه حديثًا، ثم انقر على علامة التبويب المفاتيح.
انقر على إضافة مفتاح ثم على إنشاء مفتاح جديد.
اختَر JSON ثمّ انقر على إنشاء.

يتم إغلاق مربّع الحوار ويتم تلقائيًا تنزيل زوج المفتاح العام/الخاص الذي تم إنشاؤه حديثًا إلى بيئتك المحلية كملف JSON.

إنشاء مشروع "برمجة تطبيقات Google" وضبطه

انقر على الزر التالي لفتح مشروع إضافة Enterprise AI في "برمجة تطبيقات Google":

انقر على نظرة عامة > إنشاء نسخة.
في مشروع "برمجة تطبيقات Google"، انقر على إعدادات المشروع > تعديل خصائص النص البرمجي > إضافة خاصية نص برمجي لإضافة خصائص النص البرمجي.
اضبط قيمة REASONING_ENGINE_RESOURCE_NAME على اسم مورد تطبيق Gemini Enterprise. ويكون بالتنسيق التالي:

# 1. Replace PROJECT_ID with the Google Cloud project ID.
# 2. Replace GE_APP_ID with the codelab app ID found in Google Cloud console > Gemini Enterprise > Apps.

projects/<PROJECT_ID>/locations/global/collections/default_collection/engines/<GE_APP_ID>

اضبط APP_SERVICE_ACCOUNT_KEY على مفتاح JSON من ملف حساب الخدمة الذي تم تنزيله في الخطوات السابقة.
انقر على حفظ مواقع النص البرمجي.

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

في مشروعك على Apps Script، اتّبِع الخطوات التالية:

انقر على نشر > اختبار عمليات النشر، ثم على تثبيت. وهي متاحة الآن في Gmail.
انقر على نسخ ضمن رقم تعريف عملية نشر العنوان.

في وحدة تحكّم Google Cloud، اتّبِع الخطوات التالية:

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

اختَر تفعيل الميزات التفاعلية.
ألغِ اختيار الانضمام إلى المساحات والمحادثات الجماعية.
ضمن إعدادات الاتصال، اختَر Apps Script.
اضبط رقم تعريف النشر على رقم تعريف النشر الرئيسي الذي تم نسخه في الخطوات السابقة.
ضمن مستوى الرؤية، اختَر إتاحة تطبيق Chat هذا لمستخدمين ومجموعات محدّدة في نطاق Workspace وأدخِل عنوان بريدك الإلكتروني.
انقر على حفظ.

تجربة الإضافة

افتح Google Chat في علامة تبويب جديدة، ثم اتّبِع الخطوات التالية:

افتح مساحة رسائل مباشرة باستخدام تطبيق Chat Gemini Enterprise.

انقر على ضبط واتّبِع خطوات المصادقة.
اكتب What are my meetings for today? واضغط على enter. يجب أن يردّ تطبيق المحادثة Gemini Enterprise بالنتائج.

افتح Gmail في علامة تبويب جديدة، ثم اتّبِع الخطوات التالية:

أرسِل إلى نفسك رسالة إلكترونية مع ضبط الموضوع على We need to talk والنص على Are you available today between 8 and 9 AM?
افتح رسالة البريد الإلكتروني التي تلقّيتها مؤخرًا.
افتح الشريط الجانبي لإضافة الذكاء الاصطناعي للمؤسسات.
اضبط الرسالة على Am I?
انقر على إرسال رسالة.
تظهر الإجابة بعد الزر.

6. تَنظيم

حذف مشروع Google Cloud

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

في وحدة تحكّم Google Cloud، اتّبِع الخطوات التالية:

انقر على القائمة ☰ > إدارة الهوية وإمكانية الوصول والمشرف > الإعدادات.

انقر على إيقاف.
أدخِل رقم تعريف المشروع.
انقر على إيقاف الاستضافة على البنية الأساسية القديمة.

7. تهانينا

تهانينا! لقد أنشأتم حلولاً تستفيد من إمكانية دمج Gemini Enterprise وGoogle Workspace معًا لتسهيل العمل على الموظفين.

ما هي الخطوات التالية؟

نحن نعرض فقط حالات الاستخدام الأكثر شيوعًا في هذا الدرس العملي، ولكن هناك الكثير من مجالات التوسّع التي قد تحتاج إلى أخذها في الاعتبار في حلولك، مثل ما يلي:

استخدام أدوات مطوّرين مستندة إلى الذكاء الاصطناعي، مثل Gemini CLI وAntigravity
التكامل مع أُطر عمل وأدوات أخرى خاصة بالوكلاء، مثل MCP مخصّصة، واستدعاء دالات مخصّصة، وواجهات مستخدم توليدية
التكامل مع نماذج الذكاء الاصطناعي الأخرى، بما في ذلك النماذج المخصّصة والمستضافة على منصات مخصّصة مثل Vertex AI
يمكنك الدمج مع برامج أخرى مستضافة على منصات مخصصة، مثل Dialogflow أو من خلال جهات خارجية عبر Cloud Marketplace.
نشر وكلاء على Cloud Marketplace لتمكين الفِرق أو المؤسسات أو المستخدمين العامين

مزيد من المعلومات

تتوفّر العديد من المراجع للمطوّرين، مثل فيديوهات YouTube ومواقع المستندات الإلكترونية وعيّنات التعليمات البرمجية والأدلة التعليمية:

دمج "وكلاء Gemini Enterprise" مع Google Workspace

1. قبل البدء

ما هو Gemini Enterprise؟

ما هو Google Workspace؟

ما هي أنواع عمليات الدمج المخصّصة؟

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

ما ستنشئه

وكيل مخصّص بدون استخدام رمز

وكيل مخصّص باستخدام رمز

الوكيل التلقائي كإضافة على Google Workspace

ما ستتعلمه

2. طريقة الإعداد

مراجعة المفاهيم

تطبيق Gemini Enterprise

تطبيق Gemini Enterprise للويب

تهيئة الموارد والوصول إليها

تطبيق Gemini Enterprise

تطبيق Gemini Enterprise للويب

3- وكيل مخصّص بدون استخدام رمز

مراجعة المفاهيم

Gemini

مستودع بيانات Gemini Enterprise

أداة تصميم وكيل Gemini Enterprise

مراجعة بنية الحل

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

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

إنشاء بيانات اعتماد عميل OAuth

إنشاء مخازن بيانات

مخازن البيانات الاختبارية

إنشاء وكيل مخصّص

تجربة وكيل مخصّص

4. وكيل مخصّص باستخدام رموز برمجية

مراجعة المفاهيم

Vertex AI

مجموعة أدوات تطوير الوكلاء (ADK)

بروتوكول سياق النموذج (MCP)

أداة الدوال

مراجعة بنية الحل

مراجعة رمز المصدر

agent.py

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

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

تعديل بيانات اعتماد عميل OAuth

تفعيل Vertex AI Search MCP

ضبط تطبيق Chat

نشر وكيل في "محرك وكلاء Vertex AI"

تسجيل وكيل في Gemini Enterprise

تجربة وكيل

5- الوكيل التلقائي كإضافة على Google Workspace

مراجعة المفاهيم

إضافة Google Workspace

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

إطار عمل بطاقة Google Workspace

مراجعة بنية الحلّ

مراجعة رمز المصدر

appsscript.json

Chat.gs

Sidebar.gs

AgentHandler.gs

بدء حساب الخدمة

إنشاء مشروع "برمجة تطبيقات Google" وضبطه

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

تجربة الإضافة

6. تَنظيم

حذف مشروع Google Cloud

7. تهانينا

ما هي الخطوات التالية؟

مزيد من المعلومات