全面的注册表迁移指南

Amazon 代理注册表-迁移到新的agent-registry命名空间

简介

作为 2026 年 8 月 6 日新agent-registry命名空间发布的一部分， Amazon Agent Registry 对服务主体、数据和 API 模型进行了重大更改。如果您在bedrock-agentcore命名空间下使用 Amazon Agent Registry，则必须完成跨越三个区域的迁移：

命名空间和配置更改 — 我们正在将 Amazon Agent Registry 从 B Amazon edrock AgentCore 命名空间移至其自己的专用命名空间。此命名空间更改仅适用于 Amazon 代理注册表。所有其他 AgentCore 产品（例如身份、网关、运行时和策略）不受影响。对于 Amazon Agent Registry，服务命名空间从变bedrock-agentcore为agent-registry。这会影响引用该服务的每个表面：终端节点、IAM 策略、SDK 客户端、CLI 命令、资源 ARN 和可观察性集成。您必须更新代码和基础架构才能使用新的命名空间。
API 架构更改 — 注册表和注册表记录数据模型根据来自bedrock-agentcore命名空间的客户反馈进行更新。这些更改破坏了与现有 API 架构的向后兼容性。作为迁移到新命名空间的一部分，必须更新构造或解析 API 请求和响应的应用程序代码以反映新的架构。
数据迁移-您必须将现有的注册表和注册表记录从旧命名空间迁移到新命名空间。我们提供迁移工具来提取您的数据，将其转换为新架构，然后将其加载到新的命名空间中。数据会迁移到同一个账户和区域，只有命名空间会发生变化。

本指南详细介绍了每个领域，并提供了前后示例，以帮助您规划和执行迁移。

迁移时间表是什么？

对于此次迁移，您必须记住两个重要的里程碑：

2026 年 8 月 6 日 — Amazon 代理注册表的新agent-registry命名空间正式启动。在 A Amazon gent Registry 控制台中访问该服务。如果您有现有的注册表和记录，则可以同时访问bedrock-agentcore和agent-registry命名空间。迁移工具可在网站的 agentcore-samples 存储库中找到。 GitHub 您可以开始迁移过程。

注意
如果您是截至 2026 年 8 月 6 日没有现有注册表或记录的新客户，则无法通过命名空间访问 Amazon 代理注册表。bedrock-agentcore直接从agent-registry命名空间开始使用 Amazon 代理注册表。
2026 年 10 月 30 日 — 迁移窗口关闭。旧的bedrock-agentcore命名空间将在此日期关闭。您将无法 read/write 访问该服务以及旧命名空间中的任何剩余数据。在此日期之后，必须使用agent-registry命名空间。

命名空间和配置更改

agent-registry命名空间bedrock-agentcore将在以下位置替换。本节列出了所有变化的表面，并提供了如何更新代码的示例。

重要

命名空间的更改仅影响 Amazon Agent Registry 提供的 API，而不影响 B Amazon edrock 的其余部分 AgentCore，例如 Ident Amazon AgentCore ity。因此，工作负载身份和 OAuth 凭证提供者资源仍位于命名空间下。bedrock-agentcore

服务端点

您的应用程序必须指向新的终端节点主机名。新的终端节点使用该.api.aws域。

Surface	旧值	新值
数据平面端点	`bedrock-agentcore.{region}.amazonaws.com`	`agent-registry.{region}.api.aws`
控制面板端点	`bedrock-agentcore-control.{region}.amazonaws.com`	`agent-registry-control.{region}.api.aws`

IAM 和安全

bedrock-agentcore必须更新引用的所有 IAM 策略、服务控制策略 (SCP) 和权限边界。资源 ARN 也会发生变化以反映新的命名空间。

Surface	旧值	新值
IAM 操作前缀	`bedrock-agentcore:*`	`agent-registry:*`
服务主体	`bedrock-agentcore.amazonaws.com`	`agent-registry.amazonaws.com`
注册机构 ARN	`arn:aws:bedrock-agentcore:{region}:{account}:registry/{id}`	`arn:aws:agent-registry:{region}:{account}:registry/{id}`
记录 ARN	`arn:aws:bedrock-agentcore:{region}:{account}:registry/{id}/record/{rid}`	`arn:aws:agent-registry:{region}:{account}:registry/{id}/record/{rid}`

