פתרון בעיות שקשורות למאגר הסוכנים

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

חרגת מהמכסה לקצב הגשת בקשות ל-API

השגיאה הבאה מתרחשת אם חורגים ממגבלת קצב הבקשות כשמקיימים אינטראקציה עם Agent Registry API או כשמנווטים במהירות ב-Agent Registry במסוףGoogle Cloud :

429 Too Many Requests

כדי לפתור את הבעיה, צריך להטמיע השהיה מעריכית לפני ניסיון חוזר (exponential backoff) בלקוחות ה-API כדי לנהל את קצב הבקשות. המכסה לקצב הגשת הבקשות שמוגדרת כברירת מחדל ב-Agent Registry API היא 1,200 בקשות לדקה, או 20 שאילתות לשנייה, באופן גלובלי ולכל אזור.

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

שגיאה בגודל המטען הייעודי (payload) במהלך רישום ידני

השגיאה הבאה מתרחשת כשרושמים באופן ידני נציג או שרת MCP עם קובץ מפרט שחורג ממגבלת הגודל:

ה-API דוחה את הבקשה עם שגיאה שמציינת שהמטען הייעודי (payload) גדול מדי.

כדי לפתור את הבעיה, צריך לוודא שגודל הקובץ agent-card.json או toolspec.json קטן מ-10KB. גודל התוכן של AgentSpec ו-McpServerSpec מוגבל ל-10KB. כדי לעמוד במגבלה הזו, אתם יכולים למזער את קובצי ה-JSON, להסיר רווחים מיותרים או לקצר את תיאורי הכלים. למידע נוסף, קראו את המאמר סכימות JSON.

חסרים סוכנים או שרתי MCP אחרי היצירה

השגיאה הבאה מתרחשת אחרי שיוצרים נציג או שרת MCP במוצר נתמך של Google Cloud , כמו Google Workspace או Gemini Enterprise:

המשאב לא מופיע בפלט כששולחים קריאה ל-API של ListAgents או של ListMcpServers.

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

פעולות ממושכות נראות תקועות

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

הפעולה נמשכת זמן רב ונראה שהיא נתקעה.

כדי לפתור את הבעיה, צריך להשתמש בכלי get_operation MCP או בנקודת הקצה ל-API‏ google.longrunning.Operations.GetOperation כדי לדגום את סטטוס הפעולה. כדי ליצור חלק מהסוכנים וה-MCP, צריך להקצות תשתית משמעותית, ולכן יכול להיות שזמן הפעולה הממושכת (LRO) יהיה ארוך – עד 30 דקות. כתוצאה מכך, צריך להגדיר את הגדרות הזמן הקצוב לתפוגה של הלקוח ולדגום את הדגל הבוליאני done כדי לוודא שהפעולה הושלמה.

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

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

ה-API מחזיר מערך ריק או שגיאת גישה, גם אם הקישור קיים.

כדי לפתור את הבעיה, צריך לוודא שלחשבון המשתמש יש את ההרשאות הנכונות לניהול זהויות והרשאות גישה (IAM) במשאב היעד AuthProvider. ה-API מבצע בדיקות IAM מחמירות ומסיר אובייקטים מסוג Binding שמפנים לספקי אימות שלמבצע הקריאה החוזרת אין גישה אליהם. מוודאים שלחשבון המשתמש יש את הגישה הנדרשת לספק האימות ואת התפקיד roles/agentregistry.viewer בפרויקט.

הורדת גרסת המיומנות נכשלת עם השגיאה 302

השגיאה הבאה מתרחשת אם מנסים להוריד מטען ייעודי (payload) של גרסת מיומנות באמצעות ה-API של GetSkillRevision עם הפרמטר של השאילתה ?alt=media, וצד הלקוח ב-HTTP לא עוקב אחרי הפניות אוטומטיות:

{
  "error": {
    "code": 302,
    "message": "Unknown Error.",
    "status": "UNKNOWN"
  }
}

כדי לפתור את הבעיה, ודאו שצד הלקוח ב-HTTP מוגדר לעקוב באופן אוטומטי אחרי הפניות אוטומטיות. כדי להוריד את הארכיון של המיומנות, נקודת הקצה (endpoint) של ?alt=media דורשת הפניה אוטומטית מסוג 302. לדוגמה, אם אתם משתמשים ב-curl, הוסיפו לפקודה את הדגל -L או --location.

אימות גרסת המיומנות נכשל או מציג את המצב FAILED

השגיאה הבאה מתרחשת כשיוצרים גרסה חדשה של מיומנות עם ארכיון ZIP לא תקין:

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

כדי לפתור את הבעיה, צריך לבדוק את יומני האימות או את התוכן של קובץ ה-ZIP:

