# 포괄적인 레지스트리 마이그레이션 가이드
* AWS 에이전트 레지스트리 - 퍼블릭 미리 보기에서 일반 가용성으로 마이그레이션*
## 소개
2026년 8월 6일에 정식 출시(GA)의 일환으로 AWS 에이전트 레지스트리는 서비스 보안 주체, 데이터 및 API 모델에 상당한 변경 사항을 도입하고 있습니다. 공개 미리 보기 중에 AWS 에이전트 레지스트리를 사용한 경우 다음 세 영역에 걸친 마이그레이션을 완료해야 합니다.
1. **네임스페이스 및 구성 변경** - AWS Bedrock AWS AgentCore 네임스페이스에서 자체 전용 네임스페이스로 에이전트 레지스트리를 이동하고 있습니다. 이 네임스페이스 변경은 AWS 에이전트 레지스트리에만 적용됩니다. Identity, Gateway, Runtime 및 Policy와 같은 다른 모든 AgentCore 상품은 영향을 받지 않습니다. AWS 에이전트 레지스트리의 경우 서비스 네임스페이스가에서 `bedrock-agentcore`로 변경됩니다`agent-registry`. 이는 엔드포인트, IAM 정책, SDK 클라이언트, CLI 명령, 리소스 ARNs, 관찰성 통합 등 서비스를 참조하는 모든 표면에 영향을 미칩니다. 새 네임스페이스를 사용하려면 코드와 인프라를 업데이트해야 합니다.
1. **API 스키마 변경 **- 레지스트리 및 레지스트리 레코드 데이터 모델은 공개 미리 보기 중 고객 피드백을 기반으로 업데이트됩니다. 이러한 변경 사항은 기존 API 스키마와의 이전 버전과의 호환성을 깨뜨립니다. API 요청 및 응답을 구성하거나 구문 분석하는 애플리케이션 코드는 새 네임스페이스로 마이그레이션하는 과정에서 새 스키마를 반영하도록 업데이트해야 합니다.
1. **데이터 마이그레이션** - 기존 레지스트리 및 레지스트리 레코드를 이전 네임스페이스에서 새 네임스페이스로 마이그레이션해야 합니다. 데이터를 추출하고, 새 스키마로 변환하고, 새 네임스페이스에 로드하는 마이그레이션 도구를 제공합니다. 데이터는 동일한 계정 및 리전으로 마이그레이션되며 네임스페이스만 변경됩니다.
이 가이드에서는 마이그레이션을 계획하고 실행하는 데 도움이 되는 before-and-after 예제와 함께 각 영역을 자세히 다룹니다.
## 마이그레이션 타임라인이란 무엇입니까?
이 마이그레이션을 위해 기억해야 할 두 가지 중요한 마일스톤이 있습니다.
+ **2026년 8월 6일 **- AWS 에이전트 레지스트리가 정식 출시되고 새 `agent-registry` 네임스페이스가 공식적으로 시작됩니다. 기존 레지스트리 및 레코드가 있는 경우 `bedrock-agentcore` 및 `agent-registry` 네임스페이스에 동시에 액세스할 수 있습니다. 마이그레이션 도구는 [agentcore-samples GitHub 리포지토리](https://github.com/awslabs/agentcore-samples)에서 사용할 수 있게 됩니다. 마이그레이션 프로세스를 시작할 수 있습니다.
**참고**
2026년 8월 6일부터 기존 레지스트리 또는 레코드가 없는 신규 고객은 `bedrock-agentcore` 네임스페이스를 통해 AWS Agent Registry에 액세스할 수 없습니다. `agent-registry` 네임스페이스에서 직접 AWS 에이전트 레지스트리 사용을 시작합니다.
+ **2026년 9월 17일 **- 마이그레이션 기간이 종료됩니다. 이 날짜에 이전 `bedrock-agentcore` 네임스페이스가 종료됩니다. 서비스 및 이전 네임스페이스의 나머지 데이터에 대한 읽기/쓰기 액세스 권한을 잃게 됩니다. 이 날짜 이후에는 `agent-registry` 네임스페이스를 사용해야 합니다.
## 네임스페이스 및 구성 변경
`agent-registry` 네임스페이스는 다음 위치에서 `bedrock-agentcore`를 대체합니다. 이 섹션에서는 변경되는 모든 표면을 나열하고 코드를 업데이트하는 방법에 대한 예를 제공합니다.
**중요**
네임스페이스 변경 사항은 AWS Agent Registry에서 제공하는 APIs에만 영향을 미치며,AgentCore 자격 증명과 같은 나머지 AWS Bedrock AgentCore에는 영향을 미치지 않습니다. AgentCore AWS AgentCore 따라서 워크로드 자격 증명 및 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 및 보안
참조하는 모든 IAM 정책, 서비스 제어 정책(SCPs) 및 권한 경계를 업데이트해야 `bedrock-agentcore` 합니다. 리소스 ARNs 새 네임스페이스를 반영하도록 변경됩니다.
| 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}` |
ARNs 구문 분석하거나 저장하는 자동화가 있는 경우 해당 참조도 업데이트합니다. IAM 작업 접두사 또는 서비스 보안 주체에 대한 조건이 있는 사용자 지정 정책을 새 값과 일치하도록 업데이트해야 합니다. AWS 에이전트 레지스트리와 연결된 IAM 권한의 전체 목록을 보려면 [AWS 에이전트 레지스트리 IAM 권한 참조](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/registry-iam-permissions.html)를 참조하세요.
**참고**
현재 AWS 에이전트 레지스트리 액세스에 [BedrockAgentCoreFullAccess](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/BedrockAgentCoreFullAccess.html) AWS 관리형 정책을 사용하는 경우( [BedrockAgentCoreFullAccess 정책 세부 정보](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/security-iam-awsmanpol.html#security-iam-awsmanpol-BedrockAgentCoreFullAccess) 참조) 새 **AgentRegistryFullAccess** 관리형 정책(GA에서 사용 가능)으로 교체해야 합니다. 이전 BedrockAgentCoreFullAccess 관리형 정책은 `agent-registry:*` 권한을 포함하도록 업데이트되지 **않습니다**.
### SDK, CLI 및 인프라
새 클라이언트 클래스 및 CLI 네임스페이스를 참조하도록 애플리케이션 코드, 배포 스크립트 및 infrastructure-as-code 템플릿을 업데이트합니다.
| Surface | 이전 값 | 새 값 |
| --- | --- | --- |
| Dataplane SDK 클라이언트 클래스 | `BedrockAgentCoreClient` | `AgentRegistryClient` |
| Controlplane SDK 클라이언트 클래스 | `BedrockAgentCoreControlClient` | `AgentRegistryControlClient` |
| CLI 네임스페이스 | `aws bedrock-agentcore` | `aws agent-registry` |
| Service Quotas 코드 | `bedrock-agentcore` | `agent-registry` |
이전에 `bedrock-agentcore` 서비스 코드에서 사용자 지정 할당량 증가를 요청한 경우에서 다시 요청해야 합니다`agent-registry`.
### 관찰성 및 이벤트
이전 네임스페이스를 참조하는 CloudTrail Lake 쿼리, 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` |
### 예: IAM 정책 업데이트
모든 IAM 정책에서 작업 접두사와 리소스 ARN 네임스페이스를 바꿉니다.
**이전(공개 미리 보기):**
```
{
"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:*"]
}]
}
```
**이후(일반 가용성):**
```
{
"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:*"]
}]
}
```
**참고**
`BatchGetDiscoverableRegistryRecord` API에는 자체 IAM 작업이 없습니다. 작업에 대해 요청된 각 레코드에 권한을 부여합니다`agent-registry:GetDiscoverableRegistryRecord`. 정책에를 사용하도록 `GetDiscoverableRegistryRecord`가 포함되어 있는지 확인합니다`BatchGet`.
**중요**
워크로드 자격 증명 및 OAuth 자격 증명 공급자 리소스는 `bedrock-agentcore` 네임스페이스 아래에 남아 있습니다. 레지스트리가 OAuth 또는 IAM 자격 증명과 URL 동기화(`source.fromUrl`)를 사용하는 경우 새 권한과 함께 다음 `agent-registry:*` 권한을 유지해야 합니다.
```
"bedrock-agentcore:CreateWorkloadIdentity",
"bedrock-agentcore:GetWorkloadIdentity",
"bedrock-agentcore:DeleteWorkloadIdentity"
```
모든 `bedrock-agentcore` 작업을 대체하지 마십시오. 이러한 자격 증명 리소스는 의도적으로 이전 네임스페이스를 유지합니다.
### 예: SDK 클라이언트 구성 업데이트
SDK 호출에서 서비스 이름, 클라이언트 클래스 및 엔드포인트 URL을 업데이트합니다.
**이전(공개 미리 보기):**
```
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"
)
```
**이후(일반 가용성):**
```
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 네임스페이스를 바꿉니다.
**이전(공개 미리 보기):**
```
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
```
**이후(일반 가용성):**
```
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 스키마 변경 사항
네임스페이스 마이그레이션 외에도 일반 가용성에 대한 레지스트리 및 레지스트리 레코드 데이터 모델을 업데이트했습니다. 이러한 변경 사항은 공개 미리 보기의 피드백을 기반으로 API의 일관성과 확장성을 개선합니다. 이 섹션에서는 애플리케이션 코드를 업데이트할 수 있도록 이전 및 이후 예제가 포함된 각 변경 범주를 다룹니다.
### 변경 1: 레지스트리 엔터티 업데이트
레지스트리의 데이터 영역에 액세스하는 방법을 제어하는 레지스트리 리소스의 권한 부여 구성은 이제 목적을 명시적으로 만드는 전용 `discoveryConfiguration` 래퍼 아래에 배치됩니다. 승인 구성(`PENDING_APPROVAL`상태에 제출된 레코드가 `APPROVED` 자동으로 상태로 전환되는지 여부를 제어)은 부울에서 확장 가능한 열거형 배열로 이동합니다.
특정 필드 변경 사항은 다음과 같습니다.
+ `authorizerType` 및 `authorizerConfiguration`는 새 `discoveryConfiguration` 객체 내부로 이동합니다.
+ `approvalConfiguration.autoApproval` (부울)은 `approvalConfiguration.autoApprovalRules` ( 열거형 문자열 배열)로 대체됩니다. 값은와 의미`"APPROVE_ALL"`가 동일합니다`autoApproval: true`. 열거형 목록에 지정된 규칙이 적용됩니다. (null)을 지정하지 않으면 승인이 필요합니다.
**이전(공개 미리 보기):**
```
{
"name": "string",
"description": "string",
"authorizerConfiguration": { ... },
"authorizerType": "string",
"approvalConfiguration": {
"autoApproval": true
}
}
```
**이후(일반 가용성): Approval ALL 사용**
```
{
"name": "string",
"description": "string",
"discoveryConfiguration": {
"authorizerConfiguration": { ... },
"authorizerType": "string"
},
"approvalConfiguration": {
"autoApprovalRules": ["APPROVE_ALL"]
}
}
```
**이후(일반 가용성): 열거형 목록에 NULL 포함**
```
{
"name": "string",
"description": "Registry with manual approval only",
"approvalConfiguration": {
"autoApprovalRules": []
}
}
```
### 변경 2: 레지스트리 레코드의 새 필수 필드
레지스트리 레코드는 더 나은 분류 및 중복 제거를 지원하기 위해 두 개의 새로운 필수 최상위 필드를 얻습니다. `CreateRegistryRecord` API를 사용하여 레지스트리 레코드를 생성할 때 두 필드를 모두 지정해야 하며 나중에 `UpdateRegistryRecord` API를 사용하여 변경할 수 있습니다.
| Field | 유형 | 설명 |
| --- | --- | --- |
| `name` | 문자열(필수) | 레지스트리 내의 고유 식별자로, 고객이 지정할 수 있습니다. 모든 레코드는 레지스트리에 고유한 이름을 가져야 합니다. `recordVersion` 도 있는 경우 `name` 및의 조합은 고유해야 `recordVersion` 합니다. |
| `recordType` | 열거형(필수) | 레코드의 의미 체계 유형입니다. 유효한 값: `AGENT`, `MCP`, `SKILL`, `CUSTOM`. 에서 유효한 기본 설명자 키를 결정합니다`descriptors`. `ListRegistryRecords` 및와 같은 APIs 사용하여이 의미 체계 유형을 기준으로 결과를 필터링`SearchDiscoverableRegistryRecords`할 수 있습니다. |
### 변경 3: 레지스트리 레코드 재구성
`descriptors` 필드는 구분된 조합에서 플랫 키 구조로 변경됩니다.
이전 모델에서 `descriptorType` 필드(`MCP`, `A2A`, `AGENT_SKILLS`, `CUSTOM`)가 내부 셰이프를 결정했습니다. 이 결합된 설명자 콘텐츠는 대략적인 프로토콜 또는 형식 분류에 적용됩니다. 이 필드는 더 이상 존재하지 않습니다. 별도의 최상위 속성`recordType`인가 의미 체계 분류를 대체합니다. API는 구조적으로 셰이프가 아닌 런타임 `recordType` 시 각에 대해 유효한 설명자 키를 적용합니다. `descriptors` 이제 아래의 각 최상위 키는 세분화된 기본 설명자 유형(예: , `a2aAgentCard``mcpServer`, `agentSkillsDefinition`, `custom`)을 나타냅니다. 보조 설명자(예: , `tools``skillMd`)는 기본 설명자의 아래에 중첩됩니다`additionalData`. `inlineContent` 필드는이 됩니다`data`. `schemaVersion` 및 `protocolVersion` 필드는 로 통합됩니다`dataSchemaVersion`.
최상위 `synchronizationConfiguration` 속성은 각 설명자(`additionalData`하위 포함) 내에서가 `source` 되고 이동합니다.
기존 `name` 필드는가 `displayName`되어 의미를 보다 명시적으로 만듭니다. net-new `name` 필드는 중복 제거 키 역할을 하며 레지스트리의 모든 레코드에서 고유해야 합니다. 동일한 레코드`recordVersion`에 대해 `name` 및를 모두 지정하는 경우 이들의 조합은 고유해야 합니다.
다음 필드의 이름이 변경되었습니다.
| Before | After | 참고 |
| --- | --- | --- |
| `name` | `displayName` | 레코드의 표시 이름입니다. 중복 제거 키인 새 `name` 필드도 있습니다. |
| `descriptorType` | 제거됨 | 최상위 `recordType` 필드로 대체됩니다. |
| `inlineContent` | `data` | 각 설명자 내의 콘텐츠 페이로드입니다. |
| `schemaVersion` / `protocolVersion` | `dataSchemaVersion` | 모든 설명자 유형에 대한 통합 버전 필드입니다. |
| `synchronizationConfiguration` | `source` | 각 설명자(`additionalData`하위 포함) 내에서 이동되었습니다. |
**이전(공개 미리 보기):**
```
{
"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"
}
]
}
},
...
}
```
**이후(일반 가용성):**
```
{
"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"
}
},
"metadata": Document
...
}
```
다음과 같은 제약이 적용됩니다.
레코드당 정확히 하나의 기본 설명자 키를 채울 수 있습니다. 당 유효한 기본 설명자는 다음과 `recordType` 같습니다.
+ **에이전트:** `a2aAgentCard`, `mcpServer`, `custom`
+ **MCP:** `mcpServer`, `custom`
+ **기술:** `agentSkillsDefinition`, `custom`
+ **사용자 지정:** `custom`
`source`는 단일 최상위 블록이 아닌 서술자별입니다. 스키마의 `source` 필드인 `mcpServer` 및를 포함하는 설명자에 연결됩니다`a2aAgentCard`. `tools` 하위(아래`mcpServer.additionalData`), `agentSkillsDefinition` 상위 및 `custom` 설명자는를 포함하지 않습니다`source`.
GA에서는 만 지원`source.fromUrl`됩니다.
자동 동기화는 `mcpServer` 및 `a2aAgentCard` 기본 설명자, 즉 MCP 및 AGENT 레코드 유형에 대해서만 트리거됩니다. `skillMd` 하위 `source`의는 유지되지만 동기화를 실행하는 데 사용되지 않으며, SKILL 레코드는 자동 동기화할 수 없습니다. 사용자 지정 레코드는를 `data` 직접 제공하여 수동으로 생성해야 합니다.
### 변경 4: 데이터 영역 필터 업데이트
`SearchRegistryRecords`는 `SearchDiscoverableRegistryRecords` (`POST /discoverable-records-search`)가 됩니다. 요청 및 응답은 새 필드 이름과 데이터 모델을 선택합니다.
+ 필터링 기준`recordType`( 대체`descriptorType`).
+ 필터링 기준`recordVersion`( 대체`version`).
+ 응답은 없이 새 형식으로 설명자를 반환합니다`credentialProviderConfigurations`.
MCP 검색 도구는이 `search_registry_records`되고`search_discoverable_registry_records`, 새 설명자 형식을 반환하며, 새 필터 이름을 사용합니다.
### 변경 5: 새 브라우징 APIs
두 개의 새로운 데이터 영역 APIs 승인된 레코드에 대한 브라우징 및 카탈로그 경험 구축을 지원합니다. 이러한 APIs 명시적 마이그레이션이 필요하지 않습니다. 여기에서는 이를 GA의 AWS 에이전트 레지스트리 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개, 레코드 IDs)이 허용됩니다. 그룹화된 셰이프는 향후 릴리스에서 교차 레지스트리 일괄 처리와 전방 호환됩니다.
### 변경 6: API 나열 APIs화 필터 채택 파라미터
공개 미리 보기에서 목록 APIs 필터링 가능한 각 필드를 자체 쿼리 파라미터(예: , `--status READY``--recordType MCP`)로 노출합니다. GA에서는 단일 구조화 `filters` 파라미터가 이러한 개별 파라미터를 대체합니다. `filters` 값은 점으로 구분된 속성 경로인 `{ "name": "", "values": [""] }` 항목 목록`name`입니다. 중첩된 필드를 포함하여 필터링 가능한 새로운 필드는 새로운 API 파라미터가 아닌 새로운 `name` 경로가 됩니다. 목록 작업도에서 `GET`로 변경됩니다`POST`. 페이지 매김 파라미터(`maxResults`, `nextToken`)는 변경되지 않습니다.
**이전(공개 미리 보기):**
```
GET /registries?status=READY&authorizerType=AWS_IAM
GET /registries/{registryId}/records?name=my-agent&status=APPROVED&recordType=MCP
```
**이후(일반 가용성):**
```
// 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 스키마 변경을 고려하여 기존 레지스트리의 모든 기존 레코드를 새 레지스트리로 마이그레이션합니다.
### 마이그레이션 접근 방식 선택
올바른 접근 방식은 레지스트리 사용량의 규모와 운영 환경에 따라 달라집니다.
#### 사례 1: 직접 스크립트 실행을 통한 소규모 마이그레이션
+ **프로필:** 레지스트리가 5개 미만이고 레코드가 100개 미만입니다. 대상 계정의 터미널 또는 CloudShell에 직접 액세스할 수 있습니다.
+ **접근 방식:** 마이그레이션 Python 스크립트를 직접 실행합니다. 스크립트는 미리 보기 네임스페이스에 연결하고, 레지스트리와 레코드를 나열하고, 데이터를 GA 스키마로 변환하고, 새 네임스페이스에 생성합니다. 가장 간단한 경로이며 인프라 배포가 필요하지 않습니다.
#### 사례 2: Lambda 또는 Glue를 사용한 관리형 마이그레이션
+ **프로필:** 대상 환경에 대한 직접 터미널 액세스 권한이 없거나 관리형 실행 모델을 선호합니다.
+ **접근 방식:** 마이그레이션을 AWS Lambda 함수 또는 AWS Glue 작업으로 배포합니다. 마이그레이션 엔진은 동일한 extract-transform-load 워크플로를 수행하지만 계정 내에서 관리형 작업으로 실행됩니다. 대부분의 계정에서 전체 마이그레이션은 15분 이내에 완료됩니다.
마이그레이션 엔진:
+ 미리 보기 네임스페이스에서 레지스트리와 레코드를 **추출**하여 전체 로드와 증분 로드를 모두 지원합니다. 모든 API 응답을 페이지 매김하고 데이터를 스테이징 위치로 직렬화합니다.
+ API 스키마 변경 사항(필드 이름 변경, 설명자 재구성, 새 필수 필드)을 적용하여 각 레코드를 **변환합니다**.
+ 변환된 데이터를 새 `agent-registry` 네임스페이스로 **로드하여** GA API를 사용하여 레지스트리와 레코드를 생성합니다.
+ 마이그레이션된 항목, 발생한 오류를 요약하는 **보고서를 생성하고** 확인을 위해 개수를 기록합니다.
#### 사례 3: 활성 프로덕션 워크로드에 대한 이중 쓰기 마이그레이션
+ **프로필:** 퍼블릭 미리 보기 APIs를 기반으로 플랫폼 또는 자동화 파이프라인을 구축했으며 프로덕션 환경에서 새 데이터를 적극적으로 작성하고 있습니다.
+ **접근 방식:** 전환 중에 데이터 손실을 방지하려면 이중 쓰기 마이그레이션 전략을 사용합니다.
+ **라이터 업데이트** - 미리 보기 네임스페이스와 새 `agent-registry` 네임스페이스 모두에 동시에 쓰도록 애플리케이션을 수정합니다.
+ **중복 제거를 사용하여 마이그레이션 스크립트 실행 **- 마이그레이션 도구를 실행하여 기록 데이터를 마이그레이션합니다. 스크립트는 `name` 필드를 기반으로 중복 제거되므로 새 네임스페이스(이중 쓰기)에 이미 있는 레코드는 중복되지 않습니다.
+ **리더 전환** - 모든 데이터가 새 네임스페이스에 존재하는지 확인한 후 에서만 읽도록 애플리케이션을 업데이트합니다`agent-registry`.
+ **이중 쓰기 제거 -** 새 네임스페이스에서 모든 읽기 및 쓰기가 성공했는지 확인한 후 애플리케이션에서 미리 보기 네임스페이스 라이터를 제거합니다.
### 마이그레이션 확인
마이그레이션을 실행한 후 데이터가 올바르게 마이그레이션되었는지 확인합니다.
+ `list-registries` CLI 명령을 사용하여 새 네임스페이스의 모든 레지스트리를 나열하고 개수가 소스와 일치하는지 확인합니다.
+ 각 레지스트리에 대해를 사용하여 레코드 수를 비교합니다`list-registry-records`.
+ 개별 레코드를 스팟 확인하여 설명자가 올바르게 변환되었는지 확인합니다(필드 이름 변경, 설명자 재구성).
+ 네임스페이스 및 구성 변경 섹션에 설명된 대로 IAM 정책, 엔드포인트 및 SDK 클라이언트를 업데이트합니다.
+ 애플리케이션이 새 네임스페이스를 사용하여 성공적으로 읽고 쓸 수 있는지 확인합니다.
## FAQ
### AWS 에이전트 레지스트리에서 변경되는 사항은 무엇입니까?
AWS 에이전트 레지스트리가 퍼블릭 미리 보기 `bedrock-agentcore` 네임스페이스에서 일반적으로 사용 가능한 `agent-registry` 네임스페이스로 이동하고 있습니다. 마이그레이션은 네임스페이스 및 구성 변경(엔드포인트, IAM, SDK, CLI, ARNs, 관찰성), API 스키마 변경(레지스터리 및 레코드에 대한 재구성된 데이터 모델), 데이터 마이그레이션(기존 레지스트리 및 레코드를 새 네임스페이스로 이동)의 세 가지 영역에 걸쳐 있습니다.
### `bedrock-agentcore` 네임스페이스에서 레지스트리를 계속 사용할 수 있나요?
`bedrock-agentcore` 네임스페이스의 기존 레지스트리 사용은 마이그레이션 기간 동안 중단 없이 계속 작동합니다. 그러나 데이터 마이그레이션과 코드 업데이트를 모두 완료할 수 있는 충분한 시간을 확보하려면 도구를 사용할 수 있게 되는 즉시 마이그레이션을 시작하는 것이 좋습니다.
그러나 2026년 8월 6일부터 기존 레지스트리 또는 레코드가 없는 경우 2026년 8월 6일부터 AWS 에이전트 레지스트리의 `bedrock-agentcore` 네임스페이스에 액세스할 수 없습니다. 2026년 8월 6일 현재 기존 레지스트리 또는 레코드가 있는 경우 마이그레이션 기간(2026년 8월 6일\~2026년 9월 17일) 동안 AWS 에이전트 레지스트리의 `bedrock-agentcore` 네임스페이스에 액세스할 수 있습니다.
### 내 데이터가 자동으로 마이그레이션되나요?
아니요. 제공하는 마이그레이션 도구를 사용하여 직접 마이그레이션을 시작해야 합니다. 규모에 따라 사용 가능한 접근 방식에 대한 자세한 내용은 데이터 마이그레이션 섹션을 참조하세요.
### 어떤 API 스키마 변경 사항이 포함되나요?
네임스페이스 변경 외에도 레지스트리 엔터티(에 그룹화된 권한 부여 구성`discoveryConfiguration`), 레지스트리 레코드 새 필드(`name` 및 `recordType`), 레지스트리 레코드 재구성(설명자 평면화, 필드 이름 변경), 검색 API 필터 업데이트(`recordType`, `recordVersion`), 새 브라우징 APIs(`ListDiscoverableRegistryRecords`, `BatchGetDiscoverableRegistryRecord`) 및 목록 작업에 대한 구조화된 필터의 6개 영역에서 API 데이터 모델을 업데이트했습니다.
### 데이터 마이그레이션에는 얼마나 걸리나요?
마이그레이션 시간은 계정의 레지스트리 및 레코드 수에 따라 달라집니다. 레코드가 100개 미만인 계정의 경우 로컬에서 실행될 때 몇 분 안에 마이그레이션이 완료됩니다. 레코드가 수천 개인 계정의 경우 관리형 작업으로 실행할 때 15분 이내에 마이그레이션이 완료될 것으로 예상합니다.
### 활성 쓰기를 사용하는 대규모 배포가 있는 경우 어떻게 해야 하나요?
프로덕션 환경에서 미리 보기 네임스페이스에 데이터를 적극적으로 쓰는 경우 사례 3에 설명된 대로 이중 쓰기 마이그레이션 전략을 사용합니다. 이 접근 방식은 두 네임스페이스에 동시에 쓰고 중복 제거를 통해 기록 데이터를 마이그레이션한 다음 읽기를 줄여 전환 중에 데이터가 손실되지 않도록 합니다.
### 어디에서 도움을 받을 수 있나요?
마이그레이션에 대한 질문이나 도움이 필요하면 [AWS Support](https://aws.amazon.com/support)에 문의하세요.