如果您的自动化功能可以解析或存储 ARN，请同时更新这些引用。必须更新带有 IAM 操作前缀或服务委托人条件的自定义策略以匹配新值。要查看与 Amazon 代理注册表关联的 IAM 权限的完整列表，请参阅Amazon 代理注册表 IAM 权限参考。

注意

如果您当前使用BedrockAgentCoreFullAccess Amazon 托管策略访问 Amazon 代理注册表（请参阅BedrockAgentCoreFullAccess 策略详细信息），则必须将其替换为新的AgentRegistryFullAccess托管策略（2026 年 8 月 6 日推出）。旧的 BedrockAgentCoreFullAccess 托管策略不会更新为包含agent-registry:*权限。

软件开发工具包、CLI 和基础架构

更新您的应用程序代码、部署脚本和基础架构即代码模板以引用新的客户端类和 CLI 命名空间。

Surface	旧值	新值
Dataplane SDK 客户端类	`BedrockAgentCoreClient`	`AgentRegistryClient`
控制平面 SDK 客户端类	`BedrockAgentCoreControlClient`	`AgentRegistryControlClient`
CLI 命名空间	`aws bedrock-agentcore`	`aws agent-registry`
Service Quotas 代码	`bedrock-agentcore`	`agent-registry`

如果您之前在服务代码下请求增加自定义配额，则必须根据bedrock-agentcoreagent-registry服务代码重新申请。

可观察性和事件

更新引用旧命名空间的所有 La CloudTrail ke 查询、Athena 查询、SIEM 集成 EventBridge CloudWatch 、规则、仪表板和警报。

Surface	旧值	新值
CloudTrail 事件源	`bedrock-agentcore.amazonaws.com`	`agent-registry.amazonaws.com`
EventBridge 来源	`aws.bedrock-agentcore`	`aws.agent-registry`
CloudWatch 命名空间	`AWS/BedrockAgentCore`	`AWS/AgentRegistry`

EventBridge 通知

在bedrock-agentcore命名空间下， Amazon 代理注册表在事件源下发出两个 Amazon EventBridge aws.bedrock-agentcore 事件。现在，事件源更改为aws.agent-registry，资源 ARN 采用新的命名空间，通知覆盖范围扩展到完整的注册记录和注册表生命周期。事件继续进入资源自己账户中的默认 EventBridge 总线。您必须更新与旧来源或旧详细信息类型字符串匹配的所有 EventBridge 规则。

Surface	旧值	新值
事件源	`aws.bedrock-agentcore`	`aws.agent-registry`
资源 ARN 命名空间	`arn:aws:bedrock-agentcore:{region}:{account}:registry/…`	`arn:aws:agent-registry:{region}:{account}:registry/…`
事件总线	默认总线	默认总线（未更改）
Registry-record 事件	1 个细节类型 (`Registry Record State changed to Pending Approval`)	5 种详细信息类型（完整的审批生命周期）
注册表事件	1 个细节类型 (`Registry State transitions from Creating to Ready`)	7 种详细信息类型（完整的注册表生命周期）
事件`detail`有效负载	`registryRecordId`，`registryId`（记录）	（不变）

重要

注册表（父级）详细信息类型从句子更改为简短的状态字符串。与详细信息类型匹配的规则Registry State transitions from Creating to Ready不再触发，请将其更新为Registry Ready。注册表记录详细信息类型未更改，因此Registry Record State changed to Pending Approval在您更新注册记录详细信息类型后，与之匹配的规则将继续生效。source

Registry-record 事件。当注册表记录在批准工作流程状态之间转换时发出。 Resources是完整记录 ARN；detail包含registryRecordId和。registryId

细节类型	触发器
`Registry Record State changed to Draft`	录制版本进入 `DRAFT`
`Registry Record State changed to Pending Approval`	`SubmitRegistryRecordForApproval`已调用（未更改）
`Registry Record State changed to Approved`	将过渡记录到 `APPROVED`
`Registry Record State changed to Rejected`	将过渡记录到 `REJECTED`
`Registry Record State changed to Deprecated`	将过渡记录到 `DEPRECATED`

注册表事件。在注册表配置和生命周期过渡时发出。 Resources是完整的注册表 ARN；detail包含registryId和。registryName

