Guide complet de migration de registre

AWS Registre des agents : migration de la version préliminaire publique à la disponibilité générale

Introduction

Dans le cadre du lancement en tant que service généralement disponible (GA) le 6 août 2026, AWS Agent Registry introduit des modifications importantes au principal du service, aux données et au modèle d'API. Si vous avez utilisé AWS Agent Registry lors de la version préliminaire publique, vous devez effectuer une migration qui couvre trois domaines :

Ce guide couvre chaque domaine en détail avec des exemples avant-après pour vous aider à planifier et à exécuter votre migration.

Quel est le calendrier de migration ?

Il y a deux étapes importantes dont vous devez tenir compte lors de cette migration :

Changements d'espace de noms et de configuration

L'espace de agent-registry noms est remplacé bedrock-agentcore aux emplacements suivants. Cette section répertorie toutes les surfaces modifiées et fournit des exemples de mise à jour de votre code.

Points de terminaison de service

Vos applications doivent pointer vers les nouveaux noms d'hôte des points de terminaison. Les nouveaux points de terminaison utilisent le .api.aws domaine.

IAM et sécurité

Toutes les politiques IAM, les politiques de contrôle des services (SCP) et les limites d'autorisation auxquelles il est fait référence bedrock-agentcore doivent être mises à jour. Les ARN des ressources changent également pour refléter le nouvel espace de noms.

Si vous disposez d'une automatisation qui analyse les ARN ou les stocke, mettez également à jour ces références. Les politiques personnalisées assorties de conditions relatives au préfixe d'action IAM ou au principal de service doivent être mises à jour pour correspondre aux nouvelles valeurs. Pour consulter la liste complète des autorisations IAM associées au registre des AWS agents, reportez-vous à la référence des autorisations IAM du registre des AWS agents.

SDK, CLI et infrastructure

Mettez à jour le code de votre application, vos scripts de déploiement et vos modèles d'infrastructure en tant que code pour faire référence à la nouvelle classe client et à l'espace de noms de la CLI.

Si vous avez déjà demandé des augmentations de quotas personnalisées en vertu du code de bedrock-agentcore service, vous devez les demander à nouveau en vertu agent-registry du code de service.

Observabilité et organisation d'événements

Mettez à jour les requêtes CloudTrail Lake, les requêtes Athena, les intégrations SIEM, les EventBridge règles, les CloudWatch tableaux de bord et les alarmes qui font référence à l'ancien espace de noms.

Exemple : mise à jour des politiques IAM

Remplacez le préfixe d'action et l'espace de noms ARN des ressources dans toutes vos politiques IAM.

Avant (avant-première publique) :

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

Après (disponibilité générale) :

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

Exemple : mise à jour de la configuration du client SDK

Mettez à jour le nom du service, la classe du client et l'URL du point de terminaison dans vos appels au SDK.

Avant (avant-première publique) :

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

Après (disponibilité générale) :

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

Exemple : mise à jour des commandes CLI

Remplacez l'espace de noms CLI dans tous les scripts et automatismes.

Avant (avant-première publique) :

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

Après (disponibilité générale) :

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

Modifications du schéma de l'API

Outre la migration de l'espace de noms, nous avons mis à jour les modèles de données du registre et des enregistrements de registre pour la disponibilité générale. Ces modifications améliorent la cohérence et l'extensibilité de l'API en fonction des commentaires issus de la version préliminaire publique. Cette section couvre chaque catégorie de modification avec des exemples avant et après afin que vous puissiez mettre à jour le code de votre application.

Modification 1 : mises à jour des entités de registre

La configuration d'autorisation sur la ressource de registre, qui contrôle le mode d'accès au plan de données d'un registre, se trouve désormais dans un discoveryConfiguration wrapper dédié qui précise son objectif. La configuration d'approbation (qui contrôle si les enregistrements soumis au PENDING_APPROVAL statut passent automatiquement au APPROVED statut) passe d'un booléen à un tableau d'énumération extensible.

Les modifications spécifiques apportées aux champs sont les suivantes :

Avant (avant-première publique) :

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

Après (disponibilité générale) : avec approbation ALL

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

Après (disponibilité générale) : avec NULL dans la liste d'énumération

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

Modification 2 : Nouveaux champs obligatoires dans les enregistrements du registre

Les enregistrements du registre reçoivent deux nouveaux champs de premier niveau obligatoires pour permettre une meilleure catégorisation et une meilleure déduplication. Vous devez spécifier les deux champs lors de la création d'un enregistrement de registre à l'aide de l'CreateRegistryRecordAPI, et vous pouvez les modifier ultérieurement à l'aide de l'UpdateRegistryRecordAPI.

