دمج "وكلاء Vertex AI" مع Google Workspace

1. قبل البدء

99afae2505f696fb.png

ما هي منصة Vertex AI؟

‫Vertex AI هي منصة تطوير موحّدة من Google Cloud لإنشاء وتفعيل وتوسيع نطاق تطبيقات ووكلاء الذكاء الاصطناعي المصمّمة للمؤسسات. توفّر هذه المنصة للمطوّرين وعلماء البيانات الأدوات المتطورة اللازمة لتصميم سير عمل مخصّص مستند إلى الذكاء الاصطناعي الوكيل ومدمج بشكل كبير مع بنية أساسية عالمية النطاق.

  • الوصول إلى Model Garden: يمكنك الاختيار من بين أكثر من 150 نموذجًا أساسيًا، بما في ذلك مجموعة Gemini الكاملة ونماذج الجهات الخارجية والنماذج المتخصصة المفتوحة المصدر للعثور على النموذج المناسب لمهام الوكيل المحددة.
  • تصميم عمليات تنظيم معقّدة: توفّر Vertex AI إطارًا لتصميم وكلاء مستقلين يستخدمون المنطق للتخطيط وتنفيذ المهام المتعدّدة الخطوات واستدعاء واجهات برمجة التطبيقات الخارجية.
  • التأسيس على بيانات المؤسسة: يمكنك ربط الوكلاء ببيانات النشاط التجاري المباشرة، بما في ذلك ميزة RAG (الإنشاء المستند إلى الاسترجاع) العالية الأداء، وذلك لإزالة الهلوسات وضمان الدقة الواقعية.
  • عمليات التطوير والتشغيل (DevOps): يمكنك دمج عملية تطوير الوكيل بسلاسة في مسارات CI/CD الحالية باستخدام حِزم تطوير البرامج (SDK) وواجهات برمجة التطبيقات (API) وأدوات التقييم القوية لقياس أداء الوكيل وسلامته على نطاق واسع.
  • أمان على مستوى المؤسسة: تضمن Vertex AI بقاء بيانات العملاء المستخدَمة في التدريب أو التأسيس خاصة ومشفّرة ومتوافقة مع متطلبات الإقامة العالمية.
  • بنية تحتية محسّنة: يمكنك توسيع نطاق أحجام المعالجة المستندة إلى الوكلاء بسهولة على مستوى مجموعات وحدات معالجة الموتّرات (TPU) ووحدات معالجة الرسومات (GPU) ذات المستوى العالمي من Google، ما يضمن أداءً سريعًا حتى بالنسبة إلى التطبيقات العالمية الأكثر تطلّبًا.

127f2ed7d484722c.png

ما هو Google Workspace؟

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

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

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

تتيح Google Workspace وVertex AI إنشاء حلقة ملاحظات فعّالة، حيث يوفّر Workspace بيانات في الوقت الفعلي وسياقًا للتعاون، بينما توفّر Vertex AI النماذج والاستدلال الوكيلي والتنظيم اللازم لأتمتة سير العمل الذكي.

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

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

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

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

ما ستنشئه

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

تطبيق Vertex AI Search

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

  • النموذج: Gemini
  • البيانات والإجراءات: مخازن بيانات Vertex AI لـ Google Workspace (تقويم Google وGmail وDrive)
  • مضيف الوكيل: Vertex AI Search
  • واجهة المستخدم: أداة الويب الخاصة بخدمة Vertex AI Search

d276ff8e2b9d0ddf.png

الوكيل المخصّص

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

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

145f47f45332e6be.png

293ec4d3e2bb6a0.png

وكيل كإضافة في Google Workspace

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

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

172da43f310a0579.png

840b494aa5eaa1ef.png

ما ستتعلمه

  • نقاط الدمج بين Vertex AI Search وGoogle Workspace التي تتيح البيانات والإجراءات
  • خيارات إنشاء وكلاء مخصّصين مستضافين في Vertex AI
  • الطرق التي يمكن للمستخدمين من خلالها الوصول إلى الوكلاء، مثل "أداة البحث على الويب" في Vertex AI Search وتطبيقات Google Workspace

2. إعداد

قبل إنشاء الحلول، علينا ضبط إعدادات "تطبيقات Vertex AI" الخاصة بالمشروع وتفعيل واجهات برمجة التطبيقات المطلوبة وإنشاء مستودعات بيانات Vertex AI Workspace.

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

