本页面介绍了如何解决 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 时，系统不会显示相应资源。
如需解决此问题，请等待后台同步完成。您的资源会实时更新，但其他集成是通过定期运行的离线批处理作业填充的。如果您的资源在几个小时后仍未显示，请验证项目的Service Usage设置，并确保已启用相关 API。
长时间运行的操作似乎卡住了
如果您部署代理或配置复杂的绑定，可能会遇到此问题：操作需要花费大量时间，并且看起来卡住了。
如需解决此问题，请使用 get_operation MCP 工具或 google.longrunning.Operations.GetOperation API 端点轮询操作的状态。创建某些代理和 MCP 后端需要大量的基础设施配置，这可能会导致长时间运行的操作 (LRO) 耗时过长，可能长达 30 分钟。相应地配置客户端超时设置，并轮询 done 布尔值标志以验证是否完成。
提取可用绑定时结果为空
如果您为身份验证提供方提取可用绑定，可能会遇到此问题：即使您已验证绑定存在，API 仍会返回 empty array 或访问错误。
如需解决此问题，请验证您的正文是否对目标 AuthProvider 资源拥有正确的 Identity and Access Management (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 命令管理代理注册表资源的出站政策，则可能会遇到此问题：
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 Web IAM 政策时权限遭拒
如果您为 Agent Registry 资源应用或修改 Identity-Aware Proxy Web IAM 政策，则可能会遇到此问题：
ERROR: (gcloud.iap.web.set-iam-policy) PERMISSION_DENIED
如需解决此问题，请验证您的有效用户或服务账号是否对托管注册中心和网关的项目具有所需权限：
- 确保调用方在中央治理项目上拥有 IAP Policy Admin (
roles/iap.admin) 或 Project IAM Admin (roles/resourcemanager.projectIamAdmin) 角色。 - 确认调用者具有
iap.web.setIamPolicy和resourcemanager.projects.setIamPolicy权限。
使用员工身份联合访问 Agent Registry 时出现故障
如果您在Google Cloud 控制台中访问 Agent Registry 或在使用员工身份联合进行身份验证时使用 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 治理服务对联合身份的支持有限。向联合身份验证主账号授予更广泛的 IAM 角色并不能解决此问题。