Modification 3 : Restructuration des enregistrements du registre

Le descriptors champ passe d'une union discriminée à une structure à clé plate.

Dans le modèle précédent, le descriptorType champ (MCP,, A2AAGENT_SKILLS,CUSTOM) déterminait la forme intérieure. Cela associait le contenu du descripteur à un protocole grossier ou à une classification de format. Ce champ n'existe plus. recordType, un attribut de premier niveau distinct, le remplace pour la catégorisation sémantique. L'API applique des clés de descripteur valides pour chacun recordType au moment de l'exécution plutôt que de manière structurelle dans la forme. Chaque clé de niveau supérieur ci-dessous représente descriptors désormais un type de descripteur principal granulaire (par exemple,, a2aAgentCardmcpServer,agentSkillsDefinition). custom Les descripteurs supplémentaires (par exempletools,skillMd) sont imbriqués sous ceux du descripteur principal. additionalData Le inlineContent champ devientdata. Les protocolVersion champs schemaVersion et se consolident dansdataSchemaVersion.

L'synchronizationConfigurationattribut de niveau supérieur devient source et se déplace dans chaque descripteur (y compris additionalData les enfants).

Le name champ existant le devientdisplayName, ce qui rend sa signification plus explicite. Un nouveau name champ net sert de clé de déduplication et doit être unique dans tous les enregistrements d'un registre. Si vous spécifiez les deux name et recordVersion pour le même enregistrement, leur combinaison doit être unique.

Les champs suivants sont renommés :

Avant (avant-première publique) :

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

Après (disponibilité générale) :

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

Les contraintes suivantes s’appliquent :

Une seule clé de descripteur principal peut être renseignée par enregistrement. Les descripteurs principaux valides recordType sont les suivants :

sourceest un descripteur par descripteur plutôt qu'un seul bloc de haut niveau. Il s'attache aux descripteurs qui contiennent un source champ dans le schéma — mcpServer eta2aAgentCard. L'toolsenfant (moins demcpServer.additionalData), le agentSkillsDefinition parent et le custom descripteur portent le numérosource.

Chez GA, seul source.fromUrl est pris en charge.

Auto-synchronization n'est déclenché que pour mcpServer les descripteurs a2aAgentCard principaux, c'est-à-dire les types d'enregistrement MCP et AGENT. A source sur l'skillMdenfant est conservé mais n'est pas utilisé pour exécuter la synchronisation, et les enregistrements SKILL ne peuvent pas être synchronisés automatiquement. Les enregistrements PERSONNALISÉS doivent être créés manuellement en les fournissant data directement.

Modification 4 : mises à jour du filtre du plan de données

SearchRegistryRecordsdevient SearchDiscoverableRegistryRecords (POST /discoverable-records-search). Sa demande et sa réponse reprennent les nouveaux noms de champs et le nouveau modèle de données :

L'outil de recherche MCP search_registry_records devientsearch_discoverable_registry_records, renvoie le nouveau format de descripteur et utilise les nouveaux noms de filtres.

Modification 5 : nouvelles API de navigation

Deux nouvelles API de plan de données permettent de créer des expériences de navigation et de catalogue sur des enregistrements approuvés. Ces API ne nécessitent aucune migration explicite ; nous les mentionnons ici en tant qu'ajouts au modèle d'API du registre des AWS agents de GA.

ListDiscoverableRegistryRecords— Renvoie une liste paginée des enregistrements de registre approuvés. Utilisez-le pour créer des interfaces de navigation sur du contenu publié.

// 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— Récupère tous les détails d'un lot d'enregistrements dans un ou plusieurs registres en un seul appel.

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

La réponse inclut un registryRecords tableau contenant les détails complets des enregistrements et un errors tableau pour tous les enregistrements qui n'ont pas pu être récupérés.

