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

כשאתם רושמים, מגלים או מחברים רכיבים ב-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 מסוימים ב-backend, צריך להקצות תשתית משמעותית. לכן, יכול להיות שזמני פעולה ממושכת (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 יש בלוק Front Matter תקין של YAML, שבו מוגדרים גם name וגם description.
• מוודאים שקובץ ה-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 לאינטרנט במשאבים של 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 או של 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.

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

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

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

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

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

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

השגיאה הבאה מתקבלת אם מנסים לרשום באופן ידני סוכן, שרת MCP או נקודת קצה, או ליצור קישור, במיקום בכמה אזורים כמו us או eu:

ה-API דוחה את הבקשה ומחזיר שגיאה על מיקום לא נתמך או ארגומנט לא תקין.

כדי לפתור את הבעיה, צריך לציין מיקום אזורי נתמך, כמו us-central1 או europe-west1, או את המיקום global. המיקומים במספר אזורים us ו-eu תומכים רק בגילוי רכיבים שנרשמו באופן אוטומטי, וברישום או בגילוי של מיומנויות עצמאיות. רשימת המיקומים הנתמכים מופיעה במאמר מיקומים של Agent Registry.

כשלים בגישה ל-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 יש תמיכה מוגבלת בזהויות מאוחדות. הקצאת תפקידי IAM רחבים יותר לחשבון משתמש מאוחד לא פותרת את הבעיה.