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

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

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

• הגדרת הפרויקט
• הגדרת תפקידים ב-IAM
• הגדרת סביבת הענן
• פריסת הסוכן
• ניפוי באגים בכשלים בפריסה
• בדיקה ומעקב

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

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

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

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

1. In the Cloud de Confiance console, on the project selector page, select or create a Cloud de Confiance 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

2. Verify that billing is enabled for your Cloud de Confiance project.

3. Install the Google Cloud CLI.

4. Configure the gcloud CLI to use your federated identity.

   For more information, see Sign in to the gcloud CLI with your federated identity.

5. To initialize the gcloud CLI, run the following command:

   gcloud init

6. כברירת מחדל, מומלץ להקצות זהות סוכן מאובטחת שמנוהלת על ידי המערכת לסוכן על ידי העברת הדגלים --functional-type=agent ו---identity-type=agent-identity במהלך הפריסה. הוראות מופיעות במאמר הגדרת תכונות של פלטפורמת הנציגים. אם אתם חייבים לפרוס את הנציג עם חשבון שירות רגיל, אתם יכולים ליצור חשבון שירות בניהול המשתמש ולהעביר את הדגל --service-account במהלך הפריסה.

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

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

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

• מפתח מקור ב-Cloud Run ‏ (roles/run.sourceDeveloper) בפרויקט
• אדמין IAM של פרויקט (roles/resourcemanager.projectIamAdmin) בפרויקט
• אדמין Secret Manager (roles/secretmanager.admin) בפרויקט
• משתמש בחשבון שירות (roles/iam.serviceAccountUser) בזהות השירות
• ‫Secret Manager Secret Accessor (roles/secretmanager.secretAccessor) on the service account
• משתמש ב-Vertex AI ‏ (roles/aiplatform.user) בחשבון השירות
• אם אתם פורסים באמצעות AlloyDB ל-PostgreSQL, צריך להקצות את התפקידים הבאים:
  • לקוח AlloyDB ל-PostgreSQL (roles/alloydb.client) בחשבון השירות
  • אדמין IAM בפרויקט (roles/resourcemanager.projectIamAdmin) בחשבון השירות

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

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

     gcloud projects add-iam-policy-binding PROJECT_ID \
         --member=PRINCIPAL \
         --role=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

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

• אפליקציות Python ב-Cloud Run:‏ Cloud Run מחפש קובץ main.py כדי ליצור ולפרוס שירותי Python. מידע נוסף זמין במדריך למתחילים פריסת שירות Python ב-Cloud Run.
• אפליקציות Node.js ב-Cloud Run: ב-Cloud Run מחפשים קובץ index.js כדי ליצור ולפרוס שירותי Node.js. המדריך למתחילים: פריסת שירות Node.js ב-Cloud Run

פריסת סוכן A2A ב-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בזמן הפריסה הוא הדרך המומלצת להגדרת אימות ללקוחות פנימיים Cloud de Confiance by S3NS , כמו 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 \
    --functional-type=agent \
    --identity-type=agent-identity \
    --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.s3nsrun.fr"

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

• ‫REGION: Cloud de Confiance by S3NS האזור שבו רוצים לפרוס את השירות, לדוגמה europe-west1.
• PROJECT_ID: מזהה הפרויקט.
• ‫PROJECT_NUMBER: מספר הפרויקט.

פריסה באמצעות 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 \
    --functional-type=agent \
    --identity-type=agent-identity \
    --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.s3nsrun.fr",USE_ALLOY_DB="True",DB_INSTANCE="projects/PROJECT_ID/locations/REGION/clusters/CLUSTER_NAME/instances/primary-instance",DB_NAME="postgres"

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

• ‫REGION: Cloud de Confiance by S3NS האזור שבו רוצים לפרוס את השירות, לדוגמה europe-west1.
• PROJECT_ID: מזהה הפרויקט.
• ‫PROJECT_NUMBER: מספר הפרויקט.
• ‫CLUSTER_NAME: השם של אשכול AlloyDB ל-PostgreSQL.

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

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

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

• כתובת URL לא תואמת: אם כתובת ה-URL של s3nsrun.fr שמוחזרת על ידי פקודת הפריסה שונה מכתובת ה-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: Cloud de Confiance by S3NS האזור שבו רוצים לפרוס את השירות. לדוגמה 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 של s3nsrun.fr, שמשמשת כנקודת הקצה לשליחת שאילתות לשירות ה-A2A הפעיל. כתובת ה-URL היא דטרמיניסטית וניתנת לחיזוי אם שם השירות קצר מספיק.

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

בדיקה ומעקב אחרי פריסת סוכן A2A

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

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

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

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

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

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

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

אם השירות משתמש באימות מבוסס-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) צריכים להיות roles/run.invoker תפקידי IAM.

בודקים באופן מקומי את תהליך האימות של השירות שפרסתם באמצעות הפקודה 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 שפרסתם.