本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

AgentCore 运行时的文件系统配置

AgentCore 运行时通过filesystemConfigurations参数支持永久文件系统。每种配置都会在您指定的路径上安装存储。您不需要自定义挂载代码、特权容器或下载编排。

AgentCore 运行时支持两类文件系统配置：

托管类型取决于运行时的计算类型。在 microVM 运行时上使用会话存储，在实例运行时上使用容量提供者卷。在 microVM 运行时，您可以在单个代理运行时（总共最多 5 种配置）上将会话存储与自带文件系统相结合。

存储选项一览

下表比较了可用的文件系统配置类型。

快速入门

以下清单提供了配置每种文件系统类型的简要步骤。

托管会话存储（预览版）

会话存储在 microVM 运行时上可用。

容量提供商容量

容量提供商卷可在实例运行时使用。

有关完整演练，请参阅使用 AWS CLI 使用开始使用实例 AWS CLI 或 SDK 开始使用实例。

Bring-your-own 文件系统

亚马逊 S3 文件接入点

亚马逊 EFS 接入点

S3 文件和 EFS 都需要在代理运行时进行 VPC 连接。

每种类型的工作原理

以下各节描述了每种文件系统类型在 AgentCore Runtime 中的运行方式。

Bring-your-own 文件系统

当您配置自带文件系统时，Runt AgentCore ime 会将指定的接入点安装到您配置的路径上的每个会话中。数据是共享的 — 多个会话、多个代理或外部应用程序可以同时访问同一个文件系统。

AgentCore 自动处理所有装载操作。您无需安装挂载助手、管理 TLS 证书或在代理中编写挂载代码。

亚马逊 S3 文件挂载流程

配置 S3 文件接入点时，会出现以下顺序：

S3 文件语义

亚马逊 EFS 挂载流程

配置 EFS 接入点时，会出现以下顺序：

EFS 语义

管理会话存储（预览版）

使用托管会话存储 stop/resume 通过文件系统配置保持会话状态。 AgentCore 运行时管理的会话存储是一种完全由服务管理的功能， AgentCore Runtime 可处理所有存储操作。您的代理在整个会话期间读取和写入本地文件系统挂载，运行时环境会透明地将数据复制到服务存储。

会话存储是每个会话隔离的 — 每个会话只能访问自己的存储，不能从相同代理运行时的其他会话或不同代理运行时的会话读取或写入数据。

当您在代理运行时上配置会话存储时，每个会话都会在您指定的挂载路径上获得一个永久目录。生命周期的工作原理如下：

文件系统语义

会话存储在您配置的挂载路径上提供标准的 Linux 文件系统。标准工具和操作无需修改即可运行—— ls、cat、mkdir、git、、npm、pip、、cargo所有操作均按预期运行。

支持的操作

常规文件、目录和符号链接。读取、写入、重命名chmod、删除chown、stat、和 readdir — 常用开发工具使用的标准 POSIX 文件操作。

限制

有关会话存储限制，包括最大存储大小、文件数和目录深度，请参阅会话存储限制。

不支持的操作

不支持以下文件系统操作：

会话存储生命周期

在以下情况下，会话数据将被删除（重置为干净状态）：

使用DeleteAgentRuntime或删除DeleteAgentRuntimeEndpoint与运行时或端点关联的所有会话存储数据。

容量提供商容量（实例）

容量提供者卷是使用实例计算类型的运行时的托管存储类型。您无需在运行时指定存储，而是在容量提供商上定义命名的 Amazon EBS 卷，然后运行时按逻辑名称挂载它们。 AgentCore 为您创建、附加和保留卷——您无需自己预置或装载 Amazon EBS 卷。

与会话存储一样，容量提供商卷在每个会话中是隔离的，并且持续存在 stop/resume。由于实例上的会话是专用 EC2 实例，因此该量遵循该会话的生命周期：

音量将在这些停靠点之间保持不变，包括当会话达到其最大生命周期时。仅当您删除会话或删除容量提供器（删除其会话及其卷）时，它才会被删除。

