שילוב של סוכני Gemini Enterprise עם Google Workspace

1. לפני שמתחילים

מה זה Gemini Enterprise?

‫Gemini Enterprise היא פלטפורמה מתקדמת שמבוססת על סוכנים ומביאה את היכולות הכי שימושיות של Google AI לכל עובד, בכל תהליך עבודה. הפלטפורמה עוזרת לצוותים לגלות, ליצור, לשתף ולהפעיל סוכני AI בסביבה מאובטחת אחת.

גישה למודלים מתקדמים: המשתמשים מקבלים גישה מיידית ל-AI מולטי-מודאלי הכי מתקדם של Google, כולל Gemini, כדי להתמודד עם אתגרים עסקיים מורכבים.
שימוש בסוכנים מומחים: החבילה כוללת סוכני Google מוכנים לשימוש למחקר, לכתיבת קוד ולסיכום הערות, כדי לספק ערך מיידי.
העצמת כל העובדים: אפשרויות בלי צורך בתכנות ועם קוד מאפשרות לעובדים בכל המחלקות ליצור ולנהל סוכנים מותאמים אישית משלהם לאוטומציה של תהליכי עבודה.
התבססות של סוכנים על נתונים: אפשר לחבר סוכנים בצורה מאובטחת לנתונים פנימיים של החברה ולאפליקציות של צד שלישי, כדי לוודא שהתשובות שלהם מדויקות בהקשר.
ניהול מרכזי: אדמינים יכולים לראות את כל הפעילות של הסוכנים ולבדוק אותה כדי לוודא שהארגון עומד בתקני אבטחה ותאימות מחמירים.
הרחבה באמצעות מערכות אקולוגיות: הפלטפורמה משתלבת עם רשת רחבה של אפליקציות שותפים וספקי שירותים כדי להרחיב את האוטומציה במערכות שונות.

מה זה Google Workspace?

‫Google Workspace היא אוסף של פתרונות מבוססי-ענן לפרודוקטיביות ולשיתוף פעולה, שמיועדים לאנשים פרטיים, לבתי ספר ולעסקים:

תקשורת: שירותי אימייל מקצועיים (Gmail), שיחות ועידה בווידאו (Meet) והודעות לצוות (Chat).
יצירת תוכן: כלים לכתיבת מסמכים (Docs), ליצירת גיליונות אלקטרוניים (Sheets) ולעיצוב מצגות (Slides).
ארגון: יומנים משותפים (יומנים) וסיכום פגישות דיגיטלי (Keep).
אחסון: נפח אחסון בענן שבו אפשר לשמור ולשתף קבצים באופן מאובטח (Drive).
ניהול: אמצעי בקרה לאדמינים לניהול משתמשים והגדרות אבטחה (מסוף Admin של Workspace).

איזה סוג של שילובים בהתאמה אישית?

‫Google Workspace ו-Gemini Enterprise יוצרים לולאת משוב עוצמתית שבה Workspace מספק נתונים בזמן אמת והקשר לשיתוף פעולה, ו-Gemini Enterprise מציע את המודלים, את ההסקה האג'נטית ואת התזמור שנדרשים כדי להפוך תהליכי עבודה חכמים לאוטומטיים.

קישוריות חכמה: מאגרי נתונים, ממשקי API ושרתי MCP (מנוהלים על ידי Google ומותאמים אישית) שמנוהלים על ידי Google מאפשרים לסוכנים לגשת בצורה חלקה ומאובטחת לנתוני Workspace ולבצע פעולות בשם המשתמשים.
סוכנים בהתאמה אישית: צוותים יכולים ליצור סוכנים מיוחדים שמתבססים על נתונים ופעולות ב-Workspace שמנוהלים על ידי האדמין, באמצעות מעצבים בלי צורך בתכנות או מסגרות קוד מקצועיות.
שילוב מקורי: תוספים ל-Workspace מגשרים על הפער בין מערכות AI לבין אפליקציות כמו Chat ו-Gmail, בין אם באמצעות רכיבי ממשק משתמש ייעודיים או תהליכים שמתבצעים ברקע. כך הנציגים יכולים לפגוש את המשתמשים בדיוק במקום שבו הם נמצאים ולספק להם עזרה מיידית בהתאם להקשר.

שילוב של מערכת הפרודוקטיביות החזקה של Google Workspace עם היכולות המתקדמות של Gemini Enterprise מאפשר לארגונים לשנות את הפעילות שלהם באמצעות סוכני AI מותאמים אישית שמבוססים על נתונים ומבצעים אוטומציה של תהליכי עבודה מורכבים ישירות בכלים שהצוותים שלהם כבר משתמשים בהם מדי יום.

דרישות מוקדמות

