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

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

נכנסים לחשבון 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.

Install the Google Cloud CLI.

If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

To initialize the gcloud CLI, run the following command:

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.

Install the Google Cloud CLI.

If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

To initialize the gcloud CLI, run the following command:

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). אחרת, תוכלו לקבל את ההרשאה הזו דרך התפקיד 'אדמין בממשק 'שימוש בשירות'' (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)
• כדי לנהל את המשאבים של מרכז האפליקציות, צריך אחד מהדברים הבאים:
  • אדמין ב-App Hub (roles/apphub.admin)
  • אדמין של Agent Registry API (roles/apiregistry.admin)
• כדי לפרוס עם זהות ספציפית, אחת מהאפשרויות הבאות:
  • משתמש בחשבון שירות ב-IAM (roles/iam.serviceAccountUser)
  • אדמין של חשבון שירות ב-IAM (roles/iam.serviceAccountAdmin)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• כדי לעדכן שירות קיים לשימוש בזהות סוכן:

  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

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

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).

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

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

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