细节类型	触发器
`Registry Creating`	注册表进入 `CREATING`
`Registry Ready`	注册表变成 `READY`（替换`bedrock-agentcore`命名空间值`Registry State transitions from Creating to Ready`）
`Registry Create Failed`	注册表进入 `CREATE_FAILED`
`Registry Updating`	注册表进入 `UPDATING`
`Registry Update Failed`	注册表进入 `UPDATE_FAILED`
`Registry Deleting`	注册表进入 `DELETING`
`Registry Delete Failed`	注册表进入 `DELETE_FAILED`

示例事件（注册表记录）。

之前（bedrock-agentcore命名空间，待弃用）：


{
  "version": "0",
  "detail-type": "Registry Record State changed to Pending Approval",
  "source": "aws.bedrock-agentcore",
  "account": "123456789012",
  "region": "us-west-2",
  "resources": ["arn:aws:bedrock-agentcore:us-west-2:123456789012:registry/REG_ID/record/REC_ID"],
  "detail": { "registryRecordId": "REC_ID", "registryId": "REG_ID" }
}

之后（agent-registry命名空间）：


{
  "version": "0",
  "detail-type": "Registry Record State changed to Pending Approval",
  "source": "aws.agent-registry",
  "account": "123456789012",
  "region": "us-west-2",
  "resources": ["arn:aws:agent-registry:us-west-2:123456789012:registry/REG_ID/record/REC_ID"],
  "detail": { "registryRecordId": "REC_ID", "registryId": "REG_ID" }
}

注意

要将任何注册表记录状态更改与单个规则相匹配，请匹配 source (aws.agent-registry) 加上detail-type前缀。Registry Record State changed to要匹配任何注册表生命周期的更改，请匹配 “Registry” 详细信息类型前缀。

示例：更新 IAM 策略

替换所有 IAM 策略中的操作前缀和资源 ARN 命名空间。

之前（bedrock-agentcore命名空间，待弃用）：


{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": [
      "bedrock-agentcore:CreateRegistry",
      "bedrock-agentcore:GetRegistry",
      "bedrock-agentcore:UpdateRegistry",
      "bedrock-agentcore:ListRegistries",
      "bedrock-agentcore:DeleteRegistry",
      "bedrock-agentcore:CreateRegistryRecord",
      "bedrock-agentcore:GetRegistryRecord",
      "bedrock-agentcore:UpdateRegistryRecord",
      "bedrock-agentcore:ListRegistryRecords",
      "bedrock-agentcore:DeleteRegistryRecord",
      "bedrock-agentcore:SubmitRegistryRecordForApproval",
      "bedrock-agentcore:UpdateRegistryRecordStatus",
      "bedrock-agentcore:SearchRegistryRecords"
    ],
    "Resource": ["arn:aws:bedrock-agentcore:us-west-2:123456789012:*"]
  }]
}

之后（agent-registry命名空间）：


{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": [
      "agent-registry:CreateRegistry",
      "agent-registry:GetRegistry",
      "agent-registry:UpdateRegistry",
      "agent-registry:ListRegistries",
      "agent-registry:DeleteRegistry",
      "agent-registry:CreateRegistryRecord",
      "agent-registry:GetRegistryRecord",
      "agent-registry:UpdateRegistryRecord",
      "agent-registry:ListRegistryRecords",
      "agent-registry:DeleteRegistryRecord",
      "agent-registry:SubmitRegistryRecordForApproval",
      "agent-registry:UpdateRegistryRecordStatus",
      "agent-registry:SearchDiscoverableRegistryRecords",
      "agent-registry:ListDiscoverableRegistryRecords",
      "agent-registry:GetDiscoverableRegistryRecord"
    ],
    "Resource": ["arn:aws:agent-registry:us-west-2:123456789012:*"]
  }]
}

注意

BatchGetDiscoverableRegistryRecordAPI 没有自己的 IAM 操作。它授权每条请求的记录针对该agent-registry:GetDiscoverableRegistryRecord操作。确保您的保单包括GetDiscoverableRegistryRecord使用BatchGet。

重要

工作负载身份和 OAuth 凭证提供者资源仍位于命名空间下。bedrock-agentcore如果您的注册管理机构使用带有 OAuth 或 IAM 凭证的 URL sync (source.fromUrl)，则除了新权限外，您还必须保留以下权限：agent-registry:*


