View a markdown version of this page

问题排查 - 亚马逊基岩 AgentCore
架构验证错误记录同步错误Auto-detection 错误

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

问题排查

迁移现已开放

AWS 代理注册表已在新agent-registry命名空间下启动。对公共预览bedrock-agentcore命名空间的支持将于 2026 年 9 月 17 日停止。有关迁移说明，请参阅综合注册表迁移指南。

架构验证错误

创建不同类型的记录时，您可能会看到描述符的验证异常。有关有效架构，请参阅 “支持的记录类型” 部分。

常见错误：

  • “描述符类型'a2a'不支持架构版本'0.3.0'。” — schemaVersion 字段值应0.3改为。0.3.0这与A2A协议网站上官方的A2A协议版本描述一致：“使用每个主要版本支持的最新次要版本”。

  • “架构验证失败：内容不符合描述符类型'a2a'的架构版本'0.3'。” — 您可以在 “支持的记录类型” 上找到架构。请注意，内容将根据 json 架构definitions/AgentCard 中的 #/进行验证。

记录同步错误

当您使用同步功能创建或更新记录时，该记录可能会转换为 CREATE_FAILED 或 UPDATE_FAILED 状态，并解释发生了什么。statusReason

在高级别，错误可以分为：权限错误、连接错误、验证错误和服务器端错误。

权限错误

同步配置错误或已过期：

  • “无法连接到 MCP 服务器，因为呼叫者凭证已过期。” — 您的创建或更新 API 的凭证已过期。您可以使用 UpdateRegistryRecord API 重试。

  • “收到来自 GetWorkloadAccessToken API 的异常：<detailed message>” — 注册表代表您调用 GetWorkloadAccessToken API。有关具体错误，请参阅详细消息。如果您看到访问被拒绝错误，请参阅同步来自外部来源的记录。

  • “无法解析凭据提供商 ARN:<arn>” — 凭证提供商 ARN 格式不正确。提供通过 Identity 创建的有效凭证提供商 ARN。 AgentCore

  • “收到来自 GetResourceOauth2Token API 的异常：<detailed message>” — 注册表代表您调用 GetResourceOauth2Token API。有关具体错误，请参阅详细消息。如果您看到访问被拒绝错误，请参阅同步来自外部来源的记录。

  • “无法代入提供的 IAM 角色进行 MCP 服务器授权。” — 注册表代表您调用 AssumeRole API。有关预期的 IAM 权限，请参阅同步来自外部来源的记录。例如，你必须拥有iam:PassRole权限。

连接错误

无法访问服务器：

  • “无法从 URL 提取代理卡:%s” — A2A IOException

  • “MCP 服务器返回了 HTTP<code>” — 来自 MCP 服务器的非 200/202 HTTP 响应。请检查 URL 是否正确，是否可以连接 MCP 服务器。

  • 如果状态码为 401 或 403，请确认您配置了正确的凭据提供商，以及您的凭据是否有权连接到 MCP 服务器。要进行故障排除，请手动获取凭据并直接连接到 MCP 服务器。

  • “提供的 URL 解析为非公共 IP 地址” — 注册表仅支持连接到公有 IP 地址服务器。

  • “无法连接到 MCP 服务器” — IOException/connection 失败

  • “MCP 服务器 URL 无效” — URL 格式不正确

  • “无法初始化 MCP 连接” — 初始化请求异常

  • “无法发送初始化通知” — 通知异常

  • “无法列出 MCP 服务器中的工具” — 异常 tools/list

  • “MCP 服务器 tools/list 分页超时” — 从 MCP 服务器对工具进行分页时，注册表最多仅支持 30 秒。如果您的 MCP 服务器需要更多时间进行同步，请联系 AWS 支持人员。

验证错误

服务器已响应，但不支持内容：

  • “无法解析代理卡 JSON” — A2A 内容为空或 JSON 格式不正确

  • “代理卡超过最大大小限制” — A2A 响应太大

  • “无法解析 MCP 服务器响应 JSON” — MCP 内容为空或格式不正确

  • “MCP 服务器返回无效响应：缺少结果” — MCP JSON-RPC 缺少结果

  • “MCP 服务器响应超出允许的最大大小” — MCP 响应太大

  • “描述符类型 %s 不支持 URL 同步” — 不支持的描述符类型

服务器端错误

  • “未知错误”-这是服务器端错误。请稍后重试或联系 AWS 支持部门寻求帮助。

Auto-detection 错误

“创建组织范围的注册表需要调用者成为注册表的一部分 AWS 组织。”

创建注册表的账户不是 AWS 组织的成员（例如，它是一个独立账户）。使用属于您的组织的账户创建注册表。

“该组织的Auto-detection 先决条件不满足。”