אם רוצים לבצע את כל השלבים בסביבה שלכם, צריך:

ידע בסיסי ב-Google Cloud וב-Python.
פרויקט בענן של Google שאתם הבעלים שלו עם חיוב. במאמר אימות סטטוס החיוב של פרויקטים מוסבר איך לבדוק אם החיוב מופעל בפרויקט קיים. כדי ליצור פרויקט ולהגדיר חיוב, אפשר לעיין במאמר יצירת פרויקט בענן ב-Google Cloud. כדי לשנות את הבעלות על פרויקט, אפשר לעיין במאמר ניהול חברים בפרויקט או שינוי הבעלות על פרויקט.
מהדורות Gemini Enterprise Standard או Plus מופעלות. כדי להשוות בין מהדורות Gemini Enterprise, אפשר לעיין במאמר השוואה בין מהדורות Gemini Enterprise. אם אין לכם רישיון ל-Gemini Enterprise, בשלב הבא תהיה לכם אפשרות ליצור רישיון לתקופת ניסיון.
חשבון Google Workspace במהדורת Business או Enterprise עם גישה ל-Google Chat והתכונות החכמות מופעלות.
ה-CLI של Google Cloud מותקן ומופעל עבור הפרויקט שלכם ב-Google Cloud.
‫Python 3.11 ואילך מותקן. הוראות מפורטות זמינות באתר הרשמי של Python.

מה תפַתחו

ב-Codelab הזה נבנה שלושה פתרונות עם סוכני AI של 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 (יומן, Gmail, ‏ Drive, ‏ NotebookLM), ‏ חיפוש Google, שרת Model Context Protocol‏ (MCP) של חיפוש מבוסס-Vertex AI שמנוהל על ידי Google, פונקציית כלי בהתאמה אישית לשליחת הודעות ב-Google Chat (באמצעות Google Chat API).
כלים ליצירת סוכנים: Agent Development Kit (ADK).
מארח הסוכן: Vertex AI Agent Engine.
ממשק משתמש: Gemini Enterprise בדפדפן.

הגדרת סוכן ברירת המחדל כתוסף ל-Google Workspace

הסוכן הזה מאפשר למשתמשים לחפש נתונים ב-Workspace בשפה טבעית בהקשר של ממשקי משתמש של אפליקציות Workspace. הוא מבוסס על הרכיבים הבאים:

מודל: Gemini.
נתונים: מאגרי נתונים של Gemini Enterprise ל-Google Workspace (יומן Google, ‏ Gmail, ‏ Drive, ‏ NotebookLM), ‏ חיפוש Google.
מארח הסוכן: Gemini Enterprise.
ממשק משתמש: תוסף Google Workspace ל-Chat ול-Gmail (אפשר להרחיב אותו בקלות ליומן, ל-Drive, ל-Docs, ל-Sheets ול-Slides).
תוסף ל-Google Workspace: Apps Script, ממשקי Gemini Enterprise ו-Vertex AI API, נתונים הקשריים (מטא-נתונים של המשתמש, הודעת Gmail שנבחרה).

מה תלמדו

נקודות השילוב בין Gemini Enterprise ל-Google Workspace שמאפשרות נתונים ופעולות.
אפשרויות ליצירת סוכנים בהתאמה אישית שמתארחים ב-Gemini Enterprise, בלי צורך בתכנות או עם תכנות.
הדרכים שבהן משתמשים יכולים לגשת לסוכנים מאפליקציית האינטרנט Gemini Enterprise ומאפליקציות Google Workspace.

2. להגדרה

מושגים שכדאי להכיר

אפליקציית Gemini Enterprise

אפליקציית Gemini Enterprise מספקת למשתמשי הקצה תוצאות חיפוש, פעולות וסוכנים. המונח 'אפליקציה' יכול לשמש לסירוגין עם המונח 'מנוע' בהקשר של ממשקי API. כדי להשתמש בנתונים ממאגר נתונים להצגת תוצאות חיפוש, תשובות או פעולות, צריך לקשר את האפליקציה למאגר הנתונים.

אתר Gemini Enterprise

אפליקציית Gemini Enterprise בדפדפן משויכת לאפליקציית Gemini Enterprise. היא משמשת כמרכז AI שבו העובדים יכולים להשתמש בממשק צ'אט יחיד כדי לחפש נתונים של החברה שמאוחסנים במיקומים שונים, להפעיל סוכני AI מיוחדים לתהליכי עבודה מורכבים וליצור תוכן מקצועי עם פרטיות ברמה ארגונית.

הפעלה וגישה למשאבים

בקטע הזה מוסבר איך לגשת למשאבים הבאים ולהגדיר אותם מדפדפן האינטרנט המועדף.

אפליקציית Gemini Enterprise

