הגדרת תכונות של Agent Platform ל-Cloud Run

תצוגה מקדימה — הגדרת תכונות של Agent Platform ל-Cloud Run

השימוש בתכונה הזו כפוף לתנאי השימוש במוצרים בגרסת טרום-GA, שמפורטים בחלק "תנאי שירות הכלליים" בתנאים הספציפיים של השירות. השימוש בתכונות בגרסת טרום-GA הוא "כפי שהן" (As is), ויכול להיות שהתמיכה בהן תהיה מוגבלת. מידע נוסף זמין בקטע תיאור שלבי ההשקה.

תכונות של Gemini Enterprise Agent Platform כמו Agent Identity ו-Agent Registry מספקות יכולות מובנות ליצירה, לפריסה ולניהול של סוכני AI, שרתים של Model Context Protocol‏ (MCP) וכלים. הפעלת התכונות האלה במשאבי Cloud Run מאפשרת לכם ליהנות מזהויות שמנוהלות על ידי המערכת ומרישום אוטומטי, כדי לפשט את הגילוי והאבטחה של עומסי העבודה של הסוכנים.

במדריך הזה נסביר איך:

• הגדרת התפקידים הנדרשים ב-IAM
• הסבר על סוגים פונקציונליים וסוגי זהויות
• הגדרת תכונות לשירותים ולעבודות
• הצגת הזהויות שהוקצו
• צפייה בסוכנים ובכלים רשומים ב-Agent Registry

‫Cloud Run תומך בתכונות הבאות של Agent Platform:

• זהות הסוכן: מוקצית לעומס העבודה זהות ייחודית שניתנת לאימות קריפטוגרפי, שמאפשרת חיבורים מאובטחים לסוכנים, לכלים ול-Google Cloud APIs אחרים.
• Agent Registry: רושם אוטומטית את הסוכנים והכלים שלכם כדי שמפתחים וסוכנים אחרים בארגון יוכלו לגלות אותם.

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

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

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

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

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

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

gcloud init

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

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

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

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

gcloud init

1. מפעילים את Cloud Run Admin API,‏ Identity and Access Management API,‏ Agent Registry API ו-App Hub API, אם אחד מהם לא מופעל כבר.

   תפקידים שנדרשים להפעלת ממשקי API

   כדי להפעיל ממשקי API, נדרשת ההרשאה serviceusage.services.enable. אם יצרתם את הפרויקט, סביר להניח שכבר יש לכם את ההרשאה הזו דרך התפקיד 'בעלים' (roles/owner). אחרת, תוכלו לקבל את ההרשאה הזו דרך התפקיד 'אדמין בממשק Service Usage' (roles/serviceusage.serviceUsageAdmin). איך מקצים תפקידים

   הפעלת ממשקי ה-API

2. מוודאים שהגדרתם את Agent Registry בפרויקט או בארגון.
3. מתקינים ומפעילים את ה-CLI של gcloud.
4. מעדכנים את הרכיבים:

   gcloud components update

5. במחירון Cloud Run אפשר לראות את העלויות של מעבד, זיכרון ותעבורת נתונים יוצאת (egress) ברשת. הגודל הכולל של הדיסק שהוקצה ומשך החיים של המופע שמשתמש בו משפיעים על העלות.

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

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

• כדי לפרוס ולנהל משאבים של Cloud Run: אדמין של Cloud Run (roles/run.admin)
• כדי לנהל את המשאבים של מרכז האפליקציות, צריך אחד מהדברים הבאים:
  • אדמין ב-מרכז האפליקציות (roles/apphub.admin)
  • אדמין של Agent Registry API (roles/apiregistry.admin)
• כדי לפרוס עם זהות ספציפית, אחת מהאפשרויות הבאות:
  • משתמש בחשבון שירות ב-IAM (roles/iam.serviceAccountUser)
  • אדמין של חשבון שירות ב-IAM (roles/iam.serviceAccountAdmin)

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

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

תרחישים לדוגמה

כדאי להשתמש בתכונות של Agent Platform עם Cloud Run בתרחישים הבאים:

• אימות הסוכן מול סוכנים, כלים וממשקי Google Cloud API אחרים באמצעות זהות ייחודית שמנוהלת על ידי המערכת וקשורה למחזור החיים שלו.
• הפעלת גילוי אוטומטי של סוכנים ושרתי MCP ב-Agent Registry של הארגון.
• משתמשים בשרת proxy לאימות זהויות (IAP) כמדיניות אימות כדי לאבטח שרתי MCP.