"bedrock-agentcore:CreateWorkloadIdentity",
"bedrock-agentcore:GetWorkloadIdentity",
"bedrock-agentcore:DeleteWorkloadIdentity"

不要替换所有bedrock-agentcore操作——这些身份资源会故意保留旧的命名空间。

示例：更新 SDK 客户端配置

更新 SDK 调用中的服务名称、客户端类和终端节点 URL。

之前（bedrock-agentcore命名空间，待弃用）：


import boto3

session = boto3.Session(region_name="us-west-2")

cp_client = session.client(
    "bedrock-agentcore-control",
    endpoint_url="https://bedrock-agentcore-control.us-west-2.amazonaws.com"
)

dp_client = session.client(
    "bedrock-agentcore",
    endpoint_url="https://bedrock-agentcore.us-west-2.amazonaws.com"
)

之后（agent-registry命名空间）：


import boto3

session = boto3.Session(region_name="us-west-2")

cp_client = session.client(
    "agent-registry-control",
    endpoint_url="https://agent-registry-control.us-west-2.api.aws"
)

dp_client = session.client(
    "agent-registry",
    endpoint_url="https://agent-registry.us-west-2.api.aws"
)

示例：更新 CLI 命令

替换所有脚本和自动化中的 CLI 命名空间。

之前（bedrock-agentcore命名空间，待弃用）：


aws bedrock-agentcore-control create-registry \
    --name "MyRegistry" \
    --description "Production registry" \
    --region us-west-2 \
    --endpoint-url https://bedrock-agentcore-control.us-west-2.amazonaws.com

之后（agent-registry命名空间）：


aws agent-registry-control create-registry \
    --name "MyRegistry" \
    --description "Production registry" \
    --region us-west-2 \
    --endpoint-url https://agent-registry-control.us-west-2.api.aws

API 架构变更

除了命名空间迁移外，我们还更新了agent-registry命名空间中的注册表和注册表记录数据模型。这些更改根据bedrock-agentcore命名空间的反馈提高了 API 的一致性和可扩展性。本节通过之前和之后的示例介绍了每个更改类别，因此您可以更新应用程序代码。

更改 1：注册表实体更新

注册表资源上的授权配置（控制如何访问注册表的数据平面）现在位于专用discoveryConfiguration封装器下，该封装器明确了其用途。批准配置（控制提交到PENDING_APPROVAL状态的记录是否自动转换为APPROVED状态）从布尔值变为可扩展的枚举数组。

具体的字段变化是：

authorizerType并authorizerConfiguration被移动到一个新discoveryConfiguration对象内。
approvalConfiguration.autoApproval（布尔值）替换为approvalConfiguration.autoApprovalRules（枚举字符串数组）。该值"APPROVE_ALL"的语义含义与相同。autoApproval: true将应用枚举列表中指定的规则。未指定（空）表示需要批准。

之前（bedrock-agentcore命名空间，待弃用）：


{
  "name": "string",
  "description": "string",
  "authorizerConfiguration": { ... },
  "authorizerType": "string",
  "approvalConfiguration": {
    "autoApproval": true
  }
}

之后（agent-registry命名空间）：全部获得批准


{
  "name": "string",
  "description": "string",
  "discoveryConfiguration": {
    "authorizerConfiguration": { ... },
    "authorizerType": "string"
  },
  "approvalConfiguration": {
    "autoApprovalRules": ["APPROVE_ALL"]
  }
}

之后（agent-registry命名空间）：枚举列表中为 NULL


{
  "name": "string",
  "description": "Registry with manual approval only",
  "approvalConfiguration": {
    "autoApprovalRules": []
  }
}

更改 2：注册表记录上新的必填字段

注册表记录增加了两个新的必填顶级字段，以支持更好的分类和重复数据删除。使用 CreateRegistryRecord API 创建注册表记录时，必须同时指定这两个字段，以后可以使用 UpdateRegistryRecord API 对其进行更改。

字段	类型	说明
`name`	字符串（必填）	注册表中的唯一标识符，可以由客户指定。每条记录在注册表中都必须有一个唯一的名称。当还`recordVersion`存在时，`name`和的组合`recordVersion`必须是唯一的。
`recordType`	枚举（必填）	记录的语义类型。有效值：`AGENT`、`MCP`、`SKILL`、`CUSTOM`。确定哪个主描述符键在下`descriptors`有效。您可以使用`ListRegistryRecords`和`SearchDiscoverableRegistryRecords`之类的 API 按此语义类型筛选结果。

