Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

Konfigurasi sistem file untuk AgentCore Runtime

AgentCore Runtime mendukung sistem file persist filesystemConfigurations en melalui 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:

Jenis terkelola tergantung pada tipe komputasi runtime Anda. Gunakan penyimpanan sesi pada runtime microVM dan volume penyedia kapasitas pada runtime Instans. Pada runtime microVM, Anda dapat menggabungkan penyimpanan sesi dengan sistem file bawa-sendiri pada runtime agen tunggal (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 mengonfigurasi setiap jenis sistem file.

Penyimpanan sesi terkelola (Pratinjau)

Penyimpanan sesi tersedia pada runtime microVM.

Volume penyedia kapasitas

Volume penyedia kapasitas tersedia pada runtime Instans.

Untuk panduan lengkapnya, lihat Memulai dengan Instans menggunakan AWS CLI.

Bring-your-own sistem file

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 file

Saat Anda mengonfigurasi sistem file bawa 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.

Alur pemasangan File Amazon S3

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

S3 Files semantik

Alur pemasangan Amazon EFS

Saat Anda mengonfigurasi titik akses EFS, urutan berikut terjadi:

Semantik EFS

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 sepanjang 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 bekerja sebagai berikut:

Semantik sistem file

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

Operasi yang didukung

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

Batasan

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

Operasi yang tidak didukung

Operasi sistem file berikut tidak didukung:

Siklus hidup penyimpanan sesi

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

Gunakan DeleteAgentRuntime atau DeleteAgentRuntimeEndpoint untuk menghapus semua data penyimpanan sesi yang terkait dengan runtime atau titik akhir.

Volume penyedia kapasitas (Instans)

Volume penyedia kapasitas adalah jenis penyimpanan terkelola untuk runtime yang menggunakan tipe komputasi Instans. Alih-alih menentukan penyimpanan pada runtime, Anda menentukan volume Amazon EBS bernama pada penyedia kapasitas, dan runtime memasangnya dengan nama logis. AgentCore membuat, melampirkan, dan menyimpan volume untuk Anda—Anda tidak menyediakan atau memasang volume Amazon EBS sendiri.

Seperti penyimpanan sesi, volume penyedia kapasitas diisolasi per sesi dan bertahan di seluruh sesi stop/resume. Karena sesi pada Instans adalah instans EC2 khusus, volume mengikuti siklus hidup sesi tersebut:

Volume dipertahankan di seluruh pemberhentian ini, termasuk ketika sesi mencapai masa pakai maksimumnya. Itu dihapus hanya saat Anda menghapus sesi, atau ketika Anda menghapus penyedia kapasitas (yang menghapus sesi dan volumenya).

Untuk informasi tentang mengelola data pada volume ini, lihat Mengel ola data Anda di Instans Runtime.

Agen dapat berbagi volume, tetapi berbagi tidak otomatis. Agar volume dipasang untuk runtime agen, runtime tersebut harus mengkonfigurasi capacityProviderVolume (byvolumeName) yang sama dalam dirinya sendirifilesystemConfigurations. Ketika dua runtime tersebut dipanggil dengan yang samaruntimeSessionId, mereka berjalan pada instance yang sama dan masing-masing memasang volume bersama, sehingga mereka dapat berkolaborasi pada file yang sama. Mengkonfigurasi capacityProviderVolume kontrol volume AgentCore mana yang dipasang untuk runtime; itu tidak, dengan sendirinya, mengisolasi data antar agen dalam sesi. Batas isolasi adalah sesi. Untuk model isolasi sesi dan agen, lihat Model keamanan dan izin untuk Instans Runtime.

Jenis penyimpanan sesi terkelola dan jenis bawa sendiri tidak didukung pada runtime Instans. Jenis-jenis ini adalah sessionStorages3FilesAccessPoint,, danefsAccessPoint. Menentukan salah satu dari mereka di samping capacityProviderConfiguration gagal dengan aValidationException. Untuk cara menentukan volume pada penyedia kapasitas dan memasangnya, lihat Mem ulai dengan Instans menggunakan AWS CLI dan penyimpanan Per sisten di seluruh sesi.

Prasyarat untuk membawa sistem file Anda sendiri

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

Konfigurasi VPC

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

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

Hilangkan ClientWrite jika agen Anda hanya membutuhkan akses baca. Iz s3files:GetAccessPoint in diperlukan untuk validasi titik akses S3 Files 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.

Mengonfigurasi titik akses Amazon S3 Files

Untuk mengonfigurasi titik akses S3 Files, tentukan titik akses ARN dan mount path difilesystemConfigurations. Runtime agen Anda harus menggunakan mode jaringan VPC.

Mengonfigurasi titik akses Amazon EFS

Untuk mengonfigurasi titik akses EFS, tentukan titik akses ARN dan mount path difilesystemConfigurations. 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 UpdateAgentRuntime filesystemConfigurations parameter yang sama.

Mengkonfigurasi volume penyedia kapasitas

Untuk memasang volume penyedia kapasitas, pertama-tama tentukan volume pada penyedia kapasitas. Kemudian referensikan dengan nama filesystemConfigurations saat Anda membuat runtime agen. Ini berlaku untuk runtime yang menggunakan tipe komputasi Instances.

volumeNameHarus cocok dengan volume yang ditentukan dalam penyedia kapasitasec2Configuration.volumes. Untuk langkah-langkah menentukan volume pada penyedia kapasitas, lihat Mem ulai dengan Instans menggunakan AWS CLI.

Gabungkan sistem file

Anda dapat menggabungkan penyimpanan sesi terkelola dengan sistem file bawa-sendiri pada runtime agen microVM tunggal. 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 pemasangan mereka saat agen Anda dipanggil. Bring-your-own sistem file (File S3, 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 ditinggalkannya — file sumber, paket yang diinstal, artefak build, dan riwayat .git semuanya utuh. Saat Anda melanjutkan sesi, lingkungan komputasi baru akan memasang penyimpanan persisten. Agen Anda dapat terus bekerja tanpa menginstal ulang paket atau meregenerasi file.

Batas

Tabel berikut mencantumkan batas untuk konfigurasi sistem file.

Konfigurasi total, File S3, EFS, dan batas penyimpanan sesi berlaku untuk runtime microVM. Batas volume penyedia kapasitas ditentukan pada provider kapasitas (ec2Configuration.volumes) bukan per runtime.

Kendala jalur pemasangan

Semua konfigurasi sistem file harus mengikuti aturan jalur pemasangan ini:

Perilaku siklus hidup

Tabel berikut membandingkan perilaku siklus hidup di seluruh jenis sistem file yang dikelola dan bawa-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 FileSessionManager untuk riwayat percakapan dan penyimpanan sesi untuk file proyek. Keduanya bertahan melintasi 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(str(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. Baik 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)

Men FileSessionManager yimpan riwayat percakapan ke/mnt/workspace/.sessions/, memungkinkan agen mengingat konteks lintas stop/resume siklus.

Persyaratan jaringan

Bagian ini mencakup persyaratan jaringan untuk penyimpanan sesi terkelola dan sistem file bawa-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, sehingga VPC Anda harus mengizinkan konektivitas keluar ke S3. Jika Anda menggunakan titik akhir S3 Gateway dengan kebijakan khusus, Anda dapat menjangkau akses 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 file

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 lengkap 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 Mem asang sistem file S3.

Persyaratan bersama

Bagaimana 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 kredensia, dan pemantauan kesehatan.

Pemilihan Subnet dan Zona Ketersediaan

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 Zona Ketersediaan subnet Anda:

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

Untuk mengidentifikasi Zona Ketersediaan 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 Zone tempat sistem file Anda memiliki target mount.

Untuk Zona Ketersediaan yang didukung menurut wilayah, lihat Zona Ketersediaan yang Di dukung di topik konfigurasi VPC. Untuk konfigurasi grup keamanan, lihat Contoh: Menghubungkan ke Amazon EFS atau File Amazon S3.

Memecahkan masalah pemasangan sistem file bawa-Anda sendiri

Ketika pemasangan sistem file bring-your-own 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 Memec ahkan masalah penyimpanan BYO.