포괄적인 레지스트리 마이그레이션 가이드

AWS 에이전트 레지스트리 - 퍼블릭 미리 보기에서 일반 가용성으로 마이그레이션

소개

2026년 8월 6일에 정식 출시(GA)의 일환으로 AWS 에이전트 레지스트리는 서비스 보안 주체, 데이터 및 API 모델에 상당한 변경 사항을 도입하고 있습니다. 공개 미리 보기 중에 AWS 에이전트 레지스트리를 사용한 경우 다음 세 영역에 걸친 마이그레이션을 완료해야 합니다.

이 가이드에서는 마이그레이션을 계획하고 실행하는 데 도움이 되는 before-and-after 예제와 함께 각 영역을 자세히 다룹니다.

마이그레이션 타임라인이란 무엇입니까?

이 마이그레이션을 위해 기억해야 할 두 가지 중요한 마일스톤이 있습니다.

네임스페이스 및 구성 변경

agent-registry 네임스페이스는 다음 위치에서 bedrock-agentcore를 대체합니다. 이 섹션에서는 변경되는 모든 표면을 나열하고 코드를 업데이트하는 방법에 대한 예를 제공합니다.

서비스 엔드포인트

애플리케이션은 새 엔드포인트 호스트 이름을 가리켜야 합니다. 새 엔드포인트는 .api.aws 도메인을 사용합니다.

IAM 및 보안

참조하는 모든 IAM 정책, 서비스 제어 정책(SCPs) 및 권한 경계를 업데이트해야 bedrock-agentcore 합니다. 리소스 ARNs 새 네임스페이스를 반영하도록 변경됩니다.

ARNs 구문 분석하거나 저장하는 자동화가 있는 경우 해당 참조도 업데이트합니다. IAM 작업 접두사 또는 서비스 보안 주체에 대한 조건이 있는 사용자 지정 정책을 새 값과 일치하도록 업데이트해야 합니다. AWS 에이전트 레지스트리와 연결된 IAM 권한의 전체 목록을 보려면 AWS 에이전트 레지스트리 IAM 권한 참조를 참조하세요.

SDK, CLI 및 인프라

새 클라이언트 클래스 및 CLI 네임스페이스를 참조하도록 애플리케이션 코드, 배포 스크립트 및 infrastructure-as-code 템플릿을 업데이트합니다.

이전에 bedrock-agentcore 서비스 코드에서 사용자 지정 할당량 증가를 요청한 경우에서 다시 요청해야 합니다agent-registry.

관찰성 및 이벤트

이전 네임스페이스를 참조하는 CloudTrail Lake 쿼리, Athena 쿼리, SIEM 통합, EventBridge 규칙, CloudWatch 대시보드 및 경보를 업데이트합니다.

예: 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:*"]
  }]
}

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

예: 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 자동으로 상태로 전환되는지 여부를 제어)은 부울에서 확장 가능한 열거형 배열로 이동합니다.

특정 필드 변경 사항은 다음과 같습니다.

이전(공개 미리 보기):

{
  "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를 사용하여 변경할 수 있습니다.

변경 3: 레지스트리 레코드 재구성

descriptors 필드는 구분된 조합에서 플랫 키 구조로 변경됩니다.

이전 모델에서 descriptorType 필드(MCP, A2A, AGENT_SKILLS, CUSTOM)가 내부 셰이프를 결정했습니다. 이 결합된 설명자 콘텐츠는 대략적인 프로토콜 또는 형식 분류에 적용됩니다. 이 필드는 더 이상 존재하지 않습니다. 별도의 최상위 속성recordType인가 의미 체계 분류를 대체합니다. API는 구조적으로 셰이프가 아닌 런타임 recordType 시 각에 대해 유효한 설명자 키를 적용합니다. descriptors 이제 아래의 각 최상위 키는 세분화된 기본 설명자 유형(예: , a2aAgentCardmcpServer, agentSkillsDefinition, custom)을 나타냅니다. 보조 설명자(예: , toolsskillMd)는 기본 설명자의 아래에 중첩됩니다additionalData. inlineContent 필드는이 됩니다data. schemaVersion 및 protocolVersion 필드는 로 통합됩니다dataSchemaVersion.

최상위 synchronizationConfiguration 속성은 각 설명자(additionalData하위 포함) 내에서가 source 되고 이동합니다.

기존 name 필드는가 displayName되어 의미를 보다 명시적으로 만듭니다. net-new name 필드는 중복 제거 키 역할을 하며 레지스트리의 모든 레코드에서 고유해야 합니다. 동일한 레코드recordVersion에 대해 name 및를 모두 지정하는 경우 이들의 조합은 고유해야 합니다.

다음 필드의 이름이 변경되었습니다.

이전(공개 미리 보기):

{
  "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 같습니다.

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)가 됩니다. 요청 및 응답은 새 필드 이름과 데이터 모델을 선택합니다.

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": "<dotted.path>", "values": ["<value>"] } 항목 목록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: 직접 스크립트 실행을 통한 소규모 마이그레이션

사례 2: Lambda 또는 Glue를 사용한 관리형 마이그레이션

마이그레이션 엔진:

사례 3: 활성 프로덕션 워크로드에 대한 이중 쓰기 마이그레이션

마이그레이션 확인

마이그레이션을 실행한 후 데이터가 올바르게 마이그레이션되었는지 확인합니다.

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에 문의하세요.