AgentCore 代码解释器的文件系统配置

AgentCore 代码解释器支持通过filesystemConfigurations参数将您自己的文件系统安装到代码解释器会话中。每种配置都会在您指定的路径上挂载一个 Amazon S3 文件或 Amazon EFS 接入点。您不需要自定义挂载代码、特权容器或下载编排—— AgentCore 在会话沙箱内执行所有挂载操作。

Bring-your-own 文件系统是共享存储：多个会话、多个代码解释器或外部应用程序可以同时访问同一个接入点。数据将在您自己的 AWS 账户中保存和管理。

您可以在使用创建代码解释器filesystemConfigurations时提供 CreateCodeInterpreter（从该代码解释器启动的每个会话都继承挂载），或者在启动会话时提供 StartCodeInterpreterSession（挂载适用于该会话）。两个地方的参数和形状是相同的。

注意

与 AgentCore Runtime 不同， AgentCore 代码解释器不提供托管会话存储选项。代码解释器仅支持自带亚马逊 S3 文件和 Amazon EFS 接入点。

存储选项一览

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

Type	隔离	Persistence	需要 VPC	适用于
Amazon S3 Files	共享 — 多个会话和代码解释器访问相同的数据	Customer-managed （永久，同步到备份 S3 存储桶）	是	可通过标准文件操作和 S3 API 访问数据集和对象
Amazon EFS	共享 — 多个会话和代码解释器访问相同的数据	Customer-managed （永久有效，直到你将其删除）	是	跨会话共享参考数据、下载、读写协作

快速入门

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

亚马逊 S3 文件接入点

将带s3files:AccessPointArn条件s3files:GetAccessPoint的代码解释器执行角色添加s3files:ClientMounts3files:ClientWrite、和。
允许 TCP 端口 2049 从您的代码解释器安全组出站到您的 S3 文件挂载目标安全组。
确认 S3 文件挂载目标与您的代码解释器子网位于同一 VPC 和可用区内。
在您的CreateCodeInterpreter或StartCodeInterpreterSession通话中添加filesystemConfigurations一个s3FilesConfiguration条目。
开始会话。您的挂载路径上的文件（例如，/mnt/s3data）与后备的 S3 存储桶双向同步。

亚马逊 EFS 接入点

将elasticfilesystem:ClientMount和elasticfilesystem:ClientWrite添加到您的代码解释器执行角色中，并附带elasticfilesystem:AccessPointArn条件。
允许 TCP 端口 2049 从您的代码解释器安全组出站到您的 EFS 挂载目标安全组。
确认 EFS 挂载目标与您的至少一个代码解释器子网位于同一个可用区内。
在您的CreateCodeInterpreter或StartCodeInterpreterSession电话中添加filesystemConfigurations一个efsConfiguration条目。
开始会话。您的文件可在您的装载路径中找到（例如，/mnt/efs）。

S3 文件和 EFS 都需要在代码解释器上进行 VPC 连接。

工作原理

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

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

注意

创建接入点（S3 文件或 EFS）时，需要指定 POSIX 用户 ID (UID) 和群组 ID (GID)。通过接入点进行的所有文件操作都以此身份运行。

亚马逊 S3 文件挂载流程

您可以创建 S3 文件文件系统（由 S3 存储桶支持）并在 VPC 中挂载目标。
您可以创建一个 S3 文件访问点，指定 POSIX UID/GID 和根目录。
您可以使用接入点 ARN、文件系统 ARN 和装载路径配置代码解释器（或会话）。
会话启动时，预 AgentCore 置一个可以访问您的 VPC 的网络沙箱。
沙箱通过您的 VPC NFSv4.2 通过 TLS 和 IAM 身份验证（端口 2049）通过 TLS 挂载文件系统。
您的代理在装载路径上读取和写入文件。更改会自动同步到备份 S3 存储桶。

亚马逊 EFS 挂载流程

您可以创建 EFS 文件系统并在 VPC 中挂载目标（每个可用区一个）。
您可以创建一个 EFS 接入点，指定 POSIX UID/GID 和根目录。
您可以使用接入点 ARN、文件系统 ARN 和装载路径配置代码解释器（或会话）。
会话启动时，预 AgentCore 置一个可以访问您的 VPC 的网络沙箱。
沙箱通过挂载目标 NFSv4.1 通过 TLS（端口 2049）在同一可用区中挂载文件系统。
您的代理使用标准文件操作在装载路径上读取和写入文件。

先决条件

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

VPC 配置

您的代码解释器必须使用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如果您的代理只需要读取权限，则省略。

安全组

允许将端口 2049 上的出站 TCP 从您的代码解释器安全组发送到挂载目标安全组。允许来自代码解释器安全组的装载目标安全组上端口 2049 的入站 TCP。

配置文件系统

将中的每个文件系统指定filesystemConfigurations为s3FilesConfiguration或efsConfiguration。两者都需要三个字段：

accessPointArn— 要挂载的 S3 文件或 EFS 接入点的 ARN。
fileSystemArn— 拥有接入点的文件系统的 ARN。此字段为必填字段。
mountPath— 安装接入点的会话内的绝对路径（例如，/mnt/s3data）。

你可以使用相同的形状filesystemConfigurations在两个地方供应：

控制平面 — CreateCodeInterpreter — 挂载由从代码解释器启动的每个会话继承。代码解释器必须使用 VPC 网络模式。
数据平面 StartCodeInterpreterSession — — 挂载适用于该特定会话。

注意

