自动检测的工作原理 AWS Organizations 先决条件 Permissions 在整个组织中启用自动检测处理自动检测到的记录关闭自动检测问题排查

使用 AWS 代理注册表为 AWS Organizations

AWS 代理注册表与 AWS 组织集成，因此您可以在单个注册表中自动对组织成员账户中支持的资源进行编目。

当您为注册表启用自动检测时，组织成员账户中支持的资源（ AgentCore 运行时和网关）将自动编目为注册表记录，无需在成员账户中进行设置。为组织范围的自动检测而配置的注册表称为组织范围的注册表；在创建、更新或删除资源以及帐户加入或离开组织时，它会保持同步。

本页说明了自动检测如何与 AWS 组织配合使用、如何启用自动检测以及如何管理其生成的记录。

注意

Auto-detection 使用它发现的资源填充注册表。您仍然可以在同一个注册表中手动创建和管理记录。自动检测创建的记录会被标记，因此您可以将它们与自己添加的记录区分开来。

自动检测的工作原理 AWS Organizations

账户

两个账户参与自动检测：

管理账户 -贵 AWS 组织的管理账户启用可信访问权限以进行自动检测，并注册委派的管理员。这些是只有管理账户才能执行 AWS 的组织操作。
注册管理员 -拥有组织范围的注册表及其自动检测记录的帐户。为此，我们建议使用委派管理员帐户，遵循最小权限 AWS 的安全最佳实践。管理账户也可以拥有注册表，但我们不建议这样做。

注意

一个组织在每个区域只能有一个有效的组织范围的注册表。在管理账户或委派管理员中创建，如果该地区的组织中已经存在一个，则创建另一个将被拒绝。

自动检测会发现什么

为组织范围内的注册表启用自动检测后，它会从您的成员账户中发现以下资源类型：

亚马逊 Bedrock AgentCore 运行时间 () AWS::BedrockAgentCore::Runtime
亚马逊基岩 AgentCore 网关 () AWS::BedrockAgentCore::Gateway

Auto-detection 发现启用该功能时已经存在的资源和之后创建的资源。

检测到的资源如何变成记录

对于每个发现的资源， AWS 代理注册表会在管理员的注册表中创建一个注册表记录。每条自动检测到的记录都包含一个来源条目，该条目将其链接回源资源，其中包含源资源的 ARN (sourceId)、类型 (sourceType) 和关系。DETECTED_FROM您可以使用来源将任何记录追溯到其来源的资源和成员帐户。

Auto-detection 已完全托管。启用后，无需在个人成员账户中安装或配置任何内容——没有代理、没有每个账户的权限，也没有可供设置的成员账户资源。

资源字段如何映射到记录字段

下表显示自动检测如何将属性从源资源映射到注册表记录字段。

AgentCore 运行时间 → 注册表记录

来源（运行时属性）	记录字段	注意
账户 ID、区域、资源 ID	`name`	Auto-generated 如`aws-autodetected-<accountId>-<region>-<resourceId>`。不是运行时的显示名称 (`AgentRuntimeName`)。
`ProtocolConfiguration.ServerProtocol`	`recordType`	始终为 `AGENT`。每个运行时协议 (`MCP`、、`HTTPA2A`、`AGUI`) 都映射到`AGENT`，因为自动检测无法区分独立的 MCP 服务器和公开 MCP 接口的代理。您可以将运行时检测到的记录范围从自己缩小`AGENT`到`MCP`自己——请参阅。丰富自动检测到的记录
`ProtocolConfiguration.ServerProtocol`	描述符类型（内`descriptors`）	`MCP`→`mcpServer`; `HTTP` →`http`; `A2A` →`a2aAgentCard`; `AGUI` → `agui`。`http`如果不存在或无法识别，则默认为。
`AgentRuntimeVersion`	`recordVersion`	首次检测时从运行时版本进行设置，然后将其视为您拥有的值——稍后对运行时版本的更改不会对其进行更改（参见丰富自动检测到的记录）。`"1"`如果不存在，则默认为。
根据运行时 ARN 和区域构建	终端节点 URL（内`descriptors`）	格式：`https://bedrock-agentcore.<region>.amazonaws.com/runtimes/<url-encoded-arn>/invocations?qualifier=DEFAULT`
运行时 ARN	`provenance[].sourceId`	源运行时的完整 ARN。
`AWS::BedrockAgentCore::Runtime`	`provenance[].sourceType`	所有运行时记录的常量。
`ProtocolConfiguration.ServerProtocol`	`provenance[].sourceDetails.agentcoreRuntime.protocolConfiguration.serverProtocol`	原始电线值（例如，`MCP`、`HTTP`、`A2A`）。
`AuthorizerConfiguration.CustomJWTAuthorizer.DiscoveryUrl`	`provenance[].sourceDetails.agentcoreRuntime.authorizerConfiguration.customJWTAuthorizer.discoveryUrl`	仅适用于具有 JWT 授权的运行时。其他授权方字段（`AllowedClientsAllowedAudience`、、`AllowedScopes`）未包含在记录中。
`WorkloadIdentityDetails.WorkloadIdentityArn`	`provenance[].sourceDetails.agentcoreRuntime.workloadIdentityDetails.workloadIdentityArn`	当运行时配置了工作负载标识时出现。