הסבר על סוגים של זהויות ופונקציות

כדי להגדיר את התכונות של Agent Platform, צריך להגדיר מאפיינים פונקציונליים ומאפייני זהות במשאבי Cloud Run.

שני המאפיינים האלה קובעים איך לרשום ולזהות עומס עבודה:

• סוג פונקציונלי: מציין את המטרה העיקרית של עומס העבודה. אחרי שמגדירים את הנכס הזה, אי אפשר לשנות או לבטל את ההגדרה שלו. אתם מקצים לעומס העבודה שלכם אחד מהסוגים הפונקציונליים הבאים:
  • ‫agent: מציין שעומס העבודה הוא סוכן AI. עומסי עבודה מהסוג הזה חייבים להשתמש בסוג agent-identity.
  • ‫mcp-server: מציין את עומס העבודה כשרת MCP שמנוהל על ידי המשתמש. בסוג הזה אפשר להשתמש בכל סוג נתמך של זהות.
• סוג הזהות: מציין את סוג הזהות שהוקצה לעומס העבודה. אחרי שמגדירים את הנכס הזה, אי אפשר לשנות או לבטל את ההגדרה שלו. מקצים לעומס העבודה אחד מסוגי הזהויות הבאים:
  • ‫agent-identity: מקצה זהות של סוכן שמנוהלת על ידי המערכת ומיועדת לסוכנים. כשפורסים באמצעות agent-identity, Agent Platform מאפשרת אישורי זהות כברירת מחדל. כדי לבטל את ההסכמה, מעדכנים את השירות באמצעות הדגל --no-identity-certificate או מגדירים את ההערה run.googleapis.com/identity-certificate-enabled: "false". פועלים לפי המדריך לאימות גישה לכלים ולמשאבים לסוכנים שפועלים על סמך הסמכות שלהם או בשם משתמשי קצה. כדי להבין את המושגים העיקריים ואת יתרונות האבטחה של זהויות סוכנים שמנוהלות על ידי המערכת, אפשר לקרוא מידע נוסף על זהות סוכן.
  • ‫service-account: משתמש בחשבון שירות רגיל של Google Cloud.

אופן הפעולה של ההגדרה

ההתנהגות של מאפייני הזהות והפונקציונליות תלויה בשילוב שתבחרו:

סוג פונקציונלי	סוג הזהות	התנהגות שמתקבלת
agent	agent-identity	עומס העבודה רשום כסוכן ב-Agent Registry ומוקצית לו Agent Identity שמנוהלת על ידי המערכת.
agent	אחר או לא צוין	שגיאה. עומסי עבודה עם functional-type=agent חייבים להשתמש ב-identity-type=agent-identity.
mcp-server	‫agent-identity,‏ service-account או לא צוין	עומס העבודה רשום כשרת MCP‏ (/mcpServers) ב-Agent Registry. אם לא מציינים ערך, ברירת המחדל היא זהות של חשבון שירות.
לא צוין	service-account	עומס העבודה פועל כשירות או כמשימה רגילים של Cloud Run.

הגדרת תכונות בשירותים ובעבודות

אתם מגדירים את התכונות של Agent Platform בשירותים ובעבודות של Cloud Run באמצעות Google Cloud CLI.

שירותים

• כדי לפרוס סוכן, צריך לציין את הפרטים הבאים: --functional-type=agent ו---identity-type=agent-identity:

  gcloud beta run deploy SERVICE_NAME \
      --image=IMAGE_URL \
      --functional-type=agent \
      --identity-type=agent-identity

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

  • ‫SERVICE_NAME: השם של שירות Cloud Run.
  • ‫IMAGE_URL: הפניה לקובץ אימג' בקונטיינר, לדוגמה, us-docker.pkg.dev/cloudrun/container/hello:latest. אם אתם משתמשים ב-Artifact Registry, צריך ליצור מראש את המאגר REPO_NAME. כתובת ה-URL היא בפורמט LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG

