תכנון נסיעות באמצעות סוכן AI שזמין בכל אפליקציות Google Workspace

רמת הקידוד: מתקדמת
משך הזמן: 45 דקות
סוג הפרויקט: תוסף ל-Google Workspace להרחבת Chat,‏ Gmail,‏ יומן Google,‏ Drive,‏ Docs,‏ Sheets ו-Slides.

במדריך הזה נסביר איך לפרסם סוכני AI ב-Google Workspace כתוספים ל-Google Workspace, באמצעות Apps Script או נקודות קצה של HTTP. אחרי שמפרסמים את התוסף, המשתמשים יכולים ליצור אינטראקציה עם סוכני ה-AI בתהליכי העבודה שלהם.

סקירה כללית

במדריך הזה תפרסו את הדוגמה של סוכן הנסיעות מתוך ערכת פיתוח הסוכנים (ADK). התכונה 'סוכן נסיעות' היא AI בממשק שיחה עם כמה סוכנים, שמשתמשת בכלים כמו Google Maps Platform Places API, ‏ Google Search Grounding ושרת Model Context Protocol ‏(MCP).

ערכת ה-ADK מספקת למפתחים ממשקים לשיחות וצ'אטים כברירת מחדל. במדריך הזה, מוסיפים ממשק משתמש גרפי (GUI) לאפליקציות של Google Workspace שהמשתמשים יכולים לגשת אליו ישירות ב-Chat,‏ Gmail,‏ Calendar,‏ Drive,‏ Docs,‏ Sheets ו-Slides.

• 

  איור 1. שימוש בסוכן ה-AI מ-Chat כדי להעלות רעיונות לנסיעות.

• 

  איור 2. שימוש בסוכן מבוסס-AI מ-Gmail כדי לתכנן נסיעה על סמך ההקשר באימייל שנבחר.

מטרות

• מגדירים את הסביבה.
• פורסים את סוכן ה-AI.
• מגדירים את הפרויקט.
• הפריסה ב-Gmail, ביומן Google, ב-Drive, ב-Docs, ב-Sheets וב-Slides.
• פריסה ב-Chat.
• בודקים את הפתרון.

מידע על הפתרון הזה

הפתרון הזה מבוסס על טכנולוגיות הליבה הבאות: ADK,‏ Google Cloud ו-Google Workspace APIs,‏ Vertex AI Agent Engine ו-Card framework.

ממשקי המשתמש הגרפיים מתוכננים בצורה שונה באפליקציות Chat ובאפליקציות אחרות (Gmail, יומן Google,‏ Drive,‏ Docs,‏ Sheets,‏ Slides), כדי להתאים לתכונות ולמגבלות הספציפיות שלהן.

תכונות

התכונות הבאות של אפליקציית Travel Concierge משותפות לכל האפליקציות של Google Workspace:

• סשנים קבועים של משתמשים: הסשנים מנוהלים על ידי Vertex AI כדי לשמור על רציפות. כל משתמש משתף סשן אחד בכל האפליקציות של Workspace. המשתמשים יכולים לאפס את הסשן באופן ידני כדי להתחיל שיחה חדשה.

• הודעות עשירות: משתמשים שולחים הודעות טקסט ומקבלים תשובות עם טקסט עשיר ווידג'טים של כרטיסים.

• טיפול בשגיאות: שגיאות בלתי צפויות מטופלות בצורה אלגנטית באמצעות ניסיונות חוזרים וסטטוסים שניתנים להגדרה בתגובות.

אפליקציית Chat כוללת את התכונות הנוספות הבאות:

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

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

באפליקציות אחרות יש את התכונות הנוספות האלה:

• הקשר של פרופיל Google: משתמשים יכולים לשלוח הודעות עם פרטי הפרופיל שלהם (מוגבל לימי הולדת בדוגמה הזו).

• הקשר ב-Gmail: משתמשים יכולים לשלוח הודעות עם אימיילים (מוגבל לנושא אחד ולגוף אחד בדוגמה הזו).

• גישה של נציגים למרחב ב-Chat: המשתמשים יכולים לפתוח את המרחב בצ'אט ישיר (DM) באפליקציית Chat בכרטיסייה חדשה בלחיצת כפתור אחת.