تطبيق Vertex AI

تطبيق Vertex AI هو حلّ مُدار ومتكامل على Google Cloud يدمج نماذج تعلُّم الآلة (مثل الوكلاء المستندين إلى الذكاء الاصطناعي التوليدي أو محركات البحث) مع بيانات المؤسسة والأدوات المتخصصة لتنفيذ مهام معقدة، مثل البحث الدلالي أو إنشاء المحتوى أو التفاعل الآلي مع العملاء.

مخزن بيانات Vertex AI

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

بدء إعدادات "تطبيقات Vertex AI"

ابدأ إعدادات "تطبيقات Vertex AI" لتفعيل إنشاء الوكلاء.

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

  1. اختَر مشروعك.
  2. في حقل البحث في Google Cloud، انتقِل إلى تطبيقات الذكاء الاصطناعي.

  1. انقر على متابعة وتفعيل واجهة برمجة التطبيقات بعد مراجعة البنود والموافقة عليها.
  2. الانتقال إلى الإعدادات (Settings)، ثم
  3. في علامة التبويب المصادقة، عدِّل العالمي.

93b0cc6ed63fba0c.png

  1. اختَر Google Identity، ثمّ انقر على حفظ.

5c01b4cbeebaa93b.png

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

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

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

3877dcaa56624d0b.png

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

.

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

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

  1. في Google Cloud Console، انتقِل إلى تطبيقات الذكاء الاصطناعي، ثم انتقِل إلى مخازن البيانات.

  1. انقر على + إنشاء مستودع بيانات.
  2. في المصدر، ضِمن Google Drive، انقر على اختيار.

6939363368bde36d.png

  1. في البيانات، اختَر الكل، ثم انقر على متابعة.

5044243322acec9e.png

  1. في الإعداد، اضبط اسم أداة ربط البيانات على drive، ثم انقر على متابعة بعد مراجعة الرسوم التي قد تنطبق والموافقة عليها.

1f5deb1aeecee983.png

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

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

  1. انقر على + إنشاء مستودع بيانات.
  2. في المصدر، ابحث عن تقويم Google وانقر على اختيار.
  3. في قسم الإجراءات، انقر على تخطّي.
  4. في قسم الإعداد، اضبط اسم أداة ربط البيانات على calendar.
  5. انقر على إنشاء.
  6. ستتم إعادة توجيهك تلقائيًا إلى مخازن البيانات حيث يمكنك الاطّلاع على مخزن البيانات الذي تمت إضافته حديثًا.

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

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

3- تطبيق Vertex AI Search

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

  • النموذج: Gemini
  • البيانات والإجراءات: مخازن بيانات Vertex AI لـ Google Workspace (تقويم Google وGmail وDrive)
  • مضيف الوكيل: Vertex AI Search
  • واجهة المستخدم: أداة الويب الخاصة بخدمة Vertex AI Search

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

تطبيق Vertex AI Search

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

أداة الويب Vertex AI Search

‫Vertex AI Search Web Widget هو مكوّن واجهة مستخدم مبرمَج مسبقًا وقابل للتخصيص يتيح للمطوّرين تضمين شريط بحث وواجهة نتائج مستندَين إلى الذكاء الاصطناعي مباشرةً في موقع إلكتروني بأقل قدر من الترميز.

معاينة Vertex AI Search

‫Vertex AI Search Preview هي بيئة اختبار مدمجة ضمن Google Cloud Console تتيح للمطوّرين التحقّق من صحة إعدادات البحث والإجابات التوليدية قبل نشر هذه الإعدادات بسلاسة في أداة ويب Vertex AI Search الجاهزة للاستخدام في مرحلة الإنتاج.

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

1f337dc91da74391.png

إنشاء تطبيق

أنشئ تطبيق بحث جديدًا لربط مخازن البيانات.

افتح تطبيقات الذكاء الاصطناعي > التطبيقات من Cloud Console، ثم اتّبِع الخطوات التالية:

  1. انقر على إنشاء تطبيق.
  2. في النوع، ضِمن البحث المخصّص (عام)، انقر على إنشاء.

9714a5fff49b5e1b.png

  1. في الإعداد، ضَع علامة في المربّع بجانب ميزات إصدار Enterprise والردود التوليدية بعد مراجعة الأسعار والموافقة عليها.
  2. اضبط اسم التطبيق على codelab.
  3. يتم إنشاء معرّف استنادًا إلى الاسم ويظهر تحت الحقل، لذا انسَخه.
  4. اضبط اسم الشركة على Codelab.
  5. اضبط المنطقة المتعدّدة على global (Global).
  6. انقر على متابعة.

