פיתוח אפליקציה ל-Google Chat באמצעות סוכן AI ב-ADK

בדף הזה מוסבר איך ליצור תוסף ל-Google Workspace שפועל ב-Google Chat ומתקשר עם סוכן AI של Agent Development Kit (ADK) שמארח ב-Vertex AI Agent Engine.

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

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

התרשים הבא מציג את הארכיטקטורה ואת דפוס העברת ההודעות:

בתרשים שלמעלה, משתמש שמקיים אינטראקציה עם אפליקציית צ'אט שהוטמעה באמצעות סוכן AI של ADK, נהנה מזרימת המידע הבאה:

1. משתמש שולח הודעה לאפליקציית Chat, בצ'אט ישיר או במרחב ב-Chat.
2. הלוגיקה של אפליקציית Chat, שמוטמעת ב-Apps Script או כשרת אינטרנט עם נקודות קצה של HTTP, מקבלת את ההודעה ומעבדת אותה.
3. סוכן ה-AI שמיושם באמצעות ADK ומתארח ב-Vertex AI Agent Engine מקבל את האינטראקציה ומעבד אותה.
4. אפשר גם לשלב את אפליקציית Chat או את סוכן ה-AI עם שירותי Google Workspace, כמו יומן Google או Google Sheets, או עם שירותים אחרים של Google, כמו מפות Google או YouTube.
5. אפליקציית Chat שולחת תגובות באופן אסינכרוני באמצעות Google Chat API כדי לעדכן לגבי ההתקדמות של סוכן ה-AI.
6. התשובות נשלחות למשתמש.

מטרות

• מגדירים את הסביבה.
• פורסים את סוכן ה-AI של ADK.
• פורסים את אפליקציית Chat.
• מגדירים את אפליקציית Chat.
• בודקים את אפליקציית Chat.

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

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

הגדרת הסביבה

הפעלת ממשקי ה-API של Google Cloud

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

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

  הפעלת ממשקי ה-API

מגדירים את מסך ההסכמה של OAuth

כל האפליקציות שמשתמשות ב-OAuth 2.0 דורשות הגדרה של מסך הסכמה. הגדרת מסך ההסכמה ל-OAuth של האפליקציה קובעת מה מוצג למשתמשים ולבודקי האפליקציות, ורושמת את האפליקציה כדי שתוכלו לפרסם אותה בהמשך.

1. במסוף Google Cloud, עוברים אל תפריט > Google Auth platform > Branding.

   מעבר לדף Branding

2. אם כבר הגדרתם את Google Auth platform, אתם יכולים לקבוע את ההגדרות הבאות של מסך ההסכמה ל-OAuth בקטעים Branding,‏ Audience וData Access. אם מופיעה ההודעה Google Auth platform not configured yet, לוחצים על Get Started:
1. בקטע App Information בשדה App name, מזינים שם לאפליקציה.
2. בקטע User support email, בוחרים כתובת אימייל לתמיכה שאליה משתמשים יפנו אם יש להם שאלות לגבי ההסכמה שלהם.
3. לוחצים על Next.
4. בקטע Audience, לוחצים על Internal.
5. לוחצים על Next.
6. בקטע Contact Information, מזינים כתובת אימייל שאליה אפשר לשלוח התראות על שינויים בפרויקט.
7. לוחצים על Next.
8. בקטע Finish, קוראים את המדיניות של Google בנושא נתוני משתמשים בשירותי API. אם אתם מסכימים, סמנו את התיבה I agree to the Google API Services: User Data Policy.
9. לוחצים על Continue.
10. לוחצים על Create.
3. כרגע אתם יכולים לדלג על הוספת היקפי הרשאות. בעתיד, כשתיצרו אפליקציה לשימוש מחוץ לארגון שלכם ב-Google Workspace, תצטרכו לשנות את סוג המשתמש ל-External. לאחר מכן מוסיפים את היקפי ההרשאות שהאפליקציה דורשת. למידע נוסף, אפשר לעיין במדריך המלא בנושא הגדרת הסכמה ל-OAuth.

איך יוצרים חשבון שירות במסוף Google Cloud

כדי ליצור חשבון שירות חדש עם התפקיד Vertex AI User, פועלים לפי השלבים הבאים:

מסוף Google Cloud

1. במסוף Google Cloud, לוחצים על סמל התפריט > IAM & Admin > Service Accounts (חשבונות שירות).

   לדף Service accounts

2. לוחצים על יצירת חשבון שירות.
3. ממלאים את פרטי חשבון השירות ולוחצים על יצירה והמשך.
   הערה: כברירת מחדל, Google יוצרת מזהה ייחודי לחשבון שירות. אם רוצים לשנות את המזהה, משנים אותו בשדה של מזהה חשבון השירות.