פותחים את מסוף Google Cloud בכרטיסייה חדשה ופועלים לפי השלבים הבאים:

בוחרים את הפרויקט הרצוי.
בשדה החיפוש של Google Cloud, מחפשים את Gemini Enterprise ובוחרים בו, ואז לוחצים על + Create app (יצירת אפליקציה). אם אין לכם רישיון ל-Gemini Enterprise, תתבקשו להפעיל רישיון לניסיון חינם למשך 30 יום.

מגדירים את שם האפליקציה ל-codelab.
המערכת יוצרת מזהה על סמך השם ומציגה אותו מתחת לשדה. מעתיקים אותו.
מגדירים את במספר אזורים לערך global (Global).
לוחצים על יצירה.

האפליקציה נוצרת ואתם מועברים אוטומטית אל Gemini Enterprise > סקירה כללית.
בקטע קבלת גישה מלאה, לוחצים על הגדרת זהות.
במסך החדש, בוחרים באפשרות שימוש בזהות Google ולוחצים על אישור זהות כוח העבודה.

ההגדרה נשמרת ואתם מועברים אוטומטית אל Gemini Enterprise > סקירה כללית.
עוברים אל הגדרות.
בכרטיסייה ניהול תכונות, מפעילים את האפשרות הפעלת כלי לעיצוב סוכנים ולוחצים על שמירה.

‫Gemini Enterprise בדפדפן

פותחים את Gemini Enterprise ממסוף Cloud בכרטיסייה חדשה, ואז מבצעים את השלבים הבאים:

לוחצים על האפליקציה שנקראת codelab.
מעתיקים את כתובת ה-URL שמופיעה, כי נשתמש בה כדי לנווט לאפליקציית האינטרנט של Gemini Enterprise בשלבים הבאים.

3. סוכן מותאם אישית בלי צורך בתכנות

הסוכן הזה מאפשר למשתמשים לחפש נתונים ולבצע פעולות ב-Workspace בשפה טבעית. הוא מבוסס על הרכיבים הבאים:

מודל: Gemini.
נתונים ופעולות: מאגרי נתונים של Gemini Enterprise ל-Google Workspace (יומן Google, ‏ Gmail, ‏ Drive, ‏ NotebookLM), ‏ חיפוש Google.
כלי בניית סוכנים: Gemini Enterprise כלי לתכנון סוכנים.
מארח הסוכן: Gemini Enterprise.
ממשק משתמש: Gemini Enterprise בדפדפן.

מושגים שכדאי להכיר

Gemini

‫Gemini הוא מודל שפה גדול (LLM) מולטי-מודאלי מבית Google. הוא עוזר לאנשים לממש את הפוטנציאל האנושי שלהם, כדי שיוכלו להרחיב את הדמיון, להגביר את הסקרנות ולשפר את הפרודוקטיביות.

מאגר נתונים של Gemini Enterprise

מאגר נתונים של Gemini Enterprise הוא ישות שמכילה את הנתונים שנקלטים ממקור נתונים מאינטראקציה ישירה (First-Party), כמו Google Workspace או אפליקציות של צד שלישי כמו Jira או Salesforce. מאגרי נתונים שמכילים נתונים מאפליקציות של צד שלישי נקראים גם מחברי נתונים.

כלי לתכנון סוכנים ב-Gemini Enterprise

‫ Gemini Enterprise Agent Designer הוא כלי אינטראקטיבי לתכנון סוכנים, בלי צורך בתכנות או עם תכנות מינימלי, שמאפשר ליצור, לנהל ולהפעיל סוכנים עם שלב אחד או כמה שלבים ב-Gemini Enterprise.

בדיקת ארכיטקטורת הפתרון

הפעלת ממשקי API

כדי להשתמש במאגרי הנתונים של Workspace ב-Gemini Enterprise, צריך להפעיל את ממשקי ה-API הבאים:

ב-מסוף Google Cloud, מפעילים את ממשקי ה-API של יומן Google, Gmail ואנשים:

לוחצים על תפריט ☰ > ממשקי API ושירותים > ממשקי API ושירותים מופעלים ומוודאים ש-Google Calendar API,‏ Gmail API ו-People API מופיעים ברשימה.

כדי להשתמש בפעולות של יומן Google ו-Gmail ב-Gemini Enterprise, צריך להגדיר מסך הסכמה:

במסוף Google Cloud, לוחצים על תפריט ☰ > פלטפורמת האימות של Google > מיתוג.