变动 3：注册表记录重组

该descriptors字段从区分式联合变为扁平键控结构。

在之前的模型中，descriptorType字段（MCP、A2A、AGENT_SKILLS、CUSTOM）决定了内部形状。这种描述符内容与粗略的协议或格式分类相结合。该字段已不存在。 recordType，一个单独的顶级属性，用于语义分类，取而代之。API 在运行时为每个密钥强制执行有效的描述符密钥，而不是recordType在形状上强制执行有效的描述符密钥。descriptors现在，下面的每个顶级键都代表一种精细的主描述符类型（例如、、a2aAgentCardmcpServeragentSkillsDefinition、custom）。补充描述符（例如tools，skillMd）嵌套在主描述符的下面。additionalData该inlineContent字段变成data。schemaVersion和protocolVersion字段合并为dataSchemaVersion。

顶级synchronizationConfiguration属性变为每个描述符（包括additionalData子项）source并在其中移动。

现有name字段变成displayName，使其含义更加明确。net-new name 字段用作重复数据删除密钥，并且在注册表中的所有记录中必须是唯一的。如果recordVersion为同一条记录同时指定name和，则它们的组合必须是唯一的。

以下字段已重命名：

Before	晚于	注意
`name`	`displayName`	记录的显示名称。还将有一个新`name`字段，即重复数据删除密钥。
`descriptorType`	已删除	替换为顶级`recordType`字段。
`inlineContent`	`data`	每个描述符中的内容负载。
`schemaVersion` / `protocolVersion`	`dataSchemaVersion`	所有描述符类型的统一版本字段。
`synchronizationConfiguration`	`source`	在每个描述符（包括`additionalData`子项）内移动。

之前（bedrock-agentcore命名空间，待弃用）：


{
  "recordId": "string",
  "name": "string",
  "descriptorType": "string", // A2A, MCP, AGENT_SKILL, CUSTOM
  "descriptors": {
    "agent": {
      "a2aAgentCard": {
        "inlineContent": "string",
        "schemaVersion": "string"
      }
    },
    "agentSkills": {
      "skillDefinition": {
        "inlineContent": "string",
        "schemaVersion": "string"
      },
      "skillMd": {
        "inlineContent": "string"
      }
    },
    "mcp": {
      "server": {
        "inlineContent": "string",
        "schemaVersion": "string"
      },
      "tools": {
        "inlineContent": "string",
        "protocolVersion": "string"
      }
    },
    "custom": {
      "inlineContent": "string"
    }
  },
  "synchronizationType": "URL",
  "synchronizationConfiguration": {
    "fromUrl": {
      "url": "string",
      "credentialProviderConfigurations": [
        {
          "credentialProvider": { ... },
          "credentialProviderType": "string"
        }
      ]
    }
  },
  ...
}

之后（agent-registry命名空间）：


{
  "recordId": "string",
  "displayName": "string",
  "name": "string",
  "recordVersion": "string",
  "recordType": "AGENT" | "MCP" | "SKILL" | "CUSTOM",
  "descriptors": {
    "a2aAgentCard": {
      "data": "string",
      "dataSchemaVersion": "string",
      "source": { "fromUrl": { "url": "string", "credentialProviderConfigurations": [...] } }
    },
    "mcpServer": {
      "data": "string",
      "dataSchemaVersion": "string",
      "source": { "fromUrl": { ... } },
      "additionalData": {
        "tools": { "data": "string", "dataSchemaVersion": "string" }
      }
    },
    "agentSkillsDefinition": {
      "data": "string",
      "dataSchemaVersion": "string",
      "additionalData": {
        "skillMd": { "data": "string", "dataSchemaVersion": "string", "source": { "fromUrl": { ... } } }
      }
    },
    "custom"?: {
      "data": "string"
    }
  }
  ...
}

以下限制适用：

每条记录只能填充一个主描述符键。有效的主描述符recordType为：

代理:a2aAgentCard,mcpServer, custom
MCP:mcpServer, custom
技能:agentSkillsDefinition, custom
自定义：custom

source是每个描述符而不是单个顶级块。它附加到架构中带有source字段的描述符上 — mcpServer 和。a2aAgentCardtools孩子（下方mcpServer.additionalData）、agentSkillsDefinition父母和custom描述符带有 no source。