ארכיטקטורה

אפליקציית Travel Concierge מקבלת ומעבדת אירועי אינטראקציה של תוספים ל-Google Workspace מאפליקציות של Google Workspace, משתמשת ב-Vertex AI כדי להנחות את סוכן ה-AI של ADK ולנהל את סשנים של משתמשים, ומסתמכת על ממשקי API של Google Cloud ו-Google Workspace כדי לאסוף הקשר ולהציג תשובות.

בתרשים הבא מוצג תהליך המשתמש העיקרי: שליחת הודעה לנציג ה-AI.

HTTP

• 

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

• 

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

Apps Script

• 

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

• 

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

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

• חשבון Google Workspace במהדורת Business או Enterprise עם גישה ל-Google Chat.

• דפדפן אינטרנט עם גישה לאינטרנט.

• דרישות מוקדמות שספציפיות לסוכן ה-AI של Travel Concierge ADK

  • ‫Python 3.10 ואילך: כדי להתקין, פועלים לפי ההוראות באתר Python הרשמי.
  • ‫uv: כדי להתקין את התוסף, פועלים לפי ההוראות באתר הרשמי של uv.
  • ‫Google Cloud CLI: כדי להתקין את הכלי, פועלים לפי ההוראות באתר הרשמי של Google Cloud.

הכנת הסביבה

בקטע הזה מוסבר איך ליצור ולהגדיר פרויקט ב-Google Cloud.

יצירת פרויקט של Google Cloud

מסוף Google Cloud

1. במסוף Google Cloud, עוברים אל תפריט > IAM & Admin > Create a Project (יצירת פרויקט).

   כניסה לדף Create a Project

2. בשדה Project Name (שם הפרויקט), מזינים שם תיאורי לפרויקט.

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

3. בשדה Location, לוחצים על Browse כדי להציג מיקומים אפשריים לפרויקט. אחר כך לוחצים על בחירה.
   זהירות: לא מוצאים את הארגון שלכם ב-Google Workspace?
   המשמעות היא שלא נכנסתם לחשבון Google Workspace. חלק מהתכונות שמתוארות במסמכי התיעוד למפתחים של Google Workspace זמינות רק לפרויקטים שמשויכים לארגון.
4. לוחצים על יצירה. מערכת Google Cloud תעביר אתכם לדף Dashboard, והפרויקט ייצור תוך כמה דקות.

CLI של gcloud

באחת מסביבות הפיתוח הבאות, ניגשים אל Google Cloud CLI‏ (gcloud):

• Cloud Shell: כדי להשתמש בטרמינל אונליין שבו כבר מוגדר ה-CLI של gcloud, צריך להפעיל את Cloud Shell.
  הפעלת Cloud Shell
• מעטפת מקומית: כדי להשתמש בסביבת פיתוח מקומית צריך להתקין ולהפעיל את ה-CLI של gcloud.
  כדי ליצור פרויקט ב-Cloud, משתמשים בפקודה gcloud projects create:
  ‫

  gcloud projects create PROJECT_ID

  מחליפים את PROJECT_ID במזהה של הפרויקט שרוצים ליצור.

הפעלת החיוב בפרויקט ב-Cloud

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

מסוף Google Cloud

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

   מעבר לדף Billing for My Projects

2. בקטע Select an organization (בחירת ארגון), בוחרים את הארגון שמשויך לפרויקט Google Cloud.
3. בשורת הפרויקט, פותחים את התפריט Actions (), לוחצים על Change billing ובוחרים את החשבון לחיוב ב-Cloud.
4. לוחצים על Set account.

CLI של gcloud

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

   gcloud billing accounts list

2. קישור חשבון לחיוב לפרויקט ב-Google Cloud:

   gcloud billing projects link PROJECT_ID --billing-account=BILLING_ACCOUNT_ID

   מחליפים את מה שכתוב בשדות הבאים:

   • ‫PROJECT_ID הוא מזהה הפרויקט של פרויקט Cloud שרוצים להפעיל בו חיוב.
   • ‫BILLING_ACCOUNT_ID הוא מזהה החשבון לחיוב שאליו רוצים לקשר את הפרויקט ב-Google Cloud.

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