327702cd837cbb18.png

  1. في البيانات، اختَر مخازن البيانات drive وgmail وcalendar، ثم انقر على متابعة.

5745607f3c43d5c0.png

  1. في الأسعار، اختَر نموذج الأسعار المفضّل لديك وانقر على إنشاء. يُنصح باستخدام الأسعار العامة في سياق هذا الدرس العملي.
  2. يتم إنشاء التطبيق ويتمّت إعادة توجيهك تلقائيًا إلى تطبيقات الذكاء الاصطناعي > التطبيقات > codelab > نظرة عامة على التطبيق.
  3. انتقِل إلى مخازن البيانات المرتبطة.
  4. بعد بضع دقائق، من المفترض أن تكون جميع حالات "مخزن البيانات" المرتبط نشطة.

d53ed9d9d1ced955.png

ضبط أداة الويب

ضبط المظهر المرئي وسلوك أداة البحث

  1. انتقِل إلى الإعدادات.
  2. في علامة التبويب واجهة المستخدم، اضبط نوع البحث على البحث مع المتابعات، ثم انقر على حفظ ونشر.

af1ca3bd78e1cb4f.png

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

اختبِر تطبيق البحث مباشرةً في Google Cloud Console.

  1. انتقِل إلى معاينة، وسيتم عرض تطبيق الويب المصغّر.
  2. في المحادثة، اكتب Do I have any meetings today? واضغط على enter.
  3. في المحادثة، اكتب Did I receive an email on March 1st 2026? واضغط على enter.
  4. في المحادثة، اكتب Give me the title of the latest Drive file I created واضغط على enter.

d276ff8e2b9d0ddf.png

4. الوكيل المخصّص

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

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

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

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

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

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

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

أداة الدوال

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

ADK Web

‫ADK web هي واجهة مستخدم مدمجة للمطوّرين تأتي مع حزمة تطوير البرامج (SDK) الخاصة بـ ADK لتسهيل عملية التطوير وتصحيح الأخطاء.

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

f14251cca6a19b1f.png

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

agent.py

يصادق الرمز التالي على Vertex AI، ويهيئ أدوات واجهة برمجة التطبيقات MCP وChat في Vertex AI Search، ويحدد سلوك الوكيل.

  1. المصادقة: تسترد هذه السمة ACCESS_TOKEN من متغيّرات البيئة لمصادقة MCP وطلبات البيانات من واجهة برمجة التطبيقات.
  2. إعداد الأدوات: يتم تهيئة vertexai_mcp، وهي مجموعة أدوات تتصل بخادم Model Context Protocol (MCP) الخاص بخدمة "بحث Vertex AI"، والأداة send_direct_message. يمنح هذا الإذن الوكيل القدرة على البحث في مستودعات البيانات المرتبطة وإرسال رسائل Google Chat.
  3. تعريف الوكيل: يحدّد root_agent باستخدام نموذج gemini-2.5-flash. تطلب التعليمات من الوكيل تحديد أولوية استخدام أداة البحث لاسترداد المعلومات وأداة send_direct_message لتنفيذ الإجراءات، ما يضمن استناد الوكيل إلى بيانات مؤسستك.
...
MODEL = "gemini-2.5-flash"

# Access token for authentication
ACCESS_TOKEN = os.environ.get("ACCESS_TOKEN")
if not ACCESS_TOKEN:
    raise ValueError("ACCESS_TOKEN environment variable must be set")

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 send_direct_message(email: str, message: str) -> dict:
    """Sends a Google Chat Direct Message (DM) to a specific user by email address."""
    chat_client = chat_v1.ChatServiceClient(
        credentials=Credentials(token=ACCESS_TOKEN)
    )

    # 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,
        headers={"Authorization": f"Bearer {ACCESS_TOKEN}"}
    ),
    tool_filter=['search']
)

# 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)]
)

تنزيل رمز المصدر

نزِّل الرمز النموذجي إلى بيئتك المحلية للبدء.

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

  1. في نافذة طرفية، افتح الدليل solutions/enterprise-ai-agent-local.

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

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

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

60bae4065338c5bf.png

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