4. אופציונלי: מקצים תפקידים לחשבון השירות כדי לתת גישה למשאבים בפרויקט Google Cloud. פרטים נוספים זמינים במאמר הענקה, שינוי וביטול גישה למשאבים.
5. לוחצים על המשך.
6. אופציונלי: מזינים משתמשים או קבוצות שיכולים לנהל את חשבון השירות הזה ולבצע בו פעולות. פרטים נוספים זמינים במאמר ניהול התחזות לחשבון שירות.
7. לוחצים על סיום. רושמים את כתובת האימייל של חשבון השירות.

CLI של gcloud

1. יוצרים את חשבון השירות:

   gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
     --display-name="SERVICE_ACCOUNT_NAME"

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

חשבון השירות מופיע בדף של חשבון השירות.

יצירת מפתח פרטי

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

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

כדי ליצור ולהוריד מפתח פרטי לחשבון השירות, פועלים לפי השלבים הבאים:

1. במסוף Google Cloud, לוחצים על סמל התפריט > IAM & Admin > Service Accounts (חשבונות שירות).

   לדף Service accounts

2. בוחרים את חשבון השירות.
3. לוחצים על מפתחות > הוספת מפתח > יצירת מפתח חדש.
4. בוחרים באפשרות JSON ולוחצים על Create.

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

5. לוחצים על סגירה.

מידע נוסף על חשבונות שירות זמין במאמר בנושא חשבונות שירות במסמכי העזרה של Google Cloud IAM.

פריסת סוכן ה-AI של ADK

1. פותחים את הדוגמה של LLM Auditor ב-Vertex AI Agent Garden:

   פתיחת הדוגמה

2. לוחצים על פריסה.

3. אם מתבקשים, בוחרים את הפרויקט ב-Google Cloud.

4. לוחצים על Deploy in Cloud Shell (פריסה ב-Cloud Shell).

5. אם מתבקשים, לוחצים על Authorize ומבצעים את תהליך OAuth עבור Cloud Shell.

6. כש-Cloud Shell נטען באופן מלא, מקישים על Enter כדי להפעיל את שורת הפקודה שנטענה מראש ולהתחיל בפריסה.

7. אם מתבקשים להזין אזור, מקישים על Enter כדי להשתמש בברירת המחדל.

8. בסיום, עוברים אל Vertex AI Agent Engine:

   פתיחת Vertex AI Agent Engine

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

יצירה והגדרה של פרויקט אפליקציית Chat

1. לוחצים על הלחצן הבא כדי לפתוח את פרויקט Apps Script של ADK AI Agent Quickstart.

   פתיחת הפרויקט

2. לוחצים על סקירה כללית > יצירת עותק.

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

   1. ‫REASONING_ENGINE_RESOURCE_NAME עם שם המשאב של סוכן Vertex AI שהעתקתם בשלבים הקודמים.
   2. ‫SERVICE_ACCOUNT_KEY עם מפתח ה-JSON מחשבון השירות שהורדתם בשלבים הקודמים, כמו { ... }.

4. לוחצים על שמירת מאפייני סקריפט.

5. במסוף Google Cloud, לוחצים על סמל התפריט > IAM & Admin > Settings.

   כניסה לדף IAM & Admin Settings

6. מעתיקים את הערך בשדה מספר הפרויקט.

7. בפרויקט Apps Script, לוחצים על הגדרות הפרויקט.

8. בקטע פרויקט Google Cloud Platform (GCP)‎, לוחצים על שינוי הפרויקט.

9. בשדה מספר פרויקט GCP, מדביקים את מספר הפרויקט ב-Google Cloud שהועתק בשלבים הקודמים.

10. לוחצים על הגדרת פרויקט. הפרויקט ב-Cloud והפרויקט ב-Apps Script מקושרים עכשיו.

יצירת פריסת בדיקה

כדי להשתמש בפרויקט הזה של Apps Script בשלב הבא, צריך מזהה פריסה.

כדי לקבל את מזהה הפריסה העיקרית:

1. בפרויקט Apps Script של אפליקציית Chat, לוחצים על Deploy (פריסה) > Test deployments (פריסות לבדיקה).
2. בקטע מזהה פריסה של גרסת Head, לוחצים על העתקה.
3. לוחצים על סיום.

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

כדי לפרוס את אפליקציית Google Chat לבדיקה, פועלים לפי השלבים הבאים באמצעות הפריסה של Apps Script:

1. במסוף, מחפשים את Google Chat API ולוחצים על Google Chat API.
2. לוחצים על ניהול.

