Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Condivisione di un registro tra account con AWS RAM

È possibile condividere un registro AWS Agent Registry con altri AWS account utilizzando AWS Resource Access Manager (RAM). Grazie alla condivisione della RAM, gli account esterni al tuo possono scoprire, pubblicare o amministrare i record del tuo registro, senza possedere il registro stesso.

Quando condividi un registro, RAM crea e gestisce una policy basata sulle risorse per tuo conto. Scegli un'autorizzazione gestita che controlla le azioni che l'account utente può eseguire e RAM si occupa del resto.

Come funziona la condivisione tra account

Cross-account la condivisione segue un processo in tre fasi:

Caratteristiche principali:

Prerequisiti

Prima di condividere un registro, assicurati di soddisfare i seguenti requisiti:

Nell'account del proprietario del registro:

Nell'account del consumatore:

Per la condivisione interna all'organizzazione:

Autorizzazioni gestite dalla RAM per AWS Registro degli agenti

Quando si condivide un registro, si allega un'autorizzazione gestita dalla AWS RAM che controlla le azioni che l'account utente può eseguire. AWS Agent Registry fornisce quattro autorizzazioni gestite: una predefinita e tre basate sui ruoli. Queste consentono di concedere l'accesso minimo necessario per ogni caso d'uso.

AWSRAMDefaultPermissionAgentRegistryReadOnly

Questa è l'autorizzazione predefinita per il tipo di agent-registry:Registry risorsa. Quando si crea una condivisione di risorse senza specificare un'autorizzazione, la RAM attribuisce automaticamente tale autorizzazione. Consente l'accesso in sola lettura ai metadati e ai record del registro, sia letture sul piano di controllo che scoperta del piano dati, ma non consente la pubblicazione di record o l'invocazione dell'endpoint MCP (Model Context Protocol) del registro.

Caso d'uso: condividere un registro per la visibilità e il controllo. Il consumatore può sfogliare e cercare nel catalogo, ma non può pubblicare, modificare o richiamare strumenti tramite l'endpoint MCP.

Autorizzazioni concesse:

AWSRAMPermissionAgentRegistryForConsumer

Questa autorizzazione garantisce l'accesso al data plane discovery e la possibilità di richiamare l'endpoint MCP del registro. Usa questa autorizzazione per il consumatore: agenti di intelligenza artificiale o utenti umani che devono scoprire e utilizzare gli strumenti registrati nel catalogo.

Caso d'uso: condividi un registro con un account i cui agenti devono scoprire gli strumenti e richiamarli tramite l'endpoint MCP. Il consumatore non può creare o gestire record.

Autorizzazioni concesse:

AWSRAMPermissionAgentRegistryForPublisher

Questa autorizzazione concede tutto ciò che l'autorizzazione Consumer concede, oltre all'accesso al piano di controllo per creare, aggiornare, eliminare e inviare i record per l'approvazione. Usa questa autorizzazione per gli editori persona—creatori di un account condiviso che forniscono risorse a un registro gestito centralmente.

Caso d'uso: condividi un registro con un team che deve pubblicare server, agenti o strumenti MCP nel tuo catalogo. L'editore può gestire i propri record e scoprirne altri, ma non può approvare o rifiutare i record.

Autorizzazioni concesse:

AWSRAMPermissionAgentRegistryForAdmin

Questa autorizzazione garantisce tutto ciò che l'autorizzazione di Publisher concede, oltre alla possibilità di approvare, rifiutare o deprecare i record. Usa questa autorizzazione per l'amministratore, un amministratore delegato di un altro account che cura il registro condiviso per conto del proprietario.

Caso d'uso: condividi un registro con un account che gestisce l'intero ciclo di vita dei record (pubblicazione, revisione e approvazione dei record) senza possedere l'infrastruttura del registro stessa. L'amministratore non può aggiornare o eliminare il registro.

Autorizzazioni concesse:

Scelta di un'autorizzazione gestita

Creazione di un'autorizzazione gestita dal cliente

Per casi d'uso avanzati, ad esempio limitando l'accesso ai soli record creati da un account specifico utilizzando chiavi di condizione, puoi creare un'autorizzazione RAM gestita dal cliente. Customer-managed le autorizzazioni consentono di definire blocchi personalizzati che fanno riferimento alle chiavi di condizione di Agent Registry. Condition AWS