• מוודאים שארכיון ה-ZIP מכיל קובץ SKILL.md ברמה הבסיסית (root).
• מוודאים שבקובץ SKILL.md יש בלוק YAML front matter תקין, שמוגדרים בו גם name וגם description.
• מוודאים שהמטען הייעודי (payload) של קובץ ה-ZIP לא חורג ממגבלות הגודל: הגודל של הקובץ הדחוס צריך להיות קטן מ-500KB, הגודל הכולל של הקובץ הלא דחוס צריך להיות קטן מ-10MB והגודל של כל קובץ בנפרד צריך להיות קטן מ-1MB.
• מוודאים שהארכיון לא מכיל קישורים סמליים, רכיבים של מעבר בין ספריות כמו .. או נתיבים מוחלטים.

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

השגיאה הבאה מתרחשת אם שולחים שאילתה לרשימות של הסוכנים או השירותים לגבי מיומנויות עצמאיות, למשל על ידי הפעלת gcloud agent-registry services list או gcloud agent-registry agents list:

היכולת העצמאית לא מופיעה בפלט.

כדי לפתור את הבעיה, צריך לשלוח שאילתה לאוסף skills:

• בניגוד לסוכנים, לשרתי MCP ולנקודות קצה שנרשמו באופן ידני, מיומנויות עצמאיות לא משתמשות במשאבי Service שניתנים לכתיבה או במשאבי גילוי של Agent, McpServer או Endpoint. במקום זאת, ב-Agent Registry, מיומנויות עצמאיות מיוצגות ישירות כמשאבי Skill ברמה העליונה וכמשאבי SkillRevision עם גרסאות.
• כדי להציג, לחפש או לבדוק מיומנויות עצמאיות, משתמשים בכרטיסייה Skills במסוףGoogle Cloud , מריצים את gcloud alpha agent-registry skills list או את gcloud alpha agent-registry skills search, או קוראים ל-methods של ה-API בארכיטקטורת REST‏ skills. הוראות מפורטות זמינות במאמרים ניהול מיומנויות וחיפוש מיומנויות עצמאיות.
• כדי לחפש מיומנויות A2A מוטבעות שהוצהרו בכרטיס הסוכן של הסוכן, בודקים את השדה skills במשאב הגילוי Agent באמצעות gcloud agent-registry agents describe או gcloud agent-registry agents search.

שגיאה מסוג "לא נמצאה ישות משאב" כשמנהלים את כללי המדיניות של IAP

השגיאה הבאה מתרחשת כשמשתמשים בפקודות gcloud iap web כדי לנהל את כללי מדיניות התעבורה היוצאת של שרת proxy לאימות זהויות (IAP) במשאבים של Agent Registry:

NOT_FOUND: Requested entity was not found

כדי לפתור את הבעיה, צריך לוודא את הדברים הבאים:

• סטטוס הרישום: מוודאים שרכיב היעד רשום ב-Agent Registry במיקום הצפוי.
• פורמט המזהה: מוודאים שהפקודה או קישור המדיניות מציינים את שם המשאב הרגיל ולא URN של מזהה מרשם.
• דגל המשאב: מוודאים שדגל המשאב שמעבירים אל gcloud iap web תואם לסוג המשאב הבסיסי של הצאצא של Agent Registry:
  • לנקודות קצה (endpoints), כמו ממשקי API חיצוניים או נקודות יציאה של Google API, משתמשים בדגל --endpoint.
  • לשרתי Model Context Protocol, משתמשים בדגל --mcp-server.
  • בשביל סוכנים רשומים, משתמשים בדגל --agent.

בודקים את שם המשאב שמוחזר על ידי gcloud agent-registry endpoints list,‏ gcloud agent-registry mcp-servers list או gcloud agent-registry agents list כדי לוודא ששם המשאב מכיל את הערך /endpoints/,‏ /mcpServers/ או /agents/. אם תעבירו את דגל המשאב הלא נכון, למשל --endpoint במקום מזהה שרת MCP, תופיע השגיאה NOT_FOUND.

ההרשאה נדחתה כשניסית להחיל כללי מדיניות IAM באינטרנט של IAP

השגיאה הבאה מתקבלת כשמחילים או משנים את מדיניות ה-IAM של IAP Web למשאבים של Agent Registry בלי תפקידי האדמין הנדרשים:

ERROR: (gcloud.iap.web.set-iam-policy) PERMISSION_DENIED

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

• מוודאים שלגורם המבקש יש את התפקיד "אדמין מדיניות IAP"‏ (roles/iap.admin) או "אדמין IAM בפרויקט"‏ (roles/resourcemanager.projectIamAdmin) בפרויקט הניהול המרכזי.
• מוודאים שלגורם המבקש יש את ההרשאות iap.web.setIamPolicy ו-resourcemanager.projects.setIamPolicy.

שרת ה-MCP המרוחק לא נמצא במיקום אזורי

השגיאה הבאה מתרחשת אם שולחים שאילתה לשרת MCP של Google או שרת MCP מרוחק Google Cloud שנרשם באופן אוטומטי, או אם מחילים עליו מדיניות תעבורת נתונים יוצאת של IAP, במיקום אזורי כמו us-central1:

