Guida completa alla migrazione del registro

AWS Agent Registry: migrazione dall'anteprima pubblica alla disponibilità generale

Introduzione

Nell'ambito del lancio come Generally Available (GA) il 6 agosto 2026, AWS Agent Registry sta introducendo modifiche significative al modello principale del servizio, ai dati e all'API. Se hai utilizzato AWS Agent Registry durante l'anteprima pubblica, devi completare una migrazione che si estende su tre aree:

Questa guida copre ogni area in dettaglio con esempi precedenti e successivi per aiutarti a pianificare ed eseguire la migrazione.

Qual è la tempistica della migrazione?

Ci sono due tappe importanti da ricordare per questa migrazione:

Modifiche allo spazio dei nomi e alla configurazione

Il agent-registry namespace viene sostituito nelle seguenti posizionibedrock-agentcore. Questa sezione elenca tutte le superfici che cambiano e fornisce esempi su come aggiornare il codice.

Endpoint di servizio

Le applicazioni devono puntare ai nuovi nomi host degli endpoint. I nuovi endpoint utilizzano il dominio. .api.aws

IAM e sicurezza

Tutte le policy IAM, le policy di controllo dei servizi (SCP) e i limiti di autorizzazione a cui fanno riferimento bedrock-agentcore devono essere aggiornati. Anche gli ARN delle risorse vengono modificati in base al nuovo spazio dei nomi.

Se disponi di un'automazione che analizza gli ARN o li archivia, aggiorna anche questi riferimenti. Le politiche personalizzate con condizioni sul prefisso dell'azione IAM o sul principale del servizio devono essere aggiornate in modo che corrispondano ai nuovi valori. Per visualizzare l'elenco completo delle autorizzazioni IAM associate ad AWS Agent Registry, consulta il riferimento alle autorizzazioni IAM di AWS Agent Registry.

SDK, CLI e infrastruttura

Aggiorna il codice dell'applicazione, gli script di distribuzione e i modelli infrastructure-as-code per fare riferimento alla nuova classe client e allo spazio dei nomi CLI.

Se in precedenza hai richiesto aumenti delle quote personalizzati in base al codice bedrock-agentcore di servizio, devi richiederli nuovamente con. agent-registry

Osservabilità ed eventi

Aggiorna tutte le query CloudTrail Lake, le query Athena, le integrazioni SIEM, le regole EventBridge CloudWatch , i dashboard e gli allarmi che fanno riferimento al vecchio namespace.

Esempio: aggiornamento delle politiche IAM

Sostituisci il prefisso dell'azione e lo spazio dei nomi ARN della risorsa in tutte le tue policy IAM.

Prima (anteprima pubblica):

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

Dopo (disponibilità generale):

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

Esempio: aggiornamento della configurazione del client SDK

Aggiorna il nome del servizio, la classe client e l'URL dell'endpoint nelle chiamate SDK.

Prima (anteprima pubblica):

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

Dopo (disponibilità generale):

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

Esempio: aggiornamento dei comandi CLI

Sostituisci lo spazio dei nomi CLI in tutti gli script e l'automazione.

Prima (anteprima pubblica):

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

Dopo (disponibilità generale):

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

Modifiche allo schema dell'API

Oltre alla migrazione dello spazio dei nomi, abbiamo aggiornato i modelli di dati del registro e dei record di registro per la disponibilità generale. Queste modifiche migliorano la coerenza e l'estensibilità dell'API in base al feedback dell'anteprima pubblica. Questa sezione copre ogni categoria di modifica con esempi precedenti e successivi in modo da poter aggiornare il codice dell'applicazione.

Modifica 1: aggiornamenti delle entità del registro

La configurazione di autorizzazione sulla risorsa di registro, che controlla il modo in cui viene effettuato l'accesso al piano dati del registro, ora si trova in un discoveryConfiguration wrapper dedicato che ne rende esplicito lo scopo. La configurazione di approvazione (che controlla se i record inviati allo status passano automaticamente allo PENDING_APPROVAL APPROVED status) passa da un array enum booleano a uno estensibile.

Le modifiche specifiche ai campi sono:

Prima (anteprima pubblica):

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

Dopo (disponibilità generale): con approvazione ALL

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

Dopo (disponibilità generale): con NULL nell'elenco enum

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

Modifica 2: nuovi campi obbligatori nei record del registro

I record di registro acquisiscono due nuovi campi obbligatori di primo livello per supportare una migliore categorizzazione e deduplicazione. È necessario specificare entrambi i campi quando si crea un record di registro utilizzando l'CreateRegistryRecordAPI e successivamente è possibile modificarli utilizzando l'API. UpdateRegistryRecord

