As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
Utilizar AWS Registro de agentes com AWS Organizações
AWS O Agent Registry se integra às AWS organizações para que você possa catalogar automaticamente os recursos suportados nas contas dos membros da sua organização em um único registro.
Quando você ativa a detecção automática de um registro, os recursos compatíveis — AgentCore Runtimes e Gateways — nas contas dos membros da sua organização são automaticamente catalogados como registros do registro, sem necessidade de configuração nas contas dos membros. Um registro configurado para detecção automática em toda a organização é chamado de registro com escopo organizacional; ele permanece sincronizado à medida que os recursos são criados, atualizados ou excluídos e quando as contas entram ou saem da organização.
Esta página explica como a detecção automática funciona com AWS organizações, como habilitá-la e como gerenciar os registros que ela produz.
nota
Auto-detection preenche um registro a partir dos recursos que ele descobre. Você ainda pode criar e gerenciar registros manualmente no mesmo registro. Os registros criados pela detecção automática são marcados para que você possa diferenciá-los dos registros que você mesmo adiciona.
Como a detecção automática funciona com AWS Organizações
Contas
Duas contas participam da detecção automática:
-
Conta de gerenciamento — A conta de gerenciamento da sua AWS organização permite acesso confiável para detecção automática e registra o administrador delegado. Essas são operações da AWS organização que somente a conta de gerenciamento pode realizar.
-
Administrador do registro — A conta que possui o registro com escopo organizacional e seus registros detectados automaticamente. Recomendamos usar uma conta de administrador delegada para isso, seguindo a melhor prática AWS de segurança de menor privilégio. A conta de gerenciamento também pode ser proprietária do registro, mas não recomendamos isso.
nota
Uma organização pode ter somente um registro ativo com escopo organizacional por região. Crie-a na conta de gerenciamento ou no administrador delegado — se uma já existir na organização nessa região, a criação de outra será rejeitada.
O que a detecção automática descobre
Quando a detecção automática é ativada para um registro com escopo organizacional, ela descobre os seguintes tipos de recursos em suas contas de membros:
-
AgentCore Tempos de execução do Amazon Bedrock ()
AWS::BedrockAgentCore::Runtime -
AgentCore Gateways Amazon Bedrock ()
AWS::BedrockAgentCore::Gateway
Auto-detection descobre os recursos que já existem quando você ativa o recurso e os recursos que são criados posteriormente.
Como os recursos detectados se tornam registros
Para cada recurso descoberto, o AWS Agent Registry cria um registro de registro no registro do administrador. Cada registro detectado automaticamente inclui uma entrada de proveniência que o vincula ao recurso de origem, contendo o ARN (sourceId), o tipo (sourceType) e a relação do recurso de origem. DETECTED_FROM Você pode usar a proveniência para rastrear qualquer registro até o recurso — e a conta do membro — de onde ele se originou.
Auto-detection é totalmente gerenciado. Depois de ativada, não há nada para instalar ou configurar em contas de membros individuais — sem agentes, sem permissões por conta e sem recursos de conta de membro para configurar.
Como os campos de recursos são mapeados para campos de registro
As tabelas a seguir mostram como a detecção automática mapeia as propriedades do recurso de origem para os campos de registro do registro.
AgentCore Tempo de execução → Registro de registro
| Fonte (propriedade Runtime) | Campo de registro | Observações |
|---|---|---|
|
ID da conta, região, ID do recurso |
|
Auto-generated como |
|
|
|
Sempre |
|
|
Tipo de descritor (dentro |
|
|
|
|
Definido a partir da versão de tempo de execução na primeira detecção e, em seguida, tratado como um valor que você possui — uma alteração posterior na versão do tempo de execução não a altera (consulteEnriquecimento de registros detectados automaticamente). O padrão é se |
|
Construído a partir do ARN e da região em tempo de execução |
URL do endpoint (dentro |
Formato: |
|
ARN de tempo de execução |
|
O ARN completo do tempo de execução de origem. |
|
|
|
Constante para todos os registros de tempo de execução. |
|
|
|
Valor bruto do fio (por exemplo |
|
|
|
Presente somente para tempos de execução com autorização do JWT. Outros campos do autorizador ( |
|
|
|
Presente quando o tempo de execução tem uma identidade de carga de trabalho configurada. |
AgentCore Gateway → Registro de registro
| Fonte (propriedade do gateway) | Campo de registro | Observações |
|---|---|---|
|
ID da conta, região, ID do recurso |
|
Auto-generated como |
|
|
|
|
|
|
Tipo de descritor (dentro |
|
|
(codificado) |
|
Sempre |
|
|
URL do endpoint (dentro |
Extraído literalmente da configuração do gateway (por exemplo, |
|
ARN de gateway |
|
O ARN completo do gateway de origem. |
|
|
|
Constante para todos os registros do gateway. |
|
|
|
Valor bruto do fio (por exemplo, |
|
|
|
Por exemplo, |
|
|
|
Presente somente para gateways com autorização JWT. Outros campos do autorizador ( |
|
|
|
Presente quando o gateway tem uma identidade de carga de trabalho configurada. |
Como o catálogo permanece sincronizado
Depois que a detecção automática estiver ativa, o AWS Agent Registry mantém o registro alinhado com o estado da sua organização:
| Evento em uma conta de membro | Efeito no registro |
|---|---|
|
Já existe um recurso compatível quando você ativa a detecção automática |
Um registro é criado para ele. |
|
Um recurso suportado é criado |
Um registro é criado para ele. |
|
Um recurso suportado é atualizado |
Quando um atributo derivado da fonte muda (como o protocolo, o autorizador ou o endpoint do recurso), os campos derivados da fonte do registro — seu descritor e sua proveniência — são atualizados, enquanto os valores que você mesmo define (como, e) são preservados. |
|
Um recurso suportado foi excluído |
Seu registro é removido. |
|
Uma conta se junta à organização |
Seus recursos suportados são detectados e adicionados. |
|
Uma conta sai (ou é removida) da organização |
Todos os registros detectados dessa conta são removidos. |
nota
Se você descontinuar um registro detectado automaticamente (definir seu status comoDEPRECATED), a detecção automática interromperá a sincronização das alterações do recurso de origem com esse registro. As atualizações subsequentes no recurso de origem, como alterações de protocolo, autorizador ou endpoint, não são aplicadas ao registro obsoleto. Use a suspensão de uso quando quiser congelar um registro específico detectado automaticamente enquanto a ressincronização continua ocorrendo com os outros registros detectados automaticamente no registro.
A configuração de detecção automática versus seu status
Auto-detection envolve dois campos relacionados — um que você define e outro que o serviço relata:
-
autoDetectionConfiguration.enabledé a configuração que você controla. Você o configura ao criar ou atualizar o registro para solicitar que a detecção automática esteja ativada (true) ou desativada (false). AWS O Agent Registry também o desativa para você em alguns casos de desativação: quando o acesso confiável para detecção automática está desativado ou quando o registro de um administrador delegado proprietário do registro é cancelado. -
autoDetection.statusé o estado que o serviço relata —ACTIVEouINACTIVE. Você não configura isso. AWS O Agent Registry faz issoACTIVEsomente quandoenabledestátruee a organização atende às pré-condições de detecção automática; caso contrário, é.INACTIVE
Em resumo, enabled é o que você solicita e autoDetection.status é o que realmente está em vigor. enabledDefinir como true é necessário, mas não suficiente autoDetection.status para serACTIVE.
Pré-requisitos
Antes de ativar a detecção automática, verifique se você tem o seguinte:
-
Suas contas são membros de uma organização nas AWS Organizações, com todos os recursos ativados. Para obter mais informações, consulte Habilitando todos os recursos em sua organização no Guia do usuário AWS das organizações.
-
Você pode entrar na conta de gerenciamento para ativar o acesso confiável e registrar o administrador delegado.
-
Você pode entrar na conta que será o administrador do registro — o administrador delegado é recomendado — para criar o registro com escopo organizacional.
-
Você tem as permissões descritas Permissões em cada uma dessas contas.
Permissões
Na conta de gerenciamento
Para habilitar o acesso confiável e registrar o administrador delegado, o chamador na conta de gerenciamento precisa das seguintes permissões da AWS organização:
-
organizations:EnableAWSServiceAccess -
organizations:RegisterDelegatedAdministrator -
organizations:DeregisterDelegatedAdministratoreorganizations:DisableAWSServiceAccesspara desativar o recurso mais tarde
A conta de gerenciamento também precisa criar iam:CreateServiceLinkedRole a função vinculada ao serviço AWS Agent Registry. Essa função deve existir na conta de gerenciamento antes que um registro com escopo organizacional possa ser criado — consulte a Etapa 1 em “Habilitar a detecção automática em sua organização”.
Na conta do administrador do registro
Para criar e gerenciar o registro com escopo organizacional e seus registros, o chamador precisa de permissões do AWS Agent Registry, incluindo,agent-registry:CreateRegistry, e. agent-registry:UpdateRegistry agent-registry:GetRegistry agent-registry:ListRegistryRecords agent-registry:UpdateRegistryRecord Para ver a lista completa e exemplos de políticas, consulte Permissões do IAM.
Habilitando a detecção automática em toda a sua organização
A ativação da detecção automática é um processo de três etapas: a conta de gerenciamento permite o acesso confiável e registra um administrador delegado e, em seguida, o administrador cria um registro no escopo da organização com a detecção automática ativada.
nota
As etapas desta seção devem ser executadas em ordem. Depois de registrar o administrador delegado (etapa 2), pode demorar um pouco para que o estado da organização se propague. Até que isso aconteça, a criação de um registro com escopo organizacional (etapa 3) é rejeitada. Consulte Solução de problemas.
Etapa 1: habilitar o acesso confiável e criar a função vinculada ao serviço (conta de gerenciamento)
Faça login na conta de gerenciamento, habilite o acesso confiável para detecção automática e certifique-se de que a conta de gerenciamento tenha a função vinculada ao serviço AWS Agent Registry.
Importante
A função vinculada ao serviço AWS Agent Registry (AWSServiceRoleForAgentRegistry) deve existir na conta de gerenciamento antes que um registro com escopo organizacional possa ser criado, inclusive quando o registro é criado pelo administrador delegado em vez da conta de gerenciamento. Habilitar o acesso confiável a partir do console do AWS Agent Registry cria essa função para você. Se você configurar com a AWS CLI ou a API, crie-a explicitamente com o segundo comando abaixo.
Se o registro com escopo organizacional for criptografado com uma chave gerenciada pelo cliente, a função vinculada ao serviço também deverá existir na conta do administrador do registro (normalmente o administrador delegado) antes de ser chamada. CreateRegistry A política de chaves do KMS nessa conta nomeia a função vinculada ao serviço como principal, e o IAM rejeita qualquer política de chave que faça referência a uma principal que ainda não exista. A habilitação do acesso confiável fornece a função na conta do administrador do registro por meio do ASLRP, mas a propagação pode ser adiada brevemente — até que a função chegue lá, CreateRegistry falha na política de chaves do KMS. Para evitar essa corrida, faça com que a conta do administrador do registro crie a função diretamente comaws iam create-service-linked-role --aws-service-name agent-registry.amazonaws.com.
Organization-scoped os registros que não usam uma chave gerenciada pelo cliente não precisam dessa etapa extra — CreateRegistry cria a função vinculada ao serviço na conta do administrador do registro, se ela ainda não estiver lá.
Console
-
Abra o console do AWS Agent Registry — Configurações
. -
Na seção Detalhes da integração AWS das organizações, escolha Editar.
-
Na página de configurações AWS das organizações, em Acesso confiável, ative o botão Ativado. Isso autoriza o AWS Agent Registry a descobrir recursos nas contas dos membros e cria a função
AWSServiceRoleForAgentRegistryvinculada ao serviço nessa conta. -
Em Conta de administrador delegada, insira o ID da conta de 12 dígitos da conta membro que você deseja usar como administrador do registro.
-
Escolha Salvar.
AWS CLI
Habilite o acesso confiável para detecção automática:
aws organizations enable-aws-service-access \ --service-principal agent-registry.amazonaws.com
Crie a função vinculada ao serviço AWS Agent Registry na conta de gerenciamento:
aws iam create-service-linked-role \ --aws-service-name agent-registry.amazonaws.com
Etapa 2: registrar um administrador delegado (conta de gerenciamento)
Ainda na conta de gerenciamento, registre a conta que será proprietária do registro com escopo organizacional como administrador delegado para detecção automática.
nota
A conta que você registra já deve ser membro da sua organização. Se não estiver, adicione-o AWS às Organizações antes de executar esta etapa.
Console
O administrador delegado está registrado como parte da Etapa 1 acima. Quando você configura o acesso confiável e insere o ID da conta do administrador delegado na página de configurações AWS das organizações, as duas etapas são concluídas juntas.
AWS CLI
<delegated-admin-account-id>Substitua pelo ID da conta de 12 dígitos da conta que você deseja usar como administrador do registro.
aws organizations register-delegated-administrator \ --account-id <delegated-admin-account-id> \ --service-principal agent-registry.amazonaws.com
Etapa 3: criar um registro com escopo organizacional (administrador do registro)
Entre na conta de administrador delegada e crie um registro com uma configuração de detecção automática que scope defina como ORGANIZATION e a. enabled true enableddeve ser true para que a detecção automática seja ativada — se forfalse, o registro será criado, mas seu status de detecção automática nunca será ativado ACTIVE e nenhum recurso será detectado.
Console
-
Abra o console do AWS Agent Registry — Registry
. -
Escolha Criar registro.
-
Preencha os campos obrigatórios (nome e, opcionalmente, descrição, autorização de descoberta, aprovação de registro , chave KMS e tags).
-
Expanda a seção Auto-detection.
-
Ative o botão Ativar detecção automática. O escopo é definido como Organização e as permissões de acesso ao serviço são exibidas.
-
Escolha Criar registro.
nota
Auto-detection é executado na região atual. Para descobrir recursos em outras regiões, crie um registro separado com a detecção automática ativada em cada região. Somente um registro pode ter a detecção automática ativada por região.
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 você executa get-registry oulist-registries, você vê dois campos de status separados. O status campo de registro começa como CREATING e passa para READY quando o provisionamento é concluído. O autoDetection.status campo é rastreado separadamente: é INACTIVE até que a detecção automática seja executada e depois se torna. ACTIVE Quando o registro status é READY e autoDetection.status éACTIVE, começam a aparecer registros de recursos compatíveis em suas contas de membros.
nota
enabledA configuração para true solicitar a detecção automática, mas não é suficiente por si só. O autoDetection.status campo é ativado ACTIVE somente quando as duas condições prévias são atendidas: o acesso confiável é habilitado para detecção automática e o registro é de propriedade da conta de gerenciamento ou de um administrador delegado registrado. Essas condições também precisam se propagar, o que pode demorar um pouco depois que você habilita o acesso confiável ou registra um administrador delegado.
Verifique se os recursos estão sendo detectados
Liste os registros do registro e procure os registros criados pela detecção automática:
aws agent-registry-control list-registry-records \ --registry-id <registry-id-or-arn> \ --region us-east-1
nota
Na primeira configuração, a detecção automática descobre os recursos que já existem em suas contas de membros, e essa descoberta inicial pode levar até 20 minutos. Os registros de recursos preexistentes podem não aparecer imediatamente.
Para saber como diferenciar os registros detectados automaticamente dos registros que você mesmo adiciona, consulteIdentificação de registros detectados automaticamente.
Trabalhando com registros detectados automaticamente
Identificação de registros detectados automaticamente
Auto-detected os registros são identificados por duas características:
-
O nome do registro é prefixado com
aws-autodetected-. -
Eles incluem uma entrada de proveniência cuja relação é
DETECTED_FROM, cujosourceIdé o ARN do recurso de origem e quesourceTypeidentifica o tipo de recurso (por exemplo, ou).AWS::BedrockAgentCore::RuntimeAWS::BedrockAgentCore::Gateway
Use o prefixo do nome para filtrar rapidamente os registros detectados automaticamente e a proveniência para rastrear um registro até o recurso — e a conta do membro — de onde ele veio.
Console
Você pode identificar registros detectados automaticamente no console das seguintes maneiras:
-
Tabela de registros do registro — A tabela de registros na página de detalhes do registro inclui três colunas para registros detectados automaticamente: Auto-detection (Yes/No), Tipo de origem (por exemplo, tempo de AgentCore execução do Bedrock) e ID de origem (o ARN do recurso de origem).
-
Filtro de propriedades — Use o filtro de propriedades na tabela de registros para filtrar por Auto-detection = Sim ou Auto-detection = Não.
-
Página de detalhes do registro — Para registros detectados automaticamente, a página de detalhes do registro exibe uma seção de proveniência expansível mostrando a relação (detectada de), o ARN de origem, o tipo de origem, o protocolo do servidor e o ARN da identidade da carga de trabalho.
Enriquecimento de registros detectados automaticamente
Você pode editar um registro detectado automaticamente para adicionar suas próprias informações — por exemplo, uma descrição mais descritiva — usando. update-registry-record Suas edições são preservadas; a detecção automática atualiza os campos derivados da fonte do registro sem sobrescrever os valores que você definiu.
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 O Agent Registry separa os campos que você possui dos campos que a detecção automática possui em um registro detectado automaticamente:
| Campo | Editável por você | Comportamento |
|---|---|---|
|
|
Sim |
Aceitos e preservados; a detecção automática não os substitui quando atualiza o registro a partir da fonte. |
|
Descritor |
Sim |
Você pode enriquecê-lo. |
|
|
Limitado |
Você pode restringir um registro detectado em tempo de execução de |
|
Protocolo do descritor (tipo) |
Não |
Derivado do recurso de origem; uma alteração é rejeitada. |
|
URL de origem do descritor |
Não |
Derivado do recurso de origem; você não pode alterá-lo nem apagá-lo. Para anexar um provedor de credenciais para sincronização, forneça a mesma URL à fonte do descritor — consulte Sincronização de registros. |
|
|
Não |
Vincula o registro ao recurso de origem; uma alteração é rejeitada. |
nota
Se o protocolo do recurso de origem for alterado posteriormente, a detecção automática reconcilia o descritor do registro para que corresponda ao novo protocolo e o redefineAGENT, substituindo um estreitamento recordType feito por você. Suas outras edições, como name edescription, são preservadas.
Por exemplo, um tempo de execução detectado com o MCP protocolo é catalogado como recordType AGENT um mcpServer descritor e você restringe o registro a. MCP Se esse tempo de execução for atualizado posteriormente para usar o A2A protocolo, a próxima atualização substituirá o descritor por um mcpServer a2aAgentCard descritor e será recordType redefinido de volta para. MCP AGENT Oname,description, e recordVersion você definiu permanecem inalterados.
Excluindo registros detectados automaticamente
Você não pode excluir um registro detectado automaticamente enquanto a detecção automática estiver habilitada (autoDetectionConfiguration.enabledestátrue). Auto-detection gerencia o ciclo de vida desses registros — os registros são removidos automaticamente quando o recurso de origem é excluído ou a conta do membro deixa a organização.
Para excluir manualmente um registro detectado automaticamente, primeiro você deve desativar a detecção automática no registro definindo comoenabled. false Depois que a detecção automática for desativada, você poderá excluir registros detectados automaticamente da mesma forma que exclui qualquer outro registro.
Aprovação
Auto-detected os registros seguem o mesmo fluxo de trabalho de aprovação dos registros que você cria manualmente: um registro deve estar em APPROVED status para ser descoberto por meio das APIs de descoberta do registro e do diretório de registros. Se o registro estiver configurado para aprovação automática, os registros podem ser descobertos sem revisão manual; caso contrário, um curador os revisa e aprova. Para obter mais informações, consulte Como organizar o registro.
Quando a detecção automática atualiza um registro que você já aprovou — por exemplo, porque o protocolo do recurso de origem foi alterado — o conteúdo atualizado é gravado como uma nova Draft revisão e não pode ser descoberto até que seja aprovado. Enquanto isso, a revisão que você aprovou anteriormente permanece visível, portanto, a descoberta é ininterrupta. Aprove a revisão atualizada para publicá-la — se o registro usar a aprovação automática, enviá-la para aprovação a aprova imediatamente; caso contrário, um curador a analisa e aprova. Uma atualização que não altera nenhum campo derivado da fonte deixa o registro inalterado.
Desativando a detecção automática
Desativar a detecção automática no registro
Para parar de descobrir recursos, atualize o registro para definir a detecção automática enabled como. false Você deve desativar a detecção automática antes de excluir um registro com escopo organizacional.
Para excluir um registro com escopo organizacional, conclua estas etapas na ordem:
-
Desative a detecção automática no registro.
-
Exclua todos os registros do registro.
-
Exclua o registro.
aws agent-registry-control update-registry \ --registry-id <registry-id-or-arn> \ --auto-detection-configuration '{"optionalValue":{"scope":"ORGANIZATION","enabled":false}}' \ --region us-east-1
A atualização é assíncrona: o registro é movido UPDATING e retornado para READY quando a alteração entra em vigor.
Cancele o registro do administrador delegado ou desative o acesso confiável
Para remover a detecção automática no nível da organização, a conta de gerenciamento pode cancelar o registro do administrador delegado e desativar o acesso confiável:
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
Desativar o acesso confiável ou cancelar o registro de um administrador delegado que é proprietário do registro também define o registro como e comoautoDetectionConfiguration.enabled. false autoDetection.status INACTIVE O motivo do status mostra “O acesso confiável foi desativado para a organização”.
Importante
Se você reativar o acesso confiável após desativá-lo, a detecção automática não será retomada automaticamente. Você deve atualizar manualmente a configuração de detecção automática do registro para enabled voltar para o. true
Solução de problemas
Para solucionar problemas de detecção automática, consulte os Auto-detection erros na página principal de solução de problemas.