פריסת סוכני A2A ב-Cloud Run

הכנה והגדרה של סוכני Agent2Agent‏ (A2A) לפריסה ב-Cloud Run.

במדריך הזה מפורטים השלבים החשובים לפריסת סוכני A2A:

סקירה של מפרט ה-A2A וסוכנים לדוגמה

לפני שמתחילים לפתח ולפרוס את סוכן ה-A2A, כדאי להכיר את המושגים והמשאבים הבאים:

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

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

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. התקינו את ה-CLI של Google Cloud.

  5. אם אתם משתמשים בספק זהויות חיצוני (IdP), קודם אתם צריכים להיכנס ל-CLI של gcloud באמצעות המאגר המאוחד לניהול זהויות.

  6. כדי לאתחל את ה-CLI של gcloud, הריצו את הפקודה הבאה: 

    gcloud init

  7. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  8. Verify that billing is enabled for your Google Cloud project.

  9. התקינו את ה-CLI של Google Cloud.

  10. אם אתם משתמשים בספק זהויות חיצוני (IdP), קודם אתם צריכים להיכנס ל-CLI של gcloud באמצעות המאגר המאוחד לניהול זהויות.

  11. כדי לאתחל את ה-CLI של gcloud, הריצו את הפקודה הבאה: 

    gcloud init

  12. כדי ליצור חשבון שירות, מריצים את הפקודה הבאה:
    13. gcloud iam service-accounts create A2A_SERVICE_ACCOUNT_NAME \
  --description="DESCRIPTION" \
  --display-name="DISPLAY_NAME"

    מחליפים את הערכים הבאים:

    • A2A_SERVICE_ACCOUNT_NAME: השם של חשבון השירות

    • DESCRIPTION: תיאור אופציונלי של חשבון השירות

    • DISPLAY_NAME: השם של חשבון השירות שיופיע ב Google Cloud מסוף

הקצאת תפקידים לחשבון השירות

כדי להקצות לחשבון שלכם את תפקידי ה-IAM הנדרשים בפרויקט:

     gcloud projects add-iam-policy-binding PROJECT_ID \
         --member="serviceAccount:A2A_SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" \
         --role="ROLE"

מחליפים את:

  • ‫PROJECT_ID: מזהה הפרויקט
  • A2A_SERVICE_ACCOUNT_NAME: השם של חשבון השירות
  • ROLE: התפקיד שאתם מוסיפים לחשבון השירות

התפקידים הנדרשים

כדי לקבל את ההרשאות שדרושות לפריסת סוכני A2A, צריך לבקש מהאדמין להקצות לכם את תפקידי ה-IAM הבאים:

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

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

מתן התפקידים

המסוף

  1. נכנסים לדף IAM במסוף Google Cloud .

    כניסה לדף IAM
  2. בוחרים את הפרויקט.
  3. לוחצים על Grant access.

  4. בשדה New principals, מזינים את מזהה המשתמש. בדרך כלל מדובר בכתובת האימייל שמשמשת לפריסת שירות Cloud Run.

  5. בוחרים תפקיד מהרשימה Select a role.
  6. כדי להקצות עוד תפקידים, לוחצים על Add another role ומוסיפים אותם.
  7. לוחצים על Save.

gcloud

כדי להקצות לחשבון שלכם את תפקידי ה-IAM הנדרשים בפרויקט:

     gcloud projects add-iam-policy-binding PROJECT_ID \
         --member=PRINCIPAL \
         --role=ROLE

מחליפים את:

  • ‫PROJECT_NUMBER עם מספר הפרויקט ב- Google Cloud .
  • PROJECT_ID במזהה הפרויקט ב- Google Cloud .
  • ‫PRINCIPAL עם החשבון שאליו אתם מוסיפים את הקישור. בדרך כלל זו כתובת האימייל שמשמשת לפריסת שירות Cloud Run.
  • ‫ROLE עם התפקיד שאתם מוסיפים לחשבון של כלי הפריסה.

הכנה לפריסה ב-Cloud Run

