AgentCore ランタイムのファイルシステム設定

AgentCore Runtime は、 filesystemConfigurationsパラメータを使用して永続的なファイルシステムをサポートします。各設定は、指定したパスにストレージをマウントします。カスタムマウントコード、特権コンテナ、またはダウンロードオーケストレーションは必要ありません。

AgentCore Runtime は、次の 2 つのカテゴリのファイルシステム設定をサポートしています。

1 つのエージェントランタイムで両方のカテゴリを組み合わせることができます (最大合計 5 つの設定）。

ストレージオプションの概要

次の表は、使用可能なファイルシステム設定タイプを比較したものです。

クイックスタート

次のチェックリストは、各ファイルシステムタイプを設定するための詳細な手順を示しています。

マネージドセッションストレージ (プレビュー)

Bring-your-own ファイルシステム

Amazon S3 Files アクセスポイント

Amazon EFS アクセスポイント

S3 ファイルと EFS の両方に、エージェントのランタイムでの VPC 接続が必要です。

各タイプの仕組み

以下のセクションでは、各ファイルシステムタイプが AgentCore ランタイム内でどのように動作するかについて説明します。

Bring-your-own ファイルシステム

Bringbring-your-own ファイルシステムを設定すると、AgentCore Runtime は、設定したパスのすべてのセッションに指定されたアクセスポイントをマウントします。データは共有されます。複数のセッション、複数のエージェント、または外部アプリケーションが同じファイルシステムに同時にアクセスできます。

AgentCore は、すべてのマウントオペレーションを自動的に処理します。エージェントにマウントヘルパーをインストールしたり、TLS 証明書を管理したり、マウントコードを記述したりする必要はありません。

Amazon S3 Files マウントフロー

S3 Files アクセスポイントを設定すると、次のシーケンスが発生します。

S3 ファイルセマンティクス

Amazon EFS マウントフロー

EFS アクセスポイントを設定すると、次のシーケンスが発生します。

EFS セマンティクス

マネージドセッションストレージ (プレビュー)

マネージドセッションストレージを使用して、ファイルシステム設定で停止/再開全体でセッション状態を維持します。AgentCore Runtime マネージドセッションストレージは、AgentCore Runtime がすべてのストレージオペレーションを処理するフルサービスマネージド機能です。エージェントはローカルファイルシステムマウントに読み取りと書き込みを行い、ランタイム環境はセッション期間を通じてデータをサービスストレージに透過的にレプリケートします。

セッションストレージはセッションごとに分離されます。各セッションは独自のストレージにのみアクセスでき、同じエージェントランタイムの他のセッションまたは異なるエージェントランタイムのセッションからデータを読み書きすることはできません。

エージェントランタイムでセッションストレージを設定すると、各セッションは指定したマウントパスに永続ディレクトリを取得します。ライフサイクルは次のように機能します。

ファイルシステムのセマンティクス

セッションストレージは、設定されたマウントパスに標準の Linux ファイルシステムを提供します。標準のツールとオペレーションは変更なしで動作します – ls、cat、mkdir、git、npmpip、、および cargo はすべて期待どおりに動作します。

サポートされているオペレーション

通常のファイル、ディレクトリ、シンボリックリンク。読み取り、書き込み、名前変更、削除、chmod、chown、stat、 readdir- 一般的な開発ツールで使用される標準の POSIX ファイルオペレーション。

制限

最大ストレージサイズ、ファイル数、ディレクトリ深度などのセッションストレージの制限については、「セッションストレージの制限」を参照してください。

サポートされていないオペレーション

次のファイルシステムオペレーションはサポートされていません。

セッションストレージのライフサイクル

以下のシナリオでは、セッションデータは削除されます (クリーン状態にリセットされます）。

DeleteAgentRuntime または DeleteAgentRuntimeEndpoint を使用して、ランタイムまたはエンドポイントに関連付けられたすべてのセッションストレージデータを削除します。

Bringbring-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場合は、 を省略します。エージェントのランタイム作成時の S3 Files アクセスポイントの検証には、 アクセスs3files:GetAccessPoint許可が必要です。

セキュリティグループ

エージェントランタイムセキュリティグループからマウントターゲットセキュリティグループへのポート 2049 でのアウトバウンド TCP を許可します。エージェントランタイムセキュリティグループからマウントターゲットセキュリティグループのポート 2049 でインバウンド TCP を許可します。

ファイルシステムを設定する

以下のセクションでは、各ファイルシステムタイプを設定する方法を示します。

Amazon S3 Files アクセスポイントを設定する

S3 Files アクセスポイントを設定するには、 でアクセスポイント ARN とマウントパスを指定しますfilesystemConfigurations。エージェントランタイムは VPC ネットワークモードを使用する必要があります。

Amazon EFS アクセスポイントを設定する

EFS アクセスポイントを設定するには、 でアクセスポイント ARN とマウントパスを指定しますfilesystemConfigurations。エージェントランタイムは VPC ネットワークモードを使用する必要があります。

マネージドセッションストレージを設定する

エージェントランタイムを作成または更新するときに、 にsessionStorageエントリfilesystemConfigurationsを追加します。

同じfilesystemConfigurationsパラメータで UpdateAgentRuntime を使用して、既存のエージェントランタイムにセッションストレージを追加することもできます。

ファイルシステムを組み合わせる

マネージドセッションストレージと bring-your-own ファイルシステムを単一のエージェントランタイムで組み合わせることができます。次の の例では、3 つのタイプすべてを設定します。

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 ファイル、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 ファイルシステム間のライフサイクル動作を比較したものです。

ユースケース

次の表に、一般的なパターンとそれぞれの推奨されるファイルシステム設定を示します。

例: 永続ワークスペースを使用してエージェントをコーディングする

この例では、プロジェクトファイルの会話履歴とセッションストレージFileSessionManagerに で Strands エージェントを使用するコーディングエージェントを示しています。どちらも停止/再開サイクルにわたって保持されます。

セッションストレージを使用したエージェントのコーディング

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 Files マウントターゲットを確認するには:

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 (Failed Dependency) InvokeAgentRuntimeを返します。

各マウントのタイムアウトは 30 秒です。すべての設定済みファイルシステムは並行してマウントされます。1 回の失敗で呼び出し全体が失敗します。

詳細については、「BYO ストレージのトラブルシューティング」を参照してください。