AgentCore 런타임에 대한 파일 시스템 구성

AgentCore 런타임은 filesystemConfigurations 파라미터를 통해 영구 파일 시스템을 지원합니다. 각 구성은 지정한 경로에 스토리지를 탑재합니다. 사용자 지정 탑재 코드, 권한 있는 컨테이너 또는 다운로드 오케스트레이션이 필요하지 않습니다.

AgentCore 런타임은 두 가지 범주의 파일 시스템 구성을 지원합니다.

단일 에이전트 런타임에서 두 범주를 결합할 수 있습니다(총 구성 최대 5개).

스토리지 옵션 한 눈에 보기

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

빠른 시작

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

관리형 세션 스토리지(미리 보기)

Bring-your-own 파일 시스템

Amazon S3 파일 액세스 포인트

Amazon EFS 액세스 포인트

S3 파일과 EFS 모두 에이전트 런타임에 VPC 연결이 필요합니다.

각 유형의 작동 방식

다음 섹션에서는 각 파일 시스템 유형이 AgentCore 런타임 내에서 작동하는 방식을 설명합니다.

Bring-your-own 파일 시스템

bring-your-own 시스템을 구성하면 AgentCore 런타임은 구성한 경로의 모든 세션에 지정된 액세스 포인트를 마운트합니다. 데이터 공유 - 여러 세션, 여러 에이전트 또는 외부 애플리케이션이 동일한 파일 시스템에 동시에 액세스할 수 있습니다.

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

Amazon S3 파일 탑재 흐름

S3 파일 액세스 포인트를 구성하면 다음 시퀀스가 발생합니다.

S3 파일 의미 체계

Amazon EFS 탑재 흐름

EFS 액세스 포인트를 구성하면 다음 시퀀스가 발생합니다.

EFS 의미 체계

관리형 세션 스토리지(미리 보기)

관리형 세션 스토리지를 사용하여 파일 시스템 구성을 사용하여 중지/재개 간에 세션 상태를 유지합니다. AgentCore 런타임 관리형 세션 스토리지는 AgentCore 런타임이 모든 스토리지 작업을 처리하는 완전 서비스 관리형 기능입니다. 에이전트는 로컬 파일 시스템 마운트를 읽고 쓰며 런타임 환경은 세션 기간 동안 데이터를 서비스 스토리지에 투명하게 복제합니다.

세션 스토리지는 세션별로 격리됩니다. 각 세션은 자체 스토리지에만 액세스할 수 있으며 동일한 에이전트 런타임의 다른 세션 또는 다른 에이전트 런타임의 세션에서 데이터를 읽거나 쓸 수 없습니다.

에이전트 런타임에 세션 스토리지를 구성하면 각 세션은 지정한 탑재 경로에 영구 디렉터리를 가져옵니다. 수명 주기는 다음과 같이 작동합니다.

파일 시스템 의미 체계

세션 스토리지는 구성된 탑재 경로에 표준 Linux 파일 시스템을 제공합니다. 표준 도구 및 작업은 수정 없이 작동합니다. ls, cat, mkdir, git, pip, npm및 cargo 모든 작업은 예상대로 작동합니다.

지원되는 작업

일반 파일, 디렉터리 및 symlink. 읽기, 쓰기, 이름 바꾸기, 삭제, chmod, stat, 및 chownreaddir- 일반적인 개발 도구에서 사용하는 표준 POSIX 파일 작업입니다.

Limits

최대 스토리지 크기, 파일 수 및 디렉터리 깊이를 포함한 세션 스토리지 제한은 세션 스토리지 제한을 참조하세요.

지원되지 않는 작업

다음 파일 시스템 작업은 지원되지 않습니다.

세션 스토리지 수명 주기

세션 데이터는 다음 시나리오에서 삭제됩니다(클린 상태로 재설정).

DeleteAgentRuntime 또는 DeleteAgentRuntimeEndpoint를 사용하여 런타임 또는 엔드포인트와 연결된 모든 세션 스토리지 데이터를 삭제합니다.

bring-your-own 시 사전 조건

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

