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

בדף הזה מוסבר איך לפתור בעיות ב-Agent Registry.

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

כדי לפתור את הבעיה, צריך לוודא שגודל הקובץ agent-card.json או toolspec.json קטן מ-10 KB. גודל התוכן של AgentSpec ושל McpServerSpec מוגבל ל-10 KB. כדי לעמוד במגבלה הזו, אפשר לצמצם את קובצי ה-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 כדי לאמת את ההשלמה.

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

יכול להיות שתיתקלו בבעיה הזו אם תנסו לאחזר את הקישורים הזמינים לספק אימות: ה-API יחזיר empty array או שגיאת גישה, גם אם אימתתם שהקישור קיים.

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

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

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

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

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

האימות של עדכון המיומנות נכשל או שהסטטוס שלו הוא FAILED

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

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

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