# 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: 1. **Modifiche allo spazio dei nomi e alla configurazione**: stiamo spostando AWS Agent Registry dallo spazio dei nomi AWS Bedrock al relativo spazio AgentCore dei nomi dedicato. Questa modifica dello spazio dei nomi si applica solo all'Agent Registry. AWS Tutte le altre AgentCore offerte, come Identity, Gateway, Runtime e Policy, rimangono inalterate. Per AWS Agent Registry, lo spazio dei nomi del servizio cambia da a. `bedrock-agentcore` `agent-registry` Ciò influisce su ogni superficie che fa riferimento al servizio: endpoint, policy IAM, client SDK, comandi CLI, ARN di risorse e integrazioni di osservabilità. È necessario aggiornare il codice e l'infrastruttura per utilizzare il nuovo spazio dei nomi. 1. **Modifiche allo schema delle API**: i modelli di dati del registro e dei record di registro vengono aggiornati in base al feedback dei clienti durante l'anteprima pubblica. Queste modifiche compromettono la retrocompatibilità con gli schemi API esistenti. Il codice dell'applicazione che costruisce o analizza le richieste e le risposte delle API deve essere aggiornato per riflettere il nuovo schema, come parte della migrazione al nuovo spazio dei nomi. 1. **Migrazione dei dati**: è necessario migrare i registri e i record di registro esistenti dal vecchio namespace a quello nuovo. Forniamo strumenti di migrazione per estrarre i dati, trasformarli nel nuovo schema e caricarli nel nuovo spazio dei nomi. I dati vengono migrati verso lo stesso account e la stessa regione: cambia solo il namespace. 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: + **6 agosto 2026**: AWS Agent Registry diventa Generally Available e il nuovo `agent-registry` namespace viene lanciato ufficialmente. Se disponi di registri e record esistenti, hai accesso simultaneo ai namespace e. `bedrock-agentcore` `agent-registry` [Gli strumenti di migrazione diventano disponibili nel repository agentcore-samples. GitHub ](https://github.com/awslabs/agentcore-samples) È possibile iniziare il processo di migrazione. **Nota** Se sei un nuovo cliente senza registri o record esistenti al 6 agosto 2026, non puoi accedere a AWS Agent Registry tramite il namespace. `bedrock-agentcore` Inizia a utilizzare AWS Agent Registry direttamente dal namespace. `agent-registry` + **17 settembre 2026: la finestra** di migrazione si chiude. Il vecchio `bedrock-agentcore` namespace viene chiuso in questa data. Si perde read/write l'accesso al servizio e a tutti i dati rimanenti nel vecchio namespace. Dopo questa data, è necessario utilizzare lo spazio dei `agent-registry` nomi. ## Modifiche allo spazio dei nomi e alla configurazione Il `agent-registry` namespace viene sostituito nelle seguenti posizioni`bedrock-agentcore`. Questa sezione elenca tutte le superfici che cambiano e fornisce esempi su come aggiornare il codice. **Importante** Le modifiche allo spazio dei nomi riguardano solo le API offerte da AWS Agent Registry, ma non il resto di AWS Bedrock AgentCore, come Identity. AWS AgentCore Pertanto, l'identità del carico di lavoro e le risorse del provider di credenziali OAuth rimangono all'interno dello spazio dei nomi. `bedrock-agentcore` ### Endpoint di servizio Le applicazioni devono puntare ai nuovi nomi host degli endpoint. I nuovi endpoint utilizzano il dominio. `.api.aws` | Surface (Superficie) | Valore precedente | Nuovo valore | | --- | --- | --- | | Endpoint del piano dati | `bedrock-agentcore.{region}.amazonaws.com` | `agent-registry.{region}.api.aws` | | Punto finale del piano di controllo | `bedrock-agentcore-control.{region}.amazonaws.com` | `agent-registry-control.{region}.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. | Surface (Superficie) | Valore precedente | Nuovo valore | | --- | --- | --- | | Prefisso di azione IAM | `bedrock-agentcore:*` | `agent-registry:*` | | Principale del servizio | `bedrock-agentcore.amazonaws.com` | `agent-registry.amazonaws.com` | | Registro ARN | `arn:aws:bedrock-agentcore:{region}:{account}:registry/{id}` | `arn:aws:agent-registry:{region}:{account}:registry/{id}` | | Registra ARN | `arn:aws:bedrock-agentcore:{region}:{account}:registry/{id}/record/{rid}` | `arn:aws:agent-registry:{region}:{account}:registry/{id}/record/{rid}` | 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](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/registry-iam-permissions.html). **Nota** Se attualmente utilizzi la [BedrockAgentCoreFullAccess](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/BedrockAgentCoreFullAccess.html) AWS Managed Policy per l'accesso al registro degli AWS agenti (vedi [i dettagli BedrockAgentCoreFullAccess della politica](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/security-iam-awsmanpol.html#security-iam-awsmanpol-BedrockAgentCoreFullAccess)), devi sostituirla con la nuova policy **AgentRegistryFullAccess**gestita (disponibile su GA). La vecchia policy BedrockAgentCoreFullAccess gestita **NON** verrà aggiornata per includere `agent-registry:*` le autorizzazioni. ### 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. | Surface (Superficie) | Valore precedente | Nuovo valore | | --- | --- | --- | | Classe client Dataplane SDK | `BedrockAgentCoreClient` | `AgentRegistryClient` | | Classe client Controlplane SDK | `BedrockAgentCoreControlClient` | `AgentRegistryControlClient` | | Spazio dei nomi CLI | `aws bedrock-agentcore` | `aws agent-registry` | | Codice Service Quotas | `bedrock-agentcore` | `agent-registry` | 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. | Surface (Superficie) | Vecchio valore | Nuovo valore | | --- | --- | --- | | CloudTrail fonte dell'evento | `bedrock-agentcore.amazonaws.com` | `agent-registry.amazonaws.com` | | EventBridge fonte | `aws.bedrock-agentcore` | `aws.agent-registry` | | CloudWatch spazio dei nomi | `AWS/BedrockAgentCore` | `AWS/AgentRegistry` | ### 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:*"] }] } ``` **Nota** L'`BatchGetDiscoverableRegistryRecord`API non dispone di una propria azione IAM. Autorizza ogni record richiesto contro l'`agent-registry:GetDiscoverableRegistryRecord`azione. Assicurati che la tua politica `GetDiscoverableRegistryRecord` includa l'uso`BatchGet`. **Importante** L'identità del carico di lavoro e le risorse del provider di credenziali OAuth rimangono nel namespace. `bedrock-agentcore` Se i tuoi registri utilizzano URL sync (`source.fromUrl`) con credenziali OAuth o IAM, devi conservare le seguenti autorizzazioni oltre alle nuove autorizzazioni: `agent-registry:*` ``` "bedrock-agentcore:CreateWorkloadIdentity", "bedrock-agentcore:GetWorkloadIdentity", "bedrock-agentcore:DeleteWorkloadIdentity" ``` Non sostituite ogni `bedrock-agentcore` azione: queste risorse di identità conservano intenzionalmente il vecchio namespace. ### 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: + `authorizerType`e `authorizerConfiguration` vengono spostati all'interno di un nuovo `discoveryConfiguration` oggetto. + `approvalConfiguration.autoApproval`(booleano) viene sostituito da `approvalConfiguration.autoApprovalRules` (matrice di stringhe enum). Il valore `"APPROVE_ALL"` ha lo stesso significato semantico di. `autoApproval: true` Vengono applicate le regole specificate nell'elenco enum. Non specificare (null) significa che è necessaria l'approvazione. **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'`CreateRegistryRecord`API e successivamente è possibile modificarli utilizzando l'API. `UpdateRegistryRecord` | Campo | Tipo | Description | | --- | --- | --- | | `name` | Stringa (richiesta) | Un identificatore univoco all'interno del registro che può essere specificato dal cliente. Ogni record deve avere un nome univoco nel registro. Se `recordVersion` è presente anche quando è presente, la combinazione di `name` e `recordVersion` deve essere unica. | | `recordType` | Enum (richiesto) | Il tipo semantico del record. Valori validi: `AGENT`, `MCP`, `SKILL`, `CUSTOM`. Determina con quale chiave descrittrice primaria è valida. `descriptors` Puoi usare API come `ListRegistryRecords` e `SearchDiscoverableRegistryRecords` per filtrare i risultati in base a questo tipo semantico. | ### 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`,, `A2A``AGENT_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 in`dataSchemaVersion`. L'`synchronizationConfiguration`attributo di primo livello diventa `source` e si sposta all'interno di ogni descrittore (compresi `additionalData` i figli). Il `name` campo esistente diventa`displayName`, 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 | Dopo | Note | | --- | --- | --- | | `name` | `displayName` | Visualizza il nome del record. Ci sarà anche un nuovo `name` campo che è la chiave di dedup. | | `descriptorType` | Rimosso | Sostituito dal campo di primo livello`recordType`. | | `inlineContent` | `data` | Il payload del contenuto all'interno di ogni descrittore. | | `schemaVersion` / `protocolVersion` | `dataSchemaVersion` | Campo di versione unificato per tutti i tipi di descrittore. | | `synchronizationConfiguration` | `source` | Spostato all'interno di ogni descrittore (compresi `additionalData` i bambini). | **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` + **AGENTE:**`a2aAgentCard`,, `mcpServer` `custom` + **MCP:**`mcpServer`, `custom` + **ABILITÀ:**`agentSkillsDefinition`, `custom` + **PERSONALIZZATO:** `custom` `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 (sotto`mcpServer.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 `SearchRegistryRecords`diventa `SearchDiscoverableRegistryRecords` (`POST /discoverable-records-search`). La sua richiesta e risposta raccolgono i nuovi nomi di campo e il nuovo modello di dati: + Filtra per `recordType` (sostituisce`descriptorType`). + Filtra per `recordVersion` (sostituisce`version`). + La risposta restituisce i descrittori nel nuovo formato, senza. `credentialProviderConfigurations` Lo strumento di ricerca MCP `search_registry_records` diventa`search_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": "", "values": [""] }` 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 a`GET`. `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 + **Profilo:** meno di 5 registri e meno di 100 record. Hai accesso diretto a un terminale o all'account CloudShell di destinazione. + **Approccio:** Esegui direttamente lo script Python di migrazione. Lo script si connette allo spazio dei nomi di anteprima, elenca i registri e i record, trasforma i dati nello schema GA e li crea nel nuovo spazio dei nomi. Questo è il percorso più semplice e non richiede l'implementazione dell'infrastruttura. #### Caso 2: migrazione gestita con Lambda o Glue + **Profilo:** non hai accesso diretto dal terminale all'ambiente di destinazione o preferisci un modello di esecuzione gestito. + **Approccio:** implementa la migrazione come funzione AWS Lambda o lavoro AWS Glue. Il motore di migrazione esegue lo stesso flusso di lavoro extract-transform-load ma viene eseguito come processo gestito all'interno del tuo account. Per la maggior parte degli account, la migrazione completa viene completata in meno di 15 minuti. Il motore di migrazione: + **Estrae** registri e record dallo spazio dei nomi di anteprima, supportando caricamenti completi e incrementali. Esegue l'impaginazione di tutte le risposte dell'API e serializza i dati in una posizione temporanea. + **Trasforma** ogni record applicando le modifiche allo schema dell'API (ridenominazione dei campi, ristrutturazione dei descrittori, nuovi campi obbligatori). + **Carica** i dati trasformati nel nuovo spazio dei `agent-registry` nomi, creando registri e record utilizzando l'API GA. + **Genera un rapporto** che riassume ciò che è stato migrato, gli eventuali errori riscontrati e il numero di record per la verifica. #### Caso 3: Dual-write migrazione per carichi di lavoro di produzione attivi + **Profilo:** hai creato una piattaforma o una pipeline di automazione sulla base delle API di anteprima pubbliche e stai scrivendo attivamente nuovi dati in fase di produzione. + **Approccio:** utilizza una strategia di migrazione a doppia scrittura per evitare la perdita di dati durante la transizione: + **Aggiorna il tuo writer**: modifica l'applicazione per scrivere contemporaneamente sia nello spazio dei nomi di anteprima che nel nuovo spazio dei nomi. `agent-registry` + **Esegui lo script di migrazione con deduplicazione**: esegui gli strumenti di migrazione per migrare i dati storici. Lo script viene deduplicato in base al `name` campo, in modo che i record già esistenti nel nuovo spazio dei nomi (derivante dalla doppia scrittura) non vengano duplicati. + **Cambia lettore**: dopo aver verificato che tutti i dati esistano nel nuovo namespace, aggiorna l'applicazione in modo che legga esclusivamente da. `agent-registry` + **Rimuovi il dual-write**: dopo aver verificato che tutte le letture e le scritture siano state eseguite correttamente sul nuovo namespace, rimuovi il namespace writer di anteprima dall'applicazione. ### Verifica della migrazione Dopo aver eseguito la migrazione, conferma che i tuoi dati siano stati migrati correttamente: + Elenca tutti i registri nel nuovo spazio dei nomi usando il comando `list-registries` CLI e conferma che il conteggio corrisponda alla tua fonte. + Per ogni registro, confronta il conteggio dei record utilizzando. `list-registry-records` + Spot-check record individuali per confermare che i descrittori sono stati trasformati correttamente (ridenominazione dei campi, ristrutturazione dei descrittori). + Aggiorna le policy IAM, gli endpoint e i client SDK come descritto nella sezione Namespace e modifiche alla configurazione. + Verifica che le tue applicazioni siano in grado di leggere e scrivere correttamente utilizzando il nuovo spazio dei nomi. ## 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 disponibile`agent-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 (`name`and `discoveryConfiguration``recordType`), 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 elenco`ListDiscoverableRegistryRecords`. `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](https://aws.amazon.com/support).