HTTP

1. במסוף Google Cloud, מפעילים את ממשקי ה-API של Vertex AI,‏ Places,‏ People,‏ Google Chat,‏ Gmail,‏ Cloud Build,‏ Cloud Functions,‏ Cloud Pub/Sub,‏ Cloud Logging,‏ Artifact Registry,‏ Cloud Run ותוספים ל-Google Workspace.

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

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

3. מוודאים שמפעילים את ממשקי ה-API הנכונים ולוחצים על הפעלה.

Apps Script

1. במסוף Google Cloud, מפעילים את Vertex AI,‏ Places,‏ People ו-Google Chat APIs.

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

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

3. מוודאים שמפעילים את ממשקי ה-API הנכונים ולוחצים על הפעלה.

קבלת מפתח API של Places בפלטפורמה של מפות Google

1. נכנסים לדף Google Maps Platform > Keys & Credentials במסוף Google Cloud.

   כניסה לדף Keys & Credentials

2. בתיבת הדו-שיח Get Started on Google Maps Platform מוצג מפתח ה-API החדש שיצרתם, שהוא מחרוזת אלפאנומרית. תצטרכו את המחרוזת הזו בקטעים הבאים.

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

איך יוצרים חשבון שירות במסוף 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 ולוחצים על יצירה.

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

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

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

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

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

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.

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

1. אם עדיין לא עשיתם זאת, מאמתים את חשבון Google Cloud ומגדירים את Google Cloud CLI לשימוש בפרויקט Google Cloud.

   gcloud auth application-default login
   gcloud config set project PROJECT_ID
   gcloud auth application-default set-quota-project PROJECT_ID

   מחליפים את PROJECT_ID במזהה של פרויקט Cloud שיצרתם.

2. הורדת מאגר GitHub הזה

   הורדה

3. בסביבת הפיתוח המקומית המועדפת, מחלצים את קובץ הארכיון שהורדתם ופותחים את הספרייה adk-samples/python/agents/travel-concierge.

   unzip adk-samples-main.zip
   cd adk-samples-main/python/agents/travel-concierge

4. יוצרים קטגוריה חדשה ב-Cloud Storage שמוקדשת לסוכן ה-AI של ADK.

   gcloud storage buckets create gs://CLOUD_STORAGE_BUCKET_NAME --project=PROJECT_ID --location=PROJECT_LOCATION

   מחליפים את מה שכתוב בשדות הבאים:

   1. ‫CLOUD_STORAGE_BUCKET_NAME בשם ייחודי לקטגוריה שרוצים להשתמש בה.
   2. PROJECT_ID במזהה של פרויקט Cloud שיצרתם.
   3. ‫PROJECT_LOCATION במיקום של הפרויקט שיצרתם ב-Cloud.

5. מגדירים את משתני הסביבה הבאים:

   export GOOGLE_GENAI_USE_VERTEXAI=1
   export GOOGLE_CLOUD_PROJECT=PROJECT_ID
   export GOOGLE_CLOUD_LOCATION=PROJECT_LOCATION
   export GOOGLE_PLACES_API_KEY=PLACES_API_KEY
   export GOOGLE_CLOUD_STORAGE_BUCKET=CLOUD_STORAGE_BUCKET_NAME
   export TRAVEL_CONCIERGE_SCENARIO=travel_concierge/profiles/itinerary_empty_default.json

   מחליפים את מה שכתוב בשדות הבאים:

   1. PROJECT_ID במזהה של פרויקט Cloud שיצרתם.
   2. ‫PROJECT_LOCATION במיקום של הפרויקט שיצרתם ב-Cloud.
   3. PLACES_API_KEY במחרוזת של מפתח ה-API שיצרתם.
   4. ‫CLOUD_STORAGE_BUCKET_NAME בשם הקטגוריה שיצרתם.

6. מתקינים ומפעילים את סוכן ה-AI של ADK.

   uv sync --group deployment
   uv run python deployment/deploy.py --create

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

   Created remote agent: projects/PROJECT_NUMBER/locations/us-central1/reasoningEngines/ENGINE_ID