בקטע הזה מוסבר על ההגדרות שנדרשות כדי להכין את סוכן A2A לפריסה ב-Cloud Run עבור דוגמת קוד Python.

הכנת סוכן A2A

  1. כדי לאחזר את דוגמת הקוד, משכפלים את מאגר האפליקציה לדוגמה למכונה המקומית:

    git clone https://github.com/a2aproject/a2a-samples

  2. עוברים לספרייה שמכילה את הקוד לדוגמה:

    cd a2a-samples/samples/python/agents/adk_cloud_run

הגדרת סודות לשירותי Cloud Run

צריך לספק את כל פרטי הכניסה הרגישים, כמו מפתחות API וסיסמאות למסד נתונים, לשרת A2A באמצעות מנגנון מאובטח. ב-Cloud Run אפשר לספק סודות כמשתני סביבה או כנפחים שמוצמדים באופן דינמי. מידע נוסף זמין במאמר הגדרת סודות ב-Cloud Run.

סוכנים צריכים גישה לשירותים חיצוניים כדי להשלים את המשימות שלהם. הסודות הם המנגנון המאובטח להענקת הגישה הזו. כשפורסים עם AlloyDB ל-PostgreSQL, צריך את שם המשתמש והסיסמה. כדי ליצור ולנהל את סודות הסיסמה והמשתמש של מסד הנתונים ב-Secret Manager, מריצים את הפקודות הבאות ב-CLI של gcloud:

gcloud secrets create alloy_db_user --replication-policy="automatic"
# Create a file user.txt with contents of secret value
gcloud secrets versions add alloy_db_user --data-file="user.txt"

gcloud secrets create alloy_db_pass --replication-policy="automatic"
# Create a file pass.txt with contents of secret value
gcloud secrets versions add alloy_db_pass --data-file="pass.txt"

מידע נוסף זמין במאמר יצירת סוד.

קובץ Docker ליצירת קונטיינרים

ב-Cloud Run אפשר לפרוס שירותים מתמונות קונטיינר שכבר מתארחות או ישירות מקוד המקור. כשפורסים מקוד מקור, Cloud Run יוצר באופן אוטומטי קובץ אימג' של קונטיינר אם יש קובץ Dockerfile בספריית הבסיס של הפרויקט.

קובץ ה-Dockerfile קובע את הפרטים של קובץ האימג' של הקונטיינר. בהמשך מופיע קובץ Dockerfile מסוכן לדוגמה מסוג A2A ששיבטתם קודם:

FROM python:3.13-slim
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
EXPOSE 8080
WORKDIR /app
COPY . ./
RUN uv sync
ENTRYPOINT ["uv", "run", ".", "--host", "0.0.0.0", "--port", "8080"]

פריסה מקוד מקור ללא Dockerfile

במאגרי קוד מקור בלי קובץ Docker, ‏ Cloud Run מציע תמיכה מובנית בשפות תכנות פופולריות מסוימות, כדי לפשט את תהליך יצירת הקונטיינר.

פריסת סוכן A2A ב-Cloud Run

פורסים את אפליקציית A2A עם הגדרת TaskStore בזיכרון או עם AlloyDB ל-PostgreSQL.

  • בתצורה TaskStore בזיכרון, כל הנתונים מאוחסנים רק במכונת הקונטיינר של Cloud Run. המשמעות היא שכל נתוני המשימות אובדים כשמופעלת השבתה, הקטנה או הפעלה מחדש של מופע המאגר.
  • ‫AlloyDB ל-PostgreSQL מספק עמידות נתונים, ומאפשר לסוכנים להתרחב אופקית. בנוסף, הוא מבטיח שהמשימות ימשיכו לפעול גם אחרי הפעלה מחדש של קונטיינרים, אירועי שינוי גודל ופריסות.

הגדרת TaskStore בזיכרון מתאימה לפיתוח סוכני A2A בסביבה המקומית, ו-AlloyDB ל-PostgreSQL מתאים להרחבת סוכן A2A בסביבת הייצור.

הפקודות הבאות מראות איך להשתמש באימות מבוסס-IAM בשירות Cloud Run. השימוש בדגל --no-allow-unauthenticated בזמן הפריסה הוא הדרך המומלצת להגדרת אימות ללקוחות פנימיים Google Cloud , כמו Gemini Enterprise.

