VPC용 Amazon Bedrock AgentCore 런타임 및 도구 구성

Amazon Virtual Private Cloud(VPC)의 리소스에 연결하도록 Amazon Bedrock AgentCore 런타임 및 내장 도구(코드 해석기 및 브라우저 도구)를 구성할 수 있습니다. VPC 연결을 구성하면 데이터베이스, 내부 APIs 및 VPC 내 서비스와 같은 프라이빗 리소스에 대한 보안 액세스를 활성화할 수 있습니다.

Amazon Bedrock AgentCore 런타임 및 도구에 대한 VPC 연결

Amazon Bedrock AgentCore 런타임 및 내장 도구가 프라이빗 VPC의 리소스에 안전하게 액세스할 수 있도록 AgentCore는 VPC 연결 기능을 제공합니다. 이 기능을 사용하면 런타임 및 도구가 다음을 수행할 수 있습니다.

Amazon Bedrock AgentCore 런타임 및 도구에 대한 VPC 연결을 구성하는 경우:

사전 조건

VPC 액세스를 위해 Amazon Bedrock AgentCore 런타임 및 도구를 구성하기 전에 다음을 갖추어야 합니다.

지원되는 가용 영역

AgentCore는 지원되는 각 리전 내의 특정 가용 영역에서 VPC 연결을 지원합니다. Amazon Bedrock AgentCore 런타임 및 내장 도구에 대한 서브넷을 구성할 때 서브넷이 해당 리전에서 지원되는 가용 영역에 있는지 확인합니다.

다음 표에는 각 리전에서 지원되는 가용 영역 IDs 나와 있습니다.

서브넷의 가용 영역 ID를 식별하기 위해 다음 CLI 명령을 사용할 수 있습니다.

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

IAM 권한

AgentCore는 서비스 연결 역할을 AWSServiceRoleForBedrockAgentCoreNetwork 사용하여 VPC에서 네트워크 인터페이스를 생성하고 관리합니다. 이 역할은 VPC 연결을 사용하도록 Amazon Bedrock AgentCore 런타임 또는 AgentCore 내장 도구를 처음 구성할 때 자동으로 생성됩니다.

이 역할을 수동으로 생성해야 하는 경우 IAM 엔터티에는 다음 권한이 필요합니다.

{
    "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"
        }
    }
}

이 권한은 AWS 관리형 정책 BedrockAgentCoreFullAccess에 이미 포함되어 있습니다.

모범 사례

VPC에 연결된 Amazon Bedrock AgentCore 런타임 및 기본 제공 도구를 사용하여 최적의 성능과 보안을 제공하려면:

런타임 및 도구에 대한 VPC 액세스 구성

AWS 관리 콘솔, CLI 또는SDK를 사용하여 Amazon Bedrock AgentCore 런타임 및 내장 도구에 대한 AWS VPC 액세스를 구성할 수 있습니다. AWS SDKs

런타임 구성

코드 해석기 구성

브라우저 도구 구성

보안 그룹 고려 사항

보안 그룹은 VPC에 연결할 때 Amazon Bedrock AgentCore 런타임 또는 기본 제공 도구의 가상 방화벽 역할을 합니다. 인스턴스 수준에서 인바운드 및 아웃바운드 트래픽을 제어합니다. 런타임에 대한 보안 그룹을 구성하려면:

예: Amazon RDS 데이터베이스에 연결

Amazon Bedrock AgentCore 런타임이 Amazon RDS 데이터베이스에 연결되면 다음과 같이 보안 그룹을 구성합니다.

Amazon Bedrock AgentCore 런타임 보안 그룹

Amazon RDS 데이터베이스 보안 그룹

예: Amazon EFS 또는 Amazon S3 파일에 연결

에이전트 런타임에서 bring-your-own 시스템(Amazon EFS 또는 Amazon S3 파일 액세스 포인트)을 구성하면 AgentCore 런타임은 NFS를 통해 파일 시스템을 탑재합니다. 이렇게 하려면 포트 2049에서 에이전트 런타임 ENIs와 파일 시스템 탑재 대상 간의 TCP 연결이 필요합니다.

AgentCore는 TLS 암호화 및 IAM 인증을 자동으로 처리합니다. amazon-efs-utils 탑재 헬퍼는 microVM 런타임에 사전 설치되어 있으므로 컨테이너 이미지에 탑재 소프트웨어를 구성하거나 설치할 필요가 없습니다.

보안 그룹 구성

에이전트 런타임과 파일 시스템 탑재 대상 간의 NFS 트래픽을 허용하도록 보안 그룹을 구성합니다.

에이전트 런타임 보안 그룹 - 아웃바운드 규칙:

파일 시스템 탑재 대상 보안 그룹 - 인바운드 규칙:

sg-mounttarget을 EFS 또는 S3 Files 탑재 대상의 보안 그룹 ID로 바꾸고 sg-agentruntime을 에이전트 런타임에서 사용하는 보안 그룹 ID로 바꿉니다.

AWS CLI - 에이전트 런타임 보안 그룹에 아웃바운드 규칙 추가:

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

AWS CLI - 대상 보안 그룹을 탑재할 인바운드 규칙 추가:

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

VPC 엔드포인트 구성

VPC에서 Amazon Bedrock AgentCore 런타임을 실행할 때는 다음 VPC 엔드포인트를 구성하는 것이 좋습니다. 이러한 엔드포인트는 VPC에 인터넷 액세스 권한이 없는 경우 필요하며, VPC에 NAT 게이트웨이가 있더라도 NAT 게이트웨이 데이터 처리 요금을 피하는 것이 좋습니다.