Au lancement, une seule entrée (un registre, 1 à 100 identifiants d'enregistrement) est acceptée. La forme groupée est compatible avec le traitement par lots entre registres dans les versions futures.

Modification 6 : les API de liste adoptent le paramètre des filtres structurés

Dans l'aperçu public, les API List exposent chaque champ filtrable comme son propre paramètre de requête (par exemple,--status READY,--recordType MCP). En GA, un seul filters paramètre structuré remplace ces paramètres discrets. La filters valeur est une liste d'{ "name": "<dotted.path>", "values": ["<value>"] }entrées contenant un chemin name d'attribut délimité par des points. Les nouveaux champs filtrables, y compris les champs imbriqués, deviennent de nouveaux name chemins plutôt que de nouveaux paramètres d'API. Les opérations de liste passent également de GET àPOST. Les paramètres de pagination (maxResults,nextToken) restent inchangés.

Avant (avant-première publique) :

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

Après (disponibilité générale) :

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

Migrations des données

Vous devez migrer vos registres et enregistrements de registre existants de l'espace de bedrock-agentcore noms vers l'agent-registryespace de noms. Nous fournissons un script pour faciliter la migration. Le script gère l'extraction des données existantes, la transformation de l'ancien schéma vers le nouveau schéma et le chargement dans les registres du nouvel espace de noms. Le script crée de nouveaux registres dans l'espace de agent-registry noms au sein du même compte et de la même région. Il migre tous les enregistrements existants de vos anciens registres vers les nouveaux, en tenant compte des modifications de l'espace de noms et du schéma d'API.

Choix de votre approche de migration

La bonne approche dépend de l'ampleur de l'utilisation de votre registre et de votre environnement opérationnel.

Cas 1 : Small-scale migration avec exécution directe de scripts

Cas 2 : Migration gérée avec Lambda ou Glue

Le moteur de migration :

Cas 3 : Dual-write migration pour les charges de travail de production actives

Vérification de votre migration

Après avoir effectué la migration, vérifiez que vos données ont été correctement migrées :

FAQ

Qu'est-ce qui change dans AWS Registre des agents ?

AWS Le registre des agents passe de l'espace de bedrock-agentcore noms de prévisualisation public à l'espace de agent-registry noms généralement disponible. La migration couvre trois domaines : les modifications de l'espace de noms et de la configuration (points de terminaison, IAM, SDK, CLI, ARN, observabilité), les modifications du schéma d'API (modèle de données restructuré pour les registres et les enregistrements) et la migration des données (déplacement de vos registres et enregistrements existants vers le nouvel espace de noms).

Puis-je continuer à utiliser Registry sur l'espace de noms bedrock-agentcore ?

Votre utilisation actuelle du registre sur l'espace de bedrock-agentcore noms continue de fonctionner sans interruption pendant la fenêtre de migration. Toutefois, nous vous recommandons de commencer votre migration dès que les outils seront disponibles afin de disposer de suffisamment de temps pour effectuer à la fois la migration des données et les mises à jour du code.

Toutefois, si vous ne disposez pas de registres ou d'enregistrements existants au 6 août 2026, vous ne pourrez pas accéder à l'espace de bedrock-agentcore noms du registre des AWS agents à partir du 6 août 2026. Si vous avez des registres ou des enregistrements existants au 6 août 2026, vous avez accès à l'bedrock-agentcoreespace de noms du registre des AWS agents pendant la période de migration (du 6 août 2026 au 17 septembre 2026).

Mes données seront-elles automatiquement migrées ?

Non Vous devez lancer vous-même la migration à l'aide des outils de migration que nous fournissons. Consultez la section Migration des données pour plus de détails sur les approches disponibles en fonction de votre échelle.

Quelles sont les modifications du schéma d'API incluses ?

Outre le changement d'espace de noms, nous avons mis à jour le modèle de données de l'API dans six domaines : entité de registre (configuration d'autorisation groupée ci-dessousdiscoveryConfiguration), nouveaux champs d'enregistrement du registre (nameetrecordType), restructuration des enregistrements de registre (descripteurs aplatis, renommage des champs), mises à jour des filtres d'API de recherche (recordType,recordVersion), nouvelles API de navigation (ListDiscoverableRegistryRecords,) et filtres structurés pour les opérations de liste. BatchGetDiscoverableRegistryRecord

Combien de temps prendra la migration des données ?

Le délai de migration dépend du nombre de registres et d'enregistrements de votre compte. Pour les comptes contenant moins de 100 enregistrements, la migration s'effectue en quelques minutes lorsqu'elle est exécutée localement. Pour les comptes contenant des milliers d'enregistrements, attendez-vous à ce que la migration soit terminée en moins de 15 minutes s'il s'agit d'une tâche gérée.

Et si j'ai un déploiement à grande échelle avec des écritures actives ?

Si vous écrivez activement des données dans l'espace de noms de prévisualisation en production, utilisez la stratégie de migration à double écriture décrite dans le cas 3. Cette approche garantit qu'aucune donnée n'est perdue pendant la transition en écrivant simultanément dans les deux espaces de noms, en migrant les données historiques avec déduplication, puis en réduisant le nombre de lectures.

Où puis-je obtenir de l'aide ?

Pour toute question ou assistance concernant votre migration, contactez le AWS Support.