View a markdown version of this page

问题排查 - Amazon Bedrock AgentCore
架构验证错误记录同步错误Auto-detection 错误
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

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

问题排查

迁移现已开放

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

架构验证错误

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

常见错误：

  • “描述符类型'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>”-注册表代表您调用 GetWorkloadAccessTokenAPI。有关具体错误，请参阅详细消息。如果您看到拒绝访问错误，请参阅同步来自外部来源的记录。

  • “无法解析凭证提供者 ARN:<arn>”-证书提供者 ARN 格式错误。提供通过身份创建的有效凭证提供者 ARN。 AgentCore

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

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

连接错误

无法访问服务器：

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

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

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

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

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

  • “MCP 服务器 URL 无效”-格式错误的 URL

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

  • “发送初始化通知失败”-通知异常

  • “无法从 MCP 服务器列出工具”-异常 tools/list

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

验证错误

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

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

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

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

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

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

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

服务器端错误

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

Auto-detection 错误

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

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

“这个组织没有满足Auto-detection 先决条件。”

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

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

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

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

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

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

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

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

  • 组织的管理账户。

  • 当前注册为 A Amazon gent Regi stry 的委派管理员的账户。

请有权访问这些账户的管理员列出与失败呼叫相同的地区的注册表，然后寻找一个注册机构：autoDetectionConfiguration.scopeORGANIZATION

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。

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

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

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

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

CreateRegistry即使启用了可信访问权限并注册了委派的管理员，也会失败

确认管理账户具有 Amazon 代理注册表服务相关角色（AWSServiceRoleForAgentRegistry）。在创建组织范围的注册表之前，它必须存在于管理账户中，即使授权的管理员是创建该注册表的人也是如此。参见步骤 1：启用可信访问权限并创建服务相关角色。

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

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

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

当管理账户注销拥有组织范围注册表的委托管理员时， Amazon 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. 删除注册表。

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