בדיקת הקוד לדוגמה

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

Python

הצגת הקוד ב-GitHub

Apps Script

הצגת הקוד ב-GitHub

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

Python

1. הורדת מאגר GitHub הזה

   הורדה

2. בסביבת הפיתוח המקומית המועדפת, מחלצים את קובץ הארכיון שהורדתם ופותחים את הספרייה add-ons-samples/python/travel-adk-ai-agent.

   unzip add-ons-samples-main.zip
   cd add-ons-samples-main/python/travel-adk-ai-agent

3. מעבירים את קובץ מפתח ה-JSON‏ credentials.json שהורדתם בשלבים הקודמים מחשבון השירות אל ספריית הפרויקט.

4. במסוף Google Cloud, עוברים אל Cloud Run:

   כניסה ל-Cloud Run

5. לוחצים על כתיבת פונקציה.

6. בדף Create service, מגדירים את הפונקציה:

   1. בשדה שם השירות מזינים travel-concierge-app.
   2. ברשימה Region, בוחרים את המיקום של הפרויקט ב-Cloud שיצרתם, PROJECT_LOCATION.
   3. בקטע כתובת URL של נקודת קצה, לוחצים על .
   4. ברשימה Runtime בוחרים בגרסה העדכנית ביותר של Python.
   5. בקטע אימות, בוחרים באפשרות מתן גישה לכולם.
   6. בקטע Containers, Volumes, Networking, Security (מאגרי תגים, אמצעי אחסון, רשתות, אבטחה), בקטע Resources (מקורות מידע):
      1. בשדה Memory, בוחרים באפשרות 1 GiB.
      2. בשדה CPU, בוחרים באפשרות 2.
   7. לוחצים על Create (יצירה) ומחכים ש-Cloud Run ייצור את השירות. המסוף מפנה אתכם לכרטיסייה מקור.

7. בסביבת הפיתוח המקומית המועדפת, פורסים את המקור של הפרויקט:

   gcloud run deploy travel-concierge-app --quiet --source . \
       --region PROJECT_LOCATION  \
       --function adk_ai_agent  \
       --set-env-vars LOCATION=LOCATION,PROJECT_NUMBER=PROJECT_NUMBER,ENGINE_ID=ENGINE_ID,BASE_URL=BASE_URL

   מחליפים את מה שכתוב בשדות הבאים:

   1. ‫PROJECT_LOCATION במיקום של הפונקציה ב-Cloud Run שיצרתם קודם.
   2. LOCATION במיקום של הפרויקט ב-Google Cloud שנוצר בשלבים הקודמים, PROJECT_LOCATION.
   3. ‫PROJECT_NUMBER עם מספר הפרויקט של סוכן ה-AI של Travel Concierge ADK שנפרס בשלבים הקודמים.
   4. ‫ENGINE_ID עם מזהה המנוע של סוכן ה-AI של Travel Concierge ADK שנפרס בשלבים הקודמים.
   5. BASE_URL עם כתובת ה-URL של נקודת הקצה שהעתקתם קודם.

Apps Script

כדי ליצור פרויקט Apps Script ולהגדיר אותו לשימוש בסוכן ה-AI של Travel Concierge ADK שהטמעתם:

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

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

3. נותנים שם להעתק של פרויקט Apps Script:

   1. לוחצים על Copy of Travel Concierge ADK AI Agent (עותק של סוכן AI של Travel Concierge ADK).
   2. בשדה שם הפרויקט, כותבים Travel Concierge ADK AI Agent.
   3. לוחצים על Rename.

4. בפרויקט Apps Script, לוחצים על עורך ומזיזים את הקובץ VertexAi.gs למעלה עד שהוא מעל הקובץ AgentHandler.gs באמצעות פעולת הקובץ הזזת הקובץ למעלה.

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

6. ‫ENGINE_ID עם מזהה המנוע של סוכן ה-AI של ADK לניהול נסיעות שהופעל בשלבים הקודמים, ENGINE_ID.