Per ulteriori informazioni sulla creazione di autorizzazioni gestite dal cliente, consulta Risorse condivisibili nella RAM User Guide. AWS

Per le chiavi di condizione disponibili per AWS Agent Registry, vedere. Chiavi di condizione per un accesso granulare ai record

Condividere un registro con un altro account

Solo il proprietario del registro può avviare la condivisione.

Console

La tabella di condivisione del registro mostra l'associazione. Per le condivisioni esterne, lo stato Associazione indica Associazione finché il consumatore non accetta l'invito.

AWS CLI

Usa il create-resource-share comando per creare una condivisione di risorse RAM con l'ARN del registro e l'ID dell'account del consumatore:

aws ram create-resource-share \
  --name "my-registry-share" \
  --resource-arns "arn:aws:agent-registry:us-east-1:111122223333:registry/MyRegistryId" \
  --principals "444455556666" \
  --permission-arns "arn:aws:ram::aws:permission/AWSRAMPermissionAgentRegistryForConsumer" \
  --allow-external-principals

Sostituisci quanto segue:

Verifica che la condivisione sia attiva:

aws ram get-resource-share-associations \
  --association-type RESOURCE \
  --resource-arns "arn:aws:agent-registry:us-east-1:111122223333:registry/MyRegistryId"

Accetta un invito alla condivisione

Quando un registro è condiviso con un account esterno all' AWS organizzazione del proprietario, l'account del consumatore riceve un invito. Il consumatore deve accettare l'invito prima di poter accedere al registro condiviso.

Console

Dopo l'accettazione, il registro condiviso viene visualizzato nell'elenco del registro del consumatore. Puoi anche scegliere Visualizza i dettagli dell'invito per visualizzare la condivisione nella console AWS RAM.

AWS CLI

Trova l'invito in sospeso:

aws ram get-resource-share-invitations \
  --query 'resourceShareInvitations[?status==`PENDING`]'

Accetta l'invito utilizzando l'ARN di invito riportato nella risposta:

aws ram accept-resource-share-invitation \
  --resource-share-invitation-arn "arn:aws:ram:us-east-1:111122223333:resource-share-invitation/12345678-abcd-efgh-ijkl-123456789012"

Rifiuta un invito alla condivisione

Se non desideri accedere a un registro condiviso, puoi rifiutare l'invito. Rifiutare un invito significa che non avrai accesso al registro condiviso.

Console

AWS CLI

Trova l'invito in sospeso:

aws ram get-resource-share-invitations \
  --query 'resourceShareInvitations[?status==`PENDING`]'

Rifiuta l'invito:

aws ram reject-resource-share-invitation \
  --resource-share-invitation-arn "arn:aws:ram:us-east-1:111122223333:resource-share-invitation/12345678-abcd-efgh-ijkl-123456789012"

Accedere a un registro condiviso

Dopo che la condivisione è attiva (accettando un invito o accettando automaticamente a livello di organizzazione), il consumatore chiama le API di AWS Agent Registry utilizzando le proprie credenziali rispetto all'ARN del registro del proprietario. Le operazioni specifiche disponibili dipendono dall'autorizzazione gestita associata alla condivisione.

Esempio: Discover records in qualità di consumatore

# List approved records in the shared registry
aws agent-registry list-discoverable-registry-records \
  --registry-id "arn:aws:agent-registry:us-east-1:111122223333:registry/MyRegistryId"

# Search for tools
aws agent-registry search-discoverable-registry-records \
  --registry-ids "arn:aws:agent-registry:us-east-1:111122223333:registry/MyRegistryId" \
  --search-query "order management"

# Get full record details
aws agent-registry batch-get-discoverable-registry-record \
  --entries '[{"registryId":"arn:aws:agent-registry:us-east-1:111122223333:registry/MyRegistryId","recordIds":["arn:aws:agent-registry:us-east-1:111122223333:registry/MyRegistryId/record/MyRecordId"]}]'

Esempio: pubblicare un record come editore

