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à.

Utilizzo AWS Registro agenti con AWS Organizations

AWS Agent Registry si integra con AWS le organizzazioni in modo da poter catalogare automaticamente le risorse supportate tra gli account dei membri dell'organizzazione in un unico registro.

Quando abiliti il rilevamento automatico per un registro, le risorse supportate ( AgentCore Runtimes e Gateway) negli account dei membri dell'organizzazione vengono automaticamente catalogate come record di registro, senza che sia richiesta alcuna configurazione negli account membri. Un registro configurato per il rilevamento automatico a livello di organizzazione è denominato registro con ambito aziendale e rimane sincronizzato man mano che le risorse vengono create, aggiornate o eliminate e quando gli account entrano o escono dall'organizzazione.

Questa pagina spiega come funziona il rilevamento automatico AWS nelle organizzazioni, come abilitarlo e come gestire i record che produce.

Come funziona il rilevamento automatico con AWS Organizations

Account

Due account partecipano al rilevamento automatico:

Cosa rileva il rilevamento automatico

Quando il rilevamento automatico è abilitato per un registro con ambito organizzativo, rileva i seguenti tipi di risorse dagli account dei membri:

Auto-detection rileva sia le risorse già esistenti quando abiliti la funzionalità, sia le risorse che vengono create successivamente.

In che modo le risorse rilevate diventano record

Per ogni risorsa scoperta, AWS Agent Registry crea un record di registro nel registro dell'amministratore. Ogni record rilevato automaticamente include una voce di provenienza che lo collega alla risorsa di origine, contenente l'ARN (sourceId), il tipo (sourceType) e la relazione della risorsa sorgente. DETECTED_FROM Puoi utilizzare la provenienza per far risalire qualsiasi record alla risorsa e all'account membro da cui ha avuto origine.

Auto-detection è completamente gestito. Una volta abilitato, non c'è nulla da installare o configurare negli account dei singoli membri: nessun agente, nessuna autorizzazione per account e nessuna risorsa per account membro da configurare.

In che modo i campi delle risorse vengono mappati ai campi di registrazione

Le tabelle seguenti mostrano come il rilevamento automatico mappa le proprietà dalla risorsa di origine ai campi dei record del registro.

AgentCore Runtime → Record di registro

AgentCore Gateway → Record di registro

In che modo il catalogo rimane sincronizzato

Dopo l'attivazione del rilevamento automatico, AWS Agent Registry mantiene il registro allineato allo stato dell'organizzazione:

L'impostazione di rilevamento automatico e il relativo stato

Auto-detection coinvolge due campi correlati, uno impostato dall'utente e uno segnalato dal servizio:

In breve, enabled è ciò che richiedi ed autoDetection.status è ciò che è effettivamente in vigore. L'impostazione enabled su true è necessaria ma non sufficiente autoDetection.status per esserloACTIVE.

Prerequisiti

Prima di abilitare il rilevamento automatico, assicurati di avere quanto segue:

Permissions

Nell'account di gestione

Per abilitare l'accesso affidabile e registrare l'amministratore delegato, il chiamante nell'account di gestione necessita delle seguenti AWS autorizzazioni organizzative:

L'account di gestione deve inoltre iam:CreateServiceLinkedRole creare il ruolo collegato al servizio AWS Agent Registry. Questo ruolo deve essere presente nell'account di gestione prima di poter creare un registro con ambito organizzativo; vedere la Fase 1 in «Abilitazione del rilevamento automatico in tutta l'organizzazione».

Nell'account dell'amministratore del registro

Per creare e gestire il registro con ambito organizzativo e i relativi record, il chiamante necessita delle autorizzazioni del Registro degli AWS agenti, tra cuiagent-registry:CreateRegistry,,, e. agent-registry:UpdateRegistry agent-registry:GetRegistry agent-registry:ListRegistryRecords agent-registry:UpdateRegistryRecord Per l'elenco completo e gli esempi di policy, vedi Autorizzazioni IAM. Autorizzazioni IAM

Abilitare il rilevamento automatico in tutta l'organizzazione

