本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# AgentCore 运行时的文件系统配置
AgentCore 运行时通过`filesystemConfigurations`参数支持永久文件系统。每种配置都会在您指定的路径上安装存储。您不需要自定义挂载代码、特权容器或下载编排。
AgentCore 运行时支持两类文件系统配置：
+ **托管存 Service-managed 储 ** — AgentCore 处理所有存储操作的存储。有两种托管类型，每种计算类型一种：
+ **会话存储（预览版）**— MicroVM 运行时上的 Per-session 存储空间可跨 stop/resume 周期持续存储。每个会话隔离。不需要 VPC。
+ **容量提供商卷 ** — 实例运行时上的 Amazon EBS 卷，由容量提供商定义并按逻辑名称挂载。在整个会话中保持不变 stop/resume。
+ **Bring-your-own 文件系统 ** — 将您自己的 Amazon S3 文件或 Amazon EFS 接入点直接连接到代理运行时。在会话和代理之间共享。需要 VPC。在 microVM 运行时上可用。
托管类型取决于运行时的计算类型。在 microVM 运行时上使用会话存储，在实例运行时上使用容量提供者卷。在 microVM 运行时，您可以在单个代理运行时（总共最多 5 种配置）上将会话存储与自带文件系统相结合。
## 存储选项一览
下表比较了可用的文件系统配置类型。
| 类别 | Type | 隔离 | Persistence | 计算类型 | 需要 VPC | 适用于 |
| --- | --- | --- | --- | --- | --- | --- |
| 托管式 | 会话存储（预览版） | Per-session | 存活下来 stop/resume；空闲到期 14 天；版本更新时重置 | 仅限 microVM | 否 | 暂存空间、已安装的软件包、代码、项目文件、代理状态 |
| 托管式 | 容量提供商容量 | Per-session | 存活下来 stop/resume；在删除会话之前一直保留 | 仅限实例 | 是（在容量提供商上配置） | 长时间运行的实例会话的临时空间、工作空间文件、缓存和检查点 |
| 男孩 | Amazon S3 Files | 共享 — 多个会话和代理访问相同的数据 | Customer-managed （永久，同步到 S3 存储桶） | microVM | 是 | 可通过标准文件操作和 S3 API 访问数据集 |
| 男孩 | Amazon EFS | 共享 — 多个会话和代理访问相同的数据 | Customer-managed （永久有效，直到你将其删除） | microVM | 是 | 共享工具库、模型权重、读写多代理协作 |
## 快速入门
以下清单提供了配置每种文件系统类型的简要步骤。
### 托管会话存储（预览版）
会话存储在 microVM 运行时上可用。
1. 不需要 VPC 或其他 IAM 权限。
1. `--filesystem-configurations '[{"sessionStorage": {"mountPath": "/mnt/workspace"}}]'`添加到您的`create-agent-runtime`或`update-agent-runtime`致电。
1. 使用调用代理`--runtime-session-id`。
1. 停止会话，然后以相同方式继续`--runtime-session-id`。Verif `/mnt/workspace` y 会保留您的数据。
### 容量提供商容量
容量提供商卷可在实例运行时使用。
1. 创建容量提供商时，在容量提供商上定义一个或多个命名的 Amazon EBS 卷（在`ec2Configuration.volumes`）。
1. 使用引用容量提供者`capacityProviderConfiguration`的，创建代理运行时。
1. `--filesystem-configurations '[{"capacityProviderVolume": {"volumeName": "scratch", "mountPath": "/mnt/scratch"}}]'`添加到同一个`create-agent-runtime`调用中，按卷的逻辑名称引用该卷。
1. 使用调用代理`--runtime-session-id`。停止会话，然后以相同方式继续`--runtime-session-id`。Verif `/mnt/scratch` y 会保留您的数据。
有关完整演练，请参阅使用 Amazon CLI [使用开始使用实例 Amazon CLI 或 SDK](runtime-instances-get-started-cli.md) 开始使用实例。
### Bring-your-own 文件系统
#### 亚马逊 S3 文件接入点
1. 将带`s3files:AccessPointArn`条件`s3files:GetAccessPoint`的执行角色添加`s3files:ClientMount``s3files:ClientWrite`、和。
1. 允许 TCP 端口 2049 从代理运行时安全组出站到您的 S3 文件挂载目标安全组。
1. 确认 S3 文件挂载目标与您的代理运行时子网位于同一 VPC 和可用区中。
1. `--filesystem-configurations '[{"s3FilesAccessPoint": {"accessPointArn": "", "mountPath": "/mnt/s3data"}}]'`添加到您的`create-agent-runtime`或`update-agent-runtime`致电。
1. 调用代理。文件与后备的 S3 存储桶双向`/mnt/s3data`同步。
#### 亚马逊 EFS 接入点
1. 将`elasticfilesystem:ClientMount`和`elasticfilesystem:ClientWrite`添加到您的执行角色中，并附带`elasticfilesystem:AccessPointArn`条件。
1. 允许 TCP 端口 2049 从代理运行时安全组出站到您的 EFS 挂载目标安全组。
1. 确认 EFS 挂载目标与您的至少一个代理运行时子网位于同一个可用区内。
1. `--filesystem-configurations '[{"efsAccessPoint": {"accessPointArn": "", "mountPath": "/mnt/efs"}}]'`添加到您的`create-agent-runtime`或`update-agent-runtime`致电。
1. 调用代理。您的文件可在以下网址获得`/mnt/efs`。
S3 文件和 EFS 都需要在代理运行时进行 VPC 连接。
## 每种类型的工作原理
以下各节描述了每种文件系统类型在 AgentCore Runtime 中的运行方式。
### Bring-your-own 文件系统
当您配置自带文件系统时，Runt AgentCore ime 会将指定的接入点安装到您配置的路径上的每个会话中。数据是共享的 — 多个会话、多个代理或外部应用程序可以同时访问同一个文件系统。
AgentCore 自动处理所有装载操作。您无需安装挂载助手、管理 TLS 证书或在代理中编写挂载代码。
**注意**
创建接入点（S3 文件或 EFS）时，需要指定 POSIX 用户 ID (UID) 和群组 ID (GID)。通过接入点进行的所有文件操作都以此身份运行。将设置 UID/GID 为匹配运行容器进程的用户（对于非根容器，通常为 1000:1000，对于根容器，则为 0:0）。
#### 亚马逊 S3 文件挂载流程
配置 S3 文件接入点时，会出现以下顺序：
1. 您可以创建 S3 文件文件系统（由 S3 存储桶支持）并在 VPC 中挂载目标。
1. 您可以创建一个 S3 文件访问点，指定 POSIX UID/GID 和根目录。
1. 您可以使用接入点 ARN 和装载路径配置代理运行时。
1. 在使用新的会话 ID 进行调用时， AgentCore 预置一个可以访问您的 VPC 的网络的 microVM。
1. 微虚拟机通过您的 VPC NFSv4.2 通过 TLS 和 IAM 身份验证（端口 2049）通过 TLS 挂载文件系统。
1. 您的代理在装载路径上读取和写入文件。更改会自动同步到备份 S3 存储桶。
**S3 文件语义 **
+ 文件系统和备份 S3 存储桶之间的双向同步
+ Close-to-open NFS 客户端的一致性；存储桶端访问的 S3 最终一致性
+ 最大文件大小：48 TiB；最大目录深度：1,000 级
+ 不支持：硬链接、S3 存档存储类别 (Glacier)、自定义 S3 对象元数据、PNF
#### 亚马逊 EFS 挂载流程
配置 EFS 接入点时，会出现以下顺序：
1. 您可以创建 EFS 文件系统并在 VPC 中挂载目标（每个可用区一个）。
1. 您可以创建一个 EFS 接入点，指定 POSIX UID/GID 和根目录。
1. 您可以使用接入点 ARN 和装载路径配置代理运行时。
1. 在使用新的会话 ID 进行调用时， AgentCore 预置一个可以访问您的 VPC 的网络的 microVM。
1. microVM 通过挂载目标 NFSv4.1 通过 TLS（端口 2049）在同一可用区中挂载文件系统。
1. 您的代理使用标准文件操作在装载路径上读取和写入文件。
**EFS 语义 **
+ 完整的 POSIX：硬链接、符号链接、咨询文件锁定
+ 来自多个会话和代理的并行读写访问
+ Close-to-open 一致性
+ 最大文件大小：47.9 TiB；最大目录深度：1,000 级
### 管理会话存储（预览版）
使用托管会话存储 stop/resume 通过文件系统配置保持会话状态。 AgentCore 运行时管理的会话存储是一种完全由服务管理的功能， AgentCore Runtime 可处理所有存储操作。您的代理在整个会话期间读取和写入本地文件系统挂载，运行时环境会透明地将数据复制到服务存储。
会话存储是每个会话隔离的 — 每个会话只能访问自己的存储，不能从相同代理运行时的其他会话或不同代理运行时的会话读取或写入数据。
当您在代理运行时上配置会话存储时，每个会话都会在您指定的挂载路径上获得一个永久目录。生命周期的工作原理如下：
1. **首次在会话上调用 ** — 预置新的隔离计算。您的代理在装载路径上看到一个空目录。
1. **代理写入文件 ** — 所有文件操作（读取、写入、mkdir、重命名）都正常运行，类似于本地文件系统，数据异步复制到耐用存储器。
1. **会话停止 ** — 计算终止。在正常关机期间，任何尚未保存的数据都将刷新到耐用存储器中。
1. **使用相同的会话恢复 ** — 配置了新的计算，文件系统状态将从持久存储中恢复。代理可以从中断的地方继续。
#### 文件系统语义
会话存储在您配置的挂载路径上提供标准的 Linux 文件系统。标准工具和操作无需修改即可运行—— `ls`、`cat`、`mkdir`、`git`、、`npm`、`pip`、、`cargo`所有操作均按预期运行。
**支持的操作 **
常规文件、目录和符号链接。读取、写入、重命名`chmod`、删除`chown`、`stat`、和 `readdir` — 常用开发工具使用的标准 POSIX 文件操作。
**限制**
有关会话存储限制，包括最大存储大小、文件数和目录深度，请参阅[会话存储限制](bedrock-agentcore-limits.md#session-storage-limits)。
**不支持的操作 **
不支持以下文件系统操作：
+ **硬链接 **-改用符号链接。
+ **不支持设备文件、FIFO 或 UNIX 套接字**。`mknod`
+ **扩展属性 (xattr) ** — 不支持依赖于 xattr 元数据的工具。
+ **fallocate ** — 不支持稀疏文件预分配。
+ **跨会话文件锁定 ** — 咨询锁定在正在运行的会话中起作用，但不能持续保留。 stop/resume使用基于文件的锁定（例如`git`）的工具不受影响。
**注意**
权限存储在会话中，但不强制执行。`chmod`并且可以正常`stat`运行，但是访问检查总是成功的，因为代理作为 microVM 中的唯一用户运行。
#### 会话存储生命周期
在以下情况下，会话数据将被删除（重置为干净状态）：
+ 该会话在 ** 14 天内未被调用。**
+ 代理运行时版本已更新。版本更新后调用会话会预置新的文件系统。
使用[DeleteAgentRuntime](https://docs.amazonaws.cn/bedrock-agentcore-control/latest/APIReference/API_DeleteAgentRuntime.html)或删除[DeleteAgentRuntimeEndpoint](https://docs.amazonaws.cn/bedrock-agentcore-control/latest/APIReference/API_DeleteAgentRuntimeEndpoint.html)与运行时或端点关联的所有会话存储数据。
### 容量提供商容量（实例）
容量提供者卷是使用实例计算类型的运行时的托管存储类型。您无需在运行时指定存储，而是在容量提供商上定义命名的 Amazon EBS 卷，然后运行时按逻辑名称挂载它们。 AgentCore 为您创建、附加和保留卷——您无需自己预置或装载 Amazon EBS 卷。
与会话存储一样，容量提供商卷在每个会话中是隔离的，并且持续存在 stop/resume。由于实例上的会话是专用 EC2 实例，因此该量遵循该会话的生命周期：
1. **在容量提供商上定义卷 ** — 创建容量提供商时，在中列出一个或多个 Amazon EBS 卷`ec2Configuration.volumes`，每个卷都有逻辑`name``sizeGiB``volumeType`、可选`iops``throughput`、、加密和`snapshotId`。
1. **从运行时引用卷 ** — `filesystemConfigurations` 使用`volumeName`和 a 向中添加一个`capacityProviderVolume`条目`mountPath`。
1. **首次调用代理 ** — AgentCore 创建 Amazon EBS 卷并将其连接到您的挂载路径上的会话的 EC2 实例。
1. **停止会话 ** — AgentCore 终止 EC2 实例但保留音量。
1. **继续使用相同的会话 ** — 预 AgentCore 置一个新实例并重新连接现有卷，这样您的数据就完好无损。重启的会话可能会在装有最新补丁的实例上运行。
音量将在这些停靠点之间保持不变，包括当会话达到其最大生命周期时。仅当您删除会话或删除容量提供器（删除其会话及其卷）时，它才会被删除。
有关管理这些卷上的数据的信息，请参阅[管理运行时实例上的数据](runtime-instances-data-management.md)。
代理可以共享卷，但共享不是自动的。要为代理运行时安装卷，该运行时必须自行配置相同的`capacityProviderVolume`（由`volumeName`）`filesystemConfigurations`。当使用相同的运行时调用两个这样的运行时时`runtimeSessionId`，它们将在同一个实例上运行，并且每个运行时都会挂载共享卷，因此它们可以协作处理相同的文件。配置`capacityProviderVolume`控制运行时要 AgentCore 装载哪些卷；它本身并不能隔离会话中代理之间的数据。隔离边界是会话。有关会话和代理隔离模型，请参阅运行时实例[的安全模型和权限](runtime-instances-security.md)。
实例运行时不支持托管会话存储和自带类型。这些类型是`sessionStorage``s3FilesAccessPoint`、和`efsAccessPoint`。在旁边指定其中任何一个都会`capacityProviderConfiguration`失败`ValidationException`。有关如何在容量提供商上定义卷并挂载它们，请参阅使用 Amazon CLI [ 开始使用实例](runtime-instances-get-started-cli.md)和跨会话的[永久存储](runtime-instances-how-it-works.md#runtime-instances-persistent-volumes)。
## 自带文件系统的先决条件
在配置自带文件系统之前，请完成以下先决条件。
### VPC 配置
您的代理运行时必须使用`networkMode: VPC`。您指定的子网必须与文件系统挂载目标可用区重叠。
### IAM 权限
您的代理运行时执行角色必须包含挂载文件系统的权限。
**S3 文件的 IAM 权限 **
```
{
"Effect": "Allow",
"Action": [
"s3files:ClientMount",
"s3files:ClientWrite",
"s3files:GetAccessPoint"
],
"Resource": "arn:aws:s3files:::file-system/",
"Condition": {
"ArnEquals": {
"s3files:AccessPointArn": "arn:aws:s3files:::file-system//access-point/"
}
}
}
```
**EFS 的 IAM 权限 **
```
{
"Effect": "Allow",
"Action": [
"elasticfilesystem:ClientMount",
"elasticfilesystem:ClientWrite"
],
"Resource": "arn:aws:elasticfilesystem:::file-system/",
"Condition": {
"ArnEquals": {
"elasticfilesystem:AccessPointArn": "arn:aws:elasticfilesystem:::access-point/"
}
}
}
```
`ClientWrite`如果您的代理只需要读取权限，则省略。在代理运行时创建期间，需要该`s3files:GetAccessPoint`权限才能验证 S3 文件访问点。
### 安全组
允许通过端口 2049 将出站 TCP 从代理运行时安全组发送到装载目标安全组。允许来自代理运行时安全组的装载目标安全组的端口 2049 上的入站 TCP。
## 配置文件系统
以下各节显示如何配置每种文件系统类型。
### 配置 Amazon S3 文件接入点
要配置 S3 文件访问点，请在中`filesystemConfigurations`指定接入点 ARN 和挂载路径。您的代理运行时必须使用 VPC 网络模式。
**Example**
1.
```
aws bedrock-agentcore-control create-agent-runtime \
--agent-runtime-name "data-agent" \
--role-arn "arn:aws:iam:::role/AgentExecutionRole" \
--network-configuration '{
"networkMode": "VPC",
"networkModeConfig": {
"subnets": ["", ""],
"securityGroups": [""]
}
}' \
--agent-runtime-artifact '{
"containerConfiguration": {
"containerUri": ".dkr.ecr..amazonaws.com/my-agent:latest"
}
}' \
--filesystem-configurations '[{
"s3FilesAccessPoint": {
"accessPointArn": "arn:aws:s3files:::file-system//access-point/",
"mountPath": "/mnt/datasets"
}
}]'
```
1. 使用 boto3 创建带有 S3 文件访问点的 AgentCore 运行时的 Python 示例。
```
import boto3
client = boto3.client("bedrock-agentcore-control", region_name="us-west-2")
response = client.create_agent_runtime(
agentRuntimeName="data-agent",
roleArn="arn:aws:iam:::role/AgentExecutionRole",
networkConfiguration={
"networkMode": "VPC",
"networkModeConfig": {
"subnets": ["", ""],
"securityGroups": [""]
}
},
agentRuntimeArtifact={
"containerConfiguration": {
"containerUri": ".dkr.ecr..amazonaws.com/my-agent:latest"
}
},
filesystemConfigurations=[
{
"s3FilesAccessPoint": {
"accessPointArn": "arn:aws:s3files:::file-system//access-point/",
"mountPath": "/mnt/datasets"
}
}
]
)
```
### 配置 Amazon EFS 接入点
要配置 EFS 接入点，请在中指定接入点 ARN 和挂载路径。`filesystemConfigurations`您的代理运行时必须使用 VPC 网络模式。
**Example**
1.
```
aws bedrock-agentcore-control create-agent-runtime \
--agent-runtime-name "shared-tools-agent" \
--role-arn "arn:aws:iam:::role/AgentExecutionRole" \
--network-configuration '{
"networkMode": "VPC",
"networkModeConfig": {
"subnets": ["", ""],
"securityGroups": [""]
}
}' \
--agent-runtime-artifact '{
"containerConfiguration": {
"containerUri": ".dkr.ecr..amazonaws.com/my-agent:latest"
}
}' \
--filesystem-configurations '[{
"efsAccessPoint": {
"accessPointArn": "arn:aws:elasticfilesystem:::access-point/",
"mountPath": "/mnt/tools"
}
}]'
```
1. 使用 boto3 创建带有 EFS 接入点的 AgentCore 运行时的 Python 示例。
```
import boto3
client = boto3.client("bedrock-agentcore-control", region_name="us-west-2")
response = client.create_agent_runtime(
agentRuntimeName="shared-tools-agent",
roleArn="arn:aws:iam:::role/AgentExecutionRole",
networkConfiguration={
"networkMode": "VPC",
"networkModeConfig": {
"subnets": ["", ""],
"securityGroups": [""]
}
},
agentRuntimeArtifact={
"containerConfiguration": {
"containerUri": ".dkr.ecr..amazonaws.com/my-agent:latest"
}
},
filesystemConfigurations=[
{
"efsAccessPoint": {
"accessPointArn": "arn:aws:elasticfilesystem:::access-point/",
"mountPath": "/mnt/tools"
}
}
]
)
```
### 配置托管会话存储
创建或更新代理运行时时`filesystemConfigurations`使用`sessionStorage`条目添加。
**Example**
1.
```
aws bedrock-agentcore-control create-agent-runtime \
--agent-runtime-name "coding-agent" \
--role-arn "arn:aws:iam::111122223333:role/AgentExecutionRole" \
--agent-runtime-artifact '{
"containerConfiguration": {
"containerUri": "123456789012.dkr.ecr.us-west-2.amazonaws.com/my-agent:latest"
}
}' \
--filesystem-configurations '[{
"sessionStorage": {
"mountPath": "/mnt/workspace"
}
}]'
```
1. 使用 boto3 创建带有会话存储的 AgentCore 运行时的 Python 示例。
```
import boto3
client = boto3.client("bedrock-agentcore-control", region_name="us-west-2")
response = client.create_agent_runtime(
agentRuntimeName="coding-agent",
roleArn="arn:aws:iam::111122223333:role/AgentExecutionRole",
agentRuntimeArtifact={
"containerConfiguration": {
"containerUri": "123456789012.dkr.ecr.us-west-2.amazonaws.com/my-agent:latest"
}
},
filesystemConfigurations=[
{
"sessionStorage": {
"mountPath": "/mnt/workspace"
}
}
]
)
```
您还可以使用[UpdateAgentRuntime](https://docs.amazonaws.cn/bedrock-agentcore-control/latest/APIReference/API_UpdateAgentRuntime.html)具有相同`filesystemConfigurations`参数的现有代理运行时添加会话存储。
### 配置容量提供商卷
要安装容量提供商卷，请先在容量提供商上定义该卷。然后在创建代理运行`filesystemConfigurations`时时按名称引用它。这适用于使用实例计算类型的运行时。
**Example**
1. 创建容量提供器（中`ec2Configuration.volumes`）时在容量提供器`volumeName`上定义容量，然后在代理运行时引用该卷。
```
aws bedrock-agentcore-control create-agent-runtime \
--agent-runtime-name "instances-agent" \
--role-arn "arn:aws:iam::111122223333:role/AgentRuntimeRole" \
--agent-runtime-artifact '{
"containerConfiguration": {
"containerUri": "111122223333.dkr.ecr.us-west-2.amazonaws.com/my-agent:latest"
}
}' \
--capacity-provider-configuration '{
"capacityProviderArn": "arn:aws:bedrock-agentcore:us-west-2:111122223333:capacity-provider/my_capacity_provider-a1b2c3d4e5"
}' \
--filesystem-configurations '[{
"capacityProviderVolume": {
"volumeName": "scratch",
"mountPath": "/mnt/scratch"
}
}]'
```
1. 使用 boto3 在具有容量提供者卷的实例上创建 AgentCore 运行时的 Python 示例。
```
import boto3
client = boto3.client("bedrock-agentcore-control", region_name="us-west-2")
response = client.create_agent_runtime(
agentRuntimeName="instances-agent",
roleArn="arn:aws:iam::111122223333:role/AgentRuntimeRole",
agentRuntimeArtifact={
"containerConfiguration": {
"containerUri": "111122223333.dkr.ecr.us-west-2.amazonaws.com/my-agent:latest"
}
},
capacityProviderConfiguration={
"capacityProviderArn": "arn:aws:bedrock-agentcore:us-west-2:111122223333:capacity-provider/my_capacity_provider-a1b2c3d4e5"
},
filesystemConfigurations=[
{
"capacityProviderVolume": {
"volumeName": "scratch",
"mountPath": "/mnt/scratch"
}
}
]
)
```
`volumeName`必须与容量提供商中定义的容量相匹配`ec2Configuration.volumes`。有关在容量提供商上定义卷的步骤，请参阅使用 Amazon CLI [ 开始使用实例](runtime-instances-get-started-cli.md)。
### 合并文件系统
您可以在单个 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:::role/AgentExecutionRole",
networkConfiguration={
"networkMode": "VPC",
"networkModeConfig": {
"subnets": ["", ""],
"securityGroups": [""]
}
},
agentRuntimeArtifact={
"containerConfiguration": {
"containerUri": ".dkr.ecr..amazonaws.com/my-agent:latest"
}
},
filesystemConfigurations=[
{
"s3FilesAccessPoint": {
"accessPointArn": "arn:aws:s3files:::file-system//access-point/",
"mountPath": "/mnt/datasets"
}
},
{
"efsAccessPoint": {
"accessPointArn": "arn:aws:elasticfilesystem:::access-point/",
"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 历史记录都完好无损。当您恢复会话时，新的计算环境会挂载持久存储。您的代理无需重新安装软件包或重新生成文件即可继续工作。
**注意**
显式调用时，请`StopRuntimeSession`务必等待其完成后再恢复会话。这样可以确保将所有数据刷新到耐用存储器中。
**注意**
挂载的路径仅在代理调用时可用，在初始化期间不可用。
## 限制
下表列出了文件系统配置的限制。
| 资源 | 限制 |
| --- | --- |
| 每个代理运行时的文件系统配置总数 | 5 |
| 最大 S3 文件访问点配置 | 2 |
| 最大 EFS 接入点配置 | 2 |
| 最大托管会话存储配置 | 1 |
| 最大容量提供商容量 | 5 |
总配置、S3 文件、EFS 和会话存储限制适用于 microVM 运行时。容量提供者的容量限制是在容量提供商 (`ec2Configuration.volumes`) 上定义的，而不是根据每个运行时定义的。
### 装载路径限制
所有文件系统配置都必须遵循以下挂载路径规则：
+ 必须正好`/mnt/`位于一个子目录级别（例如，`/mnt/data`，`/mnt/workspace`）。
+ 模式：`/mnt/[a-zA-Z0-9._-]+/?`
+ 长度：6—200 个字符。
+ 在所有配置中，每个装载路径都必须是唯一的。
+ 挂载路径不能是彼此的子目录。
## 生命周期行为
下表比较了托管文件系统和自带文件系统类型的生命周期行为。
| 行为 | 托管会话存储（预览版、microVM） | 容量提供商容量（实例） | Bring-your-own （S3 文件、EFS） |
| --- | --- | --- | --- |
| 空闲到期 | 14 天未调用 — 数据重置 | 无 — 音量在停靠点之间保持不变，包括当会话达到其最大生命周期时 | 无 — 由客户管理 |
| 运行时版本更新时 | 数据已擦除 — 下次调用时会出现新的文件系统 | 数据仍然存在 — 下次调用时卷会重新连接 | 没有效果 — 数据仍然存在 |
| 删除时 | 会话数据已删除于 `DeleteAgentRuntime` | 删除会话时或删除容量提供器（删除其会话）时，卷已删除 | 文件系统已卸载；数据保存在您的账户中 |
| 并行访问 | 每个会话隔离 | 每个会话隔离；当每个运行时配置相同的卷时，可以由同一会话中的代理共享 | 在会话和代理之间共享 |
| Ownership | Service-managed 由 AgentCore | Service-managed 由 AgentCore （您的账户中的亚马逊 EBS） | Customer-managed 在你的 Amazon 账户中 |
**重要**
对于自带文件系统，请确保您的代理适当地处理并发访问。使用每个会话的文件命名模式或建议文件锁来避免冲突。
## 使用案例
下表列出了常见模式和每种模式的推荐文件系统配置。
| 模式 | 建议的配置 |
| --- | --- |
| 带有永久项目文件的编码代理 (microVM) | 托管会话存储（预览版）位于 `/mnt/workspace` |
| 实例上长时间运行的代理的永久工作空间 | 容量提供商的容量为 `/mnt/workspace` |
| 可从代理和 S3 管道访问的参考数据集 | S3 文件访问点位于 `/mnt/datasets` |
| 所有代理共享工具库 | S3 文件或 EFS 访问点位于 `/mnt/tools` |
| Multi-agent 共享工作空间上的协作 | S3 文件或 EFS 访问点位于 `/mnt/shared` |
| Long-running 使用检查点进行分析 | 检查点的会话存储 \+ 用于输入数据的 S3 文件 |
| Full-stack 代理（两个类别合并） | 会话存储 \+ S3 文件 \+ EFS（3 个挂载） |
## 示例：使用永久工作空间的编码代理
此示例显示编码代理使用 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}}替换为您的 Amazon 地区（例如，`us-west-2`）。
### Bring-your-own 文件系统网络
Bring-your-own 文件系统要求您的 VPC 网络满足以下要求才能成功挂载。
#### Amazon EFS
+ **挂载目标 ** — 您的 EFS 文件系统必须在代理运行时子网所在的至少一个可用区域中安装挂载目标。为了实现高可用性，建议在所有已配置的子网可用区域中挂载目标。
+ **一次只能一个 VPC ** — EFS 文件系统一次只能在一个 VPC 中设置挂载目标。 Cross-account 不支持 VPC 挂载 AgentCore。
+ **可用区协调 ** — 代理运行时子网和 EFS 挂载目标必须共享至少一个公共可用区。 Cross-AZ NFS 流量有效，但会增加延迟和数据传输成本。
+ **DNS 解析 ** — 您的 VPC 必须启用 DNS 主机名和 DNS 解析。代理在装载时解析装载目标主机名`..efs..amazonaws.com`。
要检查 EFS 挂载目标，请执行以下操作：
```
aws efs describe-mount-targets --file-system-id fs-0123456789abcdef0 --region us-west-2
```
有关 EFS 挂载目标的完整信息，请参阅 [ Amazon EFS 的工作原理](https://docs.amazonaws.cn/efs/latest/ug/how-it-works.html)。
#### Amazon S3 Files
+ **挂载目标 ** — 您的 S3 文件系统必须将挂载目标与代理运行时位于同一 VPC 中。挂载目标必须与您的代理运行时子网位于至少一个相同的可用区域中。
+ **每个可用区一个挂载目标 ** — 每个可用区最多可以有一个 S3 文件挂载目标。
+ **相同的 VPC ** — S3 文件挂载目标必须与代理运行时位于同一 VPC 中。 Cross-VPC 不支持文件系统访问。
+ **DNS 解析 ** — 您的 VPC 必须`..s3files..on.aws`在挂载时解析 S3 文件挂载目标主机名。确保在您的 VPC 设置中启用 DNS 解析。
要检查您的 S3 文件挂载目标，请执行以下操作：
```
aws s3files list-mount-targets --file-system-id fs-0123456789abcdef0 --region us-west-2
```
有关 S3 文件挂载的完整信息，请参阅[挂载 S3 文件系统](https://docs.amazonaws.cn/AmazonS3/latest/userguide/s3-files-mounting.html)。
#### 共同要求
| 要求 | EFS | S3 Files |
| --- | --- | --- |
| 需要 VPC 模式 | ✓ | ✓ |
| NFS 端口 2049 (TCP) | ✓ | ✓ |
| 在同一 AZ 中挂载目标 | ✓（推荐） | ✓（必填） |
| 相同的 VPC | ✓ | ✓ |
| 同一个 Amazon 账户 | ✓ | ✓ |
| 已启用 DNS 解析 | ✓ | ✓ |
| Cross-account VPC | ✗ 不支持 | ✗ 不支持 |
**重要**
Cross-account 不支持 VPC 配置。文件系统资源（文件系统、接入点、挂载目标）和代理运行时必须位于同一个 Amazon 账户和 VPC 中。
#### 如何 AgentCore 装载文件系统
AgentCore 自动处理 microVM 内的 NFS 挂载操作：
+ **EFS ** — NFSv4.1 通过 TLS（端口 2049）安装。当执行角色拥有带`AccessPointArn`条件的`elasticfilesystem:ClientMount`权限时，使用 IAM 身份验证。
+ **S3 文件 ** — NFSv4.2 通过 TLS 挂载，具有强制性 IAM 身份验证。TLS 和 IAM 始终处于启用状态，不能为 S3 文件禁用。
您无需安装`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 配置主题[中的](agentcore-vpc.md#agentcore-supported-azs)支持的可用区域。有关安全组配置，请参阅[示例：连接到 Amazon EFS 或 Amazon S3 文件](agentcore-vpc.md#agentcore-security-groups-filesystem)。
## 对自带文件系统挂载进行故障排除
自带文件系统挂载失败时，`InvokeAgentRuntime`返回 HTTP 424（失败的依赖关系）。
| 症状 | 可能原因 | 快速修复 |
| --- | --- | --- |
| “访问被拒绝” | 执行角色缺失`ClientMount`或 `ClientWrite` | 添加带`AccessPointArn`条件的 IAM 权限 |
| “ResourceNotFound” 或 “无法解决” | 接入点或挂载目标已删除或不可用 | 验证 ARN 存在且装载目标是否可用 |
| 挂载挂起然后失败（大约 30 秒） | 安全组在代理的可用区域中封锁端口 2049 或没有挂载目标 | 允许 TCP 2049；验证可用区重叠 |
| 写入时出现 “权限被拒绝” | 缺失`ClientWrite`或 POSIX UID/GID 不匹配 | 添加写入权限或调整接入点 POSIX 用户 |
每个坐骑都有 30 秒的超时时间。所有配置的文件系统均并行挂载——一次失败会导致整个调用失败。
有关更多信息，请参阅 BYO 存储[我的 S3 文件或 EFS 挂载失败，显示 “访问被拒绝”](runtime-troubleshooting.md#troubleshoot-byo-storage-access-denied)疑难解答。