Panduan migrasi registri yang komprehensif

AWS Registri Agen - Migrasi dari Pratinjau Publik ke Ketersediaan Umum

Pengantar

Sebagai bagian dari peluncuran sebagai Generally Available (GA) pada 6 Agustus 2026, AWS Agent Registry memperkenalkan perubahan signifikan pada prinsipal layanan, data, dan model API. Jika Anda menggunakan Registri AWS Agen selama pratinjau publik, Anda harus menyelesaikan migrasi yang mencakup tiga area:

Panduan ini mencakup setiap area secara rinci dengan contoh sebelum dan sesudah untuk membantu Anda merencanakan dan menjalankan migrasi Anda.

Apa itu timeline migrasi?

Ada dua tonggak penting yang harus Anda ingat untuk migrasi ini:

Perubahan namespace dan konfigurasi

agent-registryNamespace menggantikan bedrock-agentcore di tempat-tempat berikut. Bagian ini mencantumkan setiap permukaan yang berubah dan memberikan contoh cara memperbarui kode Anda.

Titik akhir layanan

Aplikasi Anda harus menunjuk ke nama host endpoint baru. Endpoint baru menggunakan .api.aws domain.

IAM dan keamanan

Semua kebijakan IAM, kebijakan kontrol layanan (SCP), dan batas izin yang referensi bedrock-agentcore harus diperbarui. ARN sumber daya juga berubah untuk mencerminkan namespace baru.

Jika Anda memiliki otomatisasi yang mem-parsing ARN atau menyimpannya, perbarui referensi tersebut juga. Kebijakan khusus dengan ketentuan pada awalan tindakan IAM atau prinsip layanan harus diperbarui agar sesuai dengan nilai baru. Untuk melihat daftar lengkap izin IAM yang terkait dengan AWS Agent Registry, lihat referensi izin IAM AWS Agent Registry.

SDK, CLI, dan infrastruktur

Perbarui kode aplikasi, skrip penerapan, dan templat infrastruktur-sebagai-kode untuk mereferensikan kelas klien baru dan namespace CLI.

Jika sebelumnya Anda meminta peningkatan kuota kustom di bawah kode bedrock-agentcore layanan, Anda harus memintanya kembali di bawah. agent-registry

Observabilitas dan eventing

Perbarui kueri CloudTrail Lake, kueri Athena, integrasi SIEM, aturan, dasbor CloudWatch , dan alarm yang EventBridge mereferensikan namespace lama.

Contoh: Memperbarui kebijakan IAM

Ganti awalan tindakan dan resource ARN namespace di semua kebijakan IAM Anda.

Sebelum (pratinjau publik):

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

Setelah (Ketersediaan Umum):

{
  "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"

Contoh: Memperbarui konfigurasi klien SDK

Perbarui nama layanan, kelas klien, dan URL titik akhir dalam panggilan SDK Anda.

Sebelum (pratinjau publik):

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"
)

Setelah (Ketersediaan Umum):

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"
)

Contoh: Memperbarui perintah CLI

Ganti namespace CLI di semua skrip dan otomatisasi.

Sebelum (pratinjau publik):

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

Setelah (Ketersediaan Umum):

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

Perubahan skema API

Selain migrasi namespace, kami memperbarui model data catatan registri dan registri untuk Ketersediaan Umum. Perubahan ini meningkatkan konsistensi dan ekstensibilitas API berdasarkan umpan balik dari pratinjau publik. Bagian ini mencakup setiap kategori perubahan dengan contoh sebelum dan sesudah sehingga Anda dapat memperbarui kode aplikasi Anda.

Perubahan 1: Pembaruan entitas registri

Konfigurasi otorisasi pada sumber daya registri — yang mengontrol bagaimana bidang data registri diakses — sekarang berada di bawah discoveryConfiguration pembungkus khusus yang membuat tujuannya eksplisit. Konfigurasi persetujuan (yang mengontrol apakah catatan yang dikirimkan ke PENDING_APPROVAL status secara otomatis bertransisi ke APPROVED status) berpindah dari boolean ke larik enum yang dapat diperluas.

Perubahan bidang spesifik adalah:

Sebelum (pratinjau publik):

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

Setelah (Ketersediaan Umum): dengan Persetujuan SEMUA

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

Setelah (Ketersediaan Umum): dengan NULL dalam daftar enum

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

Ubah 2: Bidang baru yang diperlukan pada catatan registri

Catatan registri mendapatkan dua bidang tingkat atas baru yang diperlukan untuk mendukung kategorisasi dan deduplikasi yang lebih baik. Anda harus menentukan kedua bidang saat membuat catatan registri menggunakan CreateRegistryRecord API, dan Anda dapat mengubahnya nanti menggunakan UpdateRegistryRecord API.

