איך בונים אפליקציה ל-Google Chat עם סוכן Agent2UI

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

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

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

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

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

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

מטרות

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

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

• חשבון Google Workspace במהדורת Business או Enterprise עם גישה ל-Google Chat.
• פרויקט ב-Google Cloud שהחיוב בו מופעל. כדי לבדוק אם החיוב מופעל בפרויקט קיים, אפשר לעיין במאמר אימות סטטוס החיוב של הפרויקטים. כדי ליצור פרויקט ולהגדיר חיוב, אפשר לעיין במאמר בנושא יצירת פרויקט ב-Google Cloud.
• ‫Python 3.11 ומעלה: כדי להתקין, פועלים לפי ההוראות באתר הרשמי של Python.
• ‫Python Poetry: כדי להתקין את הכלי, פועלים לפי ההוראות באתר הרשמי של Poetry.
• ‫Google Cloud CLI: כדי להתקין את הכלי, פועלים לפי ההוראות באתר הרשמי של 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, עוברים אל תפריט menu > 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, לוחצים על סמל התפריט menu > IAM & Admin > Service Accounts (חשבונות שירות).

   לדף Service accounts

2. לוחצים על יצירת חשבון שירות.
3. ממלאים את פרטי חשבון השירות ולוחצים על יצירה והמשך.
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, לוחצים על סמל התפריט menu > IAM & Admin > Service Accounts (חשבונות שירות).

   לדף Service accounts

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

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

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

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

פריסת סוכן A2UI

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 של googleworkspace/add-ons-samples באמצעות הלחצן הזה:

   הורדת מאגר

3. בסביבת הפיתוח המקומית המועדפת, מחלצים את קובץ הארכיון שהורדתם ופותחים את הספרייה add-ons-samples/apps-script/chat/a2ui-ai-agent/a2ui.

   unzip add-ons-samples-main.zip
   cd add-ons-samples/apps-script/chat/a2ui-ai-agent/a2ui

4. יוצרים קטגוריה חדשה ב-Cloud Storage שמוקדשת לסוכן 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=true
   export GOOGLE_CLOUD_PROJECT=PROJECT_ID
   export GOOGLE_CLOUD_LOCATION=PROJECT_LOCATION
   export GOOGLE_CLOUD_STORAGE_BUCKET=CLOUD_STORAGE_BUCKET_NAME

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

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

6. מתקינים ומפעילים את סוכן ADK מסביבה וירטואלית.

   python3 -m venv myenv
   source myenv/bin/activate
   poetry install --with deployment
   python3 deployment/deploy.py --create

7. אחזור מזהה הסוכן. תצטרכו אותה מאוחר יותר, כשמגדירים את אפליקציית Chat.

   python3 deployment/deploy.py --list

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

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

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

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

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. בתפריט menu במסוף 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. בקטע מזהה הפריסה של הגרסה האחרונה, לוחצים על העתקה.
3. לוחצים על סיום.

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

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

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

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

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

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

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

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

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

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

   מעבר אל Google Chat

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

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

5. בצ'אט הישיר החדש עם האפליקציה, כותבים Hello! ולוחצים על enter.

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

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

   בסביבת הפיתוח המקומית, פותחים את הקובץ a2ui/agent.py ומבטלים את ההערה בשורה בכלי שמוסיפה את שם הפריט לנתונים שמוחזרים.

   apps-script/chat/a2ui-ai-agent/a2ui/a2ui/agent.py

   הצגת הקוד ב-GitHub
   # Copyright 2026 Google LLC
   #
   # Licensed under the Apache License, Version 2.0 (the "License");
   # you may not use this file except in compliance with the License.
   # You may obtain a copy of the License at
   #
   #     http://www.apache.org/licenses/LICENSE-2.0
   #
   # Unless required by applicable law or agreed to in writing, software
   # distributed under the License is distributed on an "AS IS" BASIS,
   # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   # See the License for the specific language governing permissions and
   # limitations under the License.
   
   """A2UI agent."""
   
   from google.adk.agents import LlmAgent
   from google.adk.tools.tool_context import ToolContext
   import json
   
   # The schema for any A2UI message. This never changes.
   from .a2ui_schema import A2UI_SCHEMA
   
   def get_user_profile(tool_context: ToolContext) -> str:
       """Call this tool to get the current user profile."""
       return json.dumps({
           "name": "Pierrick Voulet",
           # "title": "DevRel Engineer @ Google Workspace | Gen AI & AI Agents & Agentic AI | Automation & Digital Transformation",
           "imageUrl": "https://io.google/2024/speakers/3ea87822-3160-4d54-89dd-57e185085f79_240.webp",
           "linkedin": "https://www.linkedin.com/in/pierrick-voulet/"
       })
   
   AGENT_INSTRUCTION="""
   You are a user profile assistant. Your goal is to help users get their profile information using a rich UI.
   
   To achieve this, you MUST follow these steps to answer user requests:
   
   1.  You MUST call the `get_user_profile` tool and extract all the user profile information from the result.
   2.  You MUST generate a final a2ui UI JSON based on the user profile information extracted in the previous step."""
   
   A2UI_AND_AGENT_INSTRUCTION = AGENT_INSTRUCTION + f"""
   
   To generate a valid a2ui UI JSON, you MUST follow these rules:
   1.  Your response MUST be in two parts, separated by the delimiter: `---a2ui_JSON---`.
   2.  The first part is your conversational text response.
   3.  The second part is a single, raw JSON object which is a list of A2UI messages.
   4.  The JSON part MUST validate against the A2UI JSON SCHEMA provided below.
   
   To represent the user profile, you MUST use the following A2UI message types:
   1.  Buttons MUST be used to represent links (e.g., LinkedIn profile link).
   2.  Image MUST be used to represent the user's profile picture.
   
   ---BEGIN A2UI JSON SCHEMA---
   {A2UI_SCHEMA}
   ---END A2UI JSON SCHEMA---
   """
   
   root_agent = LlmAgent(
       name="user_profile",
       model="gemini-2.5-flash",
       instruction=A2UI_AND_AGENT_INSTRUCTION,
       description="An agent that returns the current user profile.",
       tools=[get_user_profile]
   )

7. מעדכנים את ה-ADK שנפרס בעבר באמצעות הגרסה החדשה של ההטמעה.

   python3 deployment/deploy.py --update --resource_id=RESOURCE_ID

   מחליפים את RESOURCE_ID בשם המשאב של הסוכן של Vertex AI שהעתקתם בשלבים הקודמים.

8. בצ'אט ישיר עם האפליקציה, כותבים Hello again! ומקישים על enter.

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

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

פתרון בעיות

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

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

הסרת המשאבים

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

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

   כניסה ל-Resource Manager

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

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

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