הבקשה מחזירה שגיאת NOT_FOUND או רשימה ריקה, גם כשהשירות מספק נקודות קצה אזוריות (REP) או כשתעבורת הנתונים מנותבת דרך Agent Gateway אזורי.

כש-Agent Registry רושם באופן אוטומטי שרת MCP של Google אוGoogle Cloud מרוחק ל-API מופעל, הוא יוצר את המשאב McpServer רק במיקום global, ולא באזורים ספציפיים כמו us-central1. אם השירות מספק נקודות קצה אזוריות, כמו https://SERVICE.REGION.rep.googleapis.com/mcp, ב-Agent Registry מופיעות כתובות ה-URL האזוריות האלה בשדה interfaces של המשאב היחיד global McpServer.

כדי לפתור את הבעיה תוכלו לנסות אחד מהפתרונות הבאים:

• שימוש ב-global לשרתים שרשומים אוטומטית: מציינים את המיקום global כששולחים שאילתה לשרת ב-Agent Registry באמצעות --location=global, או מחילים עליו כללי מדיניות של תעבורת נתונים יוצאת ב-IAP באמצעות --region=global, גם כשהסוכן ששולח את הקריאה מנתב את התנועה דרך שער אזורי.
• רישום באזור מסוים כדי לשמור על מיקום אחסון הנתונים: אם אתם צריכים לשמור את המטא-נתונים של המרשם באזור מסוים, אתם יכולים לפרוס שרתי MCP בהתאמה אישית בסביבות זמן ריצה אזוריות של Cloud Run או של Google Kubernetes Engine (GKE), או לרשום ידנית את שרת ה-MCP ואת כתובת ה-URL של נקודת הקצה האזורית שלו באותו אזור, ואז להחיל את מדיניות ה-IAP באותו אזור. כשה-Agent Gateway פותר כתובת URL של יעד, לרשומות של מרשם אזורי יש קדימות על פני רשומות של global.

שגיאות של חוסר התאמה בין אזורים בהגדרת Model Armor ב-Agent Gateway

השגיאה הבאה מתרחשת כשמגדירים מסנני מדיניות של Model Armor ב-Agent Gateway באזורים לא תואמים:

יצירת מדיניות ההרשאה נכשלת עם שגיאה של חוסר התאמה באזור, או שתעבורת הנתונים שנותבה דרך השער לשרת MCP נכשלת בהערכת המדיניות.

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

• התאמה בין האזורים של Agent Gateway ושל Model Armor: ודאו ש-Agent Gateway, התבניות של Model Armor, התוסף שמפנה לבדיקת הרשאות והמדיניות נמצאים כולם באותו אזור, למשל us-central1.
• ניתוב לשרתי MCP אזוריים או של global: לא צריך לרשום מחדש שרתי MCP של global באזור מסוים רק כדי להשתמש ב-Model Armor. מכיוון שהגנה מוגברת על המודל בודקת את המטען הייעודי (payload) של הבקשות והתגובות בשער האזורי, שער אזורי יכול לבדוק ולנהל את התנועה שמנותבת לשרתי MCP שרשומים במיקום global וגם ליעדים אזוריים.
• התאמת קישורי היציאה של IAP למיקום הרישום של היעד: החלת קישור הרשאת היציאה של IAP במיקום שבו רשום משאב היעד של McpServer. משתמשים ב-global לשרתי MCP מרוחקים שרשומים באופן אוטומטי, או באזור הספציפי לשרתי MCP שרשומים לפי אזור.

כשלים בגישה ל-Agent Registry באמצעות איחוד שירותי אימות הזהות של כוח העבודה

השגיאות הבאות מתקבלות כשניגשים ל-Agent Registry במסוףGoogle Cloud או משתמשים ב-Google Cloud CLI, כשמאומתים באמצעות איחוד שירותי אימות הזהות של כוח עבודה:

במסוףGoogle Cloud מוצגות שגיאות טעינה כלליות, כמו:

• "אירעה שגיאה במהלך הטעינה..."
• "השרת לא הצליח לבצע את מה שביקשת"
• "הטעינה נכשלה"

בנוסף, יכול להיות שפקודות gcloud יחזירו שגיאה פנימית, כמו error 13: an internal error has occurred.

כדי לפתור את הבעיה, צריך לבצע אימות באמצעות חשבון Google רגיל שמנוהל דרך Cloud Identity או Google Workspace. מוודאים שיש לחשבון את ההרשאות הנדרשות, כמו roles/agentregistry.admin או roles/agentregistry.viewer.

לשירותי הפיקוח של Gemini Enterprise Agent Platform יש תמיכה מוגבלת בזהויות מאוחדות. הקצאת תפקידי IAM רחבים יותר לחשבון משתמש מאוחד לא פותרת את הבעיה.