כדי לרשום ולנהל סוכנים במרשם הסוכנים, צריך לעבוד עם ארבע שכבות ארכיטקטוניות. כל שכבה משתמשת במנגנון ספציפי של מתן שמות, זיהוי או ניתוב:
- מזהי רישום (מזהי סוכן, מזהי שרת MCP ומזהי נקודת קצה): שמות משאבים אחידים (URN) לוגיים וקבועים שמשמשים למעקב אחר מלאי, לאיתור רישום ולסינון. מספרי ה-URN האלה לא משמשים לניהול בזמן ריצה.
- שמות משאבים:Google Cloud
שמות משאבים (
registryResourceאוname) ייחודיים באופן גלובלי שנוצרים במהלך ההרשמה ומשמשים לכללי ניתוב של Agent Gateway, למדיניות יציאה של שרת proxy לאימות זהויות (IAP) ולקישורים למדיניות של ניהול זהויות והרשאות גישה (IAM). - חשבונות משתמשים של סוכנים: זהויות IAM שניתנות לאימות, כמו מזהי SPIFFE לסוכנים שפועלים ב-Google Cloud או חשבונות שירות לסוכנים חיצוניים, שמשמשים לאימות המתקשר, להרשאה ולרישום ביומן הביקורת.
- הפניות בזמן ריצה: נתיבי מחשוב או תשתית (
RuntimeReference) שמשמשים לשאילתות טופולוגיה ולהתאמה של תעבורת נתונים יוצאת.
בטבלה הבאה מוצגות השוואות בין השכבות השונות, המטרה העיקרית של כל שכבה, תפקיד השליטה במורד הזרם והתחביר:
| שכבה | המטרה העיקרית | תפקיד ניהול | תחביר |
|---|---|---|---|
| מזהים של Agent Registry (מזהים של Agent, שרת MCP או נקודת קצה) |
גילוי יציב של רישום, תיוג מטא-נתונים וחיפוש. | הן לא ניתנות לשינוי ולא משמשות לניהול. |
|
| שם משאב | זיהוי משאב היעד לצורך אכיפת מדיניות. | נדרש על ידי מדיניות ומשמש לניתובים של Agent Gateway ולקישורי IAP. |
|
| חשבון משתמש של סוכן | אימות של המתקשר, הרשאה ורישום ביומן ביקורת. | נאכף על ידי IAM. |
|
| הפניה בזמן ריצה | ניתוב פיזי של מחשוב והתאמה של תעבורה יוצאת. | הערכה בשאילתות טופולוגיה וב-Agent Gateway כדי להתאים לתנועת רשת. |
agentregistry.googleapis.com/system/RuntimeReference
שכולל את הנתיב של המחשוב או התשתית בתור
uri: "RUNTIME_URI"
|
מזהים של רשומות
מזהה רישום הוא שם משאב אחיד (URN) ייחודי וגלובלי שאי אפשר לשנות, שמוקצה על ידי Agent Registry לרכיב רשום. ה-URN הזה מספק הפניה יציבה לצרכנים ולסוכני תזמור כדי לגלות, לסנן ולחפש רכיבים במאגר הסוכנים, והוא נשאר קבוע ללא קשר להעברות של תשתית בסיסית או לעדכוני קוד.
מזהים של מרשם הם מספרי URN לוגיים שמשמשים אך ורק לגילוי מרשם ולהערות של מטא נתונים. הם שונים מזהויות אבטחה בזמן ריצה וממשאבים, ואי אפשר להשתמש בהם בקישורים של מדיניות IAM, בכותרות הרשאות או בכללי ניתוב של Agent Gateway.
מאגר סוכנים משתמש בשלושה סוגים של מזהים:
- מזהים של סוכנים (
agentId) - מזהים של שרתי MCP (
mcpServerId) - מזהים של נקודות קצה (
endpointId)
מזהים של סוכנים
מאגר הסוכנים מקצה מזהה סוכן (agentId) לכל הסוכנים הרשומים, כולל סוכנים שמנוהלים על ידי Google וסוכנים חיצוניים או מותאמים אישית. כדי לנהל תקשורת מאובטחת שמוגדרת על ידי מדיניות עבור סוכן, צריך להשתמש בישות מורשית של סוכן ולא במזהה הסוכן.
מאגר הסוכנים יוצר באופן אוטומטי מזהים של סוכנים במהלך הטמעת הנתונים. המבנה המדויק של ה-URN תלוי בסביבת המחשוב שבה הסוכן נפרס:
- Agent Runtime on Gemini Enterprise Agent Platform:
urn:agent:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:REGION:aiplatform:reasoningEngines:AGENT_ID - שירותי Cloud Run:
urn:agent:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:REGION:run:services:SERVICE_NAME - משימות Cloud Run:
urn:agent:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:REGION:run:jobs:JOB_NAME - פריסות של GKE:
urn:agent:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:REGION:container:clusters:CLUSTER_NAME:k8s:namespaces:NAMESPACE:apps:deployments:DEPLOYMENT_NAME - Gemini Enterprise:
urn:agent:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:global:discoveryengine:collections:default_collection:engines:ENGINE_ID:assistants:default_assistant:agents:AGENT_ID - Google Workspace:
urn:agent:googleapis.com:locations:global:workspaceagent:workspaceagent--a2a - סוכנים שנרשמו באופן ידני:
urn:agent:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:LOCATION:agentregistry:services:AGENT_ID
מזהי שרת ה-MCP
מזהה שרת MCP (mcpServerId) הוא מזהה רישום שמשמש לגילוי שרת MCP והכלים שלו ב-Agent Registry.
שרתי MCP מגיבים רק לבקשות ואין להם חשבון ראשי ב-IAM. כשסוכן מפעיל כלים בשרת MCP, הגישה מאושרת באמצעות חשבון המשתמש של הסוכן שמבצע את הקריאה.
הפורמט של ה-URN תלוי בשאלה אם השרת הוא שירות בניהול Google או שרת חיצוני רשום:
- שרתי MCP של Google ו Google Cloud שרתי MCP מרוחקים:
urn:mcp:googleapis.com:projects:PROJECT_NUMBER:locations:global:SERVER_ID - שרתי MCP שנרשמו באופן ידני:
urn:mcp:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:LOCATION:agentregistry:services:SERVER_ID
מזהים של נקודות קצה
מזהה נקודת קצה (endpointId) הוא מזהה רישום שמוקצה לנקודת קצה רשומה לצורך גילוי יעדי API.
פורמט ה-URN של נקודות קצה שנרשמו באופן ידני הוא
urn:endpoint:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:LOCATION:agentregistry:services:ENDPOINT_ID.
שמות המשאבים
כשרושמים סוכן, שרת MCP או נקודת קצה ב-Agent Registry, תהליך הרישום יוצר Google Cloud שם משאב סטנדרטי בפורמט של נתיב URI היררכי:
- סוכנים:
projects/PROJECT_NUMBER/locations/LOCATION/agents/agentregistry-ID - שרתי MCP:
projects/PROJECT_NUMBER/locations/LOCATION/mcpServers/agentregistry-ID - נקודות קצה:
projects/PROJECT_NUMBER/locations/LOCATION/endpoints/agentregistry-ID
כשיוצרים משאב Service שאפשר לכתוב בו, או בודקים אותו, למשל על ידי הפעלת הפקודה gcloud agent-registry services describe, שם המשאב הזה מוחזר בשדה registryResource לקריאה בלבד. כשמבצעים שאילתה או בודקים את המשאב Agent, McpServer או Endpoint לקריאה בלבד שמתקבל, למשל באמצעות הפקודה gcloud agent-registry agents describe, שם המשאב הזה מוחזר בשדה הסטנדרטי name.
אפשר להשתמש בשמות משאבים כדי לקשור מדיניות, לנתב תעבורת רשת ולהגדיר אמצעי בקרה לגישה. ממשקי ניהול במורד הזרם, כולל כללי ניתוב של Agent Gateway, מדיניות יציאה של IAP ומדיניות משאבים של IAM, מבצעים הערכה מול שם המשאב הזה. הם לא מקבלים URN ממזהים של רישום, כמו מזהים של סוכנים, מזהים של שרתי MCP או מזהים של נקודות קצה.
אם משתמשים ב-URN של מזהה רישום בהתקשרות למדיניות או בכלל מסלול במקום בשם המשאב, ה-API מחזיר שגיאה מסוג NOT_FOUND: Requested entity was not found.. אם נתקלתם בשגיאה הזו כשניסיתם להגדיר מדיניות ניהול, בדקו את הדברים הבאים:
- סטטוס הרישום: מוודאים שהסוכן, שרת ה-MCP או נקודת הקצה של היעד רשומים ב-Agent Registry במיקום הצפוי.
- פורמט המזהה: מוודאים שבהגדרת הקישור של המדיניות או בכלל הניתוב מצוין שם המשאב הרגיל (
projects/PROJECT_NUMBER/locations/LOCATION/.../agentregistry-ID) ולא מזהה הרישום URN.
Agent principals
חשבון משתמש של סוכן הוא זהות האבטחה של הסוכן ב-IAM. בדומה למשתמש או לחשבון שירות, לסוכן יש חשבון משתמש שמשמש אותו להחזקת הרשאות ולקריאה לשירותים במורד הזרם. כשמגדירים מדיניות IAM, משתמשים במחרוזת של חשבון המשתמש של הסוכן כדי להעניק או להגביל גישה.
במאגר הסוכנים, האופן שבו סוכן מזוהה כגורם מרכזי תלוי במקום שבו הוא פועל:
- סוכנים שפועלים בתשתית Google Cloud : בסביבות זמן ריצה מנוהלות כמו Agent Runtime ב-Gemini Enterprise Agent Platform, Google Cloudמוקצה באופן אוטומטי Workload Identity בפורמט של מזהה SPIFFE, שמקושר ישירות לסביבת זמן הריצה של הסוכן. כשמפנים לזהות הזו במדיניות ובהתחייבויות של IAM, צריך להשתמש בפורמט המחרוזת של חשבון ראשי או של קבוצת חשבונות ראשיים ב-IAM, ולא בסכימת ה-URI של SPIFFE. שימוש במחרוזת SPIFFE לקישור מדיניות IAM מחזיר שגיאת
INVALID_ARGUMENT. - סוכנים שפועלים מחוץ ל- Google Cloud: סוכנים חיצוניים או סוכנים שפועלים במערכות המקומיות בארגון צריכים לאחד את הזהות החיצונית שלהם באמצעות איחוד שירותי אימות הזהות של עומסי עבודה או להשתמש בחשבון שירות רגיל כדי ליצור אינטראקציה עם משאבי Google Cloud . אחרי האימות, מחרוזת הזהות המאוחדת של Workload Identity או כתובת האימייל של חשבון השירות משמשות כישות מורשית של הסוכן במדיניות IAM.
בסוכנים שפועלים ב- Google Cloud, מכיוון שהגורם המורשה של הסוכן המנוהל קשור ישירות למשאב החישוב של זמן הריצה של הסוכן, מחרוזת הגורם המורשה כוללת את הנתיב המלא למשאב החישוב הבסיסי הזה.
IAM תומך בניהול גישת סוכנים בהיקפים הבאים:
- מופע מנוע יחיד: נותן הרשאות לפריסת סוכן ספציפית. לדוגמה, מופע יחיד של Agent Runtime מיוצג באמצעות מחרוזת אחת של חשבון משתמש:
principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/REGION/reasoningEngines/REASONING_ENGINE_ID - היקף הפרויקט: מעניק הרשאות לכל מנועי ההסקה שפועלים בתוך פרויקט ספציפי באמצעות קבוצת משתמשים:
principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER - היקף ההרשאות בכל הארגון: מתן הרשאות לכל הסוכנים בכל הארגון באמצעות תו כללי לחיפוש של קבוצת חשבונות משתמשים:
principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/*
כשמציגים את הפרטים של סוכן, המאפיין של ישות מורשית של סוכן מוצג בפלט בלבד ב-Agent Registry.
מקורות מידע בנושא זמן ריצה
הפניה לזמן ריצה מצביעה על תשתית המחשוב הבסיסית שבה הקוד של סוכן, שרת MCP או נקודת קצה פועל. לדוגמה, הפניה בזמן ריצה יכולה להצביע על מנוע חשיבה רציונלית של Agent Runtime, על פריסת GKE או על שירות Cloud Run.
מחרוזת החשבון הראשי של הסוכן כוללת את נתיב ההפניה של זמן הריצה, שקושר את ההרשאות ב-IAM ישירות למקום שבו הסוכן פועל. אם רושמים סוכן בפרויקט אחר מזה שבו הוא נפרס, ההפניה בזמן הריצה מצביעה על הפרויקט שמארח את עומס העבודה הבסיסי.
ב-Agent Registry API, ההפניה לזמן הריצה מיוצגת על ידי המאפיין agentregistry.googleapis.com/system/RuntimeReference, שמכיל את הנתיב של המחשוב או התשתית בשדה uri. אפשר לראות את מאפיין הפלט בלבד הזה כחלק מפרטי הסוכן, או להשתמש בו כדי לשלוח שאילתות לגבי זרימות תנועה ויחסים בתרשים הטופולוגיה.
המאמרים הבאים
- מידע נוסף על תפקידים והרשאות
- ניהול סוכנים ובדיקתם.
- הסבר על מודל הנתונים של Agent Registry
- מושגי מפתח כלליים