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

Compartilhando um registro entre contas com AWS RAM

Você pode compartilhar um registro do AWS Agent Registry com outras AWS contas usando o AWS Resource Access Manager (RAM). Com o compartilhamento de RAM, contas externas às suas podem descobrir, publicar ou administrar registros em seu registro, sem possuir o registro em si.

Quando você compartilha um registro, a RAM cria e gerencia uma política baseada em recursos em seu nome. Você escolhe uma permissão gerenciada que controla quais ações a conta do consumidor pode realizar, e a RAM cuida do resto.

Como funciona o compartilhamento entre contas

Cross-account o compartilhamento segue um processo de três etapas:

Características principais:

Pré-requisitos

Antes de compartilhar um registro, verifique se você atende aos seguintes requisitos:

Na conta do proprietário do registro:

Na conta do consumidor:

Para compartilhamento interno da organização:

Permissões gerenciadas por RAM para AWS Registro de agentes

Ao compartilhar um registro, você anexa uma permissão gerenciada de AWS RAM que controla quais ações a conta do consumidor pode realizar. AWS O Agent Registry fornece quatro permissões gerenciadas: uma padrão e três baseadas em funções. Eles permitem que você conceda o acesso mínimo necessário para cada caso de uso.

AWSRAMDefaultPermissionAgentRegistryReadOnly

Essa é a permissão padrão para o tipo agent-registry:Registry de recurso. Quando você cria um compartilhamento de recursos sem especificar uma permissão, a RAM atribui essa permissão automaticamente. Ele concede acesso somente para leitura aos metadados e registros do registro — tanto leituras do plano de controle quanto descoberta do plano de dados — mas não permite publicar registros ou invocar o endpoint do Model Context Protocol (MCP) do registro.

Caso de uso: compartilhe um registro para visibilidade e auditoria. O consumidor pode navegar e pesquisar no catálogo, mas não pode publicar, modificar ou invocar ferramentas por meio do endpoint MCP.

Permissões concedidas:

AWSRAMPermissionAgentRegistryForConsumer

Essa permissão concede acesso à descoberta do plano de dados, além da capacidade de invocar o endpoint MCP do registro. Use essa permissão para a personalidade do consumidor: agentes de IA ou usuários humanos que precisam descobrir e usar ferramentas registradas no catálogo.

Caso de uso: compartilhe um registro com uma conta cujos agentes precisam descobrir ferramentas e invocá-las por meio do endpoint MCP. O consumidor não pode criar nem gerenciar registros.

Permissões concedidas:

AWSRAMPermissionAgentRegistryForPublisher

Essa permissão concede tudo o que a permissão do Consumidor concede, além de acesso ao plano de controle para criar, atualizar, excluir e enviar registros para aprovação. Use essa permissão para a personalidade do editor: criadores em uma conta compartilhada que contribuem com recursos para um registro de propriedade central.

Caso de uso: compartilhe um registro com uma equipe que precisa publicar servidores, agentes ou ferramentas MCP em seu catálogo. O editor pode gerenciar seus próprios registros e descobrir outros, mas não pode aprovar ou rejeitar registros.

Permissões concedidas:

AWSRAMPermissionAgentRegistryForAdmin

Essa permissão concede tudo o que a permissão do Editor concede, além da capacidade de aprovar, rejeitar ou descontinuar registros. Use essa permissão para a pessoa administrativa: um administrador delegado em outra conta que cuida do registro compartilhado em nome do proprietário.

Caso de uso: compartilhe um registro com uma conta que gerencia todo o ciclo de vida do registro — publicação, revisão e aprovação de registros — sem possuir a própria infraestrutura de registro. O administrador não pode atualizar ou excluir o registro.

Permissões concedidas:

Escolhendo uma permissão gerenciada

Criação de uma permissão gerenciada pelo cliente

Para casos de uso avançados, como restringir o acesso somente a registros criados por uma conta específica usando chaves de condição, você pode criar uma permissão de RAM gerenciada pelo cliente. Customer-managed as permissões permitem definir Condition blocos personalizados que fazem referência às chaves de condição do AWS Agent Registry.

Para obter mais informações sobre a criação de permissões gerenciadas pelo cliente, consulte Recursos compartilháveis no Guia do usuário da AWS RAM.

Para obter as chaves de condição disponíveis para o AWS Agent Registry, consulteChaves de condição para acesso refinado a registros.