有关管理这些卷上的数据的信息，请参阅管理运行时实例上的数据。

代理可以共享卷，但共享不是自动的。要为代理运行时安装卷，该运行时必须自行配置相同的capacityProviderVolume（由volumeName）filesystemConfigurations。当使用相同的运行时调用两个这样的运行时时runtimeSessionId，它们将在同一个实例上运行，并且每个运行时都会挂载共享卷，因此它们可以协作处理相同的文件。配置capacityProviderVolume控制运行时要 AgentCore 装载哪些卷；它本身并不能隔离会话中代理之间的数据。隔离边界是会话。有关会话和代理隔离模型，请参阅运行时实例的安全模型和权限。

实例运行时不支持托管会话存储和自带类型。这些类型是sessionStorages3FilesAccessPoint、和efsAccessPoint。在旁边指定其中任何一个都会capacityProviderConfiguration失败ValidationException。有关如何在容量提供商上定义卷并挂载它们，请参阅使用 AWS CLI 开始使用实例和跨会话的永久存储。

自带文件系统的先决条件

在配置自带文件系统之前，请完成以下先决条件。

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 文件访问点，请在中filesystemConfigurations指定接入点 ARN 和挂载路径。您的代理运行时必须使用 VPC 网络模式。

配置 Amazon EFS 接入点

要配置 EFS 接入点，请在中指定接入点 ARN 和挂载路径。filesystemConfigurations您的代理运行时必须使用 VPC 网络模式。

配置托管会话存储

创建或更新代理运行时时filesystemConfigurations使用sessionStorage条目添加。

您还可以使用UpdateAgentRuntime具有相同filesystemConfigurations参数的现有代理运行时添加会话存储。

配置容量提供商卷

要安装容量提供商卷，请先在容量提供商上定义该卷。然后在创建代理运行filesystemConfigurations时时按名称引用它。这适用于使用实例计算类型的运行时。

volumeName必须与容量提供商中定义的容量相匹配ec2Configuration.volumes。有关在容量提供商上定义卷的步骤，请参阅使用 AWS CLI 开始使用实例。

合并文件系统

您可以在单个 microVM 代理运行时上将托管会话存储与自带文件系统相结合。以下示例配置了所有三种类型。

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）。托管会话存储使用相同方法跨 stop/resume 周期保存数据runtimeSessionId。

示例：跨 stop/resume 周期使用会话存储

# 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 历史记录都完好无损。当您恢复会话时，新的计算环境会挂载持久存储。您的代理无需重新安装软件包或重新生成文件即可继续工作。

限制

下表列出了文件系统配置的限制。

总配置、S3 文件、EFS 和会话存储限制适用于 microVM 运行时。容量提供者的容量限制是在容量提供商 (ec2Configuration.volumes) 上定义的，而不是根据每个运行时定义的。

装载路径限制

所有文件系统配置都必须遵循以下挂载路径规则：

生命周期行为

下表比较了托管文件系统和自带文件系统类型的生命周期行为。

使用案例

下表列出了常见模式和每种模式的推荐文件系统配置。

示例：使用永久工作空间的编码代理

此示例显示编码代理使用 Strands Agents 来存储对话历史记录，为项目文件存储会话。FileSessionManager两者都跨 stop/resume 周期持续存在。

具有会话存储功能的编码代理

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

调用代理，停止会话，然后恢复。项目文件和对话上下文都保留。

调用、停止和恢复循环

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/，使代理能够跨 stop/resume 周期记住上下文。

联网要求

本节涵盖托管会话存储和自带文件系统的网络要求。

托管会话存储网络

如果您的代理运行时使用带有会话存储的 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 文件。

对自带文件系统挂载进行故障排除

自带文件系统挂载失败时，InvokeAgentRuntime返回 HTTP 424（失败的依赖关系）。

每个坐骑都有 30 秒的超时时间。所有配置的文件系统均并行挂载——一次失败会导致整个调用失败。

有关更多信息，请参阅 BYO 存储我的 S3 文件或 EFS 挂载失败并显示 “访问被拒绝”疑难解答。