只要代码解释器使用 VPC 网络模式并且 S3 文件或 EFS 接入点配置正确（挂载目标、IAM 权限和安全组StartCodeInterpreterSession），您就可以在控制平面 ()、数据平面 () 或两者上提供文件系统配置。CreateCodeInterpreter来自的CreateCodeInterpreter配置由每个会话继承；中的配置StartCodeInterpreterSession适用于该会话。当两者都提供时，它们将组合到会话中，并且每个装载路径在组合集合中必须是唯一的。

以下部分显示了每种文件系统类型的两个 API 调用。

配置 Amazon S3 文件接入点

控制平面：CreateCodeInterpreter

例

AWS CLI


aws bedrock-agentcore-control create-code-interpreter \
  --name "data-code-interpreter" \
  --execution-role-arn "arn:aws:iam::<account-id>:role/CodeInterpreterExecutionRole" \
  --network-configuration '{
    "networkMode": "VPC",
    "vpcConfig": {
      "subnets": ["<subnet-id-1>", "<subnet-id-2>"],
      "securityGroups": ["<security-group-id>"]
    }
  }' \
  --filesystem-configurations '[{
    "s3FilesConfiguration": {
      "accessPointArn": "arn:aws:s3files:<region>:<account-id>:file-system/<file-system-id>/access-point/<access-point-id>",
      "fileSystemArn": "arn:aws:s3files:<region>:<account-id>:file-system/<file-system-id>",
      "mountPath": "/mnt/s3data"
    }
  }]'

AWS SDK

使用 boto3 创建带有 S3 文件访问点的代码解释器的 Python 示例。


import boto3

cp = boto3.client("bedrock-agentcore-control", region_name="us-west-2")

response = cp.create_code_interpreter(
    name="data-code-interpreter",
    executionRoleArn="arn:aws:iam::<account-id>:role/CodeInterpreterExecutionRole",
    networkConfiguration={
        "networkMode": "VPC",
        "vpcConfig": {
            "subnets": ["<subnet-id-1>", "<subnet-id-2>"],
            "securityGroups": ["<security-group-id>"]
        }
    },
    filesystemConfigurations=[
        {
            "s3FilesConfiguration": {
                "accessPointArn": "arn:aws:s3files:<region>:<account-id>:file-system/<file-system-id>/access-point/<access-point-id>",
                "fileSystemArn": "arn:aws:s3files:<region>:<account-id>:file-system/<file-system-id>",
                "mountPath": "/mnt/s3data"
            }
        }
    ]
)

数据平面：StartCodeInterpreterSession

例

配置 Amazon EFS 接入点

控制平面：CreateCodeInterpreter

例

数据平面：StartCodeInterpreterSession

例

合并文件系统

通过向添加更多条目，您可以在单个呼叫中连接多个接入点（不超过以下限制）filesystemConfigurations。每个条目都必须使用唯一的挂载路径。


filesystemConfigurations=[
    {
        "s3FilesConfiguration": {
            "accessPointArn": "arn:aws:s3files:<region>:<account-id>:file-system/<file-system-id>/access-point/<access-point-id>",
            "fileSystemArn": "arn:aws:s3files:<region>:<account-id>:file-system/<file-system-id>",
            "mountPath": "/mnt/s3data"
        }
    },
    {
        "efsConfiguration": {
            "accessPointArn": "arn:aws:elasticfilesystem:<region>:<account-id>:access-point/<access-point-id>",
            "fileSystemArn": "arn:aws:elasticfilesystem:<region>:<account-id>:file-system/<file-system-id>",
            "mountPath": "/mnt/efs"
        }
    }
]

确认已挂载的文件系统

GetCodeInterpreter用于在代码解释器filesystemConfigurations上确认，以及GetCodeInterpreterSession确认正在运行的会话的有效配置。在创建代码解释器时和会话启动时设置的配置都出现在会话响应中。

限制

每个请求都强制执行文件系统配置限制。CreateCodeInterpreter配置由每个会话继承，StartCodeInterpreterSession配置适用于该会话。会话的有效坐骑是两者的组合。

配置类型	每 CreateCodeInterpreter	每 StartCodeInterpreterSession	每次会话合计
亚马逊 S3 文件访问点	2	2	4
亚马逊 EFS 接入点	2	2	4
文件系统配置总数	4	4	8

例如，您可以配置 1 个 S3 文件访问点和 1 个 EFS 接入点CreateCodeInterpreter，然后添加 1 个 S3 文件访问点和 1 个 EFS 接入点StartCodeInterpreterSession，这样会话中总共有 4 个挂载。每个装载路径在组合集合中都必须是唯一的。

装载路径限制

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

必须正好/mnt/位于一个子目录级别（例如，/mnt/data，/mnt/s3data）。
模式：/mnt/[a-zA-Z0-9._-]+/?
在所有配置中，每个装载路径都必须是唯一的。
挂载路径不能是彼此的子目录。

对文件系统装载进行故障排除

当自带文件系统挂载失败时，会StartCodeInterpreterSession返回错误并且会话不会变成。READY

症状	可能原因	快速修复
“访问被拒绝”	执行角色缺失`ClientMount`或 `ClientWrite`	使用`AccessPointArn`条件添加 IAM 权限
“ResourceNotFound” 或 “无法解决”	接入点或挂载目标已删除或不可用	验证 ARN 存在且装载目标是否可用
挂载挂起然后失败	安全组封锁端口 2049，或者会话的可用区域中没有挂载目标	允许 TCP 2049；验证可用区重叠
写入时出现 “权限被拒绝”	缺失`ClientWrite`或 POSIX UID/GID 不匹配	添加写入权限或调整接入点 POSIX 用户

所有配置的文件系统在会话启动时并行装载，单次装载失败会导致会话启动失败。

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

停止 AgentCore 代码解释器会话

API 参考示例