אירוח סוכן A2UI באמצעות Cloud Run

במדריך הזה נסביר איך לפרוס ב-Cloud Run סוכן Agent-to-Agent‏ (A2A) שנוצר באמצעות הערכה לפיתוח סוכנים (ADK) ותוסף A2UI. בנוסף, תלמדו איך לרשום את הנציג שנפרס ב-Gemini Enterprise.

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

מבנה התיקיות של המדריך

מבנה התיקיות של הפרויקט:

קובץ/ספרייה תיאור
/samples/community/agent/adk/gemini_enterprise/v0_9 ספרייה שמכילה הגדרות ונתונים לדוגמה בשביל המדריך הזה.
__init__.py מסמן את הספרייה כחבילת Python.
__main__.py נקודת הכניסה להפעלת הנציג באופן מקומי.
agent.py מגדירה את הסוכן, את המיומנויות שלו ואת ההתנהגות שלו.
agent_executor.py מנהל את תהליך ההפעלה ואת האינטראקציות עם הכלים.
deploy.sh סקריפט לפיתוח ולפריסה של הסוכן ב-Cloud Run.
examples/ ספרייה שמכילה דוגמאות לתבניות של רכיבים.
gemini_enterprise_composite_catalog.json קטלוג רכיבים שמגדיר רכיבים סטנדרטיים של Material ורכיבים בהתאמה אישית של Gemini Enterprise.
main.py נקודת הכניסה הראשית לאפליקציה (אפליקציית FastAPI).
prompt_builder.py כלי עזר ליצירת הנחיות למודל.
pyproject.toml הגדרות אישיות ויחסי תלות של פרויקט.
examples/0.9/material_table_orders.json תבנית ממשק משתמש לדוגמה שמכילה את הפריסה ואת הנתונים לדוגמה להדגמה של ההזמנות האחרונות.
tools.py מגדירה את הכלים (הפונקציות) שהסוכן יכול להשתמש בהם.

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

לפני שמתחילים, חשוב לוודא שהתנאים הבאים מתקיימים:

  • התפקיד אדמין ב-Discovery Engine.

  • אפליקציית Gemini Enterprise קיימת. כדי ליצור אפליקציה, אפשר לעיין במאמר יצירת אפליקציה.

  • משכפלים את המאגר ועוברים לספריית הדוגמה v0_9:

    git clone https://github.com/a2ui-project/a2ui.git
cd a2ui/samples/community/agent/adk/gemini_enterprise/v0_9

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

מפעילים את ממשקי ה-API הבאים בפרויקט:

המסוף

מפעילים את ממשקי ה-API הבאים:

  • Vertex AI API
  • Cloud Build API
  • Artifact Registry API
  • Cloud Run API
  • Cloud Logging API
  • Discovery Engine API
  • Cloud Storage API
  • ‫API של ניהול זהויות והרשאות גישה (IAM)

הפעלת ממשקי API

REST

אפשר להפעיל את ממשקי ה-API האלה ממסוף Google Cloud או באמצעות הפקודה הבאה ב-CLI של gcloud:

gcloud services enable aiplatform.googleapis.com cloudbuild.googleapis.com artifactregistry.googleapis.com run.googleapis.com logging.googleapis.com discoveryengine.googleapis.com storage.googleapis.com iam.googleapis.com

מתן הרשאות

נותנים הרשאה לתפקיד Cloud Run Invoker ‏ (roles/run.invoker).

gcloud projects add-iam-policy-binding PROJECT_ID \
   --member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-discoveryengine.iam." \
   --role="roles/run.invoker"

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

  • ‫PROJECT_ID : מזהה הפרויקט.
  • ‫PROJECT_NUMBER: מספר הפרויקט ב- Google Cloud .

פריסת הנציג

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

הסקריפט מבצע את הפעולות הבאות:

  1. יוצר קובץ אימג' של קונטיינר מקוד המקור.
  2. מעביר את קובץ האימג' ל-Artifact Registry.
  3. פורס את קובץ האימג' ב-Cloud Run.
  4. מגדיר משתני סביבה, כולל MODEL ו-AGENT_URL הציבורי של השירות עצמו.
chmod +x deploy.sh
./deploy.sh PROJECT_ID a2ui-demo-agent MODEL_NAME

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

  • ‫PROJECT_ID: מזהה הפרויקט.
  • ‫MODEL_NAME: אופציונלי. זהו הארגומנט השלישי של הסקריפט. הערכים הנתמכים הם gemini-2.5-pro ו-gemini-2.5-flash. אם לא מציינים את הפרמטר הזה, הסקריפט משתמש בערך ברירת המחדל gemini-2.5-flash.

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

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

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

מריצים את הפקודה הבאה של curl, ומחליפים את ערכי ה-placeholder בערכים שלכם:

curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_NUMBER/locations/LOCATION/collections/default_collection/engines/ENGINE_ID/assistants/default_assistant/agents -d '{
  "name": "a2ui-demo-agent",
  "displayName": "A2UI v0.9 Demo Agent",
  "description": "A demo agent that showcases A2UI v0.9 UI templates.",
  "a2aAgentDefinition": {
      "jsonAgentCard": "{\"protocolVersion\": \"0.3.0\", \"name\": \"A2UI v0.9 Demo\", \"description\": \"A demo agent that showcases A2UI v0.9 UIs built from the Material component catalog and Gemini Enterprise custom components (Canvas, Iframe). Ask it what can you do? to see the available demos.\", \"url\": \"AGENT_URL\", \"version\": \"1.0.0\", \"capabilities\": {\"streaming\": true, \"preferredTransport\": \"JSONRPC\", \"extensions\": [{\"uri\": \"https://a2ui.org/a2a-extension/a2ui/v0.9\", \"description\": \"Ability to render A2UI v0.9\", \"required\": false, \"params\": {\"supportedCatalogIds\": [\"https://www.gstatic.com/vertexaisearch/a2ui/v0_9/gemini_enterprise_composite_catalog.json\"]}}]}, \"skills\": [{\"id\": \"a2ui_demo\", \"name\": \"A2UI v0.9 Component Demo\", \"description\": \"Demonstrates A2UI v0.9 UIs built from the Material catalog and Gemini Enterprise custom components: cards, forms & inputs, tabs, tables, progress indicators, dialogs & menus, the Canvas side panel, and the Iframe (IFrameSrcdoc / IFrameUrl) components.\"}], \"defaultInputModes\": [\"text/plain\"], \"defaultOutputModes\": [\"text/plain\"]}"
    }
}'

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

  • ‫PROJECT_NUMBER: מספר הפרויקט ב- Google Cloud .
  • ‫LOCATION: האזור של מאגר הנתונים: global,‏ us או eu
  • ‫ENGINE_ID: המזהה של האפליקציה שבה רוצים לרשום את הנציג.
  • ‫AGENT_URL: כתובת ה-URL של השירות של הנציג שנפרס.

ביטול הרישום של הנציג (אופציונלי)

כדי לבטל את הרישום של הסוכן, מריצים את הפקודה הבאה של curl:

curl -X DELETE -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_NUMBER/locations/LOCATION/collections/default_collection/engines/ENGINE_ID/assistants/default_assistant/agents/AGENT_ID

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

  • ‫PROJECT_NUMBER: מספר הפרויקט ב- Google Cloud .
  • ‫LOCATION: האזור של מאגר הנתונים: global,‏ us או eu
  • ‫ENGINE_ID: המזהה של האפליקציה שאליה הנציג רשום.
  • ‫AGENT_ID: המזהה של הנציג שרוצים למחוק.

שימוש בסוכן באתר Gemini Enterprise

אחרי שיוצרים ורושמים סוכן, אפשר להתחיל להשתמש בו ולתקשר איתו באתר Gemini Enterprise.

איך מקבלים את כתובת ה-URL של אפליקציית האינטרנט

כדי להשתמש בנציג, קודם צריך לקבל את כתובת ה-URL של אפליקציית האינטרנט. אדמינים ב-Gemini Enterprise יכולים לקבל ולשתף את כתובת ה-URL של אפליקציית האינטרנט לפי השלבים הבאים:

  1. במסוף Google Cloud , נכנסים לדף Gemini Enterprise.

    Gemini Enterprise

  2. לוחצים על שם האפליקציה שבה רשמתם את הנציג.

  3. לוחצים על Integrations (שילובים).

  4. מעתיקים את הקישור לאפליקציית האינטרנט ומשתפים אותו עם המשתמשים בארגון.

שימוש בסוכן

כדי להשתמש בנציג ולתקשר איתו:

  1. פותחים את כתובת ה-URL של אפליקציית האינטרנט בכרטיסייה חדשה בדפדפן.
  2. בתפריט הניווט של אפליקציית האינטרנט, לוחצים על נציגים.
  3. בקטע מהארגון שלך, לוחצים על הנציג שיצרתם.
  4. הפעולה הזו פותחת את ממשק השיחה של הנציג. מתחילים לשאול שאלות ולתקשר עם הסוכן.

לדוגמה, אתם יכולים להשתמש בהנחיה כמו Show me the recent orders table כדי לקבל מידע על הזמנות אחרונות שהן חלק מהנתונים לדוגמה. הנציג מאחזר את פרטי ההזמנה מ-material_table_orders.json ומציג את הרשימה בצ'אט באמצעות רכיבים מותאמים אישית של ממשק המשתמש, כמו בדוגמה הבאה:

דוגמה לטבלת הזמנות מהזמן האחרון