AgentCore 运行时的文件系统配置

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

AgentCore Runtime 支持两类文件系统配置：

您可以在单个代理运行时中合并这两个类别（总共最多 5 个配置）。

存储选项一览

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

快速入门

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

托管会话存储（预览）

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与运行时或端点关联的所有会话存储数据。

自带文件系统的先决条件

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

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 Files 接入点。

安全组

允许端口 2049 上的出站 TCP 从您的代理运行时安全组发送到挂载目标安全组。允许来自代理运行时安全组的挂载目标安全组上端口 2049 上的入站 TCP。

配置文件系统

以下各节说明如何配置每种文件系统类型。

配置 Amazon S3 文件接入点

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

配置 Amazon EFS 接入点

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

配置托管会话存储

在创建或更新代理运行时时添加filesystemConfigurations一个sessionStorage条目。

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

合并文件系统

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

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

限制

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

装载路径限制

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

生命周期行为

下表比较了托管会话存储和自带文件系统之间的生命周期行为。

使用案例

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

示例：具有永久工作空间的编码代理

此示例显示了一个编码代理，将 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(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 存储疑难解答。