אם שרת ה-A2A שלכם מיועד לגישה ציבורית וצריך לטפל באימות ברמת הסוכן, תוכלו לציין את הדגל --allow-unauthenticated במהלך הפריסה. פרטים נוספים זמינים במאמר בנושא אימות גישה ציבורית ב-Cloud Run. כדי לאפשר גישה ציבורית לשירות Cloud Run, צריך גם לספק פרטי אימות חיוניים בכרטיס של סוכן A2A באמצעות הפרמטרים securitySchemes ו-security. למידע נוסף, ראו מפרט A2A: פרטים על אובייקט SecurityScheme.

פריסה עם הגדרות TaskStore בזיכרון

כדי לפרוס את סוכן A2A עם הגדרת TaskStore בזיכרון, מריצים את הפקודה הבאה בספרייה שמכילה את קוד המקור של סוכן A2A:

gcloud run deploy sample-a2a-agent \
    --port=8080 \
    --source="." \
    --no-allow-unauthenticated \
    --region=REGION \
    --project=PROJECT_ID \
    --memory=1Gi \
    --service-account=A2A_SERVICE_ACCOUNT_NAME \
    --set-env-vars=GOOGLE_GENAI_USE_VERTEXAI=true,GOOGLE_CLOUD_PROJECT="PROJECT_ID",GOOGLE_CLOUD_LOCATION="REGION",APP_URL="https://sample-a2a-agent-PROJECT_NUMBER.REGION.run.app"

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

  • ‫REGION: Google Cloud האזור שבו רוצים לפרוס את השירות, לדוגמה europe-west1.
  • PROJECT_ID: מזהה הפרויקט.
  • ‫PROJECT_NUMBER: מספר הפרויקט.
  • ‫A2A_SERVICE_ACCOUNT_NAME: השם של חשבון השירות של A2A.

פריסה באמצעות AlloyDB ל-PostgreSQL

כדי לשמור את משימות ה-A2A, צריך להשתמש ב-AlloyDB ל-PostgreSQL. כדי לפרוס את סוכן A2A עם AlloyDB ל-PostgreSQL בשביל אחסון מתמשך של משימות, משתמשים בפקודה הבאה:

gcloud run deploy sample-a2a-agent \
    --port=8080 \
    --source="." \
    --no-allow-unauthenticated \
    --region=REGION \
    --project=PROJECT_ID \
    --memory=1Gi \
    --update-secrets=DB_USER=alloy_db_user:latest,DB_PASS=alloy_db_pass:latest \
    --service-account=A2A_SERVICE_ACCOUNT_NAME \
    --set-env-vars=GOOGLE_GENAI_USE_VERTEXAI=true,GOOGLE_CLOUD_PROJECT="PROJECT_ID",GOOGLE_CLOUD_LOCATION="REGION",APP_URL="https://sample-a2a-agent-PROJECT_NUMBER.REGION.run.app",USE_ALLOY_DB="True",DB_INSTANCE="projects/PROJECT_ID/locations/REGION/clusters/CLUSTER_NAME/instances/primary-instance",DB_NAME="postgres"

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

  • ‫REGION: Google Cloud האזור שבו רוצים לפרוס את השירות, לדוגמה europe-west1.
  • PROJECT_ID: מזהה הפרויקט.
  • ‫PROJECT_NUMBER: מספר הפרויקט.
  • ‫CLUSTER_NAME: השם של אשכול AlloyDB ל-PostgreSQL.
  • ‫A2A_SERVICE_ACCOUNT_NAME: השם של חשבון השירות של A2A.

ניפוי באגים בפריסות שנכשלו

