本頁說明如何解決 Agent Registry 的問題。
API 頻率配額超過上限
如果您與 Agent Registry API 互動，或在 Google Cloud 控制台中快速瀏覽 Agent Registry，可能會遇到這個問題：
429 Too Many Requests
如要解決這個問題，請在 API 用戶端中實作指數輪詢，以管理要求頻率。Agent Registry API 的預設速率配額為每分鐘 1,200 項要求 (全球和每個區域)。
如果在 Google Cloud 控制台中切換分頁時遇到節流問題，請稍候片刻再試一次。如果您的程式輔助用途需要較高的限制，請為 RequestsPerMinute 指標申請提高配額。
手動註冊時發生酬載大小錯誤
如果您手動註冊代理程式或 MCP 伺服器，可能會遇到這個問題：API 會拒絕要求，並顯示酬載過大的錯誤訊息。
如要解決這個問題，請確認 agent-card.json 或 toolspec.json
檔案小於 10 KB。AgentSpec 和 McpServerSpec 內容大小上限為 10 KB。請壓縮 JSON 檔案、移除不必要的空白字元，或縮短工具說明，以符合這項限制。詳情請參閱 JSON 結構定義。
建立後缺少代理程式或 MCP 伺服器
如果您在 Google Cloud 支援的產品 (例如 Google Workspace 或 Gemini Enterprise) 中建立代理程式或 MCP 伺服器，可能會遇到這個問題：呼叫 ListAgents 或 ListMcpServers API 時，系統不會顯示資源。
如要解決這個問題，請等待背景同步完成。資源會即時更新，但其他整合功能是由定期執行的離線批次作業填入。如果資源在幾小時後仍未顯示，請檢查專案的「服務使用情形」設定，並確認已啟用相關 API。
長時間執行的作業似乎停滯
如果您部署代理程式或設定複雜繫結，可能會遇到這個問題：作業需要大量時間，且似乎停滯不前。
如要解決這個問題，請使用 get_operation MCP 工具或 google.longrunning.Operations.GetOperation API 端點，輪詢作業狀態。建立部分代理程式和 MCP 後端需要大量佈建基礎架構，因此長時間執行的作業 (LRO) 可能需要長達 30 分鐘。設定用戶端逾時設定，並輪詢 done 布林值旗標，確認是否完成。
擷取可用繫結時結果為空白
如果您擷取驗證供應商的可用繫結，可能會遇到這個問題：即使您已確認繫結存在，API 仍會傳回 empty array 或存取權錯誤。
如要解決這個問題，請確認主體在目標 AuthProvider 資源上具有正確的 IAM 權限。API 會套用嚴格的 IAM 檢查，並移除參照呼叫端無法存取的驗證供應商的 Binding 物件。請確認主體在驗證供應商上具備必要存取權，且在專案中具備 roles/agentregistry.viewer 角色。