.

يتطلّب الحلّ إعداد شاشة طلب الموافقة:

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

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

bb53eeb45c51d301.png

  1. يتم حفظ الإعدادات ويتمّ إعادة توجيهك تلقائيًا إلى منصّة Google Auth > نظرة عامة.

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

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

أنشِئ عميل OAuth جديدًا لتطبيق على الكمبيوتر المكتبي لمصادقة المستخدم في بيئة محلية:

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

  1. انقر على + إنشاء عميل.
  2. بالنسبة إلى نوع التطبيق، اختَر تطبيق على الكمبيوتر.
  3. اضبط الاسم على codelab.
  4. انقر على إنشاء. تظهر بيانات الاعتماد التي تم إنشاؤها حديثًا.
  5. انقر على تنزيل JSON واحفظ الملف باسم client_secret.json في الدليل solutions/enterprise-ai-agent-local.

c1c9bc2f8c14dd6c.png

تفعيل Vertex AI Search MCP

  1. في الوحدة الطرفية، نفِّذ ما يلي:
gcloud beta services mcp enable discoveryengine.googleapis.com \
     --project=$(gcloud config get-value project)

ضبط تطبيق Chat

اضبط تطبيق Google Chat باستخدام تفاصيله المعلوماتية الأساسية.

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

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

952e7ebcb945f1b2.png

تشغيل الوكيل في "أداة تطوير التطبيقات" على الويب

تشغيل الوكيل محليًا باستخدام واجهة ADK Web

  1. في الوحدة الطرفية، افتح الدليل solutions/enterprise-ai-agent-local ثم نفِّذ ما يلي:
# 1. Authenticate with all the required scopes
gcloud auth application-default login \
  --client-id-file=client_secret.json \
   --scopes=https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/chat.spaces,https://www.googleapis.com/auth/chat.messages

# 2. Configure environment
export ACCESS_TOKEN=$(gcloud auth application-default print-access-token)
export GOOGLE_GENAI_USE_VERTEXAI=1
export GOOGLE_CLOUD_PROJECT=$(gcloud config get-value project)
export GOOGLE_CLOUD_LOCATION=us-central1

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

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

# 5. Start ADK Web
adk web

95fc30883ce3d56f.png

تجربة وكيل

تحقَّق من صحة التدفق من خلال الدردشة مع الوكيل المخصّص.

  1. في متصفّح الإنترنت، افتح موقع ADK الإلكتروني.
  2. في المحادثة، اكتب Please find my meetings for today, I need their titles and links واضغط على enter.
  3. يجيب الوكيل بقائمة أحداث التقويم (حسب حساب المستخدم).
  4. في المحادثة، اكتب Please send a Chat message to someone@example.com with the following text: Hello! واضغط على enter.
  5. يجيب الوكيل برسالة تأكيد.

145f47f45332e6be.png

293ec4d3e2bb6a0.png

5- "الوكيل" كإضافة على Google Workspace

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

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

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

إضافة 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.

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

f2fd048ba298f431.png

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

الوكيل

agent.py

يصادق الرمز التالي على Vertex AI، ويهيئ أدوات واجهة برمجة التطبيقات MCP وChat في Vertex AI Search، ويحدد سلوك الوكيل.

  1. المصادقة: تستخدِم هذه السمة دالة مساعدة _get_access_token_from_context لاسترداد رمز المصادقة المميز (CLIENT_AUTH_NAME) الذي يدرجه العميل. هذه الرمز المميز ضروري لإجراء عمليات استدعاء آمنة للخدمات النهائية، مثل Vertex AI Search MCP وأدوات Google Chat.
  2. إعداد الأدوات: يتم تهيئة vertexai_mcp، وهي مجموعة أدوات تتصل بخادم Model Context Protocol (MCP) الخاص بخدمة "بحث Vertex AI"، والأداة send_direct_message. يمنح هذا الإذن الوكيل القدرة على البحث في مستودعات البيانات المرتبطة وإرسال رسائل Google Chat.
  3. تعريف الوكيل: يحدّد root_agent باستخدام نموذج gemini-2.5-flash. تطلب التعليمات من الوكيل تحديد أولوية استخدام أداة البحث لاسترداد المعلومات وأداة send_direct_message لتنفيذ الإجراءات، ما يضمن استناد الوكيل إلى بيانات مؤسستك.
...
MODEL = "gemini-2.5-flash"