VPC 구성

에이전트 런타임은를 사용해야 합니다networkMode: 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 경우 생략합니다. s3files:GetAccessPoint 권한은 에이전트 런타임 생성 중 S3 파일 액세스 포인트 검증에 필요합니다.

보안 그룹

포트 2049의 아웃바운드 TCP를 에이전트 런타임 보안 그룹에서 탑재 대상 보안 그룹으로 허용합니다. 에이전트 런타임 보안 그룹의 탑재 대상 보안 그룹에서 포트 2049의 인바운드 TCP를 허용합니다.

파일 시스템 구성

다음 섹션에서는 각 파일 시스템 유형을 구성하는 방법을 보여줍니다.

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

S3 파일 액세스 포인트를 구성하려면에서 액세스 포인트 ARN 및 탑재 경로를 지정합니다filesystemConfigurations. 에이전트 런타임은 VPC 네트워크 모드를 사용해야 합니다.

Amazon EFS 액세스 포인트 구성

EFS 액세스 포인트를 구성하려면에서 액세스 포인트 ARN 및 탑재 경로를 지정합니다filesystemConfigurations. 에이전트 런타임은 VPC 네트워크 모드를 사용해야 합니다.

관리형 세션 스토리지 구성

에이전트 런타임을 생성하거나 업데이트할 때 sessionStorage 항목과 filesystemConfigurations 함께를 추가합니다.

동일한 filesystemConfigurations 파라미터로 UpdateAgentRuntime을 사용하여 기존 에이전트 런타임에 세션 스토리지를 추가할 수도 있습니다.

파일 시스템 결합

단일 에이전트 런타임에서 관리형 세션 스토리지를 bring-your-own 결합할 수 있습니다. 다음 예제에서는 세 가지 유형을 모두 구성합니다.

import boto3

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

response = client.create_agent_runtime(
    agentRuntimeName="full-stack-agent",
    roleArn="arn:aws:iam::<account-id>:role/AgentExecutionRole",
    networkConfiguration={
        "networkMode": "VPC",
        "networkModeConfig": {
            "subnets": ["<subnet-id-1>", "<subnet-id-2>"],
            "securityGroups": ["<security-group-id>"]
        }
    },
    agentRuntimeArtifact={
        "containerConfiguration": {
            "containerUri": "<account-id>.dkr.ecr.<region>.amazonaws.com/my-agent:latest"
        }
    },
    filesystemConfigurations=[
        {
            "s3FilesAccessPoint": {
                "accessPointArn": "arn:aws:s3files:<region>:<account-id>:file-system/<file-system-id>/access-point/<access-point-id>",
                "mountPath": "/mnt/datasets"
            }
        },
        {
            "efsAccessPoint": {
                "accessPointArn": "arn:aws:elasticfilesystem:<region>:<account-id>:access-point/<access-point-id>",
                "mountPath": "/mnt/tools"
            }
        },
        {
            "sessionStorage": {
                "mountPath": "/mnt/workspace"
            }
        }
    ]
)

영구 스토리지 호출 및 사용

에이전트가 호출되면 구성된 모든 파일 시스템을 탑재 경로에서 사용할 수 있습니다. Bring-your-own 파일 시스템(S3 Files, EFS)은 호출할 때마다 즉시 액세스할 수 있습니다. 관리형 세션 스토리지는 동일한를 사용하여 중지/재개 주기 전반에 걸쳐 데이터를 유지합니다runtimeSessionId.

예: 중지/재개 주기에서 세션 스토리지 사용

# First invocation — agent sets up the project
aws bedrock-agentcore invoke-agent-runtime \
  --agent-runtime-arn "arn:aws:bedrock-agentcore:us-west-2:111122223333:agent-runtime/coding-agent" \
  --runtime-session-id "session-001" \
  --payload '{"prompt": "Set up the project and install dependencies in /mnt/workspace"}'

# Stop the session
aws bedrock-agentcore stop-runtime-session \
  --agent-runtime-arn "arn:aws:bedrock-agentcore:us-west-2:111122223333:agent-runtime/coding-agent" \
  --runtime-session-id "session-001"