AgentCore 网关 → 注册表记录

来源（网关属性）	记录字段	注意
账户 ID、区域、资源 ID	`name`	Auto-generated 如`aws-autodetected-<accountId>-<region>-<resourceId>`。不是网关的显示名称 (`Name`)。
`ProtocolType`	`recordType`	`MCP`→ `GATEWAY`。网关检测到的记录始终是`GATEWAY`且不能更改为另一种类型。目前不支持其他协议类型。
`ProtocolType`	描述符类型（内`descriptors`）	`MCP`→ `mcpServer`。目前不支持其他协议类型。
（硬编码）	`recordVersion`	始终为 `"1"`。网关没有版本概念；更新已到位。
`GatewayUrl`	终端节点 URL（内`descriptors`）	逐字取自网关配置（例如，）。`\https://<gateway-id>.gateway.bedrock-agentcore.<region>.amazonaws.com/mcp`
网关 ARN	`provenance[].sourceId`	源网关的完整 ARN。
`AWS::BedrockAgentCore::Gateway`	`provenance[].sourceType`	所有网关记录的常数。
`ProtocolType`	`provenance[].sourceDetails.agentcoreGateway.protocolType`	原始电线值（例如，`MCP`）。
`AuthorizerType`	`provenance[].sourceDetails.agentcoreGateway.authorizerType`	例如，`AWS_IAM` 或 `CUSTOM_JWT`。
`AuthorizerConfiguration.CustomJWTAuthorizer.DiscoveryUrl`	`provenance[].sourceDetails.agentcoreGateway.authorizerConfiguration.customJWTAuthorizer.discoveryUrl`	仅适用于具有 JWT 授权的网关。其他授权方字段（`AllowedClientsAllowedAudience`、、`AllowedScopes`）未包含在记录中。
`WorkloadIdentityDetails.WorkloadIdentityArn`	`provenance[].sourceDetails.agentcoreGateway.workloadIdentityDetails.workloadIdentityArn`	当网关配置了工作负载身份时出现。

目录如何保持同步

自动检测处于活动状态后， AWS 代理注册表会使注册表与您的组织状态保持一致：

会员账号中的活动	对注册表的影响
启用自动检测时已存在支持的资源	为其创建了一条记录。
已创建支持的资源	为其创建了一条记录。
支持的资源已更新	当源代码派生的属性（例如资源的协议、授权方或端点）发生变化时，记录的源派生字段（其描述符和来源）将被刷新，而您自己设置的值（例如、和）会被保留。`name` `description` `recordVersion`如果协议发生变化，则描述符将与新协议协调并`recordType`重置`AGENT`为源默认值（运行时）。如果您已经批准了该记录，则刷新将作为必须获得批准的新`Draft`修订版本进行应用，而您之前批准的修订版本将保持可见状态，请参阅审批。
支持的资源已删除	其记录已删除。
账户加入组织	检测并添加其支持的资源。
账户离开（或从组织中删除）	从该账户检测到的所有记录都将被删除。

注意

如果您弃用自动检测到的记录（将其状态设置为DEPRECATED），则自动检测会停止将源资源的更改同步到该记录。源资源的后续更新（例如协议、授权方或端点更改）不适用于已弃用的记录。如果您想冻结自动检测到的特定记录，同时继续对注册表中其他自动检测到的记录进行重新同步，请使用弃用。

自动检测设置与其状态

Auto-detection 涉及两个相关字段 — 一个是您设置的，另一个是服务报告的字段：