# Client injects a bearer token into the ToolContext state.
# The key pattern is "CLIENT_AUTH_NAME_<random_digits>".
# We dynamically parse this token to authenticate our MCP and API calls.
CLIENT_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(CLIENT_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)]
)

العميل

appsscript.json

يحدّد الإعداد التالي مشغّلات الإضافة وأذوناتها.

  1. تحديد الإضافة: يوضّح هذا القسم لـ Workspace أنّ هذا المشروع هو إضافة لكل من Chat وGmail.
  2. المشغّلات السياقية: بالنسبة إلى Gmail، يتم إعداد contextualTrigger يتم تشغيله onAddonEvent عندما يفتح المستخدم رسالة إلكترونية. يسمح هذا للإضافة "بالاطّلاع على" محتوى الرسالة الإلكترونية.
  3. الأذونات: تعرض هذه الصفحة oauthScopes المطلوبة لتشغيل الإضافة، مثل أذونات قراءة الرسالة الإلكترونية الحالية وتنفيذ النص البرمجي والربط بالخدمات الخارجية (مثل واجهات Vertex AI API).
...
"addOns": {
    "common": {
      "name": "Vertex 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/cloud-platform",
   "https://www.googleapis.com/auth/gmail.addons.execute",
   "https://www.googleapis.com/auth/gmail.addons.current.message.readonly"
 ]
...

Chat.gs

يتعامل الرمز التالي مع رسائل Google Chat الواردة.

  1. تلقّي الرسائل: الدالة onMessage هي نقطة الدخول للتفاعلات مع الرسائل.
  2. إدارة السياق: يتم حفظ space.name (معرّف مساحة Chat) في خصائص المستخدم. يضمن ذلك أنّه عندما يكون الوكيل جاهزًا للردّ، سيعرف بالضبط المحادثة التي يجب نشر الرسالة فيها.
  3. التفويض إلى الوكيل: يتم استدعاء requestAgent، مع تمرير رسالة المستخدم إلى المنطق الأساسي الذي يتعامل مع عملية التواصل مع واجهة برمجة التطبيقات.
...
// 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;
}

Sidebar.gs

ينشئ الرمز التالي الشريط الجانبي في Gmail ويجمع سياق الرسالة الإلكترونية.

  1. إنشاء واجهة المستخدم: ينشئ createSidebarCard الواجهة المرئية باستخدام خدمة بطاقات Workspace. ينشئ هذا الرمز تخطيطًا بسيطًا يتضمّن مساحة لإدخال النص وزر "إرسال رسالة".
  2. التقاط سياق البريد الإلكتروني: في handleSendMessage، يتحقّق الرمز مما إذا كان المستخدم يطّلع حاليًا على رسالة إلكترونية (event.gmail.messageId). وفي حال كان كذلك، يتم استرداد موضوع الرسالة الإلكترونية ونصها بشكل آمن وإلحاقهما بطلب المستخدم.
  3. عرض النتيجة: بعد أن يردّ الوكيل، يعدّل الرمز البرمجي بطاقة الشريط الجانبي لعرض الردّ.
...
// 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 response = queryAgent({ text: finalQueryText });

    // 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(response.text);
    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

ينسّق الرمز التالي طلب البيانات من واجهة برمجة التطبيقات إلى Vertex AI.

  1. تنسيق طلب البيانات من واجهة برمجة التطبيقات: يشكّل queryAgent الجسر بين الإضافة و"محرك وكلاء Vertex AI". تنشئ هذه الدالة طلبًا يتضمّن طلب البحث ورمز المصادقة في الحالة.
  2. بثّ الردود: بما أنّ ردود الوكيل قد تستغرق بعض الوقت، تستخدم واجهة برمجة التطبيقات streamQuery مع أحداث يتم إرسالها من الخادم (SSE). يجمع الرمز الردّ على شكل أجزاء ويعيد إنشاء الإجابة الكاملة.
...
// Service that handles Vertex AI Agent operations.