Perubahan 3: Restrukturisasi catatan registri

descriptorsBidang berubah dari persatuan yang didiskriminasi menjadi struktur kunci datar.

Pada model sebelumnya, descriptorType bidang (MCP,, A2AAGENT_SKILLS,CUSTOM) menentukan bentuk bagian dalam. Ini menggabungkan konten deskriptor ke protokol kasar atau klasifikasi format. Bidang itu sudah tidak ada lagi. recordType, atribut tingkat atas yang terpisah, menggantikannya untuk kategorisasi semantik. API memberlakukan kunci deskriptor yang valid untuk masing-masing recordType saat runtime daripada secara struktural dalam bentuk. Setiap kunci tingkat atas di bawah descriptors sekarang mewakili tipe deskriptor primer granular (misalnya,,, a2aAgentCardmcpServer,agentSkillsDefinition). custom Deskriptor tambahan (misalnya,tools,skillMd) bersarang di bawah deskriptor utama. additionalData inlineContentBidang menjadidata. protocolVersionBidang schemaVersion dan dikonsolidasikan menjadidataSchemaVersion.

synchronizationConfigurationAtribut tingkat atas menjadi source dan bergerak di dalam setiap deskriptor (termasuk additionalData anak-anak).

nameBidang yang ada menjadidisplayName, membuat maknanya lebih eksplisit. nameBidang net-new berfungsi sebagai kunci dedup dan harus unik di semua catatan dalam registri. Jika Anda menentukan keduanya name dan recordVersion untuk catatan yang sama, kombinasi mereka harus unik.

Bidang berikut diganti namanya:

Sebelum (pratinjau publik):

{
  "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"
        }
      ]
    }
  },
  ...
}

Setelah (Ketersediaan Umum):

{
  "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
  ...
}

Batasan berikut berlaku:

Tepat satu kunci deskriptor utama dapat diisi per catatan. Deskriptor primer yang valid per recordType adalah:

sourceadalah per-deskriptor daripada satu blok tingkat atas. Ini melekat pada deskriptor yang membawa source bidang dalam skema — dan. mcpServer a2aAgentCard toolsAnak (di bawahmcpServer.additionalData), agentSkillsDefinition orang tua, dan custom deskriptor membawa nosource.

Di GA, hanya source.fromUrl didukung.

Auto-synchronization hanya dipicu untuk deskriptor mcpServer dan a2aAgentCard primer — yaitu, jenis catatan MCP dan AGENT. A source pada skillMd anak dipertahankan tetapi tidak digunakan untuk menjalankan sinkronisasi, dan catatan SKILL tidak dapat disinkronkan secara otomatis. Catatan KUSTOM harus dibuat secara manual dengan menyediakan data secara langsung.

Ubah 4: Pembaruan filter bidang data

SearchRegistryRecordsmenjadi SearchDiscoverableRegistryRecords (POST /discoverable-records-search). Permintaan dan tanggapannya mengambil nama bidang dan model data baru:

Alat pencarian MCP search_registry_records menjadisearch_discoverable_registry_records, mengembalikan format deskriptor baru, dan menggunakan nama filter baru.

Ubah 5: API penjelajahan baru

Dua API bidang data baru mendukung penjelajahan bangunan dan pengalaman katalog atas catatan yang disetujui. API ini tidak memerlukan migrasi eksplisit apa pun; kami menyebutkannya di sini sebagai tambahan pada model AWS Agent Registry API di GA.

ListDiscoverableRegistryRecords— Mengembalikan daftar paginasi catatan registri yang disetujui. Gunakan ini untuk membangun antarmuka penelusuran di atas konten yang dipublikasikan.

// 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— Mengambil detail lengkap untuk sekumpulan catatan di satu atau lebih pendaftar dalam satu panggilan.

// 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"
    }
  ]
}

Respons termasuk registryRecords array dengan rincian catatan lengkap dan errors array untuk setiap catatan yang tidak dapat diambil.

Saat peluncuran, tepat satu entri (satu registri, 1-100 ID rekaman) diterima. Bentuk yang dikelompokkan kompatibel ke depan dengan batching lintas registri di rilis mendatang.

Perubahan 6: API Daftar mengadopsi parameter filter terstruktur

Dalam pratinjau publik, API Daftar mengekspos setiap bidang yang dapat difilter sebagai parameter kueri sendiri (misalnya,,--status READY). --recordType MCP Di GA, satu filters parameter terstruktur menggantikan parameter diskrit ini. filtersNilai adalah daftar { "name": "<dotted.path>", "values": ["<value>"] } entri di mana name adalah jalur atribut dot-delimited. Bidang baru yang dapat difilter, termasuk yang bersarang, menjadi name jalur baru daripada parameter API baru. Operasi daftar juga berubah dari GET kePOST. Parameter pagination (maxResults,nextToken) tidak berubah.