# Resume later — the project is exactly where the agent left it
aws bedrock-agentcore invoke-agent-runtime \
  --agent-runtime-arn "arn:aws:bedrock-agentcore:us-west-2:111122223333:agent-runtime/coding-agent" \
  --runtime-session-id "session-001" \
  --payload '{"prompt": "Run the tests and fix any failures"}'

에이전트는 /mnt/workspace 그대로 표시됩니다. 소스 파일, 설치된 패키지, 빌드 아티팩트 및 .git 기록은 모두 그대로 유지됩니다. 세션을 재개하면 새 컴퓨팅 환경이 지속된 스토리지를 탑재합니다. 에이전트는 패키지를 다시 설치하거나 파일을 다시 생성하지 않고도 작업을 계속할 수 있습니다.

한도

다음 표에는 파일 시스템 구성에 대한 제한이 나열되어 있습니다.

탑재 경로 제약 조건

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

수명 주기 동작

다음 표에서는 관리형 세션 스토리지와 bring-your-own 간의 수명 주기 동작을 비교합니다.

사용 사례

다음 표에는 각각에 대한 일반적인 패턴과 권장 파일 시스템 구성이 나와 있습니다.

예: 영구 워크스페이스를 사용하여 에이전트 코딩

이 예제에서는 대화 기록에 Strands Agents를 사용하고 프로젝트 파일에 FileSessionManager 세션 스토리지를 사용하는 코딩 에이전트를 보여줍니다. 둘 다 중지/재개 주기에서 지속됩니다.

세션 스토리지로 에이전트 코딩

import os

# Enable non-interactive mode for strands tools
os.environ["BYPASS_TOOL_CONSENT"] = "true"

from strands import Agent
from strands.session import FileSessionManager
from strands.models import BedrockModel
from strands_tools import file_read, file_write, shell
from bedrock_agentcore.runtime import BedrockAgentCoreApp

app = BedrockAgentCoreApp()
WORKSPACE = "/mnt/workspace"

model = BedrockModel(model_id="us.anthropic.claude-sonnet-4-20250514-v1:0")
tools = [file_read, file_write, shell]

@app.entrypoint
def handle_request(payload):
    session_id = payload.get("session_id", "default")

    # Persist conversation history alongside project files
    session_manager = FileSessionManager(
        session_id=session_id,
        storage_dir=f"{WORKSPACE}/.sessions"
    )

    agent = Agent(
        model=model,
        tools=tools,
        session_manager=session_manager,
        system_prompt="You are a coding assistant. Project files are in /mnt/workspace."
    )

    response = agent(payload.get("prompt"))
    return {"response": response.message["content"][0]["text"]}

if __name__ == "__main__":
    app.run()

requirements.txt

strands-agents
strands-agents-tools
bedrock-agentcore
boto3

에이전트를 호출하고 세션을 중지한 다음 다시 시작합니다. 프로젝트 파일과 대화 컨텍스트는 모두 유지됩니다.

주기 호출, 중지 및 재개

import boto3, json

client = boto3.client("bedrock-agentcore")
agent_arn = "arn:aws:bedrock-agentcore:us-west-2:111122223333:agent-runtime/coding-agent"
session_id = "project-xyz-001"

def invoke(prompt):
    resp = client.invoke_agent_runtime(
        agentRuntimeArn=agent_arn,
        runtimeSessionId=session_id,
        payload=json.dumps({"prompt": prompt, "session_id": "conv-001"}).encode()
    )
    return json.loads(b"".join(resp["response"]))["response"]

# First invoke: Create a simple script
invoke("Write a Python script called calculator.py with add and subtract functions.")

# Stop session — compute terminates, storage persists
client.stop_runtime_session(agentRuntimeArn=agent_arn, runtimeSessionId=session_id)

# Resume same session — new compute, but files and conversation history restored
invoke("Add a multiply function to the script you created.")
# Agent knows it created calculator.py (conversation history)
# AND finds existing file (file persistence)