לוחצים על שנתחיל?.
בקטע App Information, מגדירים את App name לערך Codelab .
בקטע User support email, בוחרים כתובת אימייל לתמיכה שאליה משתמשים יפנו אם יש להם שאלות לגבי ההסכמה שלהם.
לוחצים על Next.
בקטע Audience, לוחצים על Internal.
לוחצים על Next.
בקטע Contact Information, מזינים כתובת אימייל שאליה אפשר לשלוח התראות על שינויים בפרויקט.
לוחצים על הבא.
בקטע Finish, קוראים את המדיניות של Google בנושא נתוני משתמשים בשירותי API. אם אתם מסכימים, מסמנים את התיבה I agree to the Google API Services: User Data Policy.
לוחצים על המשך ואז על יצירה.

ההגדרה נשמרת ואתם מועברים אוטומטית אל Google Auth Platform > Overview.
עוברים אל Data Access (גישה לנתונים).
לוחצים על הוספה או הסרה של היקפים.
מעתיקים את היקפי ההרשאות הבאים ומדביקים אותם בשדה הוספת היקפי הרשאות באופן ידני.

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 > לקוחות.

לוחצים על + יצירת לקוח.
ב-Application type בוחרים באפשרות אפליקציית אינטרנט.
מגדירים את Name לערך codelab.
מדלגים על מקורות מורשים של JavaScript.
בקטע Authorized redirect URIs (כתובות URI מורשות להפניה אוטומטית), לוחצים על Add URI (הוספת כתובת URI) ומזינים https://vertexaisearch.cloud.google.com/oauth-redirect.
לוחצים על יצירה.
תיפתח תיבת דו-שיח עם מזהה הלקוח והסוד החדשים של לקוח OAuth. חשוב לשמור את המידע הזה במקום בטוח.

יצירת מאגרי נתונים

כדי לקשר את Gemini Enterprise לנתוני Workspace, צריך ליצור מאגרי נתונים.

פותחים את Gemini Enterprise ממסוף Cloud בכרטיסייה חדשה, ואז פועלים לפי השלבים הבאים:

לוחצים על האפליקציה שנקראת codelab.
בתפריט הניווט, לוחצים על מאגרי נתונים מקושרים.
לוחצים על + מאגר נתונים חדש.
במקור, מחפשים את יומן Google ולוחצים על בחירה.
בקטע Actions (פעולות), מזינים את Client ID (מזהה הלקוח) ואת Client Secret (סוד הלקוח) ששמרתם בשלבים הקודמים, ואז לוחצים על Verify Auth (אימות הרשאה) ופועלים לפי השלבים לאימות ולאישור של לקוח OAuth.
מפעילים את הפעולות יצירת אירוע ביומן ועדכון אירוע ביומן.
לוחצים על המשך.

בקטע Configuration, מגדירים את שם מחבר הנתונים לערך calendar.
לוחצים על יצירה.
תועברו אוטומטית אל מאגרי נתונים מקושרים, שם תוכלו לראות את מאגר הנתונים שנוסף לאחרונה.

יוצרים את מאגר הנתונים של Google Gmail:

לוחצים על + מאגר נתונים חדש.
בשדה מקור, מחפשים את Google Gmail ולוחצים על בחירה.
בקטע Actions (פעולות), מזינים את Client ID (מזהה לקוח) ואת Client Secret (סוד לקוח) ששמרתם בשלבים הקודמים, ואז לוחצים על Verify Auth (אימות הרשאה).
מפעילים את הפעולה שליחת אימייל.
לוחצים על המשך.
בקטע Configuration, מגדירים את שם מחבר הנתונים לערך gmail.
לוחצים על יצירה.
תועברו אוטומטית אל מאגרי נתונים מקושרים, שם תוכלו לראות את מאגר הנתונים שנוסף לאחרונה.

יוצרים את מאגר הנתונים של Google Drive:

לוחצים על + מאגר נתונים חדש.
במקור, מחפשים את Google Drive ולוחצים על בחירה.
בקטע נתונים, בוחרים באפשרות הכול ולוחצים על המשך.
בקטע Configuration, מגדירים את שם מחבר הנתונים לערך drive.
לוחצים על יצירה.
תועברו אוטומטית אל מאגרי נתונים מקושרים, שם תוכלו לראות את מאגר הנתונים שנוסף לאחרונה.

יוצרים את מאגר הנתונים של NotebookLM:

לוחצים על + מאגר נתונים חדש.
במקור, מחפשים את NotebookLM ולוחצים על בחירה.
בקטע Configuration, מגדירים את שם מחבר הנתונים לערך 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 (יומן, Gmail, ‏ Drive, ‏ NotebookLM), ‏ חיפוש Google, שרת Model Context Protocol‏ (MCP) של חיפוש מבוסס-Vertex AI שמנוהל על ידי Google, פונקציית כלי בהתאמה אישית לשליחת הודעות ב-Google Chat (באמצעות Google Chat API).
כלים ליצירת סוכנים: Agent Development Kit (ADK).
מארח הסוכן: Vertex AI Agent Engine.
ממשק משתמש: Gemini Enterprise בדפדפן.

