אירוח סוכן 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
  • Identity and Access Management (IAM) API

הפעלת ממשקי 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 הבאה, ומחליפים את הערכים הזמניים לשמירת מקום בערכים משלכם:

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. נכנסים לדף Gemini Enterprise במסוף Google Cloud .

    ‫Gemini Enterprise

  2. לוחצים על שם האפליקציה שבה רשמתם את הסוכן.

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

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

שימוש בסוכן

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

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

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

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