排查代理注册表问题

在 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 控制台中的技能标签页，运行 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 命令管理 Agent Registry 资源上的 Identity-Aware Proxy (IAP) 出站流量政策时，会发生以下错误：

NOT_FOUND: Requested entity was not found

如需解决此问题，请验证以下各项：

  • 注册状态：确认目标组件已在 Agent Registry 中的预期位置注册。
  • 标识符格式：确认您的命令或政策绑定指定的是标准资源名称，而不是注册表标识符 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/。传递错误的资源标志（例如，为 MCP 服务器 ID 传递 --endpoint）会导致 NOT_FOUND 错误。

应用 IAP Web IAM 政策时权限遭拒

如果您在没有所需管理角色的情况下为 Agent Registry 资源应用或修改 IAP 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 权限。

在区域级位置中未找到远程 MCP 服务器

如果您在区域级位置（例如 us-central1）查询自动注册的 Google 或 Google Cloud 远程 MCP 服务器，或者向其应用 IAP 出站流量政策，则会发生以下错误：

即使服务提供区域级端点 (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：在 Agent Registry 中使用 --location=global 查询服务器或使用 --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 出站流量绑定与目标的注册位置进行匹配：在目标 McpServer 资源的注册位置应用 IAP 出站流量授权绑定。对于自动注册的远程 MCP 服务器，请使用 global；对于按区域注册的 MCP 服务器，请使用特定区域。

在多区域位置中手动注册或创建绑定失败

如果您尝试在多区域位置（例如 us 或 eu）手动注册智能体、MCP 服务器或端点，或者创建绑定，则会发生以下错误：

API 会拒绝该请求，并返回位置不受支持或参数无效错误。

如需解决此问题，请指定受支持的区域级位置（例如 us-central1 或 europe-west1）或 global 位置。us 和 eu 多区域位置仅支持发现自动注册的组件以及注册或发现独立技能。如需查看支持的位置列表，请参阅 Agent Registry 位置。

使用员工身份联合访问 Agent Registry 时失败

如果您在通过员工身份联合进行身份验证后，在Google Cloud 控制台中访问智能体注册表或使用 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 角色并不能解决此问题。