스토리지 옵션 한 눈에 보기 빠른 시작 작동 방식 사전 조건 파일 시스템 구성 한도 파일 시스템 탑재 문제 해결

AgentCore 코드 해석기의 파일 시스템 구성

AgentCore Code Interpreter는 filesystemConfigurations 파라미터를 통해 자체 파일 시스템을 코드 인터프리터 세션에 탑재할 수 있도록 지원합니다. 각 구성은 지정한 경로에 Amazon S3 파일 또는 Amazon EFS 액세스 포인트를 탑재합니다. 사용자 지정 탑재 코드, 권한 있는 컨테이너 또는 다운로드 오케스트레이션이 필요하지 않음 - AgentCore는 세션 샌드박스 내에서 모든 탑재 작업을 수행합니다.

Bring-your-own 파일 시스템은 공유 스토리지입니다. 여러 세션, 여러 코드 인터프리터 또는 외부 애플리케이션이 동일한 액세스 포인트에 동시에 액세스할 수 있습니다. 데이터는 자체 AWS 계정에서 유지 및 관리됩니다.

CreateCodeInterpreter를 사용하여 코드 인터프리터를 생성할 filesystemConfigurations 때(해당 코드 인터프리터에서 시작된 모든 세션이 탑재를 상속함) 또는 StartCodeInterpreterSession으로 세션을 시작할 때( 탑재가 해당 세션에 적용됨)를 제공할 수 있습니다. 파라미터와 셰이프는 두 위치에서 동일합니다.

참고

AgentCore 런타임과 달리 AgentCore 코드 해석기는 관리형 세션 스토리지 옵션을 제공하지 않습니다. Code Interpreter는 bring-your-own Amazon S3 파일 및 Amazon EFS 액세스 포인트만 지원합니다.

스토리지 옵션 한 눈에 보기

다음 표에서는 사용 가능한 파일 시스템 유형을 비교합니다.

유형	격리	Persistence	VPC 필요	최적의 용도
Amazon S3 Files	공유 - 여러 세션 및 코드 인터프리터가 동일한 데이터에 액세스	고객 관리형(영구, 지원 S3 버킷과 동기화)	예	표준 파일 작업과 S3 APIs를 통해 액세스할 수 있는 데이터 세트 및 아티팩트
Amazon EFS	공유 - 여러 세션 및 코드 인터프리터가 동일한 데이터에 액세스	고객 관리형(삭제할 때까지 영구)	예	세션 간 공유 참조 데이터, 다운로드, 읽기-쓰기 공동 작업

빠른 시작

다음 체크리스트는 각 파일 시스템 유형을 구성하기 위한 요약된 단계를 제공합니다.

Amazon S3 파일 액세스 포인트

s3files:AccessPointArn 조건을 s3files:GetAccessPoint 사용하여 코드 인터프리터 실행 역할에 s3files:ClientWrite, 및 s3files:ClientMount를 추가합니다.
코드 인터프리터 보안 그룹에서 S3 파일 탑재 대상 보안 그룹으로 TCP 포트 2049 아웃바운드를 허용합니다.
S3 파일 탑재 대상이 코드 인터프리터 서브넷과 동일한 VPC 및 가용 영역에 있는지 확인합니다.
CreateCodeInterpreter 또는 StartCodeInterpreterSession 호출에 s3FilesConfiguration 항목과 filesystemConfigurations 함께를 추가합니다.
세션을 시작합니다. 탑재 경로의 파일(예: /mnt/s3data)은 지원 S3 버킷과 양방향으로 동기화됩니다.

Amazon EFS 액세스 포인트