7. ‫LOCATION עם המיקום של הפרויקט ב-Google Cloud שנוצר בשלבים הקודמים, PROJECT_LOCATION.

8. ‫PROJECT_NUMBER עם מספר הפרויקט של סוכן ה-AI של Travel Concierge ADK שנפרס בשלבים הקודמים, PROJECT_NUMBER.

9. ‫SERVICE_ACCOUNT_KEY עם מפתח ה-JSON מחשבון השירות שהורד בשלבים הקודמים, כמו { ... }.

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

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

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

13. בשדה GCP project number (מספר פרויקט GCP), מדביקים את מספר הפרויקט של סוכן ה-AI של Travel Concierge ADK שנפרס בשלבים הקודמים, PROJECT_NUMBER.

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

פריסה ב-Gmail, ביומן, ב-Drive, ב-Docs, ב-Sheets וב-Slides

Python

כדי לבצע בדיקה, אפשר להשתמש בפריסה של תוסף ל-Google Workspace כדי להתקין את פרויקט הדוגמה בכל אפליקציות Google Workspace (חוץ מ-Google Chat).

1. בסביבת הפיתוח המקומית המועדפת, פותחים את הקובץ deployment.json ממקור הקוד של הפרויקט ומחליפים את כל המופעים של $BASE_URL בערך של BASE_URL, כתובת ה-URL של נקודת הקצה שהעתקתם בשלבים הקודמים.

2. יוצרים פריסה של תוסף ל-Google Workspace בשם travel-concierge-addon:

   gcloud workspace-add-ons deployments create travel-concierge-addon \
       --deployment-file=deployment.json

3. מתקינים את פריסת התוסף ל-Google Workspace:

   gcloud workspace-add-ons deployments install travel-concierge-addon

Apps Script

כדי לאפשר בדיקה, מתקינים את פרויקט Apps Script בכל האפליקציות של Google Workspace (חוץ מ-Google Chat).

1. בפרויקט Apps Script, לוחצים על Deploy > Test deployments (פריסה > בדיקת פריסות) ואז על Install (התקנה).

עכשיו אפשר לגשת לתוסף מסרגלי הצד של אפליקציות Google Workspace.

פריסה ב-Chat

Python

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

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

   עוברים לדף ההגדרה של Google Chat API

2. מגדירים את אפליקציית Chat:

   1. בשדה שם האפליקציה, מזינים Travel ADK AI Agent.
   2. בשדה כתובת ה-URL של האווטאר מזינים https://goo.gle/3SfMkjb.
   3. בשדה Description (תיאור) מזינים Travel ADK AI Agent.
   4. בקטע Connection settings (הגדרות חיבור), בוחרים באפשרות HTTP endpoint URL (כתובת URL של נקודת קצה בפרוטוקול HTTP).
   5. בקטע טריגרים, בוחרים באפשרות שימוש בכתובת URL משותפת של נקודת קצה מסוג HTTP לכל הטריגרים.
   6. בשדה כתובת URL של נקודת קצה HTTP, מדביקים את כתובת ה-URL של נקודת הקצה שהעתקתם קודם, BASE_URL.
   7. רושמים פקודה מהירה שהאפליקציה המלאה של Chat משתמשת בה:
      1. בקטע Commands, לוחצים על Add a command.
      2. בשדה Command ID (מזהה הפקודה), מקלידים 1.
      3. בשדה תיאור, מקלידים Reset session.
      4. בקטע סוג הפקודה, בוחרים באפשרות פקודה מהירה.
      5. בשדה Name, כותבים Reset session.
      6. לוחצים על סיום. הפקודה המהירה נרשמת ומופיעה ברשימה.
   8. בקטע חשיפה, בוחרים באפשרות הפיכת אפליקציית Chat הזו לזמינה לאנשים ולקבוצות ספציפיים בדומיין שלכם ב-Workspace ומזינים את כתובת האימייל.
   9. בקטע יומנים, בוחרים באפשרות רישום שגיאות ביומן.
   10. לוחצים על שמירה.

Apps Script

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

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

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

   עוברים לדף ההגדרה של Google Chat API