autoDetectionConfiguration.enabled是你控制的设置。您可以在创建或更新注册表时将其设置为开启（true）或关闭（false）自动检测。 AWS Agent Registry 还会在以下几种拆解情况下为你关闭它：禁用自动检测的可信访问权限时，或者拥有注册表的委派管理员被注销时。
autoDetection.status是服务报告的州，还ACTIVE是INACTIVE. 你没设置。 AWS ACTIVE只有当组织满足自动检测的先决条件时，代理注册表才会生效；否则enabled是true。INACTIVE

简而言之，enabled就是你所要求autoDetection.status的，也是实际有效的。设置enabled为true是必要的，但还autoDetection.status不够ACTIVE。

先决条件

在启用自动检测之前，请确保您具备以下条件：

您的账户是组织中 AWS 某个组织的成员，所有功能均已启用。有关更多信息，请参阅《组织用户指南》中的启用 AWS 组织中的所有功能。
您可以登录管理账户以启用可信访问权限并注册委托管理员。
您可以登录将成为注册表管理员的帐户（建议使用委托管理员）来创建组织范围的注册表。
您拥有每个账户Permissions中描述的权限。

Permissions

在管理账户中

要启用可信访问并注册委派管理员，管理账户中的呼叫者需要以下 AWS 组织权限：

organizations:EnableAWSServiceAccess
organizations:RegisterDelegatedAdministrator
organizations:DeregisterDelegatedAdministrator然后organizations:DisableAWSServiceAccess稍后再关闭该功能

管理账户还iam:CreateServiceLinkedRole需要创建 AWS 代理注册服务相关角色。在创建组织范围的注册表之前，该角色必须存在于管理账户中——请参阅 “在整个组织中启用自动检测” 中的步骤 1。

在注册表管理员账户中

要创建和管理组织范围内的注册表及其记录，调用者需要 AWS 代理注册表权限，包括、agent-registry:CreateRegistry、agent-registry:UpdateRegistryagent-registry:GetRegistry、agent-registry:ListRegistryRecords和。agent-registry:UpdateRegistryRecord有关完整列表和示例策略，请参阅 IAM 权限。

在整个组织中启用自动检测

启用自动检测分为三个步骤：管理帐户启用可信访问并注册委派管理员，然后管理员创建开启自动检测的组织范围的注册表。

注意

本节中的步骤必须按顺序执行。注册委托管理员（步骤 2）后，组织状态可能需要很短的时间才能传播。在此之前，创建组织范围的注册表（步骤 3）将被拒绝。请参阅问题排查。

第 1 步：启用可信访问并创建服务相关角色（管理账户）

登录管理帐户，启用可信访问以进行自动检测，并确保管理账户具有 AWS 代理注册服务相关角色。

重要

在创建组织范围的注册表之前， AWS 代理注册表服务相关角色 (AWSServiceRoleForAgentRegistry) 必须存在于管理账户中，包括注册表由委托管理员而不是管理账户创建时。从 AWS 代理注册控制台启用可信访问会为您创建此角色。如果您使用 AWS CLI 或 API 进行设置，请使用下面的第二个命令显式创建。

如果使用客户管理的密钥对组织范围内的注册表进行加密，则在调用之前，服务相关角色还必须存在于注册管理机构管理员帐户（通常是委托的管理员）中。CreateRegistry该账户中的 KMS 密钥策略将服务相关角色命名为委托人，IAM 拒绝任何引用尚不存在的委托人的密钥策略。启用可信访问权限可通过 ASLRP 在注册管理机构管理员账户中配置角色，但传播可能会短暂延迟，直到角色到达该位置后，才CreateRegistry会违反 KMS 密钥策略。为了避免这种竞争，请让注册管理机构管理员账户直接使用创建角色aws iam create-service-linked-role --aws-service-name agent-registry.amazonaws.com。

Organization-scoped 不使用客户管理密钥的注册管理机构不需要这个额外的步骤——如果注册管理机构管理员账户中还没有服务相关角色，则在注册管理机构管理员账户中CreateRegistry创建服务相关角色。

控制台

打开AWS 代理注册表控制台-设置。
在 AWS 组织集成详细信息部分中，选择编辑。
在 “ AWS 组织设置” 页面的 “可信访问” 下，打开 “启用” 开关。这授权 AWS 代理注册表在成员账户中发现资源，并在该账户中创建AWSServiceRoleForAgentRegistry服务相关角色。
在 “授权管理员帐户” 下，输入您要用作注册表管理员的成员账户的 12 位数账户 ID。
选择保存。

AWS CLI

启用可信访问以进行自动检测：