aws agent-registry-control create-registry-record \
  --registry-id "arn:aws:agent-registry:us-east-1:111122223333:registry/MyRegistryId" \
  --name "my-mcp-server" \
  --display-name "Order Management MCP Server" \
  --record-type MCP \
  --descriptors '{"mcpServer": {"data": "{\"name\": \"order-mgmt\", \"description\": \"Order management tools\", \"version\": \"1.0.0\"}", "dataSchemaVersion": "2025-12-11"}}' \
  --record-version "1.0"

Interrompi la condivisione con un account

Per revocare l'accesso di un consumatore al registro condiviso, rimuovi l'account consumatore dalla condivisione delle risorse.

Console

Il consumatore perde immediatamente l'accesso al registro. Potrebbe verificarsi un breve ritardo di propagazione (fino a 30 secondi) prima che l'accesso venga revocato completamente.

AWS CLI

Usa disassociate-resource-share per rimuovere un account utente dalla condivisione:

aws ram disassociate-resource-share \
  --resource-share-arn "arn:aws:ram:us-east-1:111122223333:resource-share/12345678-1234-1234-1234-123456789012" \
  --principals "444455556666"

Verifica che il principale sia dissociato:

aws ram get-resource-share-associations \
  --association-type PRINCIPAL \
  --resource-share-arns "arn:aws:ram:us-east-1:111122223333:resource-share/12345678-1234-1234-1234-123456789012"

Per eliminare l'intera condivisione delle risorse (rimuovendo tutti gli account utente contemporaneamente):

aws ram delete-resource-share \
  --resource-share-arn "arn:aws:ram:us-east-1:111122223333:resource-share/12345678-1234-1234-1234-123456789012"

Chiavi di condizione per un accesso granulare ai record

AWS Agent Registry fornisce due chiavi di condizione specifiche del servizio. È possibile utilizzare queste chiavi nelle autorizzazioni RAM gestite dal cliente, nelle policy di identità IAM e negli SCP per controllare l'accesso a livello di singolo record. Sono particolarmente utili quando si condivide un registro tra più account, in cui si desidera che un account utente agisca solo sui record di cui è proprietario o che provengono dal proprio account, anche se un altro account è proprietario del registro stesso.

Entrambe le chiavi vengono risolte al momento dell'autorizzazione dal record archiviato e non possono essere impostate mediante l'input della richiesta, pertanto un utente non può falsificarle per accedere ai record che appartengono ad altri account.

Chiavi relative alle condizioni dei record di registro

Le seguenti chiavi di condizione si applicano alle operazioni a livello di record elencate nella colonna Operazioni API.

Se hai bisogno di tenere i record di altri account completamente fuori dalla vista dei consumatori, non concedere l'autorizzazione condivisa alle azioni di ricerca ed elenco.

Esempio: limita l'accesso ai record creati dal consumatore

La seguente autorizzazione RAM gestita dal cliente consente a un consumatore di leggere, aggiornare ed eliminare solo i record in cui l'account del creatore corrisponde all'account del consumatore:

{
  "Effect": "Allow",
  "Action": [
    "agent-registry:GetDiscoverableRegistryRecord",
    "agent-registry:GetRegistryRecord",
    "agent-registry:UpdateRegistryRecord",
    "agent-registry:DeleteRegistryRecord"
  ],
  "Condition": {
    "StringEquals": {
      "agent-registry:RecordCreatorAccount": "${aws:PrincipalAccount}"
    }
  }
}

La variabile ${aws:PrincipalAccount} policy si risolve dinamicamente al momento della valutazione: ogni consumatore può accedere solo ai record che ha creato personalmente, anche all'interno di un registro condiviso.

Esempio: limitare l'accesso ai record che provengono dall'account del consumatore

La seguente autorizzazione RAM gestita dal cliente consente a un consumatore di leggere solo i record la cui risorsa di origine risiede nell'account del consumatore, utile quando i record vengono rilevati automaticamente dalle risorse di proprietà del consumatore:

{
  "Effect": "Allow",
  "Action": [
    "agent-registry:GetDiscoverableRegistryRecord",
    "agent-registry:GetRegistryRecord"
  ],
  "Condition": {
    "StringEquals": {
      "agent-registry:RecordSourceAccount": "${aws:PrincipalAccount}"
    }
  }
}

Per istruzioni sulla creazione di un'autorizzazione RAM gestita dal cliente, consulta Creazione di un'autorizzazione gestita dal cliente nella RAM User Guide. AWS

Risoluzione dei problemi