在agent-registry命名空间中，source.fromUrl仅支持。

Auto-synchronization 仅针对mcpServer和a2aAgentCard主要描述符（即 MCP 和 AGENT 记录类型）触发。skillMd子项source上的 A 会保持不变，但不用于运行同步，并且无法自动同步技能记录。必须通过data直接提供手动创建自定义记录。

更改 4：数据平面过滤器更新

SearchRegistryRecords变成 SearchDiscoverableRegistryRecords (POST /discoverable-records-search)。它的请求和响应采用了新的字段名称和数据模型：

筛选依据recordType（替换descriptorType）。
筛选依据recordVersion（替换version）。
响应以新格式返回描述符，不credentialProviderConfigurations带。

MCP 搜索工具search_registry_records变成search_discoverable_registry_records，返回新的描述符格式，并使用新的过滤器名称。

第 5 项更改：新的浏览 API

两个新的数据平面 API 支持在已批准的记录上构建浏览和目录体验。这些 API 不需要任何显式迁移；我们在此提及它们是agent-registry命名空间中 Amazon Agent Registry API 模型的补充。

ListDiscoverableRegistryRecords— 返回已批准的注册表记录的分页列表。使用它来构建浏览已发布内容的界面。


// HTTP: POST /registries/{registryId}/discoverable-records-list
{
  "registryId": "string",           // path param, required (ARN or ID)
  "maxResults": 1-100,              // query param, optional
  "nextToken": "string",            // query param, optional
  "filters": [ { "name": "recordType", "values": ["MCP"] } ]
}
{
  "registryRecords": [
    {
      "registryArn": "string",
      "recordArn": "string",
      "recordId": "string",
      "name": "string",
      "displayName": "string",
      "description": "string",
      "recordType": "string",
      "recordVersion": "string",
      "status": "string",
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "nextToken": "string"
}

BatchGetDiscoverableRegistryRecord— 一次调用即可检索一个或多个注册表中一批记录的完整详细信息。


// HTTP: POST /discoverable-records-batch
{
  "entries": [
    { "registryId": "reg-AAA", "recordIds": ["rec-111", "rec-222"] }
  ]
}
{
  "registryRecords": [
    {
      "registryArn": "string",
      "recordArn": "string",
      "recordId": "string",
      "name": "string",
      "displayName": "string",
      "description": "string",
      "recordType": "string",
      "descriptors": { ... },
      "recordVersion": "string",
      "status": "string",
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "errors": [
    {
      "registryId": "string",
      "recordId": "string",
      "errorCode": "RESOURCE_NOT_FOUND" | "ACCESS_DENIED" | "INTERNAL_ERROR",
      "message": "string"
    }
  ]
}

响应包括一个包含完整记录详细信息的registryRecords数组和一个用于存errors放任何无法检索的记录的数组。

启动时，只接受一个条目（一个注册表，1-100 个记录 ID）。分组的形状与 future 版本中的跨注册表批处理向前兼容。

第 6 项更改：列表 API 采用结构化筛选器参数

在bedrock-agentcore命名空间中，List API 将每个可筛选字段作为自己的查询参数公开（例如--status READY，--recordType MCP）。在agent-registry命名空间中，单个结构化filters参数取代了这些离散参数。该filters值是{ "name": "<dotted.path>", "values": ["<value>"] }条目列表，其中name以点分隔的属性路径。新的可筛选字段（包括嵌套字段）将成为新的name路径，而不是新的 API 参数。列表操作也从变GET为POST。分页参数 (maxResults,nextToken) 保持不变。

之前（bedrock-agentcore命名空间，待弃用）：


GET /registries?status=READY&authorizerType=AWS_IAM
GET /registries/{registryId}/records?name=my-agent&status=APPROVED&recordType=MCP

之后（agent-registry命名空间）：


// ListRegistries
// POST /registries-list
{
  "filters": [
    { "name": "status", "values": ["READY"] },
    { "name": "discoveryConfiguration.authorizerType", "values": ["AWS_IAM"] }
  ],
  "maxResults": 100,
  "nextToken": "string"
}

// ListRegistryRecords
// POST /registries/{registryId}/records-list
{
  "filters": [
    { "name": "name", "values": ["my-agent"] },
    { "name": "status", "values": ["APPROVED"] },
    { "name": "recordType", "values": ["MCP"] }
  ],
  "maxResults": 100,
  "nextToken": "string"
}

数据迁移

您必须将现有的注册表和注册表记录从命名空间迁移到bedrock-agentcore命名agent-registry空间。我们提供迁移工具来协助迁移。该工具处理现有数据的提取、从旧架构到新架构的转换，以及加载到新命名空间中的注册表中。该工具在同一账户和区域内的agent-registry命名空间中创建新的注册表。它会将所有现有记录从旧注册表迁移到新注册表，同时考虑到命名空间和 API 架构的变化。

该迁移工具可在网站上的 agentcore-samples 存储库中找到。 GitHub 有关完整的设置说明、命令参考和操作指南，请参阅存储库 README。

选择您的迁移方法

正确的方法取决于一次性完全迁移是否足够，或者您是否需要无人值守的执行以及在转换时运行增量负载的能力。

案例 1：简单迁移

配置文件：一次性完全迁移就足够了。您无需运行增量加载或让作业在无人看管的情况下运行。
方法：直接从终端运行迁移工具，或者 Amazon CloudShell。无需部署基础架构。该工具连接到bedrock-agentcore命名空间，提取您的注册表和记录，将数据转换为agent-registry架构，然后在新命名空间中创建它们。这是最简单的方法，不需要部署基础架构。

案例 2：托管迁移 Amazon 连接词

配置文件：您更喜欢无人值守执行，或者您计划在一段时间内并行运行两个注册表版本，并且需要在直接转换时进行增量加载，以捕获在初始完全运行后在bedrock-agentcore命名空间中创建或更新的任何记录。
方法：使用提供的 CDK 堆栈将 Amazon 迁移作为 Glue 任务部署。这些任务在您的账户中运行，无需依赖于打开的终端会话。

典型的流程是：运行完整迁移以更新agent-registry命名空间，然后在验证和更新集成的同时并行操作两个命名空间。准备好切换时，运行增量加载以同步并行期间更改的所有记录，进行验证，然后将流量切换到agent-registry命名空间。

案例 3： Active-active 迁移

简介：您已经在bedrock-agentcore命名空间 API 之上构建了平台或自动化管道，并且在生产环境中不断编写新记录。
方法：从使用托管 Amazon Glue-based 方法进行全面迁移开始，将所有历史数据导入agent-registry命名空间。然后将您的平台或管道指向除agent-registry命名空间之外的bedrock-agentcore命名空间——您的应用程序同时向两者写入数据。使用这个活跃-活跃期来验证您的集成并建立对命名空间的信心。agent-registry满意后，切断所有对命名空间的读取和写入agent-registry并停用bedrock-agentcore命名空间集成。

验证您的迁移

运行迁移后，请确认您的数据已正确迁移：

使用 list-registries CLI 命令列出新命名空间中的所有注册表，并确认计数与您的来源相匹配。
对于每个注册表，使用比较记录数list-registry-records。
Spot-check 用于确认描述符已正确转换的单个记录（字段重命名、描述符重组）。
按照命名空间和配置更改部分中所述更新您的 IAM 策略、终端节点和 SDK 客户端。
使用新的命名空间，验证您的应用程序是否可以成功读取和写入。

更新同步记录的 IAM 信任策略

如果您的任何注册表记录使用与 IAM 角色凭证类型同步，则必须在运行实时加载之前更新该角色的信任策略。在新命名空间agent-registry.amazonaws.com中，担任该角色bedrock-agentcore.amazonaws.com的服务主体从变为。使用 OAuth 凭据或未授权的记录不受影响。

注意

迁移工具无法检测到这一点 — 该工具从不担任同步角色。创建记录后，注册表服务会异步假设它。如果跳过此步骤，则迁移的记录将到达指向同一角色的agent-registry命名空间，并且在该角色信任新的主体之前，同步将失败。

更新每条受影响记录所引用的角色的信任策略。

之前（bedrock-agentcore命名空间，待弃用）：


{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": { "Service": "bedrock-agentcore.amazonaws.com" },
      "Action": "sts:AssumeRole"
    }
  ]
}

之后（agent-registry命名空间）：


{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": { "Service": "agent-registry.amazonaws.com" },
      "Action": "sts:AssumeRole"
    }
  ]
}

