本页面介绍了如何解决 Agent Registry 的问题。
超出 API 速率配额
如果您与 Agent Registry API 互动或快速 浏览 Agent Registry（在 Google Cloud 控制台中）：
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 错误
如果您尝试使用带有 ?alt=media 查询参数的 GetSkillRevision API 下载技能修订版本载荷，则可能会遇到此问题：请求失败并返回类似于以下内容的错误：
{
"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。
- 验证归档是否不包含符号链接、目录遍历元素（例如
..）或绝对路径。