本頁說明如何解決 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。
- 確認封存檔不含符號連結、目錄周遊元素 (例如
..) 或絕對路徑。
管理 IAP 政策時發生找不到資源實體錯誤
如果您使用 gcloud iap web 指令管理 Agent Registry 資源的輸出政策，可能會遇到這個問題：
NOT_FOUND: Requested entity was not found
如要解決這個問題，請確認傳遞至 gcloud iap web 的資源標記與基礎 Agent Registry 子項資源類型相符：
- 如要設定端點 (例如外部 API 或 Google API 輸出點)，請使用
--endpoint標記。 - 如果是 Model Context Protocol 伺服器，請使用
--mcp-server標記。 - 如為已註冊的代理程式，請使用
--agent旗標。
檢查 gcloud agent-registry [endpoints|mcp-servers|agents] list 回傳的資源 URI，確認資源路徑是否包含 /endpoints/、/mcpServers/ 或 /agents/。如果傳遞的資源標記錯誤 (例如傳遞 MCP 伺服器 ID 的 --endpoint)，就會導致 NOT_FOUND 錯誤。
套用 IAP 網頁 IAM 政策時權限遭拒
如果您對 Agent Registry 資源套用或修改 Identity-Aware Proxy 網頁 IAM 政策，可能會遇到這個問題：
ERROR: (gcloud.iap.web.set-iam-policy) PERMISSION_DENIED
如要解決這個問題，請確認有效使用者或服務帳戶在代管登錄檔和閘道的專案中，具備必要權限：
- 請確認呼叫端在中央控管專案中具備 IAP 政策管理員 (
roles/iap.admin) 或專案 IAM 管理員 (roles/resourcemanager.projectIamAdmin) 角色。 - 確認呼叫者具備
iap.web.setIamPolicy和resourcemanager.projects.setIamPolicy權限。
透過員工身分聯盟存取 Agent Registry 時發生失敗
如果您透過Google Cloud 控制台存取 Agent Registry，或使用 Workforce Identity Federation 進行驗證時使用 gcloud CLI，可能會遇到這個問題。
Google Cloud 控制台顯示一般載入錯誤，例如：
- 「載入時發生錯誤...」
- 「伺服器無法執行要求」
- 「無法載入」
此外，gcloud 指令可能會傳回內部錯誤，例如 error 13: an internal error has occurred。
如要解決這個問題，請使用透過 Cloud Identity 或 Google Workspace 管理的標準 Google 帳戶進行驗證。確認帳戶具備必要權限，例如 roles/agentregistry.admin 或 roles/agentregistry.viewer。
Agent Platform Governance 服務僅支援部分同盟身分。將範圍較廣的 IAM 角色授予同盟主體，無法解決這個問題。