המדריך הזה יעזור לכם לנפות באגים ולפתור בעיות בקישוריות ל-Gemini Enterprise Agent Platform, במיוחד כשאתם משתמשים ב-Agent Gateway, בזהות סוכן, במדיניות של ניהול זהויות והרשאות גישה (IAM) ובמתן הרשאות באמצעות Service Extensions.
פתרון בעיות באמצעות המיומנות "פתרון בעיות בפלטפורמת Agent"
כדי לאבחן בעיות בקישוריות, בהרשאה ובאתחול באופן אינטראקטיבי באמצעות עוזר AI לתכנות, אפשר להתקין את היכולת agent-platform-troubleshooting ממאגר היכולות של הסוכן Cloud de Confiance by S3NS .
היכולת הזו מציידת את סוכני ה-AI בתרחישי אבחון, מסנני יומנים ושלבים לפתרון בעיות שספציפיים לתחום, בכל רכיבי Agent Platform, כולל:
- שלילת יציאה מ-Agent Gateway: אבחון
403 Forbiddenשגיאות שנקלטו על ידי השער ואימות החלטות הרשאה של IAP. - כשלים בהפעלה של Agent Runtime: זיהוי תפקידים חסרים (כמו
roles/browserאוresourcemanager.projects.get) וחריגים של bootstrap. - בעיות ביעד של Agent Registry: אימות של רשומות שירות, ממשקי נקודות קצה והגדרות מאוחדות של Google APIs.
- מדיניות גישה ב-IAM: אימות של קישורי מדיניות גישה מאוחדת (UAP), ביטויי תנאים והיקף של מדיניות לקביעת הגישה לישויות מורשות (PAB).
- מהימנות של קונטיינרים: אבחון של שגיאות באישור TLS ובחבילת לחיצת היד עבור קונטיינרים בהתאמה אישית (BYOC) או רשויות אישורים פרטיות (CA).
כדי להתקין את המיומנות בסביבת הנציג, מריצים את הפקודה הבאה:
npx skills add https://github.com/google/skills --skill agent-platform-troubleshooting
תהליך הבקשה ליציאה
פלטפורמת הסוכנים מאמצת מדיניות דחייה כברירת מחדל לכל התנועה היוצאת. כדי שנציג יוכל להתחבר למשאבים חיצוניים, צריך לתת לו גישה באופן מפורש בכל שכבת רשת וזהות. כשה-Agent Gateway מופעל, השער מיירט את כל הבקשות מהסוכן ומחיל את כללי המדיניות שהוגדרו.
כדי שהבקשה תאושר, היא צריכה לעמוד בכל התנאים הבאים:
- מדיניות גישה של IAM: לזהות הסוכן שהוקצתה לסוכן צריכה להיות הרשאת
iap.resources.egressViaIAPלמשאב היעד, ישירות או דרך קבוצת משתמשים. לפרטים נוספים, קראו את המאמר בנושא יצירת מדיניות של סוכני IAM. איך פותרים בעיות שקשורות למדיניות של IAP - Agent Registry: מומלץ לרשום יעדים ב-Agent Registry כדי לאכוף מדיניות גישה פרטנית לכל משאב ובקרות ברמת הכלי. אם הסוכן מנסה להגיע ליעד שלא רשום, צריך להעניק את ההרשאה
iap.resources.egressViaIAPלזהות הסוכן על ידי הגדרת מדיניות עבור נקודת קצה לא רשומה. - Agent Gateway: השער חייב להיות משויך למדיניות הרשאה שמטרגטת אותו באופן מפורש. כברירת מחדל, השער משתמש ב-IAP וב-Model Armor כדי לאבטח את הבקשות.
- הקצאת הרשאות באמצעות Service Extensions: אתם יכולים להקצות החלטות לגבי הרשאות למנוע הרשאות בהתאמה אישית באמצעות Service Extensions. בהתאם למדיניות ההרשאות שהוגדרה, אחד או יותר ממנועי ההרשאות האלה יאשרו או ידחו את הבקשה.
בעיות נפוצות
כדי לפתור בעיות ב-Agent Gateway, כדאי לעיין בבעיות הנפוצות הבאות ובפתרונות שלהן.
שגיאות במהלך ההפעלה של Agent Runtime
אם מופעים של Agent Runtime לא מצליחים להתחיל או להיפרס, יכול להיות ש-IAP חוסם תנועה פנימית או שחסרים לסוכן התפקידים הבסיסיים שהוא צריך כדי לבצע אתחול.
מוודאים ש-IAP לא חוסם קריאות לשירותים פנימיים
סימפטום: שגיאות
403 Forbiddenבמהלך ההפעלה.הסיבה: Agent Gateway משתמש במדיניות ברירת מחדל של דחייה לכל התנועה. לכן, כש-IAP במצב אכיפה, הוא חוסם קריאות גם לשירותים פנימיים (כמו
aiplatformאוlogging) אלא אם הם רשומים ולאגנט יש את הרשאות ה-IAM הנדרשות.תיקון: מעבירים באופן זמני את IAP למצב פרימטר לבדיקות כדי לראות אילו חיבורים נכשלים בלי לחסום את ההפעלה, או שולחים שאילתה ל-Cloud Logging כדי לזהות את שמות המארחים החסומים המדויקים. אחרי שמזהים את שמות המארחים של שירות היעד, רושמים אותם במרשם הסוכנים ומעניקים לסוכן את ההרשאה
iap.resources.egressViaIAP.כדי למצוא שמות מארחים ספציפיים שחסומים באמצעות Cloud Logging, מריצים את השאילתה הבאה ב-Logs Explorer:
resource.type="networkservices.googleapis.com/Gateway" resource.labels.gateway_type="SECURE_WEB_GATEWAY" httpRequest.status=403
בודקים את השדות
httpRequest.requestUrlאוjsonPayload.authzPolicyInfoבתוצאות כדי למצוא את שמות המארחים של היעד.שירותים פנימיים נפוצים שעשויים לדרוש רישום במהלך ההפעלה כוללים:
- פלטפורמת הסוכנים (מנוע חשיבה רציונלית וסשנים):
https://REGION-aiplatform.mtls.googleapis.com - מנהל המשאבים:
https://cloudresourcemanager.mtls.googleapis.comו-https://cloudresourcemanager.mtls.googleapis.com/ - Google Cloud Observability (אם מופעל):
https://telemetry.mtls.googleapis.com/ - Cloud Logging (אם מופעל):
https://logging.googleapis.com/ - Cloud Monitoring:
https://monitoring.googleapis.com/ו-https://monitoring.mtls.googleapis.com/ - Cloud Trace:
https://cloudtrace.googleapis.com/ו-https://cloudtrace.mtls.googleapis.com/ - Secret Manager:
https://secretmanager.googleapis.com/ו-https://secretmanager.mtls.googleapis.com/
- פלטפורמת הסוכנים (מנוע חשיבה רציונלית וסשנים):
מוודאים שלסוכן יש את התפקידים הבסיסיים הנדרשים
תסמינים: ביומני
aiplatform.googleapis.com/reasoning_engine_stderrמופיעות שגיאות כמוgoogle.api_core.exceptions.Unknown: NoneאוFailed to convert project number to project ID. השגיאה מופיעה במהלך ההפעלה של Reasoning Engine.הסיבה. לזהות הסוכן אין את ההרשאה
resourcemanager.projects.getשנדרשת כדי לזהות את שם הפרויקט במהלך האיניציאליזציה.תיקון. מוודאים שלסוכן (או לקבוצת המנהלים שלו) יש את ההרשאות הנדרשות לקריאת הגדרת זמן הריצה שלו. התפקידים הבאים נדרשים:
-
roles/aiplatform.agentDefaultAccess: תפקיד ברירת המחדל של הנציג. -
roles/aiplatform.user: נדרש כדי להפעיל את הסוכן. -
roles/agentregistry.viewer: נדרש כדי להציג משאבים רשומים. -
roles/logging.logWriterו-roles/monitoring.metricWriter: נדרשים לצורך ניראות. -
roles/browser: נדרש כדי להפעיל אתresourcemanager.projects.getבמהלך האתחול של ה-SDK.
כדי לבדוק את התפקידים שהוקצו לזהות של הנציג, מריצים את הפקודה הבאה:
gcloud projects get-iam-policy PROJECT_ID \ --flatten="bindings[].members" \ --filter="bindings.members:AGENT_IDENTITY_PRINCIPAL"
מחליפים את מה שכתוב בשדות הבאים:
-
PROJECT_ID: מזהה הפרויקט ב- Cloud de Confiance . -
AGENT_IDENTITY_PRINCIPAL: חשבון המשתמש של Agent Identity. בפורמט:principal://TRUST_DOMAIN/resources/SERVICE/RESOURCE_PATH
במאמר שימוש בזהות סוכן עם Agent Runtime מוסבר איך מקצים תפקידים.
-
403 Forbidden שגיאות
אם נתקלים בשגיאה 403 Forbidden, צריך לוודא שהיא קשורה לתעבורת הנתונים היוצאת של Agent Gateway. הנה דוגמה להודעת שגיאה לגבי תעבורת יציאה:
{"code": 403, "message": "403 Forbidden. {'message': 'Egress request is not authorized.', 'status': 'Forbidden'}"}
מריצים שאילתה ביומני הסוכן ב-Logging כדי למצוא את השיחות הספציפיות שנכשלו:
resource.type="aiplatform.googleapis.com/ReasoningEngine" resource.labels.location="LOCATION" resource.labels.reasoning_engine_id="AGENT_ID" textPayload:"403"
מחליפים את מה שכתוב בשדות הבאים:
-
LOCATION: האזור שבו הסוכן נפרס, לדוגמה,us-central1. -
AGENT_ID: המזהה של הסוכן (מנוע הנימוקים).
מחפשים את ההודעה Egress request is not authorized ברשומה ביומן textPayload. אם שגיאת 403 מכילה טקסט אחר, יכול להיות ששירות היעד דוחה את הקריאה ישירות, ולא Agent Gateway.
אפשר גם להציג יומנים של תנועת נתונים יוצאת, כולל דחיות של 403, באמצעות לוח הבקרה המובנה של יכולת התצפית.
יעדים עם חתימה עצמית או CA פרטי לא מצליחים להתחבר
- תיאור הבעיה: הסוכן לא מצליח להתחבר ליעדים שמציגים אישורים בחתימה עצמית או אישורים שהונפקו על ידי רשות אישורים פרטית.
- הסיבה: כברירת מחדל, Agent Gateway סומך רק על אישורים שהונפקו על ידי רשויות אישורים (CA) מהימנות שזמינות לציבור. כדי להתחבר ליעדים שמשתמשים ב-CA פרטיים או באישורים עם חתימה עצמית, נדרשת הגדרה נוספת.
- פתרון: כדי להתחבר ליעדים באמצעות רשויות אישורים פרטיות או אישורים בחתימה עצמית, צריך להגדיר נקודות אמון מותאמות אישית של TLS באמצעות ההגדרה
tlsConfigבתבנית קישוריות של סוכן.
החיבור של סוכן שפריסתו בוצעה באמצעות מאגר תגים מותאם אישית (BYOC) אל Agent Gateway נכשל
- הסימפטום: סוכן BYOC לא מצליח ליצור חיבורים כשניתוב השיחות מתבצע דרך Agent Gateway. יכול להיות שיופיעו ביומנים שגיאות של TLS handshake או של אימות אישורים.
- הגורם: מאגר התגים המותאם אישית של הסוכן לא מהימן על ידי רשות האישורים של Agent Gateway.
- פתרון: מוודאים שהוספתם את אישור הבסיס של Agent Gateway למאגר הרשויות המנפיקות אישורים (CA) של הקונטיינר. מידע נוסף זמין במאמר הגדרת סוכנים מותאמים אישית של מאגרי תגים (BYOC) עבור Agent Gateway.
קישור המדיניות נכשל או מחקה דחייה של ניהול גישה
- הסימפטום: הגדרות של שיוך מדיניות נכשלות, מוצגת לך בקשה אינטראקטיבית להזנת
etagכשמשייכים מדיניות, או שבקשות נכשלות עם שגיאת דחייה שגויה של ניהול הרשאות (למשל 'היעד הלא רשום נדחה בצורה נכונה'). - הסיבה: Identity-Aware Proxy API (
iap.googleapis.com) מושבת בפרויקט. - תיקון: מפעילים את Identity-Aware Proxy API.
כשלים בניהול של Agent Gateway באמצעות איחוד שירותי אימות הזהות של כוח העבודה
יכול להיות שתיתקלו בבעיה הזו אם אתם מנהלים את Agent Gateway במסוףCloud de Confiance או משתמשים ב-CLI של gcloud כשאתם מאומתים באמצעות איחוד שירותי אימות הזהות של עובדים (WIF).
במסוף מוצגות שגיאות גנריות של טעינה או יצירה, כמו השגיאות הבאות:
- "הייתה שגיאה במהלך הטעינה..."
- "השרת לא הצליח לבצע את מה שביקשת"
- "יצירת שער לסוכן נכשלה"
- "הטעינה נכשלה"
בנוסף, פקודות gcloud (כמו gcloud network-services agent-gateways import) עשויות להחזיר שגיאה פנימית, כמו
error 13: an internal error has occurred.
כדי לפתור את הבעיה, צריך לבצע אימות באמצעות חשבון Google רגיל שמנוהל דרך Cloud Identity או Google Workspace, שיש לו את ההרשאות הנדרשות, כמו roles/networkservices.admin.
בגרסת טרום-השקה (Preview) יש תמיכה חלקית בזהויות מאוחדות בשירותי Agent Platform Governance ו-Gateway. הקצאת תפקידי IAM רחבים יותר לחשבון משתמש מאוחד לא פותרת את הבעיה.
ניפוי באגים בתהליך העבודה
אם אחד מהתנאים שמתוארים בקטע על תהליך הבקשה ליציאה לא מתקיים, יכול להיות שהבקשות שלכם ייחסמו.
בדיקת ההחלטה של ה-IAP
כדי לצמצם את החיפוש ביומן להחלטות לגבי יציאה מ-IAP, מריצים את השאילתה הבאה ב-Logging:
protoPayload.serviceName="iap.googleapis.com" protoPayload.authorizationInfo.permission="iap.resources.egressViaIAP" protoPayload.metadata.mcp_attributes.base_protocol_method="true"
אם אתם לא רואים רשומה תואמת ביומן של IAP, יכול להיות שהשער דחה את הבקשה לפני ש-IAP העריך אותה. עוברים לשלב הבא.
אם מופיעה רשומה תואמת ביומן, בודקים את השדות הבאים:
-
protoPayload.authorizationInfo[].granted: מציין אם הבקשה אושרה (true) או נדחתה (false). -
protoPayload.authenticationInfo.principalSubject: מזהה ה-SPIFFE או הזהות של מבצע הקריאה ב-principal://.... מוודאים שהפרטים האלה תואמים לזהות של הסוכן. -
protoPayload.authorizationInfo[].resource: משאב היעד הרשום שאליו הופנתה הקריאה. -
labels."iap.googleapis.com/audited_resource_name": אם הערך הואunregisteredResource, שם המארח של היעד לא רשום. רושמים את שם המארח של היעד במאגר הסוכנים ומוודאים שלסוכן יש הרשאהiap.resources.egressViaIAPליעד הזה. - מצב אכיפה: בודקים את מצב האכיפה של הבקשה. כדי לסנן בקשות להרצת בדיקה, אפשר להוסיף לשאילתה את הערך
protoPayload.metadata.iamEnforcementMode="DRY_RUN". במצבDRY_RUN, IAP מתעד דחיות ביומן אבל לא אוכף אותן. לכן, אם הסוכן נכשל עם שגיאה403במצב הרצה יבשה, סביר להניח שהדחייה נובעת משער היציאה של שער הכניסה או ממשאב היעד.
בדיקת ההחלטה של Agent Gateway
כדי לבדוק איך Agent Gateway העריך את הבקשה, שולחים שאילתה ליומני השער ב-Logging. בדוגמה הזו אנחנו מסננים את היומנים כדי להציג רק שגיאות מסוג 403:
resource.type="networkservices.googleapis.com/Gateway" resource.labels.gateway_type="SECURE_WEB_GATEWAY" resource.labels.location="REGION" resource.labels.gateway_name="AGENT_GATEWAY_NAME" httpRequest.status=403 -httpRequest.requestMethod="CONNECT"
בודקים את השדות הבאים ברשומה התואמת ביומן:
-
jsonPayload.authzPolicyInfo.policies.result: התוצאה הכוללת של ההרשאה,ALLOWEDאוDENIED. httpRequest.requestUrl: שימו לב לכתובת היעד המדויקת שהנציג ניסה להגיע אליה. בשלב הבא, נבדוק אם שם המארח שמשמש את משאב היעד רשום במאגר סוכני המשתמשים.
אימות הרישום של היעד והכיסוי של מדיניות הגישה ב-IAM
כדי לגשת ליעדים, תמיד צריך מדיניות הרשאות ב-IAM שמעניקה את ההרשאה iap.resources.egressViaIAP לזהות הסוכן.
מומלץ לרשום יעדים ב-Agent Registry כדי לאכוף מדיניות גישה פרטנית לכל משאב, וכדי לוודא ששם המארח תואם. אם היעדים לא רשומים, צריך לוודא שמדיניות לגבי נקודות קצה לא רשומות מעניקה לסוכן את ההרשאה הנדרשת.
אם אתם מסתמכים על מדיניות לכל משאב, כל שם מארח של יעד וכל וריאציה של שם המארח שהסוכן מנסה להגיע אליהם צריכים להיות רשומים במאגר הסוכנים. הסיבה לכך היא שממשק API של Google, כמו aiplatform.googleapis.com, יכול לפעול דרך כמה שמות מארחים, בהתאם לגרסת ה-SDK, להגדרת הלקוח האזורי או לשימוש ב-mTLS (לדוגמה, us-central1-aiplatform.googleapis.com או us-central1-aiplatform.mtls.googleapis.com).
מכיוון שהשער מתאים בדיוק לשמות המארחים, אם רושמים aiplatform.googleapis.com אבל הסוכן קורא ל-us-central1-aiplatform.googleapis.com, השער מחשיב את זה כמשאב לא רשום ודוחה את הבקשה.
מריצים את הסקריפט לדוגמה הבא כדי להציג את הרשומות במרשם לפי סוג המשאב, ובודקים את הרשומות של שם המארח הספציפי שמשמש לקריאה של הסוכן:
HOSTNAME="HOSTNAME" PROJECT_ID="PROJECT_ID" LOCATION="REGION" echo "Checking Endpoints..." gcloud agent-registry endpoints list \ --project="$PROJECT_ID" \ --location="$LOCATION" | grep "$HOSTNAME" echo "Checking MCP Servers..." gcloud agent-registry mcp-servers list \ --project="$PROJECT_ID" \ --location="$LOCATION" | grep "$HOSTNAME" echo "Checking Agents..." gcloud agent-registry agents list \ --project="$PROJECT_ID" \ --location="$LOCATION" | grep "$HOSTNAME"
מחליפים את מה שכתוב בשדות הבאים:
-
HOSTNAME: שם המארח של היעד שהסוכן מנסה להגיע אליו, לדוגמהus-central1-aiplatform.mtls.googleapis.com. -
PROJECT_ID: מזהה הפרויקט ב- Cloud de Confiance . -
REGION: המיקום של משאבי Agent Registry ו-Agent Gateway, לדוגמהus-central1.
פלט 1: שם המארח כבר רשום
אם שם המארח קיים ברשומה של מאגר הסוכנים, תראו פלט שדומה לדוגמה הבאה:
Checking Endpoints... url: https://us-central1-aiplatform.mtls.googleapis.com Checking MCP Servers... Checking Agents...
כדי לבדוק אם מדיניות לכל משאב או מדיניות לכלל המאגר מעניקה גישה לזהות הסוכן, עוברים אל אימות של קשרי IAM במשאב היעד.
פלט 2: שם המארח לא קיים במרשם
אם השם המארח לא קיים במרשם, הפלט ייראה כמו בדוגמה הבאה:
Checking Endpoints... Checking MCP Servers... Checking Agents...
אם אתם מתכננים להשתמש בכללי מדיניות לכל משאב או לכל המרשם, קודם רשמו את היעד ב-Agent Registry. אם אתם משתמשים בכללי מדיניות לנקודות קצה לא רשומות, המשיכו לקטע אימות קישורי IAM במשאב היעד.
אימות של קישורי IAM במשאב היעד
מוודאים שלסוכן או לחשבון המשתמש שלו יש הרשאת iap.resources.egressViaIAP ביעד.
אפשר להגדיר את הקישורים למדיניות בשלושה היקפים:
- בכל הרישום: גישה לכל סוכן, שרת MCP ונקודת קצה שרשומים ברישום.
- לכל משאב: גישה מצומצמת. קישור לכל משאב מחליף את הקישור לכלל הרישום עבור אותו משאב ספציפי, במקום להתמזג איתו.
- מדיניות לגבי נקודות קצה לא רשומות: גישה ליעדים שלא רשומים ב-Agent Registry.
אפשר להשתמש באחת מהדוגמאות הבאות כדי לבדוק אם יש קישורים:
כדי לבדוק את קישורי המדיניות של IAM ברמת המרשם, מריצים את הפקודה הבאה:
curl -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \ -d '{}' \ -X POST "https://iap.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/iap_web/agentRegistry:getIamPolicy" \ -H "Content-Type: application/json"כדי לבדוק אם יש קישורי מדיניות IAM לכל נקודת קצה, מריצים את הפקודה הבאה:
export HOSTNAME=HOSTNAME ENDPOINT_ID=$(gcloud agent-registry endpoints list \ --project="PROJECT_ID" \ --location="REGION" \ --filter="interfaces.url:$HOSTNAME" \ --format="value(name.basename())") echo "ENDPOINT_ID=$ENDPOINT_ID" curl -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \ -H "Content-Type: application/json" \ -d '{}' \ -X POST "https://iap.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/iap_web/agentRegistry/endpoints/${ENDPOINT_ID}:getIamPolicy"
מחליפים את
HOSTNAMEבשם המארח של היעד שהסוכן מנסה להגיע אליו, לדוגמה,us-central1-aiplatform.mtls.googleapis.com.כדי לבדוק את קישורי מדיניות IAM לכל שרת MCP, מריצים את הפקודה הבאה:
export MCP_SERVER=MCP_SERVER MCP_SERVER_ID=$(gcloud agent-registry mcp-servers list \ --project="PROJECT_ID" \ --location="REGION" \ --filter="interfaces.url:$MCP_SERVER" \ --format="value(name.basename())") echo "MCP_SERVER_ID=$MCP_SERVER_ID" curl -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \ -H "Content-Type: application/json" \ -d '{}' \ -X POST "https://iap.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/iap_web/agentRegistry/mcpServers/${MCP_SERVER_ID}:getIamPolicy"
מחליפים את MCP_SERVER בכתובת ה-URL של שרת ה-MCP (לדוגמה,
https://example-abc12345-uc.a.run.app/mcp).
בפרטי המדיניות שמוחזרים, מחפשים כריכה עם ההרשאה iap.resources.egressViaIAP שתואמת לזהות של הסוכן או לקבוצת המשתמשים העיקריים שהוגדרה. אם הפלט שמוחזר מכיל את השדה "etag" אבל אין בו קישורים, זה אומר שאין מדיניות IAM.
אם קיים קישור אבל הוא כולל condition, צריך לוודא שביטוי Common Expression Language (CEL) לא מוציא את הסוכן מהכלל. יכול להיות שתנאי שמסנן לפי מאפיין שחסר לסוכן יחריג את הסוכן בלי להציג הודעה.
אם ליעד אין קישור מדיניות תואם שמעניק את ההרשאה iap.resources.egressViaIAP לזהות הסוכן או לקבוצת חשבונות המשתמשים, צריך לתת את ההרשאה באמצעות אחת מאפשרויות המדיניות הבאות:
- מדיניות ברמת המרשם (מומלץ): מגדירים מדיניות של סוכן למרשם כדי לתת גישה לכל המשאבים שרשומים ב-Agent Registry.
- מדיניות לכל משאב (שרת או נקודת קצה של MCP): רושמים את שרת ה-MCP או רושמים את נקודת הקצה ב-Agent Registry, ויוצרים מדיניות של סוכן לשרת MCP או מדיניות של סוכן לנקודת קצה.
- מדיניות לגבי נקודות קצה לא רשומות: הגדרת מדיניות לגבי נקודות קצה לא רשומות כדי להעניק גישה בלי לרשום את המשאב.
בדיקת מדיניות ההרשאות והתוסף
בקטע הזה אנחנו מוודאים שיש מדיניות הרשאה שמטרגטת באופן מפורש את Agent Gateway שמשויך לסוכן.
מקבלים את הפרטים של תוסף ההרשאה שמשויך לשער ומאשרים שהתוסף שבו אתם משתמשים מוגדר כמו שציפיתם.
gcloud service-extensions authz-extensions describe AUTHORIZATION_EXTENSION_NAME \ --location=LOCATION \ --project=PROJECT_ID
מחליפים את AUTHORIZATION_EXTENSION_NAME בשם של התוסף שמשויך לשער. אם אתם לא יודעים את שם התוסף, אתם יכולים לעבור לדף הפרטים של השער במסוף Cloud de Confiance Cloud de Confiance ולרשום את הערך של השדה Extension name בקטע Service Extensions.
מוודאים שמדיניות ההרשאות מטרגטת באופן מפורש את משאב השער ומקשרת לאותו תוסף הרשאות. אפשר לעבור לדף הפרטים של השער במסוףCloud de Confiance ב- Cloud de Confianceולבדוק את הערך של השדה Policy name בקטע Service Extensions.
אם אין מדיניות שמכוונת לשער, או אם המיפוי בין השער למדיניות שגוי, תוסף ההרשאה לא יופעל.
בדיקת המדיניות לקביעת גבול הגישה לחשבונות משתמשים (PAB)
המדיניות לקביעת גבול הגישה לחשבונות משתמשים (PAB) מקבלת עדיפות על פני כללי מדיניות ההרשאה של IAM. המשמעות היא שגם אם הגדרתם נכון את כל הקישורים ב-IAM, בקשה תיכשל אם יש מדיניות פעילה של גבולות גישה לחשבון משתמש שמוציאה את משאב היעד מההיקף של הסוכן.
כדי להציג את רשימת הכללים ברמת הארגון, מריצים את הפקודה:
gcloud iam principal-access-boundary-policies list \ --organization="ORGANIZATION_ID" \ --location=global
כדי למצוא כללי מדיניות שקשורים לקבוצת חשבונות המשתמשים של הסוכן, מריצים את הפקודה:
gcloud iam policy-bindings search-target-policy-bindings \ --project="PROJECT_ID" \ --target="PRINCIPAL_SET"
מחליפים את מה שכתוב בשדות הבאים:
-
ORGANIZATION_ID: מזהה הארגון ב- Cloud de Confiance . -
PROJECT_ID: מזהה הפרויקט ב- Cloud de Confiance . PRINCIPAL_SET: קבוצת המשתמשים העיקרית של זהות הסוכן.
אם קיים קישור, בודקים את השדה details.rules[].resources[] כדי לוודא שהיעד נמצא בהיקף של הסוכן.
בדיקת קישורים של חשבון משתמש לעומת קבוצת חשבונות משתמשים
אם ההרשאות לא פועלות באופן עקבי או נכשלות באופן בלתי צפוי, יכול להיות שהבעיה קשורה לאופן שבו מוגדרת זהות הקבוצה של הסוכן (קבוצת חשבונות המשתמשים). יכול להיות שהרשאות שמבוססות על קבוצת משתמשים לא יפעלו מהסיבות הבאות:
- עיכובים בסנכרון: כשמוסיפים זהות לקבוצה, יכול להיות שיעברו כמה דקות עד שהמערכת של IAM תתעדכן ותזהה את החבר החדש.
- מאפיינים חסרים: אם חברות בקבוצת מנהלים דורשת מאפיינים מסוימים, הזהות של הסוכן חייבת לכלול את המאפיינים האלה בדיוק (לדוגמה, תוויות של מחלקה או צוות). אם הזהות לא כוללת את המאפיינים האלה, יכול להיות שהסוכן יוחרג מהקבוצה בלי שתהיה לכך הודעה.
כדי לבדוק אם הבעיה קשורה לחברות בקבוצה, צריך להעניק הרשאות ישירות לסוכן הספציפי על ידי הוספת קשר principal:// ישיר למשאב המושפע. אם הסוכן מתחבר בהצלחה באמצעות הקישור הישיר, סביר להניח ששורש הבעיה הוא חוסר התאמה במאפיינים או עיכוב בסנכרון עם קבוצת חשבונות המשתמשים.
כדי לפתור את הבעיה, צריך לאמת ולתקן את מאפייני הזהות של הסוכן, או להשתמש בקשרי principal:// ישירים.
המאמרים הבאים
Codelab: Govern agentic workloads with Agent Platform
איך שולטים בעומסי עבודה אקטיביים באמצעות Agent Gateway ב-Gemini Enterprise Agent Platform.