如果某条记录由于此原因已经失败，则迁移的记录将处于CREATE_FAILED状态。迁移工具拒绝覆盖处于失败状态的记录，因此仅修复信任策略并不能解决问题。要恢复：

更新受影响角色的信任策略。
从agent-registry命名空间中删除CREATE_FAILED记录。
Re-run 负荷。

常见问题解答

发生了什么变化 Amazon 代理注册表？

Amazon 代理注册表正在从bedrock-agentcore命名空间移至新的专用agent-registry命名空间。迁移跨三个领域：命名空间和配置更改（终端节点、IAM、SDK、CLI、ARN、可观察性）、API 架构更改（注册表和记录的重构数据模型）和数据迁移（将现有注册表和记录移至新的命名空间）。

我能否继续在 b `edrock-agentc` ore 命名空间上使用 Registry？

在迁移窗口期间，您在bedrock-agentcore命名空间上的现有注册表使用将继续正常运行，不会中断。但是，我们建议您在工具可用后立即开始迁移，以确保您有足够的时间完成数据迁移和代码更新。

但是，如果您在 2026 年 8 月 6 日之前没有现有的注册表或记录，则从 2026 年 8 月 6 日起，您将无法访问 Amazon 代理注册表的bedrock-agentcore命名空间。如果您在 2026 年 8 月 6 日之前已有注册表或记录，则可以在迁移时段（2026 年 8 月 6 日至 2026 年 10 月 30 日）访问 Amazon 代理注册表的bedrock-agentcore命名空间。