elasticfilesystem:AccessPointArn 조건elasticfilesystem:ClientWrite과 함께 코드 인터프리터 실행 역할에 elasticfilesystem:ClientMount 및를 추가합니다.
코드 인터프리터 보안 그룹에서 EFS 탑재 대상 보안 그룹으로 TCP 포트 2049 아웃바운드를 허용합니다.
EFS 탑재 대상이 코드 인터프리터 서브넷 중 하나 이상과 동일한 가용 영역에 있는지 확인합니다.
CreateCodeInterpreter 또는 StartCodeInterpreterSession 호출에 efsConfiguration 항목과 filesystemConfigurations 함께를 추가합니다.
세션을 시작합니다. 파일은 탑재 경로(예: /mnt/efs)에서 사용할 수 있습니다.

S3 파일과 EFS 모두 코드 인터프리터에서 VPC 연결이 필요합니다.

작동 방식

bring-your-own 시스템을 구성하면 AgentCore Code Interpreter는 지정된 액세스 포인트를 구성한 경로의 세션 샌드박스에 탑재합니다. 데이터 공유 - 여러 세션, 여러 코드 인터프리터 또는 외부 애플리케이션이 동일한 파일 시스템에 동시에 액세스할 수 있습니다.

AgentCore는 모든 탑재 작업을 자동으로 처리합니다. 탑재 도우미를 설치하거나, TLS 인증서를 관리하거나, 탑재 코드를 작성할 필요가 없습니다.

참고

액세스 포인트(S3 파일 또는 EFS)를 생성할 때 POSIX 사용자 ID(UID) 및 그룹 ID(GID)를 지정합니다. 액세스 포인트를 통한 모든 파일 작업은이 자격 증명으로 실행됩니다.

Amazon S3 파일 탑재 흐름

S3 파일 시스템(S3 버킷 지원)을 생성하고 VPC에 대상을 탑재합니다.
POSIX UID/GID 및 루트 디렉터리를 지정하는 S3 파일 액세스 포인트를 생성합니다.
액세스 포인트 ARN, 파일 시스템 ARN 및 탑재 경로를 사용하여 코드 인터프리터(또는 세션)를 구성합니다.
세션 시작 시 AgentCore는 VPC에 대한 네트워크 액세스 권한이 있는 샌드박스를 프로비저닝합니다.
샌드박스는 VPC를 통한 IAM 인증(포트 2049)을 통해 TLS를 통한 NFSv4.2를 통해 파일 시스템을 탑재합니다.
에이전트는 탑재 경로에서 파일을 읽고 씁니다. 변경 사항은 백업 S3 버킷에 자동으로 동기화됩니다.

Amazon EFS 탑재 흐름

VPC에 EFS 파일 시스템 및 탑재 대상을 생성합니다(가용 영역당 하나).
POSIX UID/GID 및 루트 디렉터리를 지정하는 EFS 액세스 포인트를 생성합니다.
액세스 포인트 ARN, 파일 시스템 ARN 및 탑재 경로를 사용하여 코드 인터프리터(또는 세션)를 구성합니다.
세션 시작 시 AgentCore는 VPC에 대한 네트워크 액세스 권한이 있는 샌드박스를 프로비저닝합니다.
샌드박스는 동일한 가용 영역의 탑재 대상을 통해 TLS(포트 2049)를 통해 NFSv4.1을 통해 파일 시스템을 탑재합니다.
에이전트는 표준 파일 작업을 사용하여 탑재 경로에서 파일을 읽고 씁니다.

사전 조건

기존 보유 파일 bring-your-own 시스템을 구성하기 전에 다음 사전 조건을 완료합니다.

VPC 구성

코드 인터프리터는 VPC 네트워크 모드를 사용해야 합니다. 지정하는 서브넷이 파일 시스템 탑재 대상 가용 영역과 겹쳐야 합니다.

IAM 권한

코드 인터프리터 실행 역할에는 파일 시스템을 탑재할 수 있는 권한이 포함되어야 합니다.

S3 파일에 대한 IAM 권한