הוא ישולב ב-Gemini Enterprise באמצעות התכונה 'הוספת מודל משלכם', ולכן נצטרך לבצע את השלבים של פריסה, הרשמה והגדרה.

מושגים שכדאי להכיר

Vertex AI

‫Vertex AI מציע את כל מה שצריך כדי ליצור ולהשתמש ב-AI גנרטיבי, כולל פתרונות AI, חיפוש ושיחה, יותר מ-130 מודלים בסיסיים ופלטפורמת AI מאוחדת.

ערכת פיתוח של סוכנים (ADK)

הערכה לפיתוח סוכנים (ADK) היא חבילה ייעודית של כלים ומסגרות שנועדה לפשט את תהליך היצירה של סוכני AI אוטונומיים. היא כוללת מודולים מוכנים מראש לניתוח, לניהול זיכרון ולשילוב כלים.

Model Context Protocol (MCP)

‫ Model Context Protocol‏ (MCP) הוא תקן פתוח שנועד לאפשר שילוב חלק ומאובטח בין אפליקציות AI לבין מקורות נתונים או כלים שונים באמצעות ממשק אוניברסלי של 'הכנס והפעל'.

כלי הפונקציות

כלי פונקציות הוא שגרה מוגדרת מראש שניתנת להפעלה, ומודל AI יכול להפעיל אותה כדי לבצע פעולות ספציפיות או לאחזר נתונים בזמן אמת ממערכות חיצוניות. כך הוא יכול לבצע פעולות מעבר ליצירת טקסט פשוטה.

בדיקת ארכיטקטורת הפתרון

בדיקת קוד המקור

agent.py

הקוד הבא מבצע אימות ב-Gemini Enterprise, מאתחל את הכלים חיפוש מבוסס-Vertex AI MCP ו-Chat API, ומגדיר את ההתנהגות של הסוכן.

אימות: הפונקציה משתמשת בפונקציית עזר _get_access_token_from_context כדי לאחזר את אסימון האימות (CLIENT_AUTH_NAME) שמוזרק על ידי Gemini Enterprise. האסימון הזה חיוני כדי לבצע קריאות מאובטחות לשירותים במורד הזרם, כמו חיפוש מבוסס-Vertex AI MCP וכלי Google Chat.
הגדרת כלים: המערכת מאתחלת את vertexai_mcp, ערכת כלים שמתחברת לשרת Model Context Protocol‏ (MCP) של חיפוש מבוסס-Vertex AI, ואת הכלי send_direct_message. כך הנציג יכול לחפש במאגרי הנתונים המקושרים שלכם ולשלוח הודעות ב-Google Chat.
הגדרת הסוכן: ההגדרה מגדירה את root_agent באמצעות מודל gemini-2.5-flash. ההוראות אומרות לנציג לתת עדיפות לשימוש בכלי החיפוש לאחזור מידע ובכלי send_direct_message לביצוע פעולות, וכך למעשה הנציג מתבסס על נתוני הארגון שלכם.

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

# Gemini Enterprise authentication 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)]
)

הפעלת ממשקי API

כדי להשתמש בפתרון, צריך להפעיל ממשקי API נוספים:

ב-מסוף Google Cloud, מפעילים את ממשקי ה-API של Vertex AI,‏ Cloud Resource Manager ו-Google Chat:

לוחצים על Menu ☰ > APIs & Services > Enabled APIs & Services ומוודאים ש-Vertex AI API,‏ Cloud Resource Manager API ו-Google Chat API מופיעים ברשימה.

הפתרון דורש גישה נוספת לנתונים:

במסוף Google Cloud, לוחצים על תפריט ☰ > פלטפורמת אימות של Google > גישה לנתונים.

לוחצים על הוספה או הסרה של היקפים.
מעתיקים את היקפי ההרשאות הבאים ומדביקים אותם בשדה הוספת היקפי הרשאות באופן ידני.
לוחצים על הוספה לטבלה, ואז על עדכון ואז על שמירה.

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 > לקוחות.

לוחצים על שם הלקוח codelab.
בקטע Authorized redirect URIs (כתובות URI מורשות להפניה אוטומטית), לוחצים על Add URI (הוספת כתובת URI) ומזינים https://vertexaisearch.cloud.google.com/static/oauth/oauth.html.
לוחצים על שמירה.

הפעלת חיפוש מבוסס-Vertex AI MCP

במסוף, מריצים את הפקודה:

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

הגדרת אפליקציה ל-Chat

מגדירים את אפליקציית Google Chat עם הפרטים הבסיסיים שלה.