3. מגדירים את אפליקציית Chat:

   1. בשדה שם האפליקציה, מזינים Travel ADK AI Agent.
   2. בשדה כתובת ה-URL של האווטאר מזינים https://goo.gle/3SfMkjb.
   3. בשדה Description (תיאור) מזינים Travel ADK AI Agent.
   4. בקטע הגדרות חיבור, בוחרים באפשרות Apps Script.
   5. בשדה Deployment ID (מזהה הפריסה), מדביקים את מזהה הפריסה של Head שהעתקתם קודם.
   6. רושמים פקודה מהירה שהאפליקציה המלאה של Chat משתמשת בה:
      1. בקטע Commands, לוחצים על Add a command.
      2. בשדה Command ID (מזהה הפקודה), מקלידים 1.
      3. בשדה תיאור, מקלידים Reset session.
      4. בקטע סוג הפקודה, בוחרים באפשרות פקודה מהירה.
      5. בשדה Name, כותבים Reset session.
      6. לוחצים על סיום. הפקודה המהירה נרשמת ומופיעה ברשימה.
   7. בקטע חשיפה, בוחרים באפשרות הפיכת אפליקציית Chat הזו לזמינה לאנשים ולקבוצות ספציפיים בדומיין שלכם ב-Workspace ומזינים את כתובת האימייל.
   8. בקטע יומנים, בוחרים באפשרות רישום שגיאות ביומן.
   9. לוחצים על שמירה.

עכשיו אפשר לגשת לאפליקציה מ-Google Chat.

1. פותחים את Google Chat.

   מעבר אל Google Chat

2. יוצרים את המרחב ב-Chat לשיחה ישירה:

   1. לוחצים על צ'אט חדש.
   2. מקלידים את שם האפליקציה Travel ADK AI Agent בחיפוש ובוחרים אותה.
   3. בתיבת הדו-שיח Install app, לוחצים על התקנת האפליקציה.
   4. תיבת הדו-שיח Install app תיסגר והמרחב החדש ב-Chat לשיחה ישירה ייבחר.

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

בדיקת הנציג

1. פתח את Gmail.

   ל-Gmail

2. שולחים לעצמכם את האימייל הבא:

   • נושא: You need to travel to Paris
   • Body: Please be there between 11/25/2025 and 11/30/2025!

3. פותחים את התוסף Travel ADK AI Agent מסרגל הצד.

4. לוחצים על Grant permissions (הענקת הרשאות) כדי להשלים את הגדרת התוסף.

5. אחרי שמגדירים את הבקשה הבאה לסוכן, לוחצים על שליחה:

   • הודעה: Please help me plan this travel!
   • Context: select Current email

   סרגל הצד מתעדכן עם התשובה של הסוכן.

   

6. לוחצים על פתיחת Chat כדי לעבור למרחב של הצ'אט הישיר ב-Chat.

7. לוחצים על + > איפוס הסשן.

   תקבלו הודעה חדשה שמאשרת שהפעולה בוצעה: OK, let's start from the beginning, what can I help you with?

8. שולחים את ההודעה Give me ideas.

   תקבלו הודעות חדשות עם התשובה של הנציג.

   

9. שולחים את ההודעה I want to go there! אחרי העלאת תמונה של מיקום כלשהו, כמו מגדל אייפל.

   תקבלו הודעות חדשות עם התשובה של הנציג.

   

הערה: אפשר לפתוח את התוסף Travel ADK AI Agent גם מסרגל הצד ביומן, ב-Drive, ב-Docs, ב-Sheets וב-Slides, בדומה לאופן שבו פותחים אותו ב-Gmail.

מגבלות

HTTP

באפליקציות של Google Workspace שאינן Chat, יש לממשק מבוסס ה-AI את המגבלות הבאות:

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

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

המגבלות האלה לא קיימות ב-Chat.

Apps Script

בכל האפליקציות של Google Workspace, סוכן ה-AI קורא לממשקי Vertex AI REST באמצעות UrlFetchApp, ולכן יש מגבלות מסוימות:

• הוא סינכרוני: התשובות של סוכן ה-AI מוחזרות רק אחרי השלמה מלאה (ללא סטרימינג).

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

