排查代理注册表问题

在 Agent Registry 中注册、发现或连接组件时，您可以诊断并解决常见问题，例如配额限制、载荷和技能验证错误、位置不匹配、同步延迟和权限错误。

已超出 API 速率配额

如果您在与 Agent Registry API 交互或在Google Cloud 控制台中快速浏览 Agent Registry 时超出请求速率限制，则会发生以下错误：

429 Too Many Requests

如需解决此问题，请在 API 客户端中实现指数退避算法，以管理请求速率。Agent Registry API 具有默认的速率配额，即每个位置每分钟的请求数，这些配额适用于您的 Agent Registry 资源。

如果您在 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 载荷未超出大小限制：压缩后的大小必须小于 1 MB，解压后的总大小必须小于 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 agent-registry skills list 或 gcloud 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 服务器，请使用特定区域。

使用员工身份联合访问 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 角色并不能解决此问题。

由于发现安全问题，技能修订版本下载已被屏蔽

如果技能的扫描政策设置为 ENABLED_BLOCKING，并且修订版本存在安全问题，那么当您尝试下载技能修订版本载荷时，会发生以下错误：

FAILED_PRECONDITION: cannot download skill revision with scan findings when scanning policy is ENABLED_BLOCKING

如需解决此问题，请执行以下某项操作：

  1. 运行 gcloud agent-registry findings list 命令，检查在修订版本上检测到的安全发现结果。此命令需要 roles/agentregistry.admin 角色。
  2. 在本地源文件中修复发现结果，例如移除未经授权的网络出站流量代码、移除泄露的凭据或消除提示词注入模式。
  3. 上传并注册新的技能修订版本。
  4. 或者，如果您在获得授权的测试或预演环境中工作，请使用 --scanning-policy=enabled-nonblocking 将技能的扫描政策更新为 ENABLED_NONBLOCKING。如需了解详情，请参阅扫描技能是否存在安全问题。

设置默认修订版本或启用屏蔽政策失败

如果您更新技能的默认修订版本指针 (--default-revision)，或在修订版本有发现结果或待处理的扫描结果时将技能的扫描政策更改为 ENABLED_BLOCKING，则会发生以下错误：

API 会返回 FAILED_PRECONDITION 错误，并显示以下消息之一：

  • cannot set default revision to a revision with scan findings when scanning policy is ENABLED_BLOCKING
  • cannot set default revision to a revision with pending scan results when scanning policy is ENABLED_BLOCKING
  • cannot set scanning policy to ENABLED_BLOCKING when default revision has scan findings
  • cannot set scanning policy to ENABLED_BLOCKING when default revision has pending scan results

如需解决此问题，请执行以下操作：

  • 如果扫描仍处于待处理状态 (RUNNING)，请等待后台扫描完成，并验证 scanResult.scanState 是否解析为 SUCCEEDED 且没有 findings，然后再将修订版本设置为默认版本或启用 ENABLED_BLOCKING。
  • 如果目标修订版本或当前默认修订版本存在安全发现结果，请发布已解决安全问题的新修订版本，验证其 scanResult.scanState 是否解析为 SUCCEEDED 且未列出 findings，并将该干净修订版本设置为技能的 defaultRevision。

技能修订版本因超出未压缩大小限制而被拒

当您上传的技能修订版本超出未压缩扫描大小上限时，会发生以下错误：

长时间运行的操作失败，并显示 INVALID_ARGUMENT 错误，或者修订版本的 scanResult.scanState 转换为 UNSUPPORTED_FORMAT。

如需解决此问题，请执行以下某项操作：

  • 检查 ZIP 压缩包中解压缩后的文件。移除大型数据集、模型二进制文件或不必要的资源，使每个文件的大小保持在 1 MB 以下，且解压后的软件包总大小保持在 10 MB 以下。
  • 如果您的开发工作流需要上传大文件以便在项目中快速制作原型，请使用 --scanning-policy=disabled 将技能的扫描政策更新为 DISABLED（如果您的组织政策允许）。

由于组织政策，无法停用技能扫描

如果您创建或更新技能时将其扫描政策设置为 DISABLED，或者您更新现有技能的任何字段（其 scanningConfig.policy 之前设置为 DISABLED），则会发生以下错误：

请求失败，并显示违反自定义组织政策限制条件的错误。

如需解决此问题，请执行以下操作：

  • 您的组织已对 agentregistry.googleapis.com/Skill 应用自定义组织政策限制条件（例如 custom.skillsScanningEnforcement），该限制条件会拒绝 resource.scanningConfig.policy == "DISABLED"。
  • 如果您要更新在强制执行组织政策之前 scanningConfig.policy 已设置为 DISABLED 的现有技能，请在 UpdateSkill 请求中更新 scanningConfig.policy，将其设置为 ENABLED_BLOCKING 或允许的值。
  • 如需在测试或沙盒环境中停用扫描，请让您的组织政策管理员向您的项目添加条件免检标记，例如 exempt-scanning-enforcement: true。

如需了解详情，请参阅使用 Organization Policy Service 强制执行扫描。

启用扫描后未扫描技能修订版本

如果您在之前上传过修订版本的现有技能上启用扫描，则会发生以下错误：

现有修订版本的扫描状态 (scanResult.scanState) 仍为 DISABLED，系统不会扫描该修订版本，也不会生成任何安全发现结果。

为技能启用扫描功能仅适用于在启用扫描功能后创建的技能修订版本。Agent Registry 不会追溯扫描在启用扫描之前创建的修订版本。

如需解决此问题，请为该技能上传并注册新的技能修订版本。 上传新修订版本后，Agent Registry 会根据技能的更新后扫描配置扫描载荷。如需了解详情，请参阅创建技能修订版本和扫描技能是否存在安全问题。