Configurar o Amazon Bedrock AgentCore Runtime e as ferramentas para VPC

Você pode configurar o Amazon Bedrock AgentCore Runtime e as ferramentas integradas (Code Interpreter e Browser Tool) para se conectar aos recursos em sua Amazon Virtual Private Cloud (VPC). Ao configurar a conectividade da VPC, você permite acesso seguro a recursos privados, como bancos de dados, APIs internas e serviços dentro da sua VPC.

Conectividade VPC para Amazon Bedrock AgentCore Runtime e ferramentas

Para habilitar o Amazon Bedrock AgentCore Runtime e ferramentas integradas para acessar com segurança recursos em sua VPC privada, AgentCore fornece recursos de conectividade de VPC. Esse recurso permite que seu tempo de execução e suas ferramentas:

Quando você configura a conectividade VPC para o Amazon Bedrock AgentCore Runtime e as ferramentas:

Pré-requisitos

Antes de configurar o Amazon Bedrock AgentCore Runtime e as ferramentas para acesso à VPC, certifique-se de ter:

Zonas de disponibilidade compatíveis

AgentCore oferece suporte à conectividade VPC em zonas de disponibilidade específicas em cada região compatível. Ao configurar sub-redes para seu Amazon Bedrock AgentCore Runtime e ferramentas integradas, certifique-se de que suas sub-redes estejam localizadas nas zonas de disponibilidade suportadas em sua região.

A tabela a seguir mostra os IDs de zona de disponibilidade compatíveis para cada região:

Para identificar o ID da zona de disponibilidade de suas sub-redes, você pode usar o seguinte comando da CLI:

aws ec2 describe-subnets --subnet-ids subnet-12345678 --query 'Subnets[0].AvailabilityZoneId'

Permissões do IAM

AgentCore usa a função vinculada ao serviço AWSServiceRoleForBedrockAgentCoreNetwork para criar e gerenciar interfaces de rede em sua VPC. Essa função é criada automaticamente quando você configura pela primeira vez o Amazon Bedrock AgentCore Runtime ou as ferramentas AgentCore integradas para usar a conectividade VPC.

Se você precisar criar essa função manualmente, sua entidade do IAM precisará das seguintes permissões:

{
    "Action": "iam:CreateServiceLinkedRole",
    "Effect": "Allow",
    "Resource": "arn:aws:iam::*:role/aws-service-role/network.bedrock-agentcore.amazonaws.com/AWSServiceRoleForBedrockAgentCoreNetwork",
    "Condition": {
        "StringLike": {
            "iam:AWSServiceName": "network.bedrock-agentcore.amazonaws.com"
        }
    }
}

Essa permissão já está incluída na política AWS gerenciada BedrockAgentCoreFullAccess.

Práticas recomendadas

Para desempenho e segurança ideais com o VPC-connected Amazon Bedrock AgentCore Runtime e ferramentas integradas:

Configurando o acesso à VPC para tempo de execução e ferramentas

Você pode configurar o acesso à VPC para o Amazon Bedrock AgentCore Runtime e ferramentas integradas usando o AWS Management Console, a AWS CLI ou os SDKs. AWS

Configuração de runtime

Configuração do Code Interpreter

Configuração da ferramenta do navegador

Considerações sobre os grupos de segurança

Grupos de segurança atuam como firewalls virtuais para seu Amazon Bedrock AgentCore Runtime ou ferramenta integrada quando conectados a uma VPC. Eles controlam o tráfego de entrada e saída no nível da instância. Para configurar grupos de segurança para seu tempo de execução:

Exemplo: conexão com um banco de dados do Amazon RDS

Quando seu Amazon Bedrock AgentCore Runtime se conecta a um banco de dados do Amazon RDS, configure os grupos de segurança da seguinte forma:

Grupo de segurança Amazon Bedrock AgentCore Runtime

Grupo de segurança de banco de dados Amazon RDS

Exemplo: conexão com arquivos do Amazon EFS ou do Amazon S3

Quando você configura seus próprios sistemas de arquivos (pontos de acesso do Amazon EFS ou do Amazon S3 Files) no tempo de execução do seu agente, o AgentCore Runtime monta o sistema de arquivos no NFS. Isso requer conectividade TCP na porta 2049 entre as ENIs de tempo de execução do agente e os destinos de montagem do sistema de arquivos.

AgentCore processa a criptografia TLS e a autenticação IAM automaticamente. O auxiliar de amazon-efs-utils montagem vem pré-instalado no tempo de execução do microVM — você não precisa configurar ou instalar nenhum software de montagem na imagem do contêiner.