// Submits a query to the AI agent and returns the response string synchronously
function queryAgent(input) {
 let systemPrompt = "SYSTEM PROMPT START Do not respond with tables but use bullet points instead." +
   " Do not ask the user follow-up questions or converse with them as history is not kept in this interface." +
   " SYSTEM PROMPT END\n\n";

 const requestPayload = {
   "class_method": "async_stream_query",
   "input": {
     "user_id": "vertex_ai_add_on",
     "message": { "role": "user", "parts": [{ "text": systemPrompt + input.text }] },
     "state_delta": {
       "enterprise-ai_999": `${ScriptApp.getOAuthToken()}`
     }
   }
 };

 const responseContentText = UrlFetchApp.fetch(
   `https://${getLocation()}-aiplatform.googleapis.com/v1/${getReasoningEngine()}:streamQuery?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 author = "default";
 let answerText = "";
 for (const eventJson of events) {
   if (isInDebugMode()) {
     console.log("Event: " + eventJson);
   }
   const event = JSON.parse(eventJson);

   // Retrieve the agent responsible for generating the content
   author = event.author;
  
   // Ignore events that are not useful for the end-user
   if (!event.content) {
     console.log(`${author}: internal event`);
     continue;
   }

   // Handle text answers
   const parts = event.content.parts || [];
   const textPart = parts.find(p => p.text);
   if (textPart) {
     answerText += textPart.text;
   }
 }
 return { author: author, text: answerText };
}
...

تفعيل الوكيل في "محرك وكلاء Vertex AI"

  1. في الوحدة الطرفية، افتح الدليل solutions/enterprise-ai-agent من المصادر التي تم تنزيلها في الخطوات السابقة، ثم نفِّذ ما يلي:
# 1. Create and activate a new virtual environment
deactivate
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

eafd2f9c4fbf305.png

  1. عندما يظهر السطر 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"
  1. انتظِر إلى أن يكتمل تنفيذ الأمر adk deploy، ثم انسخ اسم المورد الخاص بالوكيل الذي تم نشره حديثًا من ناتج الأمر باللون الأخضر.

d098fe1347d6581b.png

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

أنشِئ حساب خدمة مخصّصًا لتفويض عمليات الإضافة من جهة الخادم.

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

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

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

46be0eb53f416c59.png

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

f002fef61c71ed8.png

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

7b140535d9e1af44.png

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

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

أنشئ مشروعًا جديدًا في "برمجة التطبيقات" لاستضافة رمز الإضافة وإعداد خصائص الاتصال.

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

  1. انقر على نظرة عامة > إنشاء نسخة.
  2. في مشروع "برمجة تطبيقات Google"، انقر على إعدادات المشروع > تعديل خصائص النص البرمجي > إضافة خاصية نص برمجي لإضافة خصائص النص البرمجي.
  3. اضبط قيمة REASONING_ENGINE_RESOURCE_NAME على اسم مورد وكيل Vertex AI الذي تم نسخه في الخطوات السابقة. ويكون بالتنسيق التالي:
projects/<PROJECT_NUMBER>/locations/us-central1/reasoningEngines/<AGENT_ID>
  1. اضبط APP_SERVICE_ACCOUNT_KEY على مفتاح JSON من ملف حساب الخدمة الذي تم تنزيله في الخطوات السابقة.
  2. انقر على حفظ مواقع النص البرمجي.

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

يمكنك نشر الإضافة لاختبارها مباشرةً في Gmail وGoogle Chat.

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

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

b0cba69eef271850.png

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

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

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

6ea187ccb90a0e49.png

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

تفاعَل مع الإضافة المباشرة للتأكّد من أنّها يمكنها استرداد البيانات والإجابة عن الأسئلة في السياق.

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

  1. افتح مساحة رسائل مباشرة باستخدام تطبيق Chat Vertex AI.

495632314dec5a5d.png

  1. انقر على ضبط واتّبِع خطوات المصادقة.
  2. اكتب What are my meetings for today? واضغط على enter. يجب أن يردّ تطبيق الدردشة Vertex AI بالنتائج.

172da43f310a0579.png

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

  1. أرسِل إلى نفسك رسالة إلكترونية مع ضبط الموضوع على We need to talk والنص على Are you available today between 8 and 9 AM?
  2. افتح رسالة البريد الإلكتروني التي تلقّيتها مؤخرًا.
  3. افتح الشريط الجانبي الخاص بإضافة Vertex AI.
  4. اضبط الرسالة على Do I have any meeting conflicts?
  5. انقر على إرسال رسالة.
  6. تظهر الإجابة بعد الزر.

840b494aa5eaa1ef.png

6. تَنظيم

حذف مشروع Google Cloud

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

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

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

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

3b9492d97f771b2c.png

7. تهانينا

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

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

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

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

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

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