本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 使用 Amazon 代理注册表 Amazon Organizations Amazon Agent Registry 与 Amazon Organizations 集成，因此您可以在单个注册表中自动对组织成员账户中支持的资源进行编目。 当您为注册表启用**自动检测**时，组织成员帐户中支持的资源（ AgentCore 运行时和网关）会自动归类为注册表记录，无需在成员帐户中进行任何设置。为组织范围的自动检测配置的注册表称为**组织范围的注册表**；在创建、更新或删除资源以及账户加入或离开组织时，它会保持同步。 本页说明了自动检测如何与 Organi Amazon zations 配合使用、如何启用自动检测以及如何管理自动检测产生的记录。 **注意** Auto-detection 用它发现的资源填充注册表。您仍然可以在同一个注册表中手动创建和管理记录。通过自动检测创建的记录会被标记，因此您可以将其与自己添加的记录区分开来。 ## 自动检测的工作原理 Amazon Organizations ### 账户 两个账户参与自动检测： + **管理帐户**-贵 Amazon 组织的管理帐户启用可信访问权限以进行自动检测并注册委派的管理员。这些是只有管理账户才能执行的 Amazon Organizations 操作。 + **注册管理员**-拥有组织范围内的注册表及其自动检测记录的帐户。为此，我们建议使用**委派管理员**帐户，遵循最低权限 Amazon 的安全最佳实践。管理账户也可以拥有注册表，但我们不建议这样做。 **注意** 一个组织在每个区域只能有一个有效的组织范围注册表。在管理账户或委托管理员中创建它，如果该区域的组织中已经存在管理账号或委托管理员，则创建另一个账号将被拒绝。 ### 自动检测会发现什么 为组织范围的注册表启用自动检测后，它会从您的成员账户中发现以下资源类型： + Amazon Bedrock AgentCore 运行时 () `AWS::BedrockAgentCore::Runtime` + Amazon 基岩 AgentCore 网关 () `AWS::BedrockAgentCore::Gateway` Auto-detection 发现启用该功能时已存在的资源和之后创建的资源。 ### 检测到的资源如何成为记录 对于每个发现的资源， Amazon 代理注册表都会在管理员的注册表中创建一个注册表记录。每条自动检测到的记录都包含一个**来源**条目，该条目将其链接回源资源，其中包含源资源的 ARN (`sourceId`)、类型 (`sourceType`) 和关系。`DETECTED_FROM`您可以使用出处将任何记录追溯到其来源的资源和成员帐户。 Auto-detection 已完全托管。启用后，无需在个人成员账户中安装或配置任何内容 — 没有代理、没有每个账户的权限，也没有要设置的成员账户资源。 ### 资源字段如何映射到记录字段 下表显示了自动检测如何将源资源中的属性映射到注册表记录字段。 #### AgentCore 运行时间 → 注册表记录 | 源（运行时属性） | 记录字段 | 注意 | | --- | --- | --- | | 账户 ID、区域、资源 ID | `name` | Auto-generated 如`aws-autodetected--- `。不是运行时的显示名称 (`AgentRuntimeName`)。 | | `ProtocolConfiguration.ServerProtocol` | `recordType` | 始终为 `AGENT`。每个运行时协议 (`MCP`、、`HTTP``A2A`、`AGUI`) 都映射到`AGENT`，因为自动检测无法将独立 MCP 服务器与公开 MCP 接口的代理区分开来。您可以将运行时检测到的记录范围从`MCP`自己缩小范围`AGENT`，请参阅。[丰富自动检测到的记录](#registry-organizations-enriching) | | `ProtocolConfiguration.ServerProtocol` | 描述符类型（内`descriptors`） | `MCP`→`mcpServer`; `HTTP` →`http`; `A2A` →`a2aAgentCard`; `AGUI` → `agui`。 `http`如果不存在或无法识别，则默认为。 | | `AgentRuntimeVersion` | `recordVersion` | 首次检测时从运行时版本进行设置，然后将其视为您拥有的值——稍后对运行时版本的更改不会对其进行更改（请参阅[丰富自动检测到的记录](#registry-organizations-enriching)）。`"1"`如果不存在，则默认为。 | | 根据运行时 ARN 和区域构建 | 终端节点 URL（其中`descriptors`） | 格式：`https://bedrock-agentcore..amazonaws.com/runtimes//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 授权的运行时。其他授权方字段 (`AllowedClients`、`AllowedAudience`、`AllowedScopes`) 不会被带到记录中。 | | `WorkloadIdentityDetails.WorkloadIdentityArn` | `provenance[].sourceDetails.agentcoreRuntime.workloadIdentityDetails.workloadIdentityArn` | 在运行时配置了工作负载身份时出现。 | #### AgentCore 网关 → 注册表记录 | 来源（网关属性） | 记录字段 | 注意 | | --- | --- | --- | | 账户 ID、区域、资源 ID | `name` | Auto-generated 如`aws-autodetected--- `。不是网关的显示名称 (`Name`)。 | | `ProtocolType` | `recordType` | `MCP`→ `GATEWAY`。 网关检测到的记录始终是`GATEWAY`且不能更改为其他类型。目前不支持其他协议类型。 | | `ProtocolType` | 描述符类型（内`descriptors`） | `MCP`→ `mcpServer`。 目前不支持其他协议类型。 | | （硬编码） | `recordVersion` | 始终为 `"1"`。网关没有版本概念；更新已到位。 | | `GatewayUrl` | 终端节点 URL（其中`descriptors`） | 逐字取自网关配置（例如，）。`\https://.gateway.bedrock-agentcore..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 授权的网关。其他授权方字段 (`AllowedClients`、`AllowedAudience`、`AllowedScopes`) 不会被带到记录中。 | | `WorkloadIdentityDetails.WorkloadIdentityArn` | `provenance[].sourceDetails.agentcoreGateway.workloadIdentityDetails.workloadIdentityArn` | 当网关配置了工作负载身份时出现。 | ### 目录如何保持同步 自动检测处于活动状态后， Amazon 代理注册表会使注册表与您的组织状态保持一致： | 会员账号中的活动 | 对注册表的影响 | | --- | --- | | 启用自动检测后，已存在支持的资源 | 为此创建了一条记录。 | | 已创建支持的资源 | 为此创建了一条记录。 | | 支持的资源已更新 | 当源派生的属性（例如资源的协议、授权方或终端节点）发生变化时，记录的源派生字段（其描述符和来源）会被刷新，同时保留您自己设置的值（例如、和）。`name` `description` `recordVersion`如果协议发生变化，则描述符将与新协议协调并`recordType`重置为源默认值（`AGENT`对于运行时）。如果您已经批准了记录，则刷新将作为必须获得批准的新`Draft`修订版进行应用，而您之前批准的修订版仍可被发现 — 请参阅[审批](#registry-organizations-approval)。 | | 支持的资源已删除 | 它的记录已被删除。 | | 账户加入组织 | 它支持的资源会被检测并添加。 | | 账户离开组织（或已从组织中删除） | 从该账户中检测到的所有记录都将被删除。 | **注意** 如果您弃用了自动检测到的记录（将其状态设置为`DEPRECATED`），则自动检测会停止将源资源的更改同步到该记录。对源资源的后续更新（例如协议、授权方或端点更改）不会应用于已弃用的记录。如果您想冻结自动检测到的特定记录，同时继续对注册表中其他自动检测到的记录进行重新同步，请使用弃用。 ### 自动检测设置与其状态 Auto-detection 涉及两个相关字段，一个由您设置，另一个由服务报告： + **`autoDetectionConfiguration.enabled`**是您控制的设置。您可以在创建或更新注册表时将其设置为开启 (`true`) 或关闭 (`false`) 自动检测。 Amazon 在几个拆卸案例中，Agent Registry 还会为你关闭它：禁用自动检测的可信访问权限时，或者当拥有注册表的委托管理员被取消注册时。 + **`autoDetection.status`**是服务报告的状态 — `ACTIVE` 或`INACTIVE`。你没有设置它。 Amazon Agent Reg `enabled` i `true` stry `ACTIVE` 只有在满足自动检测前提条件时才会这样做；否则就是。`INACTIVE` 简而言之，`enabled`就是你所要求`autoDetection.status`的，也是实际有效的。设置`enabled`为`true`是必要的，但还`autoDetection.status`不够`ACTIVE`。 ## 先决条件 在启用自动检测之前，请确保您具备以下条件： + 您的账户是 Organizations 中某个 Amazon 组织的成员，且所有功能均已启用。有关更多信息，请参阅 Organizati [ons *用户指南中的启用 Amazon 组织*中的所有功能](https://docs.amazonaws.cn/organizations/latest/userguide/orgs_manage_org_support-all-features.html)。 + 您可以登录**管理账户**以启用可信访问权限并注册委派的管理员。 + 您可以登录将成为**注册表管理员**的账户（建议使用委托管理员）来创建组织范围内的注册表。 + 您拥有每个账户[Permissions](#registry-organizations-permissions)中描述的权限。 ## Permissions ### 在管理账户中 要启用可信访问权限并注册委派管理员，管理账户中的来电者需要以下 Organizati Amazon ons 权限： + `organizations:EnableAWSServiceAccess` + `organizations:RegisterDelegatedAdministrator` + `organizations:DeregisterDelegatedAdministrator``organizations:DisableAWSServiceAccess`并稍后关闭该功能 管理账户还需要`iam:CreateServiceLinkedRole`创建 Amazon Agent Registry 服务相关角色。在创建组织范围的注册表之前，此角色必须存在于管理账户中，请参阅 “在整个组织中启用自动检测” 中的步骤 1。 ### 在注册表管理员账户中 要创建和管理组织范围内的注册表及其记录，调用者需要 Amazon 代理注册表权限，包括、`agent-registry:CreateRegistry`、`agent-registry:UpdateRegistry``agent-registry:GetRegistry`、`agent-registry:ListRegistryRecords`和。`agent-registry:UpdateRegistryRecord`有关完整列表和策略示例，请参阅 [IAM 权限](registry-iam-permissions.md)。 ## 在整个组织中启用自动检测 启用自动检测分为三个步骤：管理帐户启用可信访问权限并注册委派管理员，然后管理员在开启自动检测的情况下创建组织范围的注册表。 **注意** 必须按顺序执行本节中的步骤。注册委托管理员（步骤 2）后，组织状态可能需要很短的时间才能传播。在此之前，创建组织范围的注册表（步骤 3）将被拒绝。请参阅[自动检测疑难解答](#registry-organizations-troubleshooting)。 ### 步骤 1：启用可信访问权限并创建服务相关角色（管理账户） 登录管理账户，启用可信访问权限以进行自动检测，并确保管理账户具有 Amazon 代理注册服务相关角色。 **重要** 在创建组织范围的注册表之前，**管理账户**中必须存在 Amazon Agent Registry 服务相关角色 (`AWSServiceRoleForAgentRegistry`)，包括注册表是由授权的管理员而不是管理帐户创建的。从 Amazon Agent Registry 控制台启用可信访问将为您创建此角色。如果您 Amazon 使用 CLI 或 API 进行设置，请使用下面的第二个命令显式创建。 如果使用客户托管密钥对组织范围的注册表进行加密，则在调用注册表管理员帐户（通常是委托管理员）之前，服务相关角色*也*必须存在于**注册表管理员**帐户（通常是委托的管理员）中。`CreateRegistry`该账户中的 KMS 密钥策略将服务相关角色命名为委托人，IAM 拒绝任何引用尚不存在的委托人的密钥策略。启用可信访问权限会通过 ASLRP 在注册表管理员账户中配置角色，但传播可能会短暂延迟，直到角色落到那里，才`CreateRegistry`会违反 KMS 密钥策略。为避免这种竞争，请让注册表管理员帐户直接使用创建角色`aws iam create-service-linked-role --aws-service-name agent-registry.amazonaws.com`。 Organization-scoped 不使用客户托管密钥的注册管理机构不需要此额外步骤 — 如果注册表管理员账户中还没有服务关联角色，则在注册表管理员账户中`CreateRegistry`创建该角色。 **控制台** 1. 打开[Amazon 代理注册表控制台-设置](https://console.amazonaws.cn/agent-registry/home?region=us-east-1#/settings)。 1. 在 ** Amazon Organizations 集成详细信息**部分，选择**编辑**。 1. 在 Org ** Amazon anizations 设置**页面的 “**可信访问**” 下，打开 “**启用**” 开关。这授权 Amazon Agent Registry 可以跨成员账户发现资源，并在该账户中创建`AWSServiceRoleForAgentRegistry`服务相关角色。 1. 在**委托管理员账户**下，输入要用作注册管理管理员的成员账户的 12 位数账户 ID。 1. 选择**保存**。 ** Amazon CLI** 启用可信访问以进行自动检测： ``` aws organizations enable-aws-service-access \ --service-principal agent-registry.amazonaws.com ``` 在管理账户中创建 Amazon Agent Registry 服务相关角色： ``` aws iam create-service-linked-role \ --aws-service-name agent-registry.amazonaws.com ``` ### 步骤 2：注册委托管理员（管理账号） 仍然在管理账户中，将拥有组织范围注册表的账户注册为自动检测的委托管理员。 **注意** 您注册的账户必须已经是您组织的成员。如果不是，请在运行此步骤之前将其添加到 Amazon Organizations 中。 **控制台** 委托管理员已作为上述步骤 1 的一部分进行注册。当您配置可信访问权限并在 Organizations 设置页面上输入委派管理员帐户 ID 时，这两个步骤将同时完成。 Amazon ** Amazon CLI** ``替换为您要用作注册表管理员的账户的 12 位数账户 ID。 ``` aws organizations register-delegated-administrator \ --account-id \ --service-principal agent-registry.amazonaws.com ``` ### 步骤 3：创建组织范围的注册表（注册表管理员） 登录委派管理员帐户，并使用设置`scope`为`ORGANIZATION`和`enabled`的自动检测配置创建注册表。`true` `enabled`必须是`true`自动检测才能激活的 — 如果是，则注册表已创建`false`，但其自动检测状态永远不会变成`ACTIVE`，也不会检测到任何资源。 **控制台** 1. 打开[Amazon 代理注册表控制台-注册表](https://console.amazonaws.cn/agent-registry/home?region=us-east-1#/registries)。 1. 选择 “**创建注册表**”。 1. 填写必填字段（“**名称**”、“**描述**”、“**发现授权**”、“**记录批准**”、“**KMS 密钥**” 和 “**标签**”）。 1. 展开 **Auto-detection** 部分。 1. 打开 “**启用自动检测**” 开关。“**范围**” 设置为 “**组织**”，并显示服务访问权限。 1. 选择 “**创建注册表**”。 **注意** Auto-detection 在当前区域运行。要发现其他区域内的资源，请分别在各个区域中创建一个已启用自动检测功能的注册表。每个区域只能有一个注册表启用自动检测。 ** Amazon 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 my-region ``` 运行`get-registry`或时`list-registries`，您会看到两个单独的状态字段。注册表`status`字段的开头为`CREATING`，置备完成`READY`时转换为。该`autoDetection.status`字段是单独跟踪的：`INACTIVE`直到自动检测运行为止，然后变成`ACTIVE`。当注册表`status``autoDetection.status`处于`READY`和现在状态时`ACTIVE`，就会开始显示您的成员账户中受支持资源的记录。 **注意** 设置`enabled`为`true`请求自动检测，但单独设置还不够。`ACTIVE`仅当满足两个前提条件时，该`autoDetection.status`字段才会变为可信访问以进行自动检测，注册表归管理账户或注册的委派管理员所有。这些条件还必须传播，在您启用可信访问权限或注册委托管理员之后，这可能需要很短的时间。 ### 验证是否检测到资源 列出注册表的记录并查找通过自动检测创建的记录： ``` aws agent-registry-control list-registry-records \ --registry-id \ --region my-region ``` **注意** 首次设置时，自动检测会发现您的成员账户中已经存在的资源，而最初的发现最多可能需要 20 分钟。先前存在的资源的记录可能不会立即显示。 有关如何区分自动检测到的记录和您自己添加的记录，请参阅[识别自动检测到的记录](#registry-organizations-identifying)。 ## 处理自动检测到的记录 ### 识别自动检测到的记录 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 \ --record-id \ --description '{"optionalValue":"MCP server exposing the order-management API as agent tools"}' \ --region my-region ``` Amazon Agent Registry 将您拥有的字段与自动检测在自动检测记录上拥有的字段分开： | 字段 | 可由您编辑 | 行为 | | --- | --- | --- | | `name`, `description`, `recordVersion` | 是 | 接受并保留；自动检测在刷新源记录时不会覆盖它们。 | | 描述符 `data` | 是 | 你可以丰富它。 | | `recordType` | 有限 | 您可以将运行时检测到的记录从`AGENT`缩小到的范围。`MCP`任何其他更改（例如对`SKILL``GATEWAY`、或`CUSTOM`）都将被拒绝，网关检测到的记录始终会被拒绝。`GATEWAY` | | 描述符协议（种类） | 否 | 源自源资源；更改被拒绝。 | | 描述符来源 URL | 否 | 源自源资源；您无法对其进行更改或清除。要附加用于同步的凭据提供程序，请为描述符源提供相同的 URL — 请参阅[同步](registry-sync-records.md)记录。 | | `provenance` | 否 | 将记录链接到其源资源；更改被拒绝。 | **注意** 如果源资源的协议稍后发生更改，则自动检测会协调记录的描述符以匹配新协议，然后重置为`AGENT`，`recordType`从而覆盖您所做的缩小范围。您的其他编辑（例如`name`和`description`）将保留。 例如，使用该`MCP`协议检测到的运行时被归类为`recordType``AGENT``mcpServer`描述符，您可以将记录范围缩小为。`MCP`如果稍后更新该运行时以使用该`A2A`协议，则下一次刷新会将`mcpServer`描述符替换为`a2aAgentCard`描述符，并`recordType`从`MCP`返回重置为。`AGENT``name`、`description`、和`recordVersion`您设置的保持不变。 ### 删除自动检测到的记录 启用自动检测后，您无法删除自动检测到`autoDetectionConfiguration.enabled`的`true`记录。 Auto-detection 管理这些记录的生命周期 — 当源资源被删除或成员帐户离开组织时，记录会自动删除。 要手动删除自动检测到的记录，必须先在注册表上禁用自动检测，方法是设置`enabled`为。`false`禁用自动检测后，您可以像删除任何其他记录一样删除自动检测到的记录。 ### 审批 Auto-detected 记录遵循与您手动创建的记录相同的审批工作流程：记录必须处于`APPROVED`状态才能通过注册表的发现 API 和记录目录被发现。如果将注册表配置为自动批准，则无需人工审核即可发现记录；否则，管理人会对其进行审核和批准。有关更多信息，请参阅整[理注册表。](registry-curating.md) 当自动检测刷新您已经批准的记录时（例如，由于源资源的协议已更改），则刷新的内容将作为新`Draft`修订版写入，在获得批准后才能被发现。在此期间，您之前批准的修订版仍可被发现，因此发现不会中断。批准更新的修订版以将其发布 — 如果注册管理机构使用自动批准，则将其提交以供批准立即批准；否则，策展人会对其进行审核和批准。如果刷新未更改源派生字段，则记录将保持不变。 ## 关闭自动检测 ### 在注册表上禁用自动检测 要停止发现资源，请更新注册表以将自动检测设置为`enabled`。`false`必须先禁用自动检测，然后才能删除组织范围内的注册表。 要删除组织范围的注册表，请按顺序完成以下步骤： 1. 在注册表上禁用自动检测。 1. 删除所有注册表记录。 1. 删除注册表。 ``` aws agent-registry-control update-registry \ --registry-id \ --auto-detection-configuration '{"optionalValue":{"scope":"ORGANIZATION","enabled":false}}' \ --region my-region ``` 更新是异步的：注册表移动到更改生效`READY`时`UPDATING`并返回到更改生效时。 ### 取消注册委派管理员或禁用可信访问权限 要删除组织级别的自动检测，管理账户可以取消注册委派的管理员并禁用可信访问权限： ``` aws organizations deregister-delegated-administrator \ --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 错误](registry-troubleshooting.md#registry-troubleshooting-auto-detection)。