Modifica 3: ristrutturazione dei record di registro

Il descriptors campo passa da un'unione discriminata a una struttura a chiave piatta.

Nel modello precedente, il descriptorType campo (MCP,, A2AAGENT_SKILLS,CUSTOM) determinava la forma interna. Questo associava il contenuto del descrittore a un protocollo approssimativo o a una classificazione di formato. Quel campo non esiste più. recordType, un attributo di primo livello separato, lo sostituisce per la categorizzazione semantica. L'API applica chiavi descrittive valide per ciascuna di esse recordType in fase di esecuzione anziché strutturalmente nella forma. Ogni chiave di primo livello sottostante descriptors ora rappresenta un tipo di descrittore primario granulare (ad esempio,,,). a2aAgentCard mcpServer agentSkillsDefinition custom I descrittori supplementari (ad esempio,skillMd) si annidano sotto tools i descrittori primari. additionalData Il inlineContent campo diventa. data I protocolVersion campi schemaVersion and si consolidano indataSchemaVersion.

L'synchronizationConfigurationattributo di primo livello diventa source e si sposta all'interno di ogni descrittore (compresi additionalData i figli).

Il name campo esistente diventadisplayName, rendendo il suo significato più esplicito. Un name campo net-new funge da chiave di dedup e deve essere univoco per tutti i record di un registro. Se si specificano entrambi name e recordVersion per lo stesso record, la loro combinazione deve essere unica.

I seguenti campi vengono rinominati:

Prima (anteprima pubblica):

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

Dopo (disponibilità generale):

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

Vengono applicati i vincoli seguenti:

È possibile inserire esattamente una chiave descrittrice primaria per record. I descrittori primari validi per sono: recordType

sourceè per descrittore anziché per un singolo blocco di primo livello. Si collega ai descrittori che contengono un source campo nello schema: e. mcpServer a2aAgentCard Il tools bambino (sottomcpServer.additionalData), il agentSkillsDefinition genitore e il custom descrittore riportano il numero. source

In GA, source.fromUrl è supportato solo.

Auto-synchronization viene attivato solo per i descrittori mcpServer a2aAgentCard primari, ovvero i tipi di record MCP e AGENT. A source sul skillMd figlio è persistente ma non utilizzato per eseguire la sincronizzazione e i record SKILL non possono essere sincronizzati automaticamente. I record CUSTOM devono essere creati manualmente fornendoli direttamente. data

Modifica 4: aggiornamenti del filtro del piano dati

SearchRegistryRecordsdiventa SearchDiscoverableRegistryRecords (POST /discoverable-records-search). La sua richiesta e risposta raccolgono i nuovi nomi di campo e il nuovo modello di dati:

Lo strumento di ricerca MCP search_registry_records diventasearch_discoverable_registry_records, restituisce il nuovo formato descrittore e utilizza i nuovi nomi dei filtri.

Modifica 5: nuove API di navigazione

Due nuove API del piano dati supportano la creazione di esperienze di navigazione e catalogo rispetto ai record approvati. Queste API non richiedono alcuna migrazione esplicita; le citiamo qui come aggiunte al modello di API AWS Agent Registry di GA.

ListDiscoverableRegistryRecords— Restituisce un elenco impaginato di record di registro approvati. Utilizzatelo per creare interfacce di navigazione sui contenuti pubblicati.

// 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— Recupera i dettagli completi di un gruppo di record su uno o più registri in una singola chiamata.

// 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 risposta include un registryRecords array con i dettagli completi dei record e un errors array per tutti i record che non è stato possibile recuperare.

All'avvio, viene accettata una sola voce (un registro, 1-100 ID di record). La forma raggruppata è compatibile con le versioni future con il batching tra registri nelle versioni future.

Modifica 6: le API List adottano il parametro dei filtri strutturati

Nell'anteprima pubblica, le API List espongono ogni campo filtrabile come un proprio parametro di query (ad esempio,). --status READY --recordType MCP In GA, un singolo filters parametro strutturato sostituisce questi parametri discreti. Il filters valore è un elenco di { "name": "<dotted.path>", "values": ["<value>"] } voci in cui name è presente un percorso di attributo delimitato da punti. I nuovi campi filtrabili, compresi quelli annidati, diventano nuovi name percorsi anziché nuovi parametri API. Anche le operazioni relative agli elenchi cambiano da aGET. POST I parametri di paginazione (maxResults,nextToken) rimangono invariati.