필수 VPC 엔드포인트

인터넷 액세스 고려 사항

Amazon Bedrock AgentCore 런타임 또는 기본 제공 도구를 Virtual Private Cloud(VPC)에 연결하면 기본적으로 인터넷에 액세스할 수 없습니다. 기본적으로 이러한 리소스는 동일한 VPC 내의 리소스와만 통신할 수 있습니다. 런타임 또는 도구에서 VPC 리소스와 인터넷 모두에 액세스해야 하는 경우 그에 따라 VPC를 구성해야 합니다.

인터넷 액세스 아키텍처

VPC에 연결된 Amazon Bedrock AgentCore 런타임 또는 내장 도구에 대한 인터넷 액세스를 활성화하려면 다음 구성 요소로 VPC를 구성합니다.

라우팅 구성

다음과 같이 서브넷 라우팅 테이블을 업데이트합니다.

모니터링 및 문제 해결

VPC에 연결된 Amazon Bedrock AgentCore 런타임 및 도구를 모니터링하고 문제를 해결하려면:

CloudWatch Logs

Amazon Bedrock AgentCore 런타임에 대해 CloudWatch Logs를 활성화하여 연결 문제를 식별합니다.

일반적인 문제 및 해결 방법

코드 해석기 문제

브라우저 도구 문제

VPC 연결 테스트

AgentCore 런타임 및 도구에 적절한 VPC 연결이 있는지 확인하기 위해 프라이빗 리소스에 대한 연결을 테스트하고 지정된 서브넷에서 네트워크 인터페이스가 올바르게 생성되었는지 확인할 수 있습니다.

AgentCore 도구에 인터넷 액세스 권한이 있는지 확인하려면 VPC 구성으로 코드 인터프리터를 구성하고 curl 명령을 사용하여 퍼블릭 Invoke API 또는 웹 사이트에 연결executeCommand하려는와 함께 API를 사용하여 응답을 확인할 수 있습니다. 연결 시간이 초과되면 VPC 구성, 특히 라우팅 테이블 및 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"
    }
  }'

파일 시스템 연결 문제

파일 시스템 탑재가 실패하면 InvokeAgentRuntime API는 HTTP 상태 424(실패한 종속성)를 반환합니다. 다음 섹션을 사용하여 근본 원인을 진단합니다.

파일 시스템 탑재 시간 초과

증상: 파일 시스템 구성을 사용한 에이전트 호출은 장시간 지연 후 실패합니다. 오류는 탑재 작업 시간이 초과되었음을 나타냅니다.

일반적인 원인 및 해결 방법:

1: 보안 그룹 규칙 누락

에이전트 런타임 보안 그룹에서 아웃바운드 규칙을 확인합니다.

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

탑재 대상 보안 그룹에서 인바운드 규칙을 확인합니다.

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

두 쿼리 중 하나가 빈 결과를 반환하는 경우 예제: Amazon EFS 또는 Amazon S3 파일에 연결에 표시된 대로 누락된 규칙을 추가합니다.

2. 에이전트의 가용 영역에 탑재 대상이 없음

에이전트 런타임은 탑재 대상이 없는 가용 영역에 배치될 수 있습니다. 중복 확인:

# 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

해결 방법: 에이전트 런타임 서브넷이 있는 각 가용 영역에 탑재 대상을 생성하거나, 에이전트 런타임 서브넷을 탑재 대상이 있는 가용 영역으로 제한합니다.

3. 라우팅 테이블에 로컬 라우팅 누락

에이전트 런타임 서브넷과 연결된 라우팅 테이블에 로컬 VPC 경로가 포함되어 있는지 확인합니다.

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

"ResourceNotFound"로 파일 시스템 탑재 실패

증상: 에이전트 호출이 파일 시스템 호스트 이름을 참조하는 ResourceNotFound 오류와 함께 즉시 실패합니다(제한 시간 없음).

일반적인 원인 및 해결 방법:

1: DNS 확인 실패 - VPC가 파일 시스템 탑재 대상 호스트 이름을 확인할 수 없습니다.

VPC에서 DNS 설정을 확인합니다.

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

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

둘 다를 반환해야 합니다true. 그렇지 않은 경우 다음을 활성화합니다.

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. 탑재 대상이 사용 가능 상태가 아님 - 탑재 대상이 아직 생성 중이거나 삭제되었을 수 있습니다.

# 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

탑재 대상이 LifeCycleState 인지 확인합니다available. 탑재 대상이 누락된 경우 적절한 서브넷에서 다시 생성합니다.

3. 파일 시스템 또는 액세스 포인트 삭제됨 - 에이전트 런타임 구성에서 참조되는 리소스가 더 이상 존재하지 않습니다. 유효한 ARNs.

가용 영역 불일치(간접 실패)

증상: 파일 시스템 탑재가 간헐적으로 성공합니다. 일부 호출은 작동하지만 다른 호출은 제한 시간으로 인해 실패합니다.

이 경우의 이유: 에이전트 런타임에는 여러 가용 영역에 서브넷이 있지만 탑재 대상은 그 중 일부에만 존재합니다. 에이전트가 탑재 대상 없이 AZ에 배치되면 탑재 시간이 초과됩니다.

해결 방법: 에이전트 런타임 서브넷이 있는 모든 가용 영역에 탑재 대상을 생성하거나(권장) 탑재 대상이 없는 가용 영역에 있는 에이전트 런타임 서브넷을 제거합니다.

# 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