Configurando o Amazon Bedrock AgentCore Gateway para acesso seguro a recursos privados

O desafio: agentes de IA que precisam de recursos privados

Agentes de IA em ambientes de produção frequentemente precisam acessar APIs internas, bancos de dados e outros serviços que ficam dentro dos limites de uma Nuvem Privada Virtual da Amazon (Amazon VPC). Gerenciar a conectividade privada para cada par agente-ferramenta gera sobrecarga operacional e atrasa implantações.

Para resolver isso, a AWS disponibilizou a conectividade VPC do Amazon Bedrock AgentCore, projetada para implantar agentes de IA e servidores do Protocolo de Contexto de Modelo (MCP) sem que o tráfego precise ser exposto à internet pública. Essa capacidade inclui o egresso gerenciado de VPC para o Amazon Bedrock AgentCore Gateway, permitindo conexões a endpoints dentro de redes privadas em todo o ambiente AWS.

Neste guia, a AWS explica como configurar o AgentCore Gateway para acessar endpoints privados usando o Resource Gateway — um construto gerenciado que provisiona Interfaces de Rede Elásticas (ENIs) diretamente dentro da sua Amazon VPC, uma por sub-rede. São abordados dois modos de implementação (gerenciado e autogerenciado) e três cenários práticos: conexão a um Amazon API Gateway privado, integração com um servidor MCP no Amazon Elastic Kubernetes Service (Amazon EKS) e acesso a uma API REST privada.

Conceitos fundamentais da arquitetura

Antes de entrar nos modos de implementação, vale entender os termos centrais da arquitetura de egresso VPC do AgentCore Gateway:

• VPC de Recurso: a Amazon VPC onde o seu recurso privado reside — por exemplo, a VPC que hospeda seu servidor MCP ou endpoint de API. Pode estar na mesma conta AWS do AgentCore Gateway ou em uma conta diferente.
• Conta do AgentCore Gateway: a conta AWS onde você cria e gerencia os recursos do AgentCore Gateway.
• Resource Gateway: atua como ponto de entrada privado na VPC de Recurso. Ao ser criado, provisiona uma ENI por sub-rede especificada, cada uma dentro da sua VPC. O tráfego do AgentCore Gateway chega ao seu recurso privado por meio dessas ENIs.
• Resource Configuration: define o recurso específico que o AgentCore Gateway tem permissão de acessar através do Resource Gateway, identificado por nome de domínio ou endereço IP. Em vez de liberar acesso a toda a VPC, a Resource Configuration delimita a conectividade a um único endpoint.
• Service Network Resource Association: conecta uma Resource Configuration à rede de serviço do AgentCore, permitindo que o serviço AgentCore Gateway invoque o endpoint privado. O AgentCore cria e gerencia essa associação automaticamente, independentemente do modo escolhido.

Dois modos de implementação

O egresso VPC do AgentCore Gateway suporta dois modos, dependendo do nível de controle desejado sobre a infraestrutura de rede subjacente.

Modo gerenciado (Managed VPC Resource)

Neste modo, o AgentCore Gateway cuida de tudo automaticamente. Basta fornecer o ID da VPC, os IDs das sub-redes e os grupos de segurança como parte da configuração do target — o AgentCore cria e gerencia o VPC Resource Gateway na sua conta. Esse modo se integra com arquiteturas de rede existentes, seja com VPC peering para conectividade na mesma região ou entre regiões, seja com um modelo hub-and-spoke usando o AWS Transit Gateway para ambientes multi-VPC e híbridos.

O diagrama abaixo ilustra como o AgentCore Gateway se conecta a um Amazon API Gateway privado usando o modo gerenciado:

Nesse fluxo, o AgentCore Gateway inicia a requisição e a roteia para o Resource Gateway provisionado dentro da VPC de Recurso. O tráfego passa pela ENI na sub-rede privada, governado pelos grupos de segurança configurados, e então chega ao endpoint de VPC execute-api, que fornece conectividade privada ao endpoint interno do Amazon API Gateway. No modo gerenciado, você tem apenas visibilidade de leitura sobre o Resource Gateway criado pelo AgentCore.

Modo autogerenciado (Self-Managed Lattice Resource)

Neste modo, você mesmo cria e gerencia o VPC Lattice Resource Gateway e a Resource Configuration antes de referenciá-los na criação do target no AgentCore Gateway. Isso oferece visibilidade e controle completos sobre a Resource Configuration — incluindo o número de endereços IPv4 por ENI, posicionamento de sub-redes e regras de grupos de segurança. Mais importante, permite compartilhar a configuração usando o AWS Resource Access Manager (AWS RAM) (necessário para conectividade entre contas), visualizar associações e revogar acessos quando necessário.

O diagrama a seguir mostra como o AgentCore Gateway se conecta a endpoints de API REST privados usando o modo autogerenciado:

Nesse fluxo, você pré-cria o Resource Gateway e a Resource Configuration antes de configurar o AgentCore Gateway Target. Ao chamar CreateGatewayTarget, você passa o ID da Resource Configuration para associar o target do AgentCore Gateway ao seu endpoint privado. Diferente do modo gerenciado, você é o responsável pelo ciclo de vida completo do Resource Gateway e da Resource Configuration.

Comparativo entre os modos

A tabela a seguir resume as principais diferenças para ajudar a escolher o modo mais adequado para cada arquitetura:

• Complexidade de configuração: o modo gerenciado é mais simples — basta fornecer VPC ID, sub-redes e security groups. O autogerenciado exige criação prévia do Resource Gateway e das Resource Configurations.
• Conectividade entre contas: o modo gerenciado não suporta nativamente — use VPC peering ou AWS Transit Gateway. O autogerenciado suporta com AWS RAM, sem necessidade de peering ou Transit Gateway.
• Visibilidade e governança: no modo gerenciado, as Resource Configurations ficam na conta de serviço do AgentCore e não aparecem no console da VPC. No autogerenciado, há visibilidade total no console do Amazon VPC Lattice, com capacidade de auditar e revogar acessos de forma granular.
• Precificação: o modo gerenciado cobra apenas pelo processamento de dados (por GB). O autogerenciado adiciona uma cobrança por hora pela associação à rede de serviço, mais o processamento de dados.

Pré-requisitos

O tutorial foca no modo gerenciado. Para explorar o modo autogerenciado, a AWS disponibiliza exemplos de código no GitHub. Antes de começar, é necessário ter:

• Interface de Linha de Comando da AWS (AWS CLI)
• Credenciais AWS configuradas
• Certificado de Autoridade Certificadora (CA) pública — atualmente o AgentCore Gateway confia apenas em certificados TLS assinados publicamente. Se o endpoint usar certificado privado ou autoassinado, consulte a solução de contorno disponível no GitHub.
• Permissões de Gerenciamento de Identidade e Acesso da AWS (IAM): o principal IAM precisa da permissão iam:CreateServiceLinkedRole para bedrock-agentcore.amazonaws.com, para que o AgentCore possa criar a role vinculada ao serviço se ela ainda não existir.

O grupo de segurança do Resource Gateway controla o tráfego de saída que as ENIs podem enviar aos recursos dentro da Amazon VPC. Se nenhum grupo de segurança for fornecido ao chamar a API CreateGatewayTarget, o grupo de segurança padrão é utilizado.

Caso ainda não tenha um AgentCore Gateway criado, execute:

aws bedrock-agentcore create-gateway \
  --name my-gateway \
  --role-arn arn:aws:iam::<account-id>:role/AgentCoreGatewayRole

Guarde o gatewayId retornado na resposta — ele será necessário nas etapas seguintes. Para exemplos mais detalhados, consulte o repositório no GitHub.

Cenário 1: Amazon API Gateway privado

Para criar um AgentCore Gateway target que roteia para um Amazon API Gateway privado, chame a API CreateGatewayTarget com os seguintes parâmetros. No campo openApiSchema, forneça a URL do endpoint privado do Amazon API Gateway (https://{api-id}-{vpce-id}.execute-api.{region}.amazonaws.com/{stage}). No bloco managedVpcResource, forneça o ID da VPC, os IDs das sub-redes e o ID do grupo de segurança:

aws bedrock-agentcore-control create-gateway-target \
  --region us-west-2 \
  --cli-input-json '{
    "gatewayIdentifier": "<GATEWAY_ID>",
    "name": "private-apigw",
    "description": "Private API Gateway",
    "targetConfiguration": {
      "mcp": {
        "openApiSchema": {
          "inlinePayload": "..."
        }
      }
    },
    "credentialProviderConfigurations": [...],
    "privateEndpoint": {
      "managedVpcResource": {
        "vpcIdentifier": "<VPC_ID>",
        "subnetIds": ["<SUBNET_ID_1>", "<SUBNET_ID_2>"],
        "endpointIpAddressType": "IPV4",
        "securityGroupIds": ["<VPCE_SG_ID>"]
      }
    }
  }'

Após executar o comando, o AgentCore Gateway usa sua role vinculada ao serviço para provisionar um Resource Gateway na VPC, criando uma ENI por sub-rede especificada. O diagrama abaixo mostra o fluxo de rede resultante:

O AgentCore Gateway inicia a requisição e a roteia para o Resource Gateway provisionado dentro da VPC de Recurso. O tráfego passa pela ENI na sub-rede privada, onde as regras do grupo de segurança governam o próximo salto. A partir daí, a requisição alcança o endpoint de VPC execute-api, que fornece conectividade privada ao endpoint interno do Amazon API Gateway.

Cenário 2: Servidor MCP privado no Amazon EKS