Compartilhar um registro com outra conta

Somente o proprietário do registro pode iniciar o compartilhamento.

Console

A tabela de compartilhamento do Registro mostra a associação. Para ações externas, o status Associação mostra Associando até que o consumidor aceite o convite.

AWS CLI

Use o create-resource-share comando para criar um compartilhamento de recursos de RAM com o ARN do registro e o ID da conta do consumidor:

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

Substitua o seguinte:

Verifique se o compartilhamento está ativo:

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

Aceitar um convite de compartilhamento

Quando um registro é compartilhado com uma conta fora da AWS organização do proprietário, a conta do consumidor recebe um convite. O consumidor deve aceitar o convite antes de acessar o registro compartilhado.

Console

Depois de aceitar, o registro compartilhado aparecerá na lista de registros do consumidor. Você também pode escolher Exibir detalhes do convite para ver o compartilhamento no console AWS RAM.

AWS CLI

Encontre o convite pendente:

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

Aceite o convite usando o ARN do convite da resposta:

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"

Rejeitar um convite de compartilhamento

Se você não quiser acessar um registro compartilhado, poderá rejeitar o convite. Rejeitar um convite significa que você não terá acesso ao registro compartilhado.

Console

AWS CLI

Encontre o convite pendente:

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

Rejeite o convite:

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"

Acesse um registro compartilhado

Depois que o compartilhamento estiver ativo (seja por meio da aceitação de um convite ou da aceitação automática no nível da organização), o consumidor chama as APIs do AWS Agent Registry usando suas próprias credenciais no ARN do registro do proprietário. As operações específicas disponíveis dependem da permissão gerenciada anexada ao compartilhamento.

Exemplo: descubra registros como consumidor

# 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"]}]'

Exemplo: publicar um registro como editor

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"

Pare de compartilhar com uma conta

Para revogar o acesso de um consumidor ao seu registro compartilhado, remova a conta do consumidor do compartilhamento de recursos.

Console

O consumidor perde imediatamente o acesso ao registro. Pode haver um pequeno atraso de propagação (até 30 segundos) antes que o acesso seja totalmente revogado.

AWS CLI

Use disassociate-resource-share para remover uma conta de consumidor do compartilhamento:

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

Verifique se o principal está desassociado:

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"

Para excluir todo o compartilhamento de recursos (removendo todas as contas de consumidores de uma só vez):

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

Chaves de condição para acesso refinado a registros

AWS O Agent Registry fornece duas chaves de condição específicas do serviço. Você pode usar essas chaves em permissões de RAM gerenciadas pelo cliente, políticas de identidade do IAM e SCPs para controlar o acesso no nível do registro individual. Eles são especialmente úteis ao compartilhar um registro entre contas, em que você deseja que uma conta de consumidor atue somente nos registros que possui ou que se originam de sua própria conta, mesmo que outra conta seja proprietária do próprio registro.

Ambas as chaves são resolvidas no momento da autorização a partir do registro armazenado e não podem ser definidas a partir da entrada da solicitação, portanto, um consumidor não pode falsificá-las para obter acesso aos registros que pertencem a outras contas.

Chaves de condição do registro de registro

As chaves de condição a seguir se aplicam às operações em nível de registro listadas na coluna de operações da API.

Se você precisar manter registros de outras contas totalmente fora da visão do consumidor, não conceda as ações de pesquisa e lista na permissão compartilhada.

Exemplo: restringir o acesso aos registros criados pelo consumidor

A seguinte permissão de RAM gerenciada pelo cliente permite que um consumidor leia, atualize e exclua somente registros em que a conta do criador corresponda à conta do próprio consumidor:

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

A variável ${aws:PrincipalAccount} de política é resolvida dinamicamente no momento da avaliação — cada consumidor só pode acessar os registros que ele mesmo criou, mesmo dentro de um registro compartilhado.

Exemplo: restringir o acesso aos registros que se originam da conta do consumidor

A seguinte permissão de RAM gerenciada pelo cliente permite que um consumidor leia somente registros cujo recurso de origem reside na própria conta do consumidor — útil quando os registros são detectados automaticamente a partir de recursos de propriedade do consumidor:

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

Para obter instruções sobre como criar uma permissão de RAM gerenciada pelo cliente, consulte Criação de uma permissão gerenciada pelo cliente no Guia do AWS usuário de RAM.

Solução de problemas