Sebelum (pratinjau publik):

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

Setelah (Ketersediaan Umum):

// 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"
}

Migrasi data

Anda harus memigrasikan registri dan catatan registri yang ada dari namespace ke bedrock-agentcore namespace. agent-registry Kami menyediakan skrip untuk membantu migrasi. Skrip menangani ekstraksi data yang ada, transformasi dari skema lama ke skema baru, dan pemuatan ke registri di namespace baru. Skrip membuat registri baru di agent-registry namespace dalam akun dan wilayah yang sama. Ini memigrasikan semua catatan yang ada dari registri lama Anda ke yang baru, memperhitungkan namespace dan perubahan skema API.

Memilih pendekatan migrasi Anda

Pendekatan yang tepat tergantung pada skala penggunaan registri Anda dan lingkungan operasional Anda.

Kasus 1: Small-scale migrasi dengan eksekusi skrip langsung

Kasus 2: Migrasi terkelola dengan Lambda atau Glue

Mesin migrasi:

Kasus 3: Dual-write migrasi untuk beban kerja produksi aktif

Memverifikasi migrasi Anda

Setelah menjalankan migrasi, konfirmasikan bahwa data Anda telah dimigrasi dengan benar:

Pertanyaan yang Sering Diajukan

Apa yang berubah AWS Agen Registry?

AWS Agent Registry bergerak dari namespace pratinjau publik ke bedrock-agentcore namespace yang tersedia agent-registry secara umum. Migrasi mencakup tiga area: namespace dan perubahan konfigurasi (titik akhir, IAM, SDK, CLI, ARN, observabilitas), perubahan skema API (model data yang direstrukturisasi untuk pendaftar dan catatan), dan migrasi data (memindahkan registri dan catatan Anda yang ada ke namespace baru).

Bisakah saya terus menggunakan Registry di namespace bedrock-agentcore?

Penggunaan Registri Anda yang ada di bedrock-agentcore namespace terus bekerja tanpa gangguan selama jendela migrasi. Namun, kami menyarankan Anda memulai migrasi segera setelah alat tersedia untuk memastikan Anda memiliki cukup waktu untuk menyelesaikan migrasi data dan pembaruan kode.

Namun, jika Anda tidak memiliki registri atau catatan yang ada per 6 Agustus 2026, Anda tidak dapat mengakses bedrock-agentcore namespace untuk AWS Agen Registry mulai 6 Agustus 2026. Jika Anda memiliki registri atau catatan yang ada per 6 Agustus 2026, Anda memiliki akses ke bedrock-agentcore namespace untuk Registri AWS Agen selama jendela migrasi (6 Agustus 2026 — 17 September 2026).

Apakah data saya akan dimigrasikan secara otomatis?

Tidak. Anda harus memulai migrasi sendiri menggunakan alat migrasi yang kami sediakan. Lihat bagian Migrasi data untuk detail tentang pendekatan yang tersedia berdasarkan skala Anda.

Perubahan skema API apa yang disertakan?

Selain perubahan namespace, kami memperbarui model data API di enam area: entitas registri (konfigurasi otorisasi dikelompokkan di bawahdiscoveryConfiguration), registri merekam bidang baru (namedan), restrukturisasi catatan registri (deskriptor diratakan, penggantian nama bidangrecordType), pembaruan filter API pencarian (,), API penelusuran baru (,recordVersion)recordType, dan filter terstruktur untuk operasi Daftar. ListDiscoverableRegistryRecords BatchGetDiscoverableRegistryRecord

Berapa lama waktu yang dibutuhkan migrasi data?

Waktu migrasi tergantung pada jumlah pendaftar dan catatan di akun Anda. Untuk akun dengan catatan kurang dari 100, migrasi selesai dalam hitungan menit saat dijalankan secara lokal. Untuk akun dengan ribuan catatan, perkirakan migrasi selesai dalam waktu kurang dari 15 menit saat dijalankan sebagai pekerjaan terkelola.

Bagaimana jika saya memiliki penerapan skala besar dengan penulisan aktif?

Jika Anda secara aktif menulis data ke namespace pratinjau dalam produksi, gunakan strategi migrasi penulisan ganda seperti yang dijelaskan dalam Kasus 3. Pendekatan ini memastikan tidak ada data yang hilang selama transisi dengan menulis ke kedua ruang nama secara bersamaan, memigrasikan data historis dengan deduplikasi, dan kemudian memotong pembacaan.

Di mana saya bisa mendapatkan bantuan?

Untuk pertanyaan atau bantuan terkait migrasi Anda, hubungi AWS Support.