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

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

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

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

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

קובץ/ספרייה תיאור
examples/0.8/ ספרייה שמכילה הגדרות או נתונים לדוגמה.
__init__.py הסימון של הספרייה כחבילת Python.
agent.py הגדרת הסוכן, המיומנויות וההתנהגות שלו.
agent_executor.py מנהל את תהליך הביצוע ואת האינטראקציות עם הכלים.
contact_data.json נתונים לדוגמה שהסוכן משתמש בהם (לדוגמה, אנשי קשר מדומה).
deploy.sh סקריפט ליצירה ולפריסה של הסוכן ב-Cloud Run.
main.py נקודת הכניסה הראשית לאפליקציה (אפליקציית FastAPI).
prompt_builder.py עוזר ליצור הנחיות למודל.
pyproject.toml הגדרות אישיות של פרויקט ויחסי תלות.
tools.py ההגדרה הזו מגדירה את הכלים (הפונקציות) שהסוכן יכול להשתמש בהם.

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

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

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

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

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

    git clone https://github.com/google/A2UI.git
cd A2UI/samples/agent/adk/gemini_enterprise/cloud_run

הפעלת ממשקי ה-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.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 YOUR_PROJECT_ID contacts-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": "contacts-agent",
"displayName": "Contacts Agent",
"description": "This is a test agent which lists the contacts.",
"a2aAgentDefinition": {
  "jsonAgentCard": "{\"protocolVersion\": \"0.3.0\", \"name\": \"contacts-agent\", \"description\": \"This is a test agent which lists the contacts.\", \"url\": \"AGENT_URL\", \"version\": \"1.0.0\", \"capabilities\": {\"streaming\": true, \"extensions\": [{\"uri\": \"https://a2ui.org/a2a-extension/a2ui/v0.8\", \"description\": \"Ability to render A2UI\", \"required\": false, \"params\": {\"supportedCatalogIds\": [\"https://a2ui.org/specification/v0_8/standard_catalog_definition.json\"]}}]}, \"skills\": [], \"defaultInputModes\": [\"text/plain\"], \"defaultOutputModes\": [\"text/plain\"]}"
}
}'

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

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

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

לדוגמה, אפשר לבקש מהסוכן לרשום את כל אנשי הקשר. הסוכן משתמש בכלי list_contacts כדי לאחזר את אנשי הקשר מ-contact_data.json ומציג את הרשימה בצ'אט באמצעות רכיבי ממשק משתמש מותאמים אישית, כמו בדוגמה הבאה:

דוגמה לסוכן מכירות וירטואלי