L'attivazione del rilevamento automatico è un processo in tre fasi: l'account di gestione consente un accesso affidabile e registra un amministratore delegato, quindi l'amministratore crea un registro con ambito aziendale con il rilevamento automatico attivato.

Passaggio 1: abilitare l'accesso affidabile e creare il ruolo collegato al servizio (account di gestione)

Accedi all'account di gestione, abilita l'accesso affidabile per il rilevamento automatico e assicurati che l'account di gestione abbia il ruolo collegato al servizio AWS Agent Registry.

Console

AWS CLI

Abilita l'accesso affidabile per il rilevamento automatico:

aws organizations enable-aws-service-access \
  --service-principal agent-registry.amazonaws.com

Crea il ruolo collegato al servizio AWS Agent Registry nell'account di gestione:

aws iam create-service-linked-role \
  --aws-service-name agent-registry.amazonaws.com

Fase 2: Registrazione di un amministratore delegato (account di gestione)

Sempre nell'account di gestione, registra l'account che sarà proprietario del registro con ambito organizzativo come amministratore delegato per il rilevamento automatico.

Console

L'amministratore delegato è registrato come parte del passaggio 1 precedente. Quando si configura l'accesso affidabile e si immette l'ID dell'account amministratore delegato nella pagina AWS delle impostazioni dell'organizzazione, entrambi i passaggi vengono completati insieme.

AWS CLI

Sostituiscilo <delegated-admin-account-id> con l'ID di account a 12 cifre dell'account che desideri utilizzare come amministratore del registro.

aws organizations register-delegated-administrator \
  --account-id <delegated-admin-account-id> \
  --service-principal agent-registry.amazonaws.com

Passaggio 3: creare un registro con ambito organizzativo (amministratore del registro)

Accedi all'account amministratore delegato e crea un registro con una configurazione di rilevamento automatico impostata su e per. scope ORGANIZATION enabled true enableddeve essere utilizzato true per l'attivazione del rilevamento automatico: in tal casofalse, il registro viene creato ma il relativo stato di rilevamento automatico non lo diventa mai ACTIVE e non viene rilevata alcuna risorsa.

Console

AWS CLI

aws agent-registry-control create-registry \
  --name "my-organization-registry" \
  --description "Auto-detected resources across my organization" \
  --auto-detection-configuration '{"scope":"ORGANIZATION","enabled":true}' \
  --region us-east-1

Quando si esegue get-registry orlist-registries, vengono visualizzati due campi di stato separati. Il status campo del registro inizia come CREATING e passa a READY quando viene completato il provisioning. Il autoDetection.status campo viene tracciato separatamente: lo è INACTIVE fino a quando non viene eseguito il rilevamento automatico, quindi diventa. ACTIVE Quando il registro status è attivo READY e lo autoDetection.status èACTIVE, iniziano a comparire i record relativi alle risorse supportate negli account dei membri.

Verifica che le risorse vengano rilevate

Elenca i record del registro e cerca i record creati tramite rilevamento automatico:

aws agent-registry-control list-registry-records \
  --registry-id <registry-id-or-arn> \
  --region us-east-1

Per informazioni su come distinguere i record rilevati automaticamente dai record aggiunti dall'utente, consulta. Identificazione dei record rilevati automaticamente

Utilizzo dei record rilevati automaticamente

Identificazione dei record rilevati automaticamente

Auto-detected i record sono identificati da due caratteristiche:

Utilizza il prefisso del nome per filtrare rapidamente i record rilevati automaticamente e la provenienza per risalire alla risorsa e all'account membro da cui proviene.

Console

Puoi identificare i record rilevati automaticamente nella console nei seguenti modi:

Arricchimento dei record rilevati automaticamente

È possibile modificare un record rilevato automaticamente per aggiungere informazioni personalizzate, ad esempio una descrizione più descrittiva, utilizzando. update-registry-record Le modifiche vengono mantenute; il rilevamento automatico aggiorna i campi derivati dall'origine del record senza sovrascrivere i valori impostati.

aws agent-registry-control update-registry-record \
  --registry-id <registry-id-or-arn> \
  --record-id <record-id> \
  --description '{"optionalValue":"MCP server exposing the order-management API as agent tools"}' \
  --region us-east-1

