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

בדף הזה מוסבר איך לפתור בעיות במאגר סוכנים.

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

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

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

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