Para rotear para um servidor MCP privado rodando no Amazon EKS, chame a API CreateGatewayTarget com os seguintes parâmetros. No bloco mcpServer, forneça a URL interna do servidor MCP. No bloco managedVpcResource, forneça o ID da VPC, os IDs das sub-redes e o ID do grupo de segurança:

aws bedrock-agentcore-control create-gateway-target \
  --region us-west-2 \
  --cli-input-json '{
    "gatewayIdentifier": "<GATEWAY_ID>",
    "name": "private-apigw",
    "description": "Private API Gateway",
    "targetConfiguration": {
      "mcp": {
        "mcpServer": {
          "endpoint": "https://internal.example.com/csm/mcp"
        }
      }
    },
    "credentialProviderConfigurations": [...],
    "privateEndpoint": {
      "managedVpcResource": {
        "vpcIdentifier": "<VPC_ID>",
        "subnetIds": ["<SUBNET_ID_1>", "<SUBNET_ID_2>"],
        "endpointIpAddressType": "IPV4",
        "securityGroupIds": ["<VPCE_SG_ID>"]
      }
    }
  }'

O diagrama a seguir mostra o caminho completo do tráfego nesse cenário:

O AgentCore Gateway envia uma requisição HTTPS ao endpoint interno. A zona hospedada privada do Amazon Route 53 resolve o domínio para o Balanceador de Carga de Rede (NLB) interno. A requisição entra na VPC de Recurso pelo Resource Gateway, passa pela ENI governada pelos grupos de segurança e chega ao NLB. O NLB encerra o TLS na porta 443 usando um certificado público do AWS Certificate Manager (ACM) e encaminha a requisição via HTTP na porta 80 para o NGINX Ingress Controller rodando no Amazon EKS, que a roteia para o pod apropriado.

Cenário 3: API REST privada

Para rotear para qualquer API REST rodando dentro da Amazon VPC — como um microsserviço em contêiner — a chamada à API CreateGatewayTarget segue o mesmo padrão dos cenários anteriores. No campo openApiSchema, forneça o schema OpenAPI descrevendo a API REST. No bloco managedVpcResource, forneça o ID da VPC, os IDs das sub-redes e o ID do grupo de segurança.

Após o AgentCore Gateway provisionar o Resource Gateway na VPC, o fluxo de tráfego é o seguinte:

O AgentCore Gateway envia uma requisição HTTPS ao endpoint interno. A zona hospedada privada do Amazon Route 53 resolve o domínio para o Balanceador de Carga de Aplicação (ALB) interno. A requisição entra na VPC de Recurso pelo Resource Gateway, passa pela ENI governada pelos grupos de segurança e chega ao ALB interno. O ALB encerra o TLS na porta 443 usando um certificado público do ACM e encaminha a requisição via HTTP na porta 8000 para o grupo de destino contendo os servidores de backend.

Limpeza de recursos

Para evitar cobranças contínuas, exclua todos os recursos criados durante o processo. Consulte a página de preços do egresso VPC do AgentCore Gateway para referência. Clusters do Amazon EKS, load balancers e endpoints do API Gateway geram cobranças enquanto estão ativos.

Se você seguiu o exemplo no GitHub, execute a seção de limpeza ao final de cada Jupyter Notebook. Se usou o modo gerenciado, excluir o Gateway Target remove automaticamente o Amazon VPC Resource Gateway associado:

aws bedrock-agentcore delete-gateway-target \
  --gateway-identifier <gateway-id> \
  --target-id <target-id>

Conclusão e próximos passos

À medida que os agentes de IA assumem tarefas mais complexas, eles precisam de acesso seguro às ferramentas e serviços que sustentam o negócio — muitos dos quais vivem dentro de redes privadas. O egresso VPC do AgentCore Gateway permite que os agentes alcancem servidores MCP privados, APIs internas, bancos de dados e sistemas on-premises sem expô-los à internet pública.

O modo gerenciado se integra diretamente à VPC existente com configuração mínima. O modo autogerenciado oferece controle granular, mas exige configuração adicional. Ambos roteiam o tráfego por um Resource Gateway que nunca sai da rede AWS.

Como próximos passos, a AWS sugere:

• Identificar uma API interna ou servidor MCP no seu ambiente que se beneficiaria de acesso por agentes de IA
• Revisar a arquitetura Amazon VPC existente para determinar qual modo (gerenciado ou autogerenciado) se encaixa melhor
• Consultar a documentação do Amazon Bedrock AgentCore Gateway para opções adicionais de configuração
• Explorar a documentação do Amazon VPC Lattice Resource Gateway para cenários entre contas
• Explorar padrões de integração avançados nos exemplos no GitHub

Fonte

Configuring Amazon Bedrock AgentCore Gateway for secure access to private resources (https://aws.amazon.com/blogs/machine-learning/configuring-amazon-bedrock-agentcore-gateway-for-secure-access-to-private-resources/)