我的数据会自动迁移吗？

不是。您必须使用我们提供的迁移工具自行启动迁移。有关基于您的规模的可用方法的详细信息，请参阅数据迁移部分。

包括哪些 API 架构更改？

除了命名空间的更改外，我们还更新了六个方面的 API 数据模型：注册表实体（授权配置分组在下面discoveryConfiguration）、注册表记录新字段（name和recordType）、注册表记录重组（描述符扁平化、字段重命名）、搜索 API 筛选器更新（recordType、recordVersion）、新的浏览 API（ListDiscoverableRegistryRecords、BatchGetDiscoverableRegistryRecord）和列表操作的结构化筛选器。

数据迁移需要多长时间？

迁移时间取决于您账户中注册表和记录的数量。对于记录少于 100 的账户，在本地运行时，迁移将在几分钟内完成。对于拥有数千条记录的账户，作为托管作业运行时，预计迁移将在不到 15 分钟的时间内完成。

如果我的大规模部署采用主动写入操作会怎样？

如果您在生产环境中主动向bedrock-agentcore命名空间写入数据，请使用案例 3 中所述的主动-主动迁移方法。首先进行全面迁移以更新agent-registry命名空间，然后同时写入两个命名空间，以验证您的集成并建立对新命名空间的信心。准备就绪agent-registry后，切断读写操作。

我在哪里可以得到帮助？

如果您对迁移有任何疑问或需要帮助，请联系 Supp Amazon ort。

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

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

问题排查

AgentCore CLI 参考

全面的注册表迁移指南

简介

迁移时间表是什么？

注意

命名空间和配置更改

重要

服务端点

IAM 和安全

注意

软件开发工具包、CLI 和基础架构

可观察性和事件

EventBridge 通知

重要

注意

示例：更新 IAM 策略

注意

重要

示例：更新 SDK 客户端配置

示例：更新 CLI 命令

API 架构变更

更改 1：注册表实体更新

更改 2：注册表记录上新的必填字段

变动 3：注册表记录重组

更改 4：数据平面过滤器更新

第 5 项更改：新的浏览 API

第 6 项更改：列表 API 采用结构化筛选器参数

数据迁移

选择您的迁移方法

案例 1：简单迁移

案例 2：托管迁移 Amazon 连接词

案例 3： Active-active 迁移

验证您的迁移

更新同步记录的 IAM 信任策略

注意

常见问题解答

发生了什么变化 Amazon 代理注册表？

我能否继续在 b edrock-agentc ore 命名空间上使用 Registry？

我的数据会自动迁移吗？

包括哪些 API 架构更改？

数据迁移需要多长时间？

如果我的大规模部署采用主动写入操作会怎样？

我在哪里可以得到帮助？

我能否继续在 b `edrock-agentc` ore 命名空间上使用 Registry？