ב-מסוף Google Cloud, מחפשים את Google Chat API בשדה החיפוש של Google Cloud, לוחצים על Google Chat API, על Manage ואז על Configuration.

מגדירים את שם האפליקציה ואת התיאור לערך Gemini Enterprise.
מגדירים את כתובת ה-URL של האווטאר ל-https://developers.google.com/workspace/add-ons/images/quickstart-app-avatar.png.
מבטלים את הסימון של הפעלת תכונות אינטראקטיביות ואז לוחצים על השבתה בתיבת הדו-שיח המודאלית שמופיעה.
בוחרים באפשרות Log errors to Logging (רישום שגיאות ב-Logging).
לוחצים על שמירה.

פריסת סוכן ב-Vertex AI Agent Engine

פורסים את הסוכן בתשתית של Vertex AI Agent Engine.

מורידים את מאגר 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 תושלם, ואז מעתיקים את שם המשאב של הסוכן החדש שהופעל מ<b>פלט הפקודה</b> בצבע ירוק.

רישום סוכן ב-Gemini Enterprise

כדי שהמשתמשים יוכלו לגשת לסוכן שפרסתם, צריך לרשום אותו ב-Gemini Enterprise.

פותחים את Gemini Enterprise ממסוף Cloud בכרטיסייה חדשה, ואז מבצעים את השלבים הבאים:

לוחצים על האפליקציה שנקראת codelab.
בתפריט הניווט, לוחצים על Agents (סוכנים).
לוחצים על + הוספת סוכן.
לוחצים על הוספה לצד סוכן מותאם אישית באמצעות Agent Engine. יופיע הקטע הרשאות.
לוחצים על הוספת הרשאה.
מגדירים את Authorization name ל-enterprise-ai. המערכת יוצרת מזהה על סמך השם ומציגה אותו מתחת לשדה. מעתיקים אותו.
מגדירים את מזהה הלקוח לאותו ערך של לקוח OAuth שנוצר ועודכן בשלבים הקודמים.
מגדירים את Client secret (סוד הלקוח) לאותו ערך של לקוח OAuth שנוצר ועודכן בשלבים הקודמים.
מגדירים את Token URI ל-https://oauth2.googleapis.com/token.
מגדירים את Authorization 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

לוחצים על Done (סיום) ואז על Next (הבא). מוצג הקטע Configuration (הגדרה).
מגדירים את שם הנציג ואת תיאור הנציג ל-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

מודל: Gemini.
נתונים: מאגרי נתונים של Gemini Enterprise ל-Google Workspace (יומן Google, ‏ Gmail, ‏ Drive, ‏ NotebookLM), ‏ חיפוש Google.
מארח הסוכן: Gemini Enterprise.
ממשק משתמש: תוסף Google Workspace ל-Chat ול-Gmail (אפשר להרחיב אותו בקלות ליומן, ל-Drive, ל-Docs, ל-Sheets ול-Slides).
תוסף ל-Google Workspace: Apps Script, ממשקי Gemini Enterprise ו-Vertex AI API, נתונים הקשריים (מטא-נתונים של המשתמש, הודעת Gmail שנבחרה).

התוסף ל-Google Workspace יתחבר ל-Gemini Enterprise באמצעות StreamAssist API.

בדיקת מושגים

תוסף ל-Google Workspace

תוסף ל-Google Workspace הוא אפליקציה בהתאמה אישית שמרחיבה אפליקציה אחת או יותר של Google Workspace (Gmail,‏ Chat,‏ יומן,‏ Docs,‏ Drive,‏ Meet,‏ Sheets ו-Slides).

‫Apps Script

‫Apps Script היא פלטפורמת JavaScript מבוססת-ענן שמופעלת על ידי Google Drive. היא מאפשרת לכם לשלב בין מוצרי Google ולהפוך משימות לאוטומטיות.

מסגרת הכרטיסים של Google Workspace

מסגרת הכרטיסים ב-Google Workspace מאפשרת למפתחים ליצור ממשקי משתמש עשירים ואינטראקטיביים. הוא מאפשר ליצור כרטיסים מאורגנים ומושכים מבחינה ויזואלית, שיכולים לכלול טקסט, תמונות, לחצנים ווידג'טים אחרים. הכרטיסים האלה משפרים את חוויית המשתמש כי הם מספקים מידע מובנה ומאפשרים לבצע פעולות מהירות ישירות באפליקציות של Workspace.

בדיקת ארכיטקטורת הפתרון

בדיקת קוד המקור

appsscript.json

ההגדרה הבאה מגדירה את הטריגרים וההרשאות של התוסף.