AWS Agent Registry separa i campi di tua proprietà dai campi di proprietà del rilevamento automatico su un record rilevato automaticamente:

Ad esempio, un runtime rilevato dal MCP protocollo viene catalogato come recordType AGENT un mcpServer descrittore e si restringe il record a. MCP Se tale runtime viene successivamente aggiornato per utilizzare il A2A protocollo, l'aggiornamento successivo sostituisce il descrittore con un mcpServer a2aAgentCard descrittore e viene reimpostato da zero a. recordType MCP AGENT Le name impostazioni,description, e recordVersion tu rimangono invariate.

Eliminazione dei record rilevati automaticamente

Non è possibile eliminare un record rilevato automaticamente mentre il rilevamento automatico è abilitato (è). autoDetectionConfiguration.enabled true Auto-detection gestisce il ciclo di vita di questi record: i record vengono rimossi automaticamente quando la risorsa di origine viene eliminata o l'account membro lascia l'organizzazione.

Per eliminare manualmente un record rilevato automaticamente, devi prima disabilitare il rilevamento automatico nel registro impostando su. enabled false Dopo aver disabilitato il rilevamento automatico, è possibile eliminare i record rilevati automaticamente nello stesso modo in cui si elimina qualsiasi altro record.

Approval

Auto-detected i record seguono lo stesso flusso di approvazione dei record creati manualmente: un record deve essere in APPROVED stato per essere rilevabile tramite le API di rilevamento del registro e la directory Record. Se il registro è configurato per l'approvazione automatica, i record diventano rilevabili senza revisione manuale; in caso contrario, un curatore li esamina e li approva. Per ulteriori informazioni, consulta Curare il registro.

Quando il rilevamento automatico aggiorna un record che avevi già approvato, ad esempio perché il protocollo della risorsa di origine è cambiato, il contenuto aggiornato viene scritto come una nuova Draft revisione e non è rilevabile finché non viene approvato. La revisione approvata in precedenza rimane rilevabile nel frattempo, quindi l'individuazione avviene senza interruzioni. Approva la revisione aggiornata per pubblicarla: se il registro utilizza l'approvazione automatica, inviandola per l'approvazione la approva immediatamente; in caso contrario, un curatore la esamina e la approva. Un aggiornamento che non modifica alcun campo derivato dall'origine lascia il record invariato.

Disattivazione del rilevamento automatico

Disattiva il rilevamento automatico nel registro

Per interrompere l'individuazione delle risorse, aggiorna il registro impostando il rilevamento automatico enabled su. false È necessario disabilitare il rilevamento automatico prima di poter eliminare un registro con ambito organizzativo.

Per eliminare un registro con ambito organizzativo, completa questi passaggi nell'ordine:

aws agent-registry-control update-registry \
  --registry-id <registry-id-or-arn> \
  --auto-detection-configuration '{"optionalValue":{"scope":"ORGANIZATION","enabled":false}}' \
  --region us-east-1

L'aggiornamento è asincrono: il registro passa UPDATING e torna a READY quando la modifica diventa effettiva.

Annullare la registrazione dell'amministratore delegato o disattivare l'accesso attendibile

Per rimuovere il rilevamento automatico a livello di organizzazione, l'account di gestione può annullare la registrazione dell'amministratore delegato e disabilitare l'accesso affidabile:

aws organizations deregister-delegated-administrator \
  --account-id <delegated-admin-account-id> \
  --service-principal agent-registry.amazonaws.com

aws organizations disable-aws-service-access \
  --service-principal agent-registry.amazonaws.com

La disabilitazione dell'accesso attendibile o l'annullamento della registrazione di un amministratore delegato proprietario del registro comporta inoltre l'impostazione dei valori e delle condizioni del registro. autoDetectionConfiguration.enabled false autoDetection.status INACTIVE Il motivo dello stato indica «L'accesso attendibile è stato disabilitato per l'organizzazione».

Risoluzione dei problemi

Per risolvere i problemi di rilevamento automatico, vedi Auto-detection gli errori nella pagina principale di risoluzione dei problemi.