Konfigurasi sistem file untuk AgentCore Runtime

AgentCore Runtime mendukung sistem file persisten melalui filesystemConfigurations parameter. Setiap konfigurasi memasang penyimpanan di jalur yang Anda tentukan. Anda tidak memerlukan kode pemasangan khusus, wadah istimewa, atau orkestrasi unduhan.

AgentCore Runtime mendukung dua kategori konfigurasi sistem file:

Anda dapat menggabungkan kedua kategori pada satu runtime agen (hingga 5 konfigurasi total).

Sekilas tentang opsi penyimpanan

Tabel berikut membandingkan jenis konfigurasi sistem file yang tersedia.

Quick start

Daftar periksa berikut menyediakan langkah-langkah ringkas untuk mengkonfigurasi setiap jenis sistem file.

Penyimpanan sesi terkelola (Pratinjau)

Bring-your-own sistem berkas

Titik akses File Amazon S3

Titik akses Amazon EFS

File S3 dan EFS memerlukan konektivitas VPC pada runtime agen.

Bagaimana setiap jenis bekerja

Bagian berikut menjelaskan bagaimana setiap jenis sistem file beroperasi dalam AgentCore Runtime.

Bring-your-own sistem berkas

Saat Anda mengonfigurasi sistem file yang dibawa sendiri, AgentCore Runtime memasang titik akses yang ditentukan ke setiap sesi di jalur yang Anda konfigurasikan. Data dibagikan — beberapa sesi, beberapa agen, atau aplikasi eksternal dapat mengakses sistem file yang sama secara bersamaan.

AgentCore menangani semua operasi pemasangan secara otomatis. Anda tidak perlu menginstal mount helper, mengelola sertifikat TLS, atau menulis kode mount di agen Anda.

Aliran pemasangan File Amazon S3

Saat Anda mengonfigurasi titik akses File S3, urutan berikut terjadi:

S3 File semantik

Aliran pemasangan Amazon EFS

Saat Anda mengonfigurasi titik akses EFS, urutan berikut akan terjadi:

EFS semantik

Penyimpanan sesi terkelola (Pratinjau)

Pertahankan status sesi stop/resume dengan konfigurasi sistem file menggunakan penyimpanan sesi terkelola. AgentCore Penyimpanan sesi terkelola runtime adalah kemampuan yang dikelola layanan sepenuhnya di mana AgentCore Runtime menangani semua operasi penyimpanan. Agen Anda membaca dan menulis ke mount sistem file lokal dan lingkungan runtime secara transparan mereplikasi data ke penyimpanan layanan selama durasi sesi.

Penyimpanan sesi diisolasi per sesi — setiap sesi hanya dapat mengakses penyimpanannya sendiri dan tidak dapat membaca atau menulis data dari sesi lain dari runtime agen yang sama atau sesi runtime agen yang berbeda.

Saat Anda mengonfigurasi penyimpanan sesi pada runtime agen, setiap sesi mendapatkan direktori persisten di jalur pemasangan yang Anda tentukan. Siklus hidup berfungsi sebagai berikut:

Semantik sistem file

Penyimpanan sesi menyediakan sistem file Linux standar di jalur pemasangan yang dikonfigurasi. Alat dan operasi standar bekerja tanpa modifikasi —ls,cat,,mkdir,git, npmpip, dan cargo semuanya berfungsi seperti yang diharapkan.

Operasi yang didukung

File reguler, direktori, dan symlink. Baca, tulis, ganti nama, hapus,,chmod, chownstat, dan readdir — operasi file POSIX standar yang digunakan oleh alat pengembangan umum.

Batas

Untuk batas penyimpanan sesi termasuk ukuran penyimpanan maksimum, jumlah file, dan kedalaman direktori, lihat Batas penyimpanan sesi.

Operasi yang tidak didukung

Operasi sistem file berikut tidak didukung:

Siklus hidup penyimpanan sesi

Data sesi dihapus (reset ke keadaan bersih) dalam skenario berikut:

Menggunakan DeleteAgentRuntimeatau DeleteAgentRuntimeEndpointmenghapus semua data penyimpanan sesi yang terkait dengan runtime atau endpoint.

Prasyarat untuk membawa sistem file Anda sendiri

Sebelum Anda mengonfigurasi sistem file bawa-milik Anda sendiri, selesaikan prasyarat berikut.

Konfigurasi VPC

Runtime agen Anda harus menggunakannetworkMode: VPC. Subnet yang Anda tentukan harus tumpang tindih dengan sistem file mount target Availability Zones.

Izin IAM

Peran eksekusi runtime agen Anda harus menyertakan izin untuk memasang sistem file.

Izin IAM untuk File S3

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

Izin IAM untuk EFS

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

Abaikan ClientWrite jika agen Anda hanya membutuhkan akses baca. s3files:GetAccessPointIzin diperlukan untuk validasi titik akses File S3 selama pembuatan runtime agen.

Grup keamanan

Izinkan TCP keluar pada port 2049 dari grup keamanan runtime agen Anda ke grup keamanan target mount. Izinkan TCP masuk pada port 2049 pada grup keamanan target mount dari grup keamanan runtime agen.

Konfigurasikan sistem file

Bagian berikut menunjukkan cara mengkonfigurasi setiap jenis sistem file.

Konfigurasikan titik akses File Amazon S3

Untuk mengkonfigurasi titik akses File S3, tentukan titik akses ARN dan pasang jalur di. filesystemConfigurations Runtime agen Anda harus menggunakan mode jaringan VPC.

Konfigurasikan titik akses Amazon EFS

Untuk mengonfigurasi titik akses EFS, tentukan titik akses ARN dan jalur pemasangan di. filesystemConfigurations Runtime agen Anda harus menggunakan mode jaringan VPC.