התאמה אישית

הפתרון הזה תומך בסוכני AI של ADK שמארחים במנוע הסוכנים של Vertex AI, בקבוצת משנה של ממשקי משתמש של אפליקציות Google Workspace ובהצגת תשובות שספציפיות לתשובות של דוגמת Travel Concierge. הפתרון מבוסס על מסגרת ניתנת להרחבה, כך שאפשר להתאים אותו אישית על ידי שינוי הקבצים הבאים:

Python

• ‫main.py: מגדיר את ממשקי המשתמש העיקריים ואת הלוגיקה של אינטראקציות המשתמש (מטפלי אירועים של Google Workspace). דוגמה להרחבה: הפעלת מסמכי Drive כתכונת הקשר לאפליקציית Drive, בדומה למה שנעשה עם הודעות Gmail באפליקציית Gmail.

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

• ‫agent_handler.py: מיישם ממשקי Vertex AI ספציפיים שמוגדרים ב-vertex_ai.py במקרים ספציפיים של אפליקציות Chat ואפליקציות שאינן Chat. תוסף טיפוסי יכול להוסיף כפתורים למשתמשים כדי לשלוח משוב על תשובות של סוכן AI.

• ‫google_workspace.py: מיישם אינטראקציות של פלטפורמה לניהול סוכנים שאינם מבוססי AI באמצעות קריאות ל-API. בדוגמה הזו נעשה שימוש רק ב-Google Workspace APIs כדי לאסוף פרטים על ההקשר ולבצע פעולות. תוסף טיפוסי יכול להוסיף פונקציות לאחזור נתונים עסקיים מיומן Google או ממערכת לניהול קשרי לקוחות (CRM).

• ‫travel_agent_ui_render.gs: קובץ שמטמיע עיבוד של תגובות ספציפיות ל-Travel Concierge עבור סוכני המשנה ואפליקציות Workspace. תוספים אופייניים יכולים להוסיף תמיכה בעיבודים חדשים של תגובות כדי להציג באופן גרפי אפשרויות לטיסות, וסוכני AI אחרים.

Apps Script

• ‫Code.gs: מגדיר את ממשקי המשתמש העיקריים ואת הלוגיקה של אינטראקציות המשתמש (מטפלי אירועים של Google Workspace). דוגמה להרחבה: הפעלת מסמכי Drive כתכונת הקשר לאפליקציית Drive, בדומה למה שנעשה עם הודעות Gmail באפליקציית Gmail.

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

• ‫AgentHandler.gs: מיישם ממשקי Vertex AI ספציפיים שמוגדרים ב-VertexAi.gs במקרים ספציפיים של אפליקציות Chat ואפליקציות שאינן Chat. תוסף טיפוסי יכול להוסיף כפתורים למשתמשים כדי לשלוח משוב על תשובות של סוכן AI.

• ‫GoogleWorkspace.gs: מיישם אינטראקציות עם פלטפורמת ניהול של סוכנים שאינם מבוססי AI באמצעות קריאות ל-API. בדוגמה הזו נעשה שימוש רק ב-Google Workspace APIs כדי לאסוף פרטים על ההקשר ולבצע פעולות. תוסף טיפוסי יכול להוסיף פונקציות לאחזור נתונים עסקיים מיומן Google או ממערכת לניהול קשרי לקוחות (CRM).

• ‫TravelAgentUiRender.gs: קובץ שמטמיע עיבוד של תגובות ספציפיות ל-Travel Concierge עבור סוכני המשנה ואפליקציות Workspace. תוספים אופייניים יכולים להוסיף תמיכה בעיבודים חדשים של תגובות כדי להציג באופן גרפי אפשרויות לטיסות, וסוכני AI אחרים.

הסרת המשאבים

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

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

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

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

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

   כניסה ל-Resource Manager

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

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

• בדיקת עובדות של הצהרות באמצעות סוכן AI של ADK ומודל Gemini
• שילוב של מושגי AI בסיסיים באפליקציות ל-Chat
• פיתוח אפליקציה ל-Chat כתוסף ל-Google Workspace באמצעות Apps Script