{
  "Effect": "Allow",
  "Action": [
    "s3files:ClientMount",
    "s3files:ClientWrite",
    "s3files:GetAccessPoint"
  ],
  "Resource": "arn:aws:s3files:<region>:<account-id>:file-system/<file-system-id>",
  "Condition": {
    "ArnEquals": {
      "s3files:AccessPointArn": "arn:aws:s3files:<region>:<account-id>:file-system/<file-system-id>/access-point/<access-point-id>"
    }
  }
}

EFS에 대한 IAM 권한


{
  "Effect": "Allow",
  "Action": [
    "elasticfilesystem:ClientMount",
    "elasticfilesystem:ClientWrite"
  ],
  "Resource": "arn:aws:elasticfilesystem:<region>:<account-id>:file-system/<file-system-id>",
  "Condition": {
    "ArnEquals": {
      "elasticfilesystem:AccessPointArn": "arn:aws:elasticfilesystem:<region>:<account-id>:access-point/<access-point-id>"
    }
  }
}

에이전트에 읽기 액세스 권한만 필요한 ClientWrite 경우 생략합니다.

보안 그룹

포트 2049의 아웃바운드 TCP를 코드 인터프리터 보안 그룹에서 탑재 대상 보안 그룹으로 허용합니다. 코드 인터프리터 보안 그룹의 탑재 대상 보안 그룹에서 포트 2049의 인바운드 TCP를 허용합니다.

파일 시스템 구성

의 각 파일 시스템을 s3FilesConfiguration 또는 filesystemConfigurations로 지정합니다efsConfiguration. 둘 다 세 개의 필드가 필요합니다.

accessPointArn - 탑재할 S3 파일 또는 EFS 액세스 포인트의 ARN입니다.
fileSystemArn - 액세스 포인트를 소유한 파일 시스템의 ARN입니다. 이 필드는 필수입니다.
mountPath - 액세스 포인트가 마운트되는 세션 내의 절대 경로입니다(예: /mnt/s3data).

동일한 셰filesystemConfigurations이프를 사용하여 두 곳에서를 제공할 수 있습니다.

컨트롤 플레인 CreateCodeInterpreter- 코드 인터프리터에서 시작된 모든 세션에서 탑재가 상속됩니다. 코드 인터프리터는 VPC 네트워크 모드를 사용해야 합니다.
데이터 영역 StartCodeInterpreterSession- 탑재는 해당 특정 세션에 적용됩니다.

참고

코드 인터프리터가 VPC 네트워크 모드를 사용하고 S3 파일 또는 EFS 액세스 포인트가 올바르게 구성된 경우(탑재 대상, IAM 권한 및 보안 그룹) 컨트롤 플레인(CreateCodeInterpreter), 데이터 플레인(StartCodeInterpreterSession) 또는 둘 다에서 파일 시스템 구성을 제공할 수 있습니다. 의 구성CreateCodeInterpreter은 모든 세션에서 상속됩니다.의 구성은 해당 세션에 StartCodeInterpreterSession 적용됩니다. 둘 다 제공되면 세션에 대해 결합되고 각 탑재 경로는 결합된 세트에서 고유해야 합니다.

다음 섹션에서는 각 파일 시스템 유형에 대한 두 API 호출을 모두 보여줍니다.

Amazon S3 파일 액세스 포인트 구성

컨트롤 플레인: CreateCodeInterpreter

예

AWS CLI


aws bedrock-agentcore-control create-code-interpreter \
  --name "data-code-interpreter" \
  --execution-role-arn "arn:aws:iam::<account-id>:role/CodeInterpreterExecutionRole" \
  --network-configuration '{
    "networkMode": "VPC",
    "vpcConfig": {
      "subnets": ["<subnet-id-1>", "<subnet-id-2>"],
      "securityGroups": ["<security-group-id>"]
    }
  }' \
  --filesystem-configurations '[{
    "s3FilesConfiguration": {
      "accessPointArn": "arn:aws:s3files:<region>:<account-id>:file-system/<file-system-id>/access-point/<access-point-id>",
      "fileSystemArn": "arn:aws:s3files:<region>:<account-id>:file-system/<file-system-id>",
      "mountPath": "/mnt/s3data"
    }
  }]'