• כדי לעדכן שירות קיים לשימוש ב-Agent Identity:

  gcloud beta run services update SERVICE_NAME \
      --functional-type=agent \
      --identity-type=agent-identity \
      --no-traffic

  חשוב: כשמעדכנים שירות קיים מחשבון שירות ל-agent-identity, ‏ Cloud Run מקצה ישות חדשה שלא יורשת הרשאות מחשבון השירות הקודם. כדי למנוע שיבושים בחיבור, כדאי להשתמש בכלי הניתוח למדיניות כדי לזהות את התפקידים הנדרשים ולהקצות אותם מראש לprincipal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/run/projects/PROJECT_NUMBER/locations/REGION/services/SERVICE_NAMEישות המורשית--no-traffic לפני העדכון, או לעדכן את השירות כדי להקצות הרשאות לפני העברת תעבורת נתונים.

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

  • ‫SERVICE_NAME: השם של שירות Cloud Run.
  • ‫ORGANIZATION_ID: מזהה הארגון ב- Google Cloud.
  • ‫PROJECT_NUMBER: מספר הפרויקט ב- Google Cloud .
  • ‫REGION: האזור שבו השירות שלכם נפרס.

• כדי לפרוס שרת MCP שמנוהל על ידי משתמש, מציינים את הערך --functional-type=mcp-server. אפשר לציין סוג זהות באמצעות התג --identity-type:

  gcloud beta run deploy SERVICE_NAME \
      --image=IMAGE_URL \
      --functional-type=mcp-server \
      --identity-type=IDENTITY_TYPE

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

  • ‫SERVICE_NAME: השם של שירות Cloud Run.
  • ‫IMAGE_URL: הפניה לקובץ אימג' בקונטיינר, לדוגמה, us-docker.pkg.dev/cloudrun/container/hello:latest. אם אתם משתמשים ב-Artifact Registry, צריך ליצור מראש את המאגר REPO_NAME. כתובת ה-URL היא בפורמט LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG
  • ‫IDENTITY_TYPE: אופציונלי. סוג הזהות שהוקצתה לעומס העבודה. מציינים agent-identity או service-account. ברירת המחדל היא service-account.

תעסוקה

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

• כדי ליצור משימה לסוכן, מציינים את --functional-type=agent ואת --identity-type=agent-identity:

  gcloud beta run jobs create JOB_NAME \
    --image=IMAGE_URL \
    --functional-type=agent \
    --identity-type=agent-identity

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

  • ‫JOB_NAME: השם של משימת Cloud Run.
  • ‫IMAGE_URL: הפניה לקובץ אימג' בקונטיינר.

צפייה בזהויות שהוקצו

אפשר לראות את הזהות של הסוכן שהוקצתה דרך מסוף Google Cloud או דרך ה-CLI של gcloud.

שירותים

המסוף

1. נכנסים ל-Cloud Run במסוף Google Cloud :

   כניסה ל-Cloud Run

2. בתפריט הניווט של Cloud Run, בוחרים באפשרות Services ולוחצים על השירות הרצוי.

3. לוחצים על הכרטיסייה Revisions (גרסאות) ובוחרים גרסה.

4. לוחצים על הכרטיסייה אבטחה.

בשדה זהות מוצגת הזהות של הסוכן שהוקצתה לו.

gcloud

כדי לראות את Agent Identity, מתארים את הגרסה של השירות:

gcloud beta run revisions describe REVISION_NAME

מחליפים את REVISION_NAME בשם של גרסת השירות.

זהות הסוכן שהוקצתה מוצגת בפלט.

תעסוקה

המסוף

1. נכנסים ל-Cloud Run במסוף Google Cloud :

   כניסה ל-Cloud Run

2. בתפריט הניווט של Cloud Run, בוחרים באפשרות Jobs (משימות) ולוחצים על המשימה הרצויה.

3. לוחצים על הכרטיסייה Executions (הרצות) ובוחרים הרצה.

4. צופים בפרטי ההרצה.

בשדה זהות מוצגת הזהות של הסוכן שהוקצתה לו.

gcloud

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

gcloud beta run jobs executions describe EXECUTION_NAME

מחליפים את EXECUTION_NAME בשם של הפעלת העבודה.

זהות הסוכן שהוקצתה מוצגת בפלט.

הצגת סוכן או MCP ב-Agent Registry

כשפורסים משאב Cloud Run באמצעות --functional-type=agent או --functional-type=mcp-server, הוא נרשם אוטומטית במאגר הסוכנים של הארגון.

• סוכנים רשומים בקטלוג הסוכנים (/agents).
• שרתי MCP רשומים בקטלוג שרתי ה-MCP (/mcpServers).

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

המאמרים הבאים

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