הגדרת התוסף: הקובץ הזה מגדיר ל-Google Workspace שהפרויקט הזה הוא תוסף ל-Chat ול-Gmail.
טריגרים הקשריים: ב-Gmail, הוא מגדיר contextualTrigger שמופעל onAddonEvent בכל פעם שמשתמש פותח הודעת אימייל. כך התוסף יכול 'לראות' את תוכן האימייל.
הרשאות: כאן מפורטות ההרשאות שנדרשות כדי שהתוסף יפעל, כמו הרשאות לקריאת האימייל הנוכחי, להפעלת הסקריפט ולהתחברות לשירותים חיצוניים (כמו Gemini Enterprise APIs).oauthScopes

...
"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

הקוד הבא מטפל בהודעות נכנסות ב-Google Chat.

‫Receives Messages: הפונקציה onMessage היא נקודת הכניסה לאינטראקציות עם ההודעות.
ניהול ההקשר: הוא שומר את space.name (המזהה של המרחב ב-Chat) במאפיינים של המשתמש. כך, כשהנציג יהיה מוכן להשיב, הוא יידע בדיוק לאיזו שיחה לשלוח את ההודעה.
העברה לנציג: הפונקציה קוראת ל-requestAgent, ומעבירה את ההודעה של המשתמש ללוגיקה המרכזית שמטפלת בתקשורת עם ה-API.

...
// 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;
}

הקוד הבא יוצר את סרגל הצד ב-Gmail ומקבל את ההקשר של האימייל.

בניית ממשק המשתמש: createSidebarCard בונה את הממשק החזותי באמצעות Workspace Card Service. הוא יוצר פריסה פשוטה עם אזור להזנת טקסט ולחצן 'שליחת הודעה'.
הבנת ההקשר של האימייל: ב-handleSendMessage, הקוד בודק אם המשתמש צופה כרגע באימייל (event.gmail.messageId). אם כן, הוא מאחזר בצורה מאובטחת את הנושא ואת גוף האימייל ומוסיף אותם להנחיה של המשתמש.
הצגת התוצאה: אחרי שהסוכן מגיב, הקוד מעדכן את כרטיס סרגל הצד כדי להציג את התשובה.

...
// 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

הקוד הבא מתזמר את הקריאה ל-API ל-Gemini Enterprise.

מתזמר את הקריאה ל-API: queryAgent הוא הגשר בין התוסף לבין Gemini Enterprise. הוא יוצר בקשה שכוללת את השאילתה של המשתמש, אזור הזמן שלו ומזהה הסשן הפעיל.
גילוי דינמי: המערכת קוראת ל-getAgentDataStores כדי לגלות אילו מחברי נתונים זמינים.
התשובה מוזרמת: מכיוון שלוקח זמן לקבל תשובה מהסוכן, נעשה שימוש ב-streamAssist API עם Server-Sent Events‏ (SSE). הקוד אוסף את התשובה בחלקים ומרכיב מחדש את התשובה המלאה.

...
// 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;
}
...

Initiate service account

יוצרים חשבון שירות ייעודי כדי לאשר את הפעולות בצד השרת של התוסף.

במסוף Google Cloud, פועלים לפי השלבים הבאים:

לוחצים על תפריט ☰ > IAM & Admin > Service Accounts > + Create service account (תפריט ☰ > IAM ואדמין > חשבונות שירות > + יצירת חשבון שירות).

מגדירים את שם חשבון השירות לערך ge-add-on.

לוחצים על יצירה והמשך.
מוסיפים את התפקיד Discovery Engine Viewer בהרשאות.

לוחצים על המשך ואז על סיום. תועברו לדף Service accounts ותוכלו לראות את חשבון השירות שיצרתם.

בוחרים את חשבון השירות החדש שנוצר ואז את הכרטיסייה Keys.
לוחצים על Add key ואז על Create new key.
בוחרים באפשרות JSON ולוחצים על Create.

תיבת הדו-שיח תיסגר וזוג המפתחות הציבורי/פרטי שנוצר יורד אוטומטית לסביבה המקומית כקובץ JSON.

יצירה והגדרה של פרויקט Apps Script

יוצרים פרויקט חדש ב-Apps Script כדי לארח את קוד התוסף ומגדירים את מאפייני החיבור שלו.

כדי לפתוח את פרויקט Apps Script של התוסף Enterprise AI, לוחצים על הלחצן הבא:

לוחצים על סקירה כללית > יצירת עותק.
בפרויקט Apps Script, לוחצים על Project Settings (הגדרות הפרויקט) > Edit script properties (עריכת מאפייני הסקריפט) > Add script property (הוספת מאפיין סקריפט) כדי להוסיף מאפייני סקריפט.
מגדירים את 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

פורסים את התוסף כדי לבדוק אותו ישירות ב-Gmail וב-Google Chat.

בפרויקט Apps Script, פועלים לפי השלבים הבאים:

לוחצים על Deploy > Test deployments (פריסה > בדיקת פריסות) ואז על Install (התקנה). היא זמינה עכשיו ב-Gmail.
לוחצים על העתקה בקטע מזהה Head Deployment.

במסוף Google Cloud, פועלים לפי השלבים הבאים:

מחפשים את Google Chat API בשדה החיפוש של Google Cloud, לוחצים על Google Chat API, לוחצים על Manage ואז על Configuration.

בוחרים באפשרות הפעלה של תכונות אינטראקטיביות.
מבטלים את הסימון של הצטרפות למרחבים ולשיחות קבוצתיות.
בקטע הגדרות חיבור, בוחרים באפשרות Apps Script.
מגדירים את מזהה הפריסה למזהה הפריסה של Head שהועתק בשלבים הקודמים.
בקטע חשיפה, בוחרים באפשרות הפיכת אפליקציית הצ'אט הזו לזמינה לאנשים ולקבוצות ספציפיים בדומיין שלכם ב-Workspace ומזינים את כתובת האימייל.
לוחצים על שמירה.

רוצים לנסות את התוסף?

כדי לוודא שהתוסף יכול לאחזר נתונים ולענות על שאלות בהקשר, מנהלים איתו אינטראקציה.

פותחים את Google 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?
פותחים את הודעת האימייל החדשה שקיבלתם.
פותחים את סרגל הצד של התוסף Enterprise AI.
מגדירים את ההודעה לערך Am I?
לוחצים על שליחת הודעה.
התשובה מוצגת אחרי הכפתור.

6. הסרת המשאבים

מחיקת פרויקט ב-Google Cloud

כדי להימנע מחיובים בחשבון Google Cloud על המשאבים שבהם השתמשתם ב-Codelab הזה, מומלץ למחוק את הפרויקט בענן ב-Google Cloud.

במסוף Google Cloud, פועלים לפי השלבים הבאים:

לוחצים על תפריט ☰ > IAM ואדמין > הגדרות.

לוחצים על כיבוי.
מזינים את מזהה הפרויקט.
לוחצים על Shut down anyway (כיבוי בכל זאת).

7. מזל טוב

מעולה! פיתחתם פתרונות שמנצלים את היתרונות של שילוב Gemini Enterprise ו-Google Workspace כדי לעזור לעובדים!

מה השלב הבא?

ב-codelab הזה אנחנו מציגים רק את תרחישי השימוש הנפוצים ביותר, אבל יש הרבה תחומים להרחבה שכדאי לכם לשקול בפתרונות שלכם, כמו:

שימוש בכלים למפתחים שמבוססים על AI, כמו Gemini CLI ו-Antigravity.
שילוב עם מסגרות וכלים אחרים של סוכנים, כמו MCP מותאם אישית, קריאות מותאמות אישית לפונקציות וממשקי משתמש גנרטיביים.
אינטגרציה עם מודלים אחרים של AI, כולל מודלים בהתאמה אישית, שמתארחים בפלטפורמות ייעודיות כמו 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

בדיקת ארכיטקטורת הפתרון

הפעלת ממשקי API

הגדרת מסך הסכמה ל-OAuth

יצירת פרטי כניסה של לקוח OAuth

יצירת מאגרי נתונים

מאגרי נתוני בדיקה

יצירת סוכן בהתאמה אישית

רוצה לנסות סוכן בהתאמה אישית?

4. סוכן בהתאמה אישית עם קוד

מושגים שכדאי להכיר

Vertex AI

ערכת פיתוח של סוכנים (ADK)

Model Context Protocol (MCP)

כלי הפונקציות

בדיקת ארכיטקטורת הפתרון

בדיקת קוד המקור

agent.py

הפעלת ממשקי API

עדכון מסך ההסכמה ל-OAuth

עדכון פרטי כניסה של לקוח OAuth

הפעלת חיפוש מבוסס-Vertex AI MCP

הגדרת אפליקציה ל-Chat

פריסת סוכן ב-Vertex AI Agent Engine

רישום סוכן ב-Gemini Enterprise

מנסים סוכן

5. סוכן ברירת המחדל כתוסף ל-Google Workspace

בדיקת מושגים

תוסף ל-Google Workspace

‫Apps Script

מסגרת הכרטיסים של Google Workspace

בדיקת ארכיטקטורת הפתרון

בדיקת קוד המקור

appsscript.json

Chat.gs

Sidebar.gs

AgentHandler.gs

Initiate service account

יצירה והגדרה של פרויקט Apps Script

פריסה ב-Gmail וב-Chat

רוצים לנסות את התוסף?

6. הסרת המשאבים

מחיקת פרויקט ב-Google Cloud

7. מזל טוב

מה השלב הבא?

מידע נוסף