Configuração do security group

Configure seus grupos de segurança para permitir tráfego NFS entre o tempo de execução do agente e os destinos de montagem do sistema de arquivos.

Grupo de segurança de tempo de execução do agente — regra de saída:

Grupo de segurança de destino de montagem do sistema de arquivos — regra de entrada:

sg-mounttargetSubstitua pelo ID do grupo de segurança dos seus destinos de montagem de arquivos EFS ou S3 e sg-agentruntime pelo ID do grupo de segurança usado pelo tempo de execução do seu agente.

AWS CLI — Adicione uma regra de saída ao grupo de segurança de tempo de execução do agente:

aws ec2 authorize-security-group-egress \
  --group-id sg-0123456789abcdef0 \
  --protocol tcp \
  --port 2049 \
  --source-group sg-0987654321fedcba0

AWS CLI — Adicione uma regra de entrada para montar o grupo de segurança de destino:

aws ec2 authorize-security-group-ingress \
  --group-id sg-0987654321fedcba0 \
  --protocol tcp \
  --port 2049 \
  --source-group sg-0123456789abcdef0

Configuração dos endpoints da VPC

Ao executar o Amazon Bedrock AgentCore Runtime em uma VPC, é altamente recomendável configurar os seguintes endpoints de VPC. Esses endpoints são necessários se sua VPC não tiver acesso à Internet e são altamente recomendados mesmo que sua VPC tenha um gateway NAT, para evitar cobranças de processamento de dados do gateway NAT.

Endpoints de VPC necessários

Considerações sobre o acesso à Internet

Quando você conecta o Amazon Bedrock AgentCore Runtime ou uma ferramenta integrada a uma Virtual Private Cloud (VPC), ela não tem acesso à Internet por padrão. Por padrão, esses recursos podem se comunicar somente com recursos dentro da mesma VPC. Se seu tempo de execução ou ferramenta exigir acesso aos recursos da VPC e à Internet, você deverá configurar sua VPC adequadamente.

Arquitetura de acesso à Internet

Para habilitar o acesso à Internet para seu VPC-connected Amazon Bedrock AgentCore Runtime ou ferramenta integrada, configure sua VPC com os seguintes componentes:

Configuração de roteamento

Atualize suas tabelas de rotas de sub-rede da seguinte forma:

Monitoramento e solução de problemas

Para monitorar e solucionar problemas do VPC-connected Amazon Bedrock AgentCore Runtime e das ferramentas:

CloudWatch Registros

Ative CloudWatch os registros do seu Amazon Bedrock AgentCore Runtime para identificar quaisquer problemas de conectividade:

Problemas e soluções comuns de

Problemas com o Code Interpreter

Problemas com a ferramenta do navegador

Testando a conectividade VPC

Para verificar se o AgentCore Runtime e as ferramentas têm conectividade VPC adequada, você pode testar as conexões com seus recursos privados e verificar se as interfaces de rede foram criadas corretamente nas sub-redes especificadas.

Para verificar se sua AgentCore ferramenta tem acesso à Internet, você pode configurar um interpretador de código com sua configuração de VPC e usar Invoke a API executeCommand com essa tentativa de se conectar a uma API ou site público curl usando o comando e verificar a resposta. Se a conexão expirar, revise sua configuração de VPC, especialmente suas tabelas de rotas e a configuração do gateway NAT.

# Using awscurl
awscurl -X POST \
  "https://bedrock-agentcore.<Region>.amazonaws.com/code-interpreters/<code_interpreter_id>/tools/invoke" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "x-amzn-code-interpreter-session-id: your-session-id" \
  --service bedrock-agentcore \
  --region <Region> \
  -d '{
    "name": "executeCommand",
    "arguments": {
      "command": "curl amazon.com"
    }
  }'

Problemas de conectividade do sistema de arquivos

Quando a montagem do sistema de arquivos falha, a InvokeAgentRuntime API retorna o status HTTP 424 (Falha na dependência). Use as seções a seguir para diagnosticar a causa raiz.

Tempo limite de montagem do sistema de arquivos

Sintomas: as invocações do agente com configurações do sistema de arquivos falham após um atraso prolongado. O erro indica que a operação de montagem atingiu o tempo limite.

Causas e soluções comuns:

1. Faltam regras do grupo de segurança

Verifique a regra de saída no grupo de segurança de tempo de execução do agente:

aws ec2 describe-security-groups \
  --group-ids sg-0123456789abcdef0 \
  --query 'SecurityGroups[0].IpPermissionsEgress[?ToPort==`2049`]'

