排解 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 布林值旗標，確認是否完成。

擷取可用的繫結時，結果為空白

如果您擷取驗證提供者的可用繫結，但對目標 AuthProvider 資源沒有足夠權限，就會發生下列錯誤：

即使繫結存在，API 也會傳回空白陣列或存取錯誤。

如要解決這個問題，請確認主體具備目標 AuthProvider 資源的正確 Identity and Access Management (IAM) 權限。API 會套用嚴格的 IAM 檢查，並移除參照呼叫端無權存取驗證提供者的 Binding 物件。請確認主體具備驗證供應商的必要存取權，以及專案的 roles/agentregistry.viewer 角色。

技能修訂版本下載失敗，發生 302 錯誤

如果您嘗試使用 GetSkillRevision API 搭配 ?alt=media 查詢參數下載技能修訂版本酬載，且 HTTP 用戶端未遵循重新導向，就會發生下列錯誤：

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

如要解決這個問題，請確認 HTTP 用戶端已設為自動遵循重新導向。?alt=media 端點需要 302 重新導向，才能成功下載技能的封存檔。舉例來說，如果您使用 curl，請在指令中加入 -L 或 --location 旗標。

技能修訂版本驗證失敗或顯示 FAILED 狀態

使用無效的 ZIP 封存檔建立新的技能修訂版本時，會發生下列錯誤：

修訂版本會轉換為 FAILED 狀態，且無法由代理載入。

如要解決這個問題，請查看驗證記錄或檢查 ZIP 酬載內容：

  • 確認 ZIP 封存檔的根目錄中含有 SKILL.md 檔案。
  • 確認 SKILL.md 檔案具有有效的 YAML 前置內容區塊，且已定義 name 和 description。
  • 確認 ZIP 酬載未超過大小限制：壓縮後的大小必須小於 500 KB，解壓縮後的總大小必須小於 10 MB，個別檔案大小必須小於 1 MB。
  • 確認封存檔不含符號連結、目錄周遊元素 (例如 ..) 或絕對路徑。

獨立技能不會顯示在服務或代理資源清單中

如果查詢獨立技能的代理程式或服務清單 (例如執行 gcloud agent-registry services list 或 gcloud agent-registry agents list)，會發生下列錯誤：

輸出內容不會顯示獨立技能。

如要解決這個問題，請改為查詢 skills 集合：

  • 與手動註冊的代理、MCP 伺服器和端點不同，獨立技能不會使用可寫入的 Service 資源，或 Agent、McpServer 或 Endpoint 探索資源。相反地，Agent Registry 會直接將獨立技能表示為頂層 Skill 資源和版本化 SkillRevision 資源。
  • 如要列出、搜尋或檢查獨立技能，請使用Google Cloud 控制台中的「Skills」(技能) 分頁、執行 gcloud alpha agent-registry skills list 或 gcloud alpha agent-registry skills search，或呼叫 skills REST API 方法。如需操作說明，請參閱「管理技能」和「搜尋獨立技能」。
  • 如要尋找代理資訊卡中宣告的內嵌 A2A 技能，請使用 gcloud agent-registry agents describe 或 gcloud agent-registry agents search 檢查 Agent 探索資源上的 skills 欄位。

管理 IAP 政策時發生「找不到資源實體」錯誤

使用 gcloud iap web 指令管理代理程式登錄檔資源的 Identity-Aware Proxy (IAP) egress 政策時，會發生下列錯誤：

NOT_FOUND: Requested entity was not found

如要解決這個問題，請確認下列事項：

  • 註冊狀態：確認目標元件已在 Agent Registry 的預期位置註冊。
  • ID 格式：確認指令或政策繫結指定的是標準資源名稱，而非登錄檔 ID URN。
  • 資源旗標：確認傳遞至 gcloud iap web 的資源旗標與基礎 Agent Registry 子資源類型相符：
    • 如果是外部 API 或 Google API 輸出點等端點，請使用 --endpoint 旗標。
    • 如為 Model Context Protocol 伺服器，請使用 --mcp-server 旗標。
    • 如為已註冊的代理，請使用 --agent 旗標。

檢查 gcloud agent-registry endpoints list、gcloud agent-registry mcp-servers list 或 gcloud agent-registry agents list 傳回的資源名稱，確認資源名稱是否包含 /endpoints/、/mcpServers/ 或 /agents/。如果傳遞錯誤的資源旗標 (例如將 --endpoint 傳遞為 MCP 伺服器 ID)，會導致 NOT_FOUND 錯誤。

套用 IAP 網頁 IAM 政策時權限遭拒

如果沒有必要的管理角色，在套用或修改代理程式註冊資料庫資源的 IAP 網頁 IAM 政策時，會發生下列錯誤：

ERROR: (gcloud.iap.web.set-iam-policy) PERMISSION_DENIED