Prima (anteprima pubblica):

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

Dopo (disponibilità generale):

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

Migrazione dei dati

È necessario migrare i registri e i record di registro esistenti dal bedrock-agentcore namespace allo spazio dei nomi. agent-registry Forniamo uno script per facilitare la migrazione. Lo script gestisce l'estrazione dei dati esistenti, la trasformazione dal vecchio schema al nuovo schema e il caricamento nei registri del nuovo spazio dei nomi. Lo script crea nuovi registri nello spazio dei agent-registry nomi all'interno dello stesso account e della stessa regione. Migra tutti i record esistenti dai vecchi registri a quelli nuovi, tenendo conto delle modifiche allo spazio dei nomi e allo schema dell'API.

Scelta del tuo approccio alla migrazione

L'approccio giusto dipende dalla portata dell'utilizzo del registro e dall'ambiente operativo.

Caso 1: Small-scale migrazione con esecuzione diretta degli script

Caso 2: migrazione gestita con Lambda o Glue

Il motore di migrazione:

Caso 3: Dual-write migrazione per carichi di lavoro di produzione attivi

Verifica della migrazione

Dopo aver eseguito la migrazione, conferma che i tuoi dati siano stati migrati correttamente:

Domande frequenti

Cosa sta cambiando in AWS Registro degli agenti?

AWS Agent Registry sta passando dallo spazio dei bedrock-agentcore nomi di anteprima pubblica a quello generalmente disponibileagent-registry. La migrazione riguarda tre aree: modifiche allo spazio dei nomi e alla configurazione (endpoint, IAM, SDK, CLI, ARN, osservabilità), modifiche allo schema delle API (modello di dati ristrutturato per registri e record) e migrazione dei dati (spostamento dei registri e dei record esistenti nel nuovo spazio dei nomi).

Posso continuare a utilizzare Registry sullo spazio dei nomi bedrock-agentcore?

L'utilizzo del Registro di sistema esistente nello spazio dei bedrock-agentcore nomi continua a funzionare senza interruzioni durante la finestra di migrazione. Tuttavia, ti consigliamo di iniziare la migrazione non appena gli strumenti saranno disponibili per assicurarti di avere tempo sufficiente per completare sia la migrazione dei dati che gli aggiornamenti del codice.

Tuttavia, se non disponi di registri o record esistenti al 6 agosto 2026, non puoi accedere allo spazio dei bedrock-agentcore nomi di AWS Agent Registry a partire dal 6 agosto 2026. Se disponi di registri o record esistenti al 6 agosto 2026, potrai accedere allo bedrock-agentcore spazio dei nomi di AWS Agent Registry durante la finestra di migrazione (6 agosto 2026 — 17 settembre 2026).

I miei dati verranno migrati automaticamente?

No. È necessario avviare personalmente la migrazione utilizzando gli strumenti di migrazione forniti da noi. Consulta la sezione Migrazione dei dati per i dettagli sugli approcci disponibili in base alla tua scala.

Quali modifiche allo schema delle API sono incluse?

Oltre alla modifica dello spazio dei nomi, abbiamo aggiornato il modello di dati dell'API in sei aree: entità del registro (configurazione di autorizzazione raggruppata in), nuovi campi del record di registro (nameand discoveryConfigurationrecordType), ristrutturazione dei record del registro (descrittori appiattiti, ridenominazioni dei campi), aggiornamenti dei filtri dell'API di ricerca (,), nuove API di navigazione (recordType,recordVersion) e filtri strutturati per le operazioni di elencoListDiscoverableRegistryRecords. BatchGetDiscoverableRegistryRecord

Quanto durerà la migrazione dei dati?

Il tempo di migrazione dipende dal numero di registri e record presenti nell'account. Per gli account con meno di 100 record, la migrazione viene completata in pochi minuti se eseguita localmente. Per gli account con migliaia di record, si prevede che la migrazione venga completata in meno di 15 minuti se eseguita come processo gestito.

Cosa succede se dispongo di un'implementazione su larga scala con scritture attive?

Se state scrivendo attivamente dati nel namespace di anteprima in produzione, utilizzate la strategia di migrazione a doppia scrittura descritta nel Caso 3. Questo approccio garantisce che nessun dato vada perso durante la transizione, scrivendo contemporaneamente su entrambi i namespace, migrando i dati storici con deduplicazione e quindi interrompendo le operazioni di lettura.

Dove posso ottenere assistenza?

Per domande o assistenza sulla migrazione, contatta l'AWS assistenza.