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

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

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

סקירה כללית

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

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

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

מטרות

  • מגדירים את הסביבה.
  • פורסים את סוכן ה-AI.
  • מגדירים את הפרויקט.
  • פריסה ב-Gmail, ביומן, ב-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. המשתמשים יכולים לאפס את הסשן באופן ידני כדי להתחיל שיחה חדשה.

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

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

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

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

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

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

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

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

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

ארכיטקטורה

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

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

HTTP

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

Apps Script

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

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

הכנת הסביבה

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

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

Google API Console

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

    כניסה לדף Create a Project

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

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

  3. בשדה Location, לוחצים על Browse כדי להציג מיקומים אפשריים לפרויקט. אחר כך לוחצים על בחירה.
  4. לוחצים על יצירה. מערכת Google API Console תעבור לדף מרכז הבקרה והפרויקט שלכם ייווצר תוך כמה דקות.

‫CLI של gcloud

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

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

הפעלת החיוב בפרויקט בענן

Google API Console

  1. ב-Google API Console, עוברים אל 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 הוא מזהה הפרויקט של פרויקט בענן שרוצים להפעיל בו חיוב.
    • ‫BILLING_ACCOUNT_ID הוא המזהה של החשבון לחיוב שאליו רוצים לקשר את הפרויקט ב-Google Cloud.

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

HTTP

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

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

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

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

Apps Script

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

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

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

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

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

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

    כניסה לדף Keys & Credentials

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

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

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

Google Cloud Console

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

    לדף Service accounts

    שאר השלבים יופיעו במסוף Google Cloud.

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

    רושמים את כתובת האימייל של חשבון השירות.

‫CLI של gcloud

  1. יוצרים את חשבון השירות: 
    gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
  --display-name="SERVICE_ACCOUNT_NAME"
  2. אופציונלי: מקצים תפקידים לחשבון השירות כדי לתת גישה למשאבים בפרויקט בענן של Google בנוסף למשאבים ב-Google Workspace. מידע נוסף על ניהול הגישה לפרויקטים, לתיקיות ולארגונים

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

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

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

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

    לדף Service accounts

    שאר השלבים יופיעו במסוף Google Cloud.

  2. בוחרים פרויקט ב-Google Cloud.
  3. לוחצים על כתובת האימייל של חשבון השירות שעבורו רוצים ליצור מפתח.
  4. לוחצים על הכרטיסייה Keys.
  5. לוחצים על התפריט הנפתח Add key ובוחרים באפשרות Create new key.
  6. בוחרים באפשרות JSON בתור Key type ולוחצים על Create.

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

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

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

  1. ב-Google API Console, נכנסים לתפריט > Google Auth platform > Branding.

    מעבר לדף Branding

  2. אם כבר הגדרתם את פלטפורמת האימות של Google, אתם יכולים לקבוע את ההגדרות הבאות של מסך ההסכמה ל-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 לטיפול בנסיעות

  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 במזהה של פרויקט בענן שיצרתם.

  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 במזהה של פרויקט הענן שיצרתם.
    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 במזהה של פרויקט הענן שיצרתם.
    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

  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 API Console, עוברים אל Cloud Run:

    כניסה ל-Cloud Run

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

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

    1. בשדה שם השירות מזינים travel-concierge-app.
    2. ברשימה Region, בוחרים את המיקום של פרויקט הענן שיצרתם, 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 של ערכת ה-ADK של Travel Concierge שפרסתם:

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

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

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

    1. לוחצים על עותק של סוכן ה-AI של ADK לניהול נסיעות.
    2. בשדה Project title, כותבים 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 של Travel Concierge שהופעל בשלבים הקודמים, 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. לוחצים על הגדרת פרויקט. הפרויקט בענן והפרויקט ב-Apps Script מקושרים עכשיו.

פריסה ב-Gmail, ביומן Google, ב-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. ב-קונסולה לממשקי API, מחפשים את Google Chat API, לוחצים על Google Chat API, ואז על Manage ועל Configuration.

    מעבר לדף ההגדרה של Google Chat API

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

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

Apps Script

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

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

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

    מעבר לדף ההגדרה של Google Chat API

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

    1. בשדה App name, מזינים 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. בשדה שם, כותבים 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 מסרגל הצד.

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

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

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

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

    תכנון נסיעות מ-Gmail

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

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

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

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

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

    סיעור מוחות מ-Chat

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

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

    קבלת פרטי מיקום גיאוגרפי מקובץ מצורף ב-Chat

מגבלות

HTTP

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

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

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

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

Apps Script

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

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

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

התאמה אישית

הפתרון הזה תומך בסוכני AI של ADK שמארחים ב-Vertex AI Agent Engine, קבוצת משנה של ממשקי משתמש של אפליקציות 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 API כדי לאסוף פרטים על ההקשר ולבצע פעולות. תוסף טיפוסי יכול להוסיף פונקציות לאחזור נתונים עסקיים מיומן 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 API כדי לאסוף פרטים על ההקשר ולבצע פעולות. תוסף טיפוסי יכול להוסיף פונקציות לאחזור נתונים עסקיים מיומן Google או ממערכת לניהול קשרי לקוחות (CRM).

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

הסרת המשאבים

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

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

    כניסה ל-Resource Manager

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