如要解決這個問題，請確認有效使用者或服務帳戶具備託管登錄檔和閘道的專案所需權限：

  • 確認呼叫端在中央管理專案中具備 IAP 政策管理員 (roles/iap.admin) 或專案 IAM 管理員 (roles/resourcemanager.projectIamAdmin) 角色。
  • 確認呼叫端具備 iap.web.setIamPolicy 和 resourcemanager.projects.setIamPolicy 權限。

在區域位置找不到遠端 MCP 伺服器

如果您在 us-central1 等區域位置查詢自動註冊的 Google 或 Google Cloud 遠端 MCP 伺服器，或對其套用 IAP egress 政策，就會發生下列錯誤：

即使服務提供區域端點 (REP)，或流量是透過區域 Agent Gateway 轉送，要求仍會傳回 NOT_FOUND 錯誤或空白清單。

當 Agent Registry 自動為已啟用的 API 註冊 Google 或Google Cloud 遠端 MCP 伺服器時，只會在 global 位置建立 McpServer 資源，而不會在個別區域 (例如 us-central1) 建立。如果服務提供區域端點 (例如 https://SERVICE.REGION.rep.googleapis.com/mcp)，Agent Registry 會在該 global McpServer 資源的 interfaces 欄位中列出這些區域網址。

如要解決這個問題，請採取下列任一做法：

  • 針對自動註冊的伺服器使用 global：使用 --location=global 在 Agent Registry 查詢伺服器，或使用 --region=global 套用 IAP 輸出政策時，請指定 global 位置，即使呼叫代理透過區域閘道路由流量也一樣。
  • 在特定區域註冊以確保資料落地：如需將登錄檔中繼資料保留在特定區域，請將自訂 MCP 伺服器部署至區域性 Cloud Run 或 Google Kubernetes Engine (GKE) 執行階段，或在該區域手動註冊 MCP 伺服器及其區域端點網址，然後在該區域套用 IAP 政策。Agent Gateway 解析目標網址時，區域註冊項目優先於 global 項目。

在 Agent Gateway 設定 Model Armor 時，發生區域不符錯誤

在 Agent Gateway 上設定 Model Armor 政策篩選器時，如果區域不相符，會發生下列錯誤：

建立授權政策時，系統顯示區域不符錯誤，或透過閘道轉送至 MCP 伺服器的流量未通過政策評估。

如要解決這個問題，請確認閘道資源和目標政策繫結的區域是否一致：

  • 確保閘道和 Model Armor 區域一致：確認 Agent Gateway、Model Armor 範本、授權擴充功能和政策都位於相同區域，例如 us-central1。
  • 轉送至 global 或區域 MCP 伺服器：您不需要僅為了使用 Model Armor，而在區域中重新註冊 global MCP 伺服器。Model Armor 會在區域閘道檢查要求和回應酬載，因此區域閘道可以檢查及控管流量，並將流量轉送至在 global 位置註冊的 MCP 伺服器，以及區域目的地。
  • 將 IAP egress 繫結與目標的註冊位置比對：在目標 McpServer 資源註冊的位置，套用 IAP egress 授權繫結。如果是自動註冊的遠端 MCP 伺服器，請使用 global；如果是區域註冊的 MCP 伺服器，請使用特定區域。

在多區域位置中，手動註冊或建立繫結失敗

如果您嘗試在多區域位置 (例如 us 或 eu) 手動註冊代理、MCP 伺服器或端點，或建立繫結，就會發生下列錯誤：

API 會拒絕要求，並傳回不支援的位置或無效引數錯誤。

如要解決這個問題，請改為指定支援的地區位置，例如 us-central1 或 europe-west1，或 global 位置。us 和 eu 多區域位置僅支援探索自動註冊的元件，以及註冊或探索獨立技能。如需支援的位置清單，請參閱「Agent Registry 位置」。

透過員工身分聯盟存取 Agent Registry 時失敗

如果您在Google Cloud 控制台存取 Agent Registry，或使用 Google Cloud CLI，並透過員工身分聯盟進行驗證，就會發生下列錯誤：

Google Cloud 控制台會顯示一般載入錯誤，例如：

  • 「載入時發生錯誤…」
  • 「伺服器無法執行您的要求」
  • 「無法載入」

此外，gcloud 指令可能會傳回內部錯誤，例如 error 13: an internal error has occurred。

如要解決這個問題，請使用透過 Cloud Identity 或 Google Workspace 管理的標準 Google 帳戶進行驗證。確認帳戶具備必要權限，例如 roles/agentregistry.admin 或 roles/agentregistry.viewer。

Gemini Enterprise Agent Platform 管理服務對聯合身分的支援有限。即使將更廣泛的 IAM 角色授予聯合主體，也無法解決問題。