אם נתקלתם בשגיאות או בכשלים בפריסה של Cloud Run, כדאי לשקול את האפשרויות הבאות:

  • יומנים מפורטים: כדי להגדיר יומני פריסה מפורטים, צריך להגדיר את הדגל --verbosity=info בפקודה gcloud run deploy.

  • אי התאמה של כתובת ה-URL: אם כתובת ה-URL ‏run.app שמוחזרת על ידי פקודת הפריסה שונה מכתובת ה-URL הצפויה, צריך לעדכן את משתנה הסביבה APP_URL של שירות Cloud Run:

    1. משתמשים בפקודה הבאה כדי לעדכן את משתנה הסביבה APP_URL:

      gcloud run services update SERVICE_NAME \
    --project="PROJECT_ID" \
    --region="REGION" \
    --update-env-vars=APP_URL="CLOUD_RUN_SERVICE_URL"

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

      • ‫SERVICE_NAME: השם של שירות Cloud Run.
      • PROJECT_ID: מזהה הפרויקט.
      • ‫REGION: Google Cloud האזור שבו רוצים לפרוס את השירות. לדוגמה europe-west1.
      • ‫CLOUD_RUN_SERVICE_URL: כתובת ה-URL של שירות Cloud Run.

    2. כדי לוודא שהשדה APP_URL עודכן בצורה נכונה, מתארים את השירות:

      gcloud run services describe SERVICE_NAME \
    --project="PROJECT_ID" \
    --region="REGION"

הסבר על כתובת ה-URL של אפליקציית Cloud Run

לאחר פריסה מוצלחת, מערכת Cloud Run מספקת באופן אוטומטי כתובת URL, שמשמשת כנקודת הקצה לשליחת שאילתות לשירות A2A הפעיל.run.app כתובת ה-URL היא דטרמיניסטית וניתנת לחיזוי אם שם השירות קצר מספיק.

  • הפורמט של כתובת URL ב-Cloud Run: https://TAG---SERVICE_NAME-PROJECT_NUMBER.REGION.run.app
  • כתובת URL לדוגמה: https://sample-a2a-agent-1234.europe-west1.run.app

בדיקה ומעקב אחרי פריסת נציג A2A

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

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

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

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

  • הצגת כרטיס הסוכן: הצגת כרטיס הסוכן באופן אוטומטי.
  • אימות התאימות: המערכת בודקת שהכרטיס עומד בדרישות של A2A.
  • הפעלת צ'אט בשידור חי: מאפשרת לכם לשלוח ולקבל הודעות מהנציג.
  • הצגת נתונים גולמיים: הצגת הודעות גולמיות של JSON-RPC 2.0 במסוף לצורך ניפוי באגים.

אינטראקציה עם סוכן A2A שפרסנו באמצעות CLI

כדי ליצור אינטראקציה עם השירות שפרסתם, אתם יכולים להשתמש בכלי ממשק שורת הפקודה (CLI) ממאגר הדוגמאות של A2A. ממשק ה-CLI הזה תומך באימות מבוסס-אסימון Bearer.

אם השירות שלכם משתמש באימות מבוסס-IAM, צריך לייצא את האסימון gcloud כדי שהאינטראקציה תצליח:

export A2A_CLI_BEARER_TOKEN=$(gcloud auth print-identity-token)
# From CLI directory
uv run . --agent CLOUD_RUN_SERVICE_URL

מחליפים את CLOUD_RUN_SERVICE_URL בכתובת ה-URL של שירות Cloud Run שפרסתם.

בדיקה מקומית של שירותי A2A שנפרסו

אתם יכולים לבדוק את שירות Cloud Run שפרסתם באופן מקומי. האפשרות הזו שימושית במיוחד כשמטמיעים אימות מבוסס-IAM.

בדיקת אימות מבוסס-IAM לסוכני Cloud Run

לקוחות שיוצרים אינטראקציה עם שירות Cloud Run שמאובטח באמצעות ניהול זהויות והרשאות גישה (IAM) צריכים להיות בעלי תפקיד IAM‏ roles/run.invoker.

בודקים באופן מקומי את תהליך האימות של השירות שפרסתם באמצעות הפקודה gcloud auth print-identity-token:

curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" CLOUD_RUN_SERVICE_URL/.well-known/agent.json

מחליפים את CLOUD_RUN_SERVICE_URL בכתובת ה-URL של שירות Cloud Run שפרסתם.