该组织尚未满足自动检测的先决条件，或者尚未完成传播。确认已启用可信访问权限以进行自动检测，并且您是通过管理账户或注册的委派管理员创建注册表，然后稍等片刻后重试。请参阅在组织中启用自动检测。

“此账户已存在组织范围的注册表。”

该账户已经拥有组织范围的注册表，并且一个账户只能拥有一个。使用现有注册表，或在创建另一个注册表之前将其删除。如果您在此账户中找不到注册表，请参阅查找现有组织范围的注册表。

“该组织已经存在另一个具有主动自动检测功能的组织范围的注册表。”

您组织中的另一个账户已经拥有一个具有主动自动检测功能的组织范围的注册表，并且一个组织一次只能拥有一个注册表。出于安全原因，错误消息未命名拥有现有注册表的帐户。要找到它并选择如何解决冲突，请参阅查找现有组织范围的注册表。

查找现有的组织范围的注册表

当CreateRegistry报告已存在组织范围的注册表时（无论是在您的账户中还是在组织中的其他地方），该错误并未指明特定的注册表或拥有该注册表的账户。首先找到现有的注册表，然后决定如何解决冲突。

组织范围内的注册表通常由以下账户之一拥有：

  • 组织的管理账户。

  • 该账户当前注册为 AWS 代理注册表的委托管理员。

要求有权访问这些账户的管理员列出与失败通话位于同一地区的注册管理机构，并寻找一个具有以下条件的注册管理机构autoDetectionConfiguration.scope：ORGANIZATION

aws agent-registry-control list-registries --region us-east-1

在管理账户中，确认哪个账户当前是委派的管理员：

aws organizations list-delegated-administrators \
  --service-principal agent-registry.amazonaws.com

冲突仅适用于同一区域——中的注册表并us-east-1不能阻止在中创建注册表us-west-2。

找到现有注册表后，选择以下路径之一：

  • 共享并重复使用。让拥有的账户使用 AWS RAM 授予您的账户访问权限，并管理共享注册表中的记录，而不是创建新注册表。请参阅使用 AWS RAM 跨账户共享注册表。

  • 在不删除的情况下释放插槽。现有注册表false上的所有权账户设置为autoDetectionConfiguration.enabled；更新生效后，重CreateRegistry试。请参见在注册表上禁用自动检测。

  • 删除现有注册表。如果不再需要，则拥有的账户会将其删除。请参阅关闭拆解命令的自动检测。

CreateRegistry即使启用了可信访问且注册了委派管理员也失败

确认管理账户具有 AWS 代理注册表服务相关角色 (AWSServiceRoleForAgentRegistry)。在创建组织范围的注册表之前，它必须存在于管理账户中，即使委托管理员是创建注册表的人。请参见步骤 1：启用可信访问和创建服务相关角色。

注册表已准备就绪，但记录未出现

确认注册表的自动检测状态为ACTIVE（使用get-registry），并且成员账户包含支持的资源类型（AgentCore 运行时或网关）。留出时间完成发现——首次设置时，对先前存在的资源的初始发现最多可能需要 20 分钟。

Auto-detection 重新注册委派管理员后，状态仍显示 “注册表的委托管理员帐户已注销”

当管理账户注销拥有组织范围注册表的委托管理员时， AWS Agent Registry 会关闭该注册表的自动检测，并记录状态原因。The registry’s delegated administrator account was deregistered.此状态原因描述了最初禁用自动检测的原因——它是一条历史记录，在组织状态以后发生变化时不会刷新。

如果再次注册委派管理员，则注册表的自动检测不会自动恢复，状态原因会继续显示取消注册消息。这在以下每种情况下都是预期的：

  • 同一个账户被重新注册为委派管理员。

  • 另一个账户注册为委托管理员，包括该账户已经拥有自己的组织范围注册表，且之前禁用了自动检测。

  • 没有注册新的委托管理员，管理账户直接拥有组织范围的注册表。

要恢复自动检测，拥有受影响注册表的账户必须明确设置enabled回。true在一个组织ACTIVE中，每个区域只能autoDetection.status设置一个组织范围的注册表，因此，如果有多个注册表符合条件，则仅对要保持活跃状态的注册表重新启用自动检测。

aws agent-registry-control update-registry \
  --registry-id <registry-id-or-arn> \
  --auto-detection-configuration '{"optionalValue":{"scope":"ORGANIZATION","enabled":true}}' \
  --region us-east-1

有关整个生命周期，请参阅关闭自动检测。

“启用自动检测后，无法删除注册表。请先禁用自动检测。”

必须先禁用自动检测，然后才能删除组织范围内的注册表。要删除注册表，请按顺序完成以下步骤：

  1. 禁用注册表上的自动检测（设置autoDetectionConfiguration.enabled为false）。

  2. 删除所有注册表记录。

  3. 删除注册表。

有关更多信息，请参阅在注册表上禁用自动检测。