AWS SDK

boto3를 사용하여 S3 파일 액세스 포인트가 있는 코드 인터프리터를 생성하는 Python 예제입니다.


import boto3

cp = boto3.client("bedrock-agentcore-control", region_name="us-west-2")

response = cp.create_code_interpreter(
    name="data-code-interpreter",
    executionRoleArn="arn:aws:iam::<account-id>:role/CodeInterpreterExecutionRole",
    networkConfiguration={
        "networkMode": "VPC",
        "vpcConfig": {
            "subnets": ["<subnet-id-1>", "<subnet-id-2>"],
            "securityGroups": ["<security-group-id>"]
        }
    },
    filesystemConfigurations=[
        {
            "s3FilesConfiguration": {
                "accessPointArn": "arn:aws:s3files:<region>:<account-id>:file-system/<file-system-id>/access-point/<access-point-id>",
                "fileSystemArn": "arn:aws:s3files:<region>:<account-id>:file-system/<file-system-id>",
                "mountPath": "/mnt/s3data"
            }
        }
    ]
)

데이터 영역: StartCodeInterpreterSession

예

Amazon EFS 액세스 포인트 구성

컨트롤 플레인: CreateCodeInterpreter

예

AWS CLI


aws bedrock-agentcore-control create-code-interpreter \
  --name "shared-tools-code-interpreter" \
  --execution-role-arn "arn:aws:iam::<account-id>:role/CodeInterpreterExecutionRole" \
  --network-configuration '{
    "networkMode": "VPC",
    "vpcConfig": {
      "subnets": ["<subnet-id-1>", "<subnet-id-2>"],
      "securityGroups": ["<security-group-id>"]
    }
  }' \
  --filesystem-configurations '[{
    "efsConfiguration": {
      "accessPointArn": "arn:aws:elasticfilesystem:<region>:<account-id>:access-point/<access-point-id>",
      "fileSystemArn": "arn:aws:elasticfilesystem:<region>:<account-id>:file-system/<file-system-id>",
      "mountPath": "/mnt/efs"
    }
  }]'

AWS SDK

boto3를 사용하여 EFS 액세스 포인트로 코드 인터프리터를 생성하는 Python 예제입니다.


import boto3

cp = boto3.client("bedrock-agentcore-control", region_name="us-west-2")

response = cp.create_code_interpreter(
    name="shared-tools-code-interpreter",
    executionRoleArn="arn:aws:iam::<account-id>:role/CodeInterpreterExecutionRole",
    networkConfiguration={
        "networkMode": "VPC",
        "vpcConfig": {
            "subnets": ["<subnet-id-1>", "<subnet-id-2>"],
            "securityGroups": ["<security-group-id>"]
        }
    },
    filesystemConfigurations=[
        {
            "efsConfiguration": {
                "accessPointArn": "arn:aws:elasticfilesystem:<region>:<account-id>:access-point/<access-point-id>",
                "fileSystemArn": "arn:aws:elasticfilesystem:<region>:<account-id>:file-system/<file-system-id>",
                "mountPath": "/mnt/efs"
            }
        }
    ]
)

데이터 영역: StartCodeInterpreterSession

예

파일 시스템 결합

에 항목을 더 추가하여 한 번의 호출로 여러 액세스 포인트(아래 한도까지)를 연결할 수 있습니다filesystemConfigurations. 각 항목은 고유한 탑재 경로를 사용해야 합니다.


