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

במדריך הזה נסביר איך לפרוס ב-Cloud Run סוכן 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 קטלוג רכיבים שמגדיר חומרים סטנדרטיים ורכיבים מותאמים אישית של 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.gserviceaccount.com" \
   --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. נכנסים לדף Gemini Enterprise במסוף Google Cloud .

    Gemini Enterprise

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

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

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

שימוש בסוכן

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

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

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

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