aws organizations enable-aws-service-access \
  --service-principal agent-registry.amazonaws.com

在管理账户中创建 AWS 代理注册表服务相关角色：


aws iam create-service-linked-role \
  --aws-service-name agent-registry.amazonaws.com

第 2 步：注册委托管理员（管理账号）

仍在管理账户中，将拥有组织范围注册表的账户注册为委托管理员以进行自动检测。

注意

您注册的账户必须已经是您的组织的成员。如果不是，请在运行此步骤之前将其添加到 “ AWS 组织” 中。

控制台

作为上述步骤 1 的一部分，已注册委托管理员。当您配置可信访问权限并在 AWS 组织设置页面上输入委派管理员帐户 ID 时，这两个步骤将同时完成。

AWS CLI

替换<delegated-admin-account-id>为您要用作注册表管理员的账户的 12 位数账户 ID。


aws organizations register-delegated-administrator \
  --account-id <delegated-admin-account-id> \
  --service-principal agent-registry.amazonaws.com

步骤 3：创建组织范围的注册表（注册管理员）

登录委派管理员帐户，使用设置scope为和的自动检测配置创建注册表。ORGANIZATION enabled trueenabled必须true激活自动检测——如果是，注册表已创建false，但其自动检测状态永远不会变成ACTIVE，也不会检测到任何资源。

控制台

打开AWS 代理注册表控制台-注册表。
选择 “创建注册表” 。
填写必填字段（名称以及可选描述、发现授权、记录批准、 KMS 密钥和标签）。
展开 Auto-detection 部分。
打开 “启用自动检测” 开关。范围设置为组织并显示服务访问权限。
选择 “创建注册表” 。

注意

Auto-detection 在当前区域运行。要发现其他地区的资源，请创建一个单独的注册表，并在每个区域启用自动检测。每个区域只能有一个注册表启用自动检测。

AWS CLI


aws agent-registry-control create-registry \
  --name "my-organization-registry" \
  --description "Auto-detected resources across my organization" \
  --auto-detection-configuration '{"scope":"ORGANIZATION","enabled":true}' \
  --region us-east-1

运行get-registry或时list-registries，您会看到两个独立的状态字段。注册表status字段开始为CREATING，配置完成READY时转换为。该autoDetection.status字段是单独跟踪的：INACTIVE直到自动检测运行为止，然后变成ACTIVE。当注册表status保持不READYautoDetection.status变时ACTIVE，会开始显示您的成员账户中支持资源的记录。

注意

设置enabled为true请求自动检测，但本身还不够。ACTIVE只有当两个前提条件都满足时，该autoDetection.status字段才会变成：启用可信访问以进行自动检测，注册表归管理账户或注册的委托管理员所有。这些条件还必须传播，在启用可信访问或注册委派管理员后可能需要很短的时间。

验证是否已检测到资源

列出注册表的记录并查找通过自动检测创建的记录：


aws agent-registry-control list-registry-records \
  --registry-id <registry-id-or-arn> \
  --region us-east-1

注意

首次设置时，自动检测会发现您的成员账户中已经存在的资源，初始发现最多可能需要 20 分钟。先前存在的资源的记录可能不会立即出现。

有关如何区分自动检测到的记录和您自己添加的记录，请参阅识别自动检测到的记录。

处理自动检测到的记录

识别自动检测到的记录

Auto-detected 记录由两个特征标识：

他们的记录名称前缀为。aws-autodetected-
它们包括一个来源条目，其关系为DETECTED_FROM，其sourceId是源资源的 ARN，其sourceType标识资源类型（例如，AWS::BedrockAgentCore::Runtime或AWS::BedrockAgentCore::Gateway）。

使用名称前缀快速筛选自动检测到的记录，并使用来源将记录追溯到其来源的资源和成员账户。

控制台

您可以通过以下方式识别控制台中自动检测到的记录：

注册表记录表 — 注册表详细信息页面上的记录表包括三列自动检测到的记录：Auto-detection(Yes/No)、来源类型（例如 Bedrock AgentCore 运行时）和来源 ID（源资源 ARN）。
属性筛选器 -使用记录表中的属性筛选器按 Auto-detection = 是或 Auto-detection = 否进行筛选。
记录详细信息页面 -对于自动检测到的记录，记录详细信息页面显示一个可扩展的来源部分，显示关系（检测来源）、来源 ARN、来源类型、服务器协议和工作负载身份 ARN。

丰富自动检测到的记录