Konfigurasikan penyimpanan sesi terkelola

Tambahkan filesystemConfigurations dengan sessionStorage entri saat membuat atau memperbarui runtime agen.

Anda juga dapat menambahkan penyimpanan sesi ke runtime agen yang ada menggunakan filesystemConfigurations parameter UpdateAgentRuntimeyang sama.

Gabungkan sistem file

Anda dapat menggabungkan penyimpanan sesi terkelola dengan sistem file yang dibawa sendiri pada satu runtime agen. Contoh berikut mengkonfigurasi ketiga jenis.

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"
            }
        }
    ]
)

Memanggil dan menggunakan penyimpanan persisten

Semua sistem file yang dikonfigurasi tersedia di jalur pemasangannya saat agen Anda dipanggil. Bring-your-own sistem file (S3 Files, EFS) dapat diakses segera pada setiap pemanggilan. Penyimpanan sesi terkelola mempertahankan data di seluruh stop/resume siklus menggunakan yang samaruntimeSessionId.

Contoh: Menggunakan penyimpanan sesi di seluruh stop/resume siklus

# 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"}'

Agen melihat /mnt/workspace persis seperti yang ditinggalkan — file sumber, paket yang diinstal, artefak build, dan histori.git semuanya utuh. Saat Anda melanjutkan sesi, lingkungan komputasi baru memasang penyimpanan yang bertahan. Agen Anda dapat terus bekerja tanpa menginstal ulang paket atau membuat ulang file.

Batas

Tabel berikut mencantumkan batas untuk konfigurasi sistem file.

Pasang kendala jalur

Semua konfigurasi sistem file harus mengikuti aturan jalur pemasangan ini:

Perilaku siklus hidup

Tabel berikut membandingkan perilaku siklus hidup antara penyimpanan sesi terkelola dan sistem file yang dibawa sendiri.

Kasus penggunaan

Tabel berikut mencantumkan pola umum dan konfigurasi sistem file yang direkomendasikan untuk masing-masing.

Contoh: Agen pengkodean dengan ruang kerja persisten

Contoh ini menunjukkan agen pengkodean menggunakan Strands Agents dengan FileSessionManager riwayat percakapan dan penyimpanan sesi untuk file proyek. Keduanya bertahan di seluruh stop/resume siklus.

Agen pengkodean dengan penyimpanan sesi

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

Panggil agen, hentikan sesi, lalu lanjutkan. File proyek dan konteks percakapan tetap ada.

Memanggil, menghentikan, dan melanjutkan siklus

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)

FileSessionManagerMenyimpan riwayat percakapan/mnt/workspace/.sessions/, memungkinkan agen untuk mengingat konteks lintas stop/resume siklus.

Persyaratan jaringan

Bagian ini mencakup persyaratan jaringan untuk penyimpanan sesi terkelola dan sistem file yang dibawa sendiri.

Jaringan penyimpanan sesi terkelola

Jika runtime agen Anda menggunakan mode VPC dengan penyimpanan sesi, agen memerlukan akses jaringan untuk menyinkronkan dengan penyimpanan jarak jauh. Data sesi disimpan di AgentCore S3, jadi VPC Anda harus mengizinkan konektivitas keluar ke S3. Jika Anda menggunakan endpoint S3 Gateway dengan kebijakan kustom, Anda dapat mengakses cakupan ke bucket penyimpanan sesi regional Anda sebagai berikut:

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

Ganti region dengan AWS Wilayah Anda (misalnya,us-west-2).

Bring-your-own jaringan sistem berkas

Bring-your-own sistem file memerlukan jaringan VPC Anda untuk memenuhi persyaratan berikut untuk pemasangan yang berhasil.

Amazon EFS

Untuk memeriksa target pemasangan EFS Anda:

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

Untuk informasi selengkapnya tentang target pemasangan EFS, lihat Cara kerja Amazon EFS.

Amazon S3 Files

Untuk memeriksa target pemasangan File S3 Anda:

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

Untuk informasi lengkap tentang pemasangan File S3, lihat Memasang sistem file S3.

Persyaratan bersama

Cara AgentCore memasang sistem file

AgentCore menangani operasi pemasangan NFS di dalam microVM secara otomatis:

Anda tidak perlu menginstalamazon-efs-utils, mengkonfigurasi/etc/fstab, atau mengelola sertifikat TLS. Runtime microVM menangani semua operasi pemasangan, rotasi kredensyal, dan pemantauan kesehatan.

Pemilihan Subnet dan Availability Zone

Saat Anda mengonfigurasi subnet VPC dan konfigurasi sistem file pada runtime agen, pilih subnet yang tumpang tindih dengan Zona Ketersediaan target pemasangan sistem file Anda.

Untuk mengidentifikasi ID Availability Zone subnet Anda:

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

Untuk mengidentifikasi Availability Zone target pemasangan EFS Anda:

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

Pastikan subnet runtime agen Anda berada di Availability Zones di mana sistem file Anda memiliki target mount.

Untuk Availability Zone yang didukung menurut wilayah, lihat Zona Ketersediaan yang Didukung dalam topik konfigurasi VPC. Untuk konfigurasi grup keamanan, lihat Contoh: Menyambungkan ke File Amazon EFS atau Amazon S3.

Memecahkan masalah membawa mount sistem file Anda sendiri

Ketika pemasangan sistem file yang dibawa sendiri gagal, InvokeAgentRuntime mengembalikan HTTP 424 (Ketergantungan Gagal).

Setiap mount memiliki batas waktu 30 detik. Semua sistem file yang dikonfigurasi dipasang secara paralel — kegagalan tunggal menyebabkan seluruh pemanggilan gagal.

Untuk informasi selengkapnya, lihat Memecahkan masalah penyimpanan BYO.