3. לוחצים על Configuration (הגדרה) ומגדירים את אפליקציית Chat:

   1. בשדה שם האפליקציה, מזינים ADK Quickstart.
   2. בשדה כתובת ה-URL של האווטאר מזינים את הערך https://developers.google.com/workspace/add-ons/images/quickstart-app-avatar.png.
   3. בשדה Description (תיאור) מזינים ADK Quickstart.
   4. בקטע פונקציונליות, בוחרים באפשרות הצטרפות למרחבים ולשיחות קבוצתיות.
   5. בקטע 'הגדרות חיבור', בוחרים באפשרות פרויקט Apps Script.
   6. בשדה Deployment ID (מזהה פריסה), מדביקים את מזהה הפריסה של Head שהעתקתם קודם.
   7. בקטע 'חשיפה', בוחרים באפשרות אנשים וקבוצות ספציפיים בדומיין ומזינים את כתובת האימייל.

4. לוחצים על שמירה.

אפליקציית Chat מוכנה להגיב להודעות.

בדיקת אפליקציית Chat

כדי לבדוק את אפליקציית Chat, פותחים מרחב לצ'אט ישיר עם אפליקציית Chat ושולחים הודעה:

1. פותחים את Google Chat באמצעות חשבון Google Workspace שציינתם כשנוספתם כבודקים מהימנים.

   מעבר אל Google Chat

2. לוחצים על צ'אט חדש.
3. בשדה הוספת אדם אחד או יותר, מקלידים את השם של אפליקציית Chat.

4. בוחרים את אפליקציית Chat מתוך התוצאות. ייפתח צ'אט ישיר.

   הערה: אם אפליקציית Chat לא מופיעה ברשימת התוצאות, צריך לוודא שחשבון Google Workspace שלכם נכלל בהגדרות Visibility בדף Chat API Configuration במסוף Google Cloud.

5. בצ'אט הישיר החדש עם האפליקציה, כותבים The Eiffel Tower was completed in 1900 ולוחצים עלenter.

   אפליקציית Chat משיבה עם תשובות של סוכני משנה מבקר ועורך.

כדי להוסיף בודקים מהימנים ולקבל מידע נוסף על בדיקת תכונות אינטראקטיביות, אפשר לעיין במאמר בדיקת תכונות אינטראקטיביות באפליקציות ל-Google Chat.

פתרון בעיות

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

יכול להיות שלא תוצג הודעת שגיאה בממשק המשתמש של Chat, אבל אם הפעלתם את רישום השגיאות באפליקציות של Chat, תוכלו לראות הודעות שגיאה תיאוריות ונתוני יומן שיעזרו לכם לתקן את השגיאות. לקבלת עזרה בצפייה בשגיאות, באיתור באגים ובתיקון שגיאות, אפשר לעיין במאמר פתרון בעיות ותיקון שגיאות ב-Google Chat.

הסרת המשאבים

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

זהירות: כשמוחקים פרויקט:

• התוכן של הפרויקט נמחק כולו. אם השתמשתם בפרויקט קיים כדי לתרגל את המדריך הזה, כשתמחקו אותו תימחק גם כל העבודה שביצעתם באותו פרויקט.
• מאבדים את מזהה הפרויקט בהתאמה אישית. כשיצרתם את הפרויקט, יכולתם לבחור לו מזהה פרויקט בהתאמה אישית כדי להשתמש בו בעתיד. כדי לשמור על כתובות ה-URL שמשתמשות במזהה הפרויקט, כמו כתובת URL ב-appspot.com, צריך למחוק את המשאבים שנבחרו בפרויקט אבל לא את הפרויקט כולו.

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

1. במסוף Google Cloud, עוברים לדף Manage resources. לוחצים על תפריט > IAM & Admin > Manage Resources.

   כניסה ל-Resource Manager

2. ברשימת הפרויקטים, בוחרים את הפרויקט שרוצים למחוק ולוחצים על מחיקה .
3. כדי למחוק את הפרויקט, כותבים את מזהה הפרויקט בתיבת הדו-שיח ולוחצים על Shut down.

נושאים קשורים

• בדיקת עובדות של הצהרות באמצעות סוכן AI של ADK ומודל Gemini
• תכנון נסיעות באמצעות סוכן AI שזמין בכל Google Workspace
• שילוב של מושגי AI בסיסיים באפליקציות ל-Chat
• קבלת תשובות לשאלות על סמך שיחות ב-Chat באמצעות אפליקציית Gemini Chat
• איך מגיבים לאירועים באמצעות Google Chat,‏ Vertex AI,‏ Apps Script ואימות משתמשים
• ניהול פרויקטים באמצעות Google Chat,‏ Vertex AI ו-Firestore