filesystemConfigurations=[
    {
        "s3FilesConfiguration": {
            "accessPointArn": "arn:aws:s3files:<region>:<account-id>:file-system/<file-system-id>/access-point/<access-point-id>",
            "fileSystemArn": "arn:aws:s3files:<region>:<account-id>:file-system/<file-system-id>",
            "mountPath": "/mnt/s3data"
        }
    },
    {
        "efsConfiguration": {
            "accessPointArn": "arn:aws:elasticfilesystem:<region>:<account-id>:access-point/<access-point-id>",
            "fileSystemArn": "arn:aws:elasticfilesystem:<region>:<account-id>:file-system/<file-system-id>",
            "mountPath": "/mnt/efs"
        }
    }
]

탑재된 파일 시스템 확인

GetCodeInterpreter를 사용하여 코드 인터프리터filesystemConfigurations에서를 확인하고 GetCodeInterpreterSession을 사용하여 실행 중인 세션에서 효과적인 구성을 확인합니다. 코드 인터프리터 생성 및 세션 시작 시 설정된 구성은 모두 세션 응답에 표시됩니다.

한도

파일 시스템 구성 제한은 요청당 적용됩니다. CreateCodeInterpreter 구성은 모든 세션에서 상속되며 StartCodeInterpreterSession 구성은 해당 세션에 적용됩니다. 세션의 효과적인 탑재는 둘 다의 조합입니다.

구성 유형	CreateCodeInterpreter당	StartCodeInterpreterSession당	세션당 합산
Amazon S3 파일 액세스 포인트	2	2	4
Amazon EFS 액세스 포인트	2	2	4
총 파일 시스템 구성	4	4	8

예를 들어에서 S3 파일 액세스 포인트 1개와 EFS 액세스 포인트 1개를 구성한 다음 CreateCodeInterpreter에서 S3 파일 액세스 포인트 1개와 EFS 액세스 포인트 1개를 추가하여 세션에 총 StartCodeInterpreterSession4개의 탑재를 구성할 수 있습니다. 각 탑재 경로는 결합된 세트에서 고유해야 합니다.

탑재 경로 제약 조건

모든 파일 시스템 구성은 다음 탑재 경로 규칙을 따라야 합니다.

정확히 하나의 하위 디렉터리 수준(예: , /mnt/data)/mnt/으로 미만이어야 합니다/mnt/s3data.
패턴: /mnt/[a-zA-Z0-9._-]+/?
각 탑재 경로는 모든 구성에서 고유해야 합니다.
탑재 경로는 서로의 하위 디렉터리일 수 없습니다.

파일 시스템 탑재 문제 해결

bring-your-own 파일 시스템 탑재에 실패하면는 오류를 StartCodeInterpreterSession 반환하고 세션은이 되지 않습니다READY.

증상	가능한 원인	빠른 수정
"액세스 거부"	실행 역할 누락 `ClientMount` 또는 `ClientWrite`	`AccessPointArn` 조건을 사용하여 IAM 권한 추가
“ResourceNotFound” 또는 “해결 실패”	액세스 포인트 또는 탑재 대상 삭제 또는 사용 불가	ARN이 존재하고 탑재 대상을 사용할 수 있는지 확인
탑재 중단 후 실패	보안 그룹이 포트 2049를 차단하거나 세션의 가용 영역에 탑재 대상이 없음	TCP 2049 허용, 가용 영역 겹침 확인
쓰기에 대한 "권한 거부"	누락 `ClientWrite` 또는 POSIX UID/GID 불일치	쓰기 권한 추가 또는 액세스 포인트 POSIX 사용자 정렬

구성된 모든 파일 시스템은 세션 시작 시 병렬로 탑재됩니다. 단일 탑재 실패로 인해 세션이 실패합니다.

javascript가 브라우저에서 비활성화되거나 사용이 불가합니다.

AWS 설명서를 사용하려면 Javascript가 활성화되어야 합니다. 지침을 보려면 브라우저의 도움말 페이지를 참조하십시오.

문서 규칙

AgentCore 코드 해석기 세션 중지

API 참조 예제