本頁說明如何解決 Agent Registry 的問題。
API 頻率配額超過上限
如果您與 Agent Registry API 互動，或在 Google Cloud 控制台中快速瀏覽 Agent Registry，可能會遇到這個問題：
429 Too Many Requests
如要解決這個問題，請在 API 用戶端中實作指數輪詢，以管理要求頻率。Agent Registry API 的預設頻率配額為每分鐘 1,200 項要求，適用於全球和每個區域 (每秒查詢次數 20 次)。
如果在 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 角色。
下載技能修訂版本時發生 302 錯誤
如果嘗試使用 GetSkillRevision API 和 ?alt=media 查詢參數下載技能修訂版本酬載，可能會遇到這個問題。要求會失敗，並傳回類似下列內容的錯誤：
{
"error": {
"code": 302,
"message": "Unknown Error.",
"status": "UNKNOWN"
}
}
如要解決這個問題，請確認 HTTP 用戶端已設為自動追蹤重新導向。?alt=media 端點需要 302 重新導向，才能順利下載技能封存檔。舉例來說，如果您使用 curl，請在指令中加入 -L 或 --location 旗標。
技能修訂版本驗證失敗或顯示 FAILED 狀態
建立新的技能修訂版本後，可能會遇到這個問題：修訂版本會轉換為 FAILED 狀態，且無法由服務專員載入。
如要解決這個問題，請檢查驗證記錄或檢查 ZIP 酬載內容：
- 確認 ZIP 壓縮檔的根目錄包含
SKILL.md檔案。 - 確認
SKILL.md檔案具有有效的 YAML 前置內容區塊，且已定義name和description。 - 確認 ZIP 酬載未超過大小限制：壓縮後大小不得超過 500 KB，解壓縮後總大小不得超過 10 MB，且個別檔案大小不得超過 1 MB。
- 確認封存檔不含符號連結、目錄周遊元素 (例如
..) 或絕對路徑。