Verifique a regra de entrada em seu grupo de segurança de destino de montagem:

aws ec2 describe-security-groups \
  --group-ids sg-0987654321fedcba0 \
  --query 'SecurityGroups[0].IpPermissions[?ToPort==`2049`]'

Se uma das consultas retornar resultados vazios, adicione a regra ausente, conforme mostrado em Exemplo: conectando-se aos arquivos do Amazon EFS ou do Amazon S3.

2. Nenhum alvo de montagem na zona de disponibilidade do agente

O tempo de execução do agente pode ser colocado em uma zona de disponibilidade onde não existe um destino de montagem. Verifique a sobreposição:

# Get agent runtime subnet AZs
aws ec2 describe-subnets \
  --subnet-ids subnet-0123456789abcdef0 subnet-0123456789abcdef1 \
  --query 'Subnets[*].[SubnetId, AvailabilityZoneId]' --output table

# Get EFS mount target AZs
aws efs describe-mount-targets \
  --file-system-id fs-0123456789abcdef0 \
  --query 'MountTargets[*].[AvailabilityZoneId, LifeCycleState]' --output table

Solução: crie um destino de montagem em cada zona de disponibilidade em que suas sub-redes de tempo de execução do agente estão localizadas ou restrinja as sub-redes de tempo de execução do agente às zonas de disponibilidade onde existem destinos de montagem.

3. Tabela de rotas sem rota local

Verifique se a tabela de rotas associada às sub-redes de tempo de execução do agente inclui a rota VPC local:

aws ec2 describe-route-tables \
  --filters "Name=association.subnet-id,Values=subnet-0123456789abcdef0" \
  --query 'RouteTables[0].Routes[?DestinationCidrBlock]'

A montagem do sistema de arquivos falha com "ResourceNotFound”

Sintomas: A invocação do agente falha imediatamente (sem tempo limite) com um ResourceNotFound erro referenciando o nome do host do sistema de arquivos.

Causas e soluções comuns:

1. Falha na resolução de DNS — A VPC não consegue resolver o nome do host de destino da montagem do sistema de arquivos.

Verifique as configurações de DNS na sua VPC:

aws ec2 describe-vpc-attribute \
  --vpc-id vpc-0123456789abcdef0 \
  --attribute enableDnsSupport

aws ec2 describe-vpc-attribute \
  --vpc-id vpc-0123456789abcdef0 \
  --attribute enableDnsHostnames

Ambos devem retornartrue. Caso contrário, habilite-os:

aws ec2 modify-vpc-attribute --vpc-id vpc-0123456789abcdef0 --enable-dns-support
aws ec2 modify-vpc-attribute --vpc-id vpc-0123456789abcdef0 --enable-dns-hostnames

2. O destino de montagem não está no estado Disponível — O destino de montagem ainda pode estar sendo criado ou pode ter sido excluído.

# For EFS
aws efs describe-mount-targets --file-system-id fs-0123456789abcdef0

# For S3 Files
aws s3files list-mount-targets --file-system-id fs-0123456789abcdef0

Certifique-se de que o alvo da montagem LifeCycleState sejaavailable. Se o destino de montagem estiver ausente, recrie-o nas sub-redes apropriadas.

3. Sistema de arquivos ou ponto de acesso excluído — O recurso referenciado na configuração de tempo de execução do agente não existe mais. Verifique e atualize o tempo de execução do agente com ARNs válidos.

Incompatibilidade de zonas de disponibilidade (falhas intermitentes)

Sintomas: as montagens do sistema de arquivos são bem-sucedidas de forma intermitente — algumas invocações funcionam, enquanto outras falham com o tempo limite.

Por que isso acontece: o tempo de execução do seu agente tem sub-redes em várias zonas de disponibilidade, mas os destinos de montagem existem apenas em algumas delas. Quando o agente é colocado em uma AZ sem um alvo de montagem, a montagem expira.

Solução: crie destinos de montagem em todas as zonas de disponibilidade em que suas sub-redes de tempo de execução do agente estão localizadas (recomendado) ou remova as sub-redes de tempo de execução do agente que estão em zonas de disponibilidade sem destinos de montagem.

# List all EFS mount target AZs
aws efs describe-mount-targets \
  --file-system-id fs-0123456789abcdef0 \
  --query 'MountTargets[*].AvailabilityZoneId' --output text

# Create a mount target in a missing AZ
aws efs create-mount-target \
  --file-system-id fs-0123456789abcdef0 \
  --subnet-id subnet-in-missing-az \
  --security-groups sg-0987654321fedcba0