는 대화 기록을에 FileSessionManager 저장하여 에이전트가 중지/재개 주기 전반에 걸쳐 컨텍스트를 기억할 /mnt/workspace/.sessions/수 있도록 합니다.

네트워킹 요구 사항

이 섹션에서는 관리형 세션 스토리지와 bring-your-own 시스템 모두에 대한 네트워킹 요구 사항을 다룹니다.

관리형 세션 스토리지 네트워킹

에이전트 런타임이 세션 스토리지와 함께 VPC 모드를 사용하는 경우 에이전트는 원격 스토리지와 동기화하기 위해 네트워크 액세스 권한이 필요합니다. 세션 데이터는 AgentCore S3에 저장되므로 VPC가 S3에 대한 아웃바운드 연결을 허용해야 합니다. 사용자 지정 정책과 함께 S3 Gateway 엔드포인트를 사용하는 경우 다음과 같이 리전 세션 스토리지 버킷에 대한 액세스 범위를 지정할 수 있습니다.

"Action": [
    "s3:GetObject",
    "s3:PutObject",
    "s3:ListBucket"
],
"Resource": [
    "arn:aws:s3:::acr-storage-*-region-an",
    "arn:aws:s3:::acr-storage-*-region-an/*"
],
"Condition": {
    "StringEquals": {
        "aws:PrincipalServiceName": "bedrock-agentcore.amazonaws.com"
    }
}

region을 AWS 해당 리전으로 바꿉니다(예: us-west-2).

Bring-your-own

기존 보유 파일 시스템을 Bring-your-own 성공적인 탑재를 위해 VPC 네트워킹이 다음 요구 사항을 충족해야 합니다.

Amazon EFS

EFS 탑재 대상을 확인하려면:

aws efs describe-mount-targets --file-system-id fs-0123456789abcdef0 --region us-west-2

EFS 탑재 대상에 대한 자세한 내용은 Amazon EFS 작동 방식을 참조하세요.

Amazon S3 Files

S3 파일 탑재 대상을 확인하려면:

aws s3files list-mount-targets --file-system-id fs-0123456789abcdef0 --region us-west-2

S3 파일 탑재에 대한 자세한 내용은 S3 파일 시스템 탑재를 참조하세요.

공유 요구 사항

AgentCore가 파일 시스템을 탑재하는 방법

AgentCore는 microVM 내에서 NFS 탑재 작업을 자동으로 처리합니다.

를 설치amazon-efs-utils하거나,를 구성하거나/etc/fstab, TLS 인증서를 관리할 필요가 없습니다. microVM 런타임은 모든 탑재 작업, 자격 증명 교체 및 상태 모니터링을 처리합니다.

서브넷 및 가용 영역 선택

에이전트 런타임에서 VPC 서브넷과 파일 시스템 구성을 모두 구성할 때 파일 시스템 탑재 대상 가용 영역과 중첩되는 서브넷을 선택합니다.

서브넷의 가용 영역 ID를 식별하려면:

aws ec2 describe-subnets \
  --subnet-ids subnet-0123456789abcdef0 \
  --query 'Subnets[0].AvailabilityZoneId'

EFS 탑재 대상의 가용 영역을 식별하려면:

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

파일 시스템에 탑재 대상이 있는 가용 영역에 에이전트 런타임 서브넷이 있는지 확인합니다.

리전별로 지원되는 가용 영역은 VPC 구성 주제의 지원되는 가용 영역을 참조하세요. 보안 그룹 구성은 예제: Amazon EFS 또는 Amazon S3 파일에 연결을 참조하세요.

bring-your-own 파일 시스템 탑재 문제 해결

bring-your-own 파일 시스템 탑재에 실패하면는 HTTP 424(실패한 종속성)를 InvokeAgentRuntime 반환합니다.

각 탑재에는 30초의 제한 시간이 있습니다. 구성된 모든 파일 시스템은 병렬로 탑재됩니다. 단일 장애로 인해 전체 간접 호출이 실패합니다.

자세한 내용은 BYO 스토리지 문제 해결을 참조하세요.