您可以使用编辑自动检测到的记录来添加自己的信息（例如，更具描述性的描述）。update-registry-record您的编辑内容将被保留；自动检测会在不覆盖您设置的值的情况下更新记录的源派生字段。


aws agent-registry-control update-registry-record \
  --registry-id <registry-id-or-arn> \
  --record-id <record-id> \
  --description '{"optionalValue":"MCP server exposing the order-management API as agent tools"}' \
  --region us-east-1

AWS 代理注册表将您拥有的字段与自动检测记录中自动检测拥有的字段分开：

字段	可由您编辑	行为
`name`, `description`, `recordVersion`	是	接受并保留；自动检测在刷新源记录时不会覆盖它们。
描述符 `data`	是	你可以丰富它。
`recordType`	有限	您可以将运行时检测到的记录从`AGENT`缩小到的范围。`MCP`任何其他更改（例如对`SKILLGATEWAY`、或`CUSTOM`）都将被拒绝，网关检测到的记录始终会被拒绝。`GATEWAY`
描述器协议（种类）	否	源自源资源；更改被拒绝。
描述符来源 URL	否	源自源资源；你无法对其进行更改或清除。要连接用于同步的凭据提供商，请为描述符源提供相同的 URL ——请参阅同步记录。
`provenance`	否	将记录链接到其源资源；更改被拒绝。

注意

如果源资源的协议后来发生变化，自动检测会协调记录的描述符以匹配新协议，然后重置为AGENT，recordType从而覆盖您所做的缩小范围。您的其他编辑（例如name和description）将保留。

例如，使用MCP协议检测到的运行时将按mcpServer描述符recordTypeAGENT进行编目，然后将记录范围缩小到。MCP如果该运行时稍后更新为使用该A2A协议，则下次刷新将mcpServer描述符替换为a2aAgentCard描述符并recordType从MCP返回重置为。AGENTrecordVersion您设置的namedescription、和保持不变。

删除自动检测到的记录

启用自动检测后，您无法删除自动检测的记录。autoDetectionConfiguration.enabled true Auto-detection 管理这些记录的生命周期 — 删除源资源或成员帐户离开组织后，记录会自动删除。

要手动删除自动检测到的记录，必须先将设置enabled为禁用注册表上的自动检测。false禁用自动检测后，您可以像删除任何其他记录一样删除自动检测到的记录。

审批

Auto-detected 记录遵循与您手动创建的记录相同的批准工作流程：记录必须处于APPROVED状态才能通过注册表的发现 API 和记录目录发现。如果将注册表配置为自动批准，则无需人工审阅即可发现记录；否则，策展人将对其进行审核和批准。有关更多信息，请参阅管理注册表。

当自动检测刷新您已经批准的记录时（例如，由于源资源的协议已更改），刷新后的内容将作为新Draft修订版本编写，在获得批准之前无法发现。在此期间，您之前批准的修订版本仍可被发现，因此发现不会中断。批准更新后的修订版本以发布——如果注册管理机构使用自动批准，则提交审批立即批准；否则将由策展人审查和批准。不更改源代码派生字段的刷新会使记录保持不变。

关闭自动检测

禁用注册表上的自动检测

要停止发现资源，请更新注册表以将自动检测设置为enabled。false必须先禁用自动检测，然后才能删除组织范围内的注册表。

要删除组织范围内的注册表，请按顺序完成以下步骤：

禁用注册表上的自动检测。
删除所有注册表记录。
删除注册表。


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

更新是异步的：注册表移至更改生效READY时UPDATING并返回。

注销委派管理员或禁用可信访问权限

要删除组织级别的自动检测，管理账户可以注销委派管理员的注册并禁用可信访问权限：


aws organizations deregister-delegated-administrator \
  --account-id <delegated-admin-account-id> \
  --service-principal agent-registry.amazonaws.com


aws organizations disable-aws-service-access \
  --service-principal agent-registry.amazonaws.com

禁用可信访问权限或取消注册拥有注册表的委托管理员也会将注册表的autoDetectionConfiguration.enabled设置为，false并将其设置autoDetection.status为INACTIVE。状态原因显示 “该组织的可信访问已禁用”。

重要

如果您在禁用可信访问后重新启用它，则自动检测不会自动恢复。必须手动更新注册表的自动检测配置才能将其设置enabled回。true

问题排查

要对自动检测问题进行故障排除，请参阅故障排除主页面中的Auto-detection 错误。

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

通知（亚马逊 EventBridge）

Cross-account 共享 (RAM)