儲存選項一目了然快速入門運作方式先決條件設定檔案系統限制對檔案系統掛載進行故障診斷

AgentCore Code Interpreter 的檔案系統組態

AgentCore Code Interpreter 支援透過 filesystemConfigurations 參數將您自己的檔案系統掛載到程式碼解譯器工作階段。每個組態都會在您指定的路徑掛載 Amazon S3 檔案或 Amazon EFS 存取點。您不需要自訂掛載程式碼、特殊權限容器或下載協同運作 — AgentCore 會在工作階段沙盒內執行所有掛載操作。

Bring-your-own檔案系統是共用儲存：多個工作階段、多個程式碼解譯器或外部應用程式可以同時存取相同的存取點。資料會在您自己的 AWS 帳戶中保留和管理。

您可以在使用 CreateCodeInterpreter 建立程式碼解譯器 filesystemConfigurations （從該程式碼解譯器啟動的每個工作階段都會繼承掛載）或使用 StartCodeInterpreterSession 啟動工作階段（掛載適用於該工作階段）時提供。參數和形狀在這兩個位置都是相同的。

注意

與 AgentCore 執行期不同，AgentCore Code Interpreter 不提供受管工作階段儲存選項。Code Interpreter 僅支援bring-your-own Amazon S3 檔案和 Amazon EFS 存取點。

儲存選項一目了然

下表比較可用的檔案系統類型。

Type	隔離	Persistence	需要 VPC	最適合
Amazon S3 Files	共用 – 多個工作階段和程式碼解譯器存取相同的資料	客戶受管（永久，同步到後端 S3 儲存貯體）	是	可透過標準檔案操作和 S3 APIs 存取的資料集和成品
Amazon EFS	共用 – 多個工作階段和程式碼解譯器存取相同的資料	客戶受管（永久，直到您將其刪除為止）	是	跨工作階段的共用參考資料、下載、讀寫協作

快速入門

下列檢查清單提供設定每個檔案系統類型的精簡步驟。

Amazon S3 檔案存取點

使用 s3files:AccessPointArn條件s3files:ClientMount將 s3files:ClientWrite、和 s3files:GetAccessPoint 新增至您的程式碼解譯器執行角色。
允許 TCP 連接埠 2049 從程式碼解譯器安全群組傳出至 S3 檔案掛載目標安全群組。
確認 S3 檔案掛載目標與您的程式碼解譯器子網路位於相同的 VPC 和可用區域。
filesystemConfigurations 使用 s3FilesConfiguration項目將新增至您的 CreateCodeInterpreter或 StartCodeInterpreterSession呼叫。
啟動工作階段。掛載路徑上的檔案（例如 /mnt/s3data) 會與後端 S3 儲存貯體雙向同步。

Amazon EFS 存取點

使用 elasticfilesystem:AccessPointArn條件將 elasticfilesystem:ClientMount和 elasticfilesystem:ClientWrite 新增至您的程式碼解譯器執行角色。
允許 TCP 連接埠 2049 從程式碼解譯器安全群組傳出至 EFS 掛載目標安全群組。
確認 EFS 掛載目標與至少一個程式碼解譯器子網路位於相同的可用區域。
filesystemConfigurations 使用 efsConfiguration項目將新增至您的 CreateCodeInterpreter或 StartCodeInterpreterSession呼叫。
啟動工作階段。您的檔案可在掛載路徑（例如 /mnt/efs) 使用。

S3 檔案和 EFS 都需要在程式碼解譯器上進行 VPC 連線。

運作方式

當您設定bring-your-own檔案系統時，AgentCore Code Interpreter 會將指定的存取點掛載到您設定的路徑的工作階段沙盒中。共用資料 – 多個工作階段、多個程式碼解譯器或外部應用程式可以同時存取相同的檔案系統。

AgentCore 會自動處理所有掛載操作。您不需要安裝掛載協助程式、管理 TLS 憑證或寫入掛載程式碼。

注意

當您建立存取點 (S3 檔案或 EFS) 時，您可以指定 POSIX 使用者 ID (UID) 和群組 ID (GID)。透過存取點執行的所有檔案操作都會以此身分執行。

Amazon S3 檔案掛載流程

您可以在 VPC 中建立 S3 檔案檔案系統（由 S3 儲存貯體後端）並掛載目標。
您可以建立指定 POSIX UID/GID 和根目錄的 S3 檔案存取點。
您可以使用存取點 ARN、檔案系統 ARN 和掛載路徑來設定程式碼解譯器（或工作階段）。
工作階段開始時，AgentCore 會佈建具有 VPC 網路存取權的沙盒。
沙盒會透過 NFSv4.2 透過 TLS 透過 VPC 透過 IAM 身分驗證（連接埠 2049) 掛載檔案系統。
您的代理程式會在掛載路徑讀取和寫入檔案。變更會自動同步到後端 S3 儲存貯體。

Amazon EFS 掛載流程

您可以在 VPC 中建立 EFS 檔案系統和掛載目標（每個可用區域一個）。
您可以建立指定 POSIX UID/GID 和根目錄的 EFS 存取點。
您可以使用存取點 ARN、檔案系統 ARN 和掛載路徑來設定程式碼解譯器（或工作階段）。
工作階段開始時，AgentCore 會佈建具有 VPC 網路存取權的沙盒。
沙盒透過 NFSv4.1 透過 TLS （連接埠 2049) 透過相同可用區域中的掛載目標掛載檔案系統。
您的代理程式會使用標準檔案操作在掛載路徑讀取和寫入檔案。

先決條件

設定bring-your-own檔案系統之前，請先完成下列先決條件。

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 如果您的代理程式只需要讀取存取權，請省略。

Security groups (安全群組)

允許連接埠 2049 上的傳出 TCP 從程式碼解譯器安全群組傳出至掛載目標安全群組。允許來自程式碼解譯器安全群組的掛載目標安全群組上連接埠 2049 上的傳入 TCP。

設定檔案系統

將中的每個檔案系統指定filesystemConfigurations為 s3FilesConfiguration或 efsConfiguration。兩者都需要三個欄位：

accessPointArn – 要掛載之 S3 檔案或 EFS 存取點的 ARN。
fileSystemArn – 擁有存取點之檔案系統的 ARN。此欄位為必要欄位。
mountPath – 掛載存取點之工作階段內的絕對路徑（例如，/mnt/s3data)。

您可以使用相同的形狀，filesystemConfigurations在兩個位置提供：

控制平面 CreateCodeInterpreter – 掛載由從程式碼解譯器啟動的每個工作階段繼承。程式碼解譯器必須使用 VPC 網路模式。
資料平面 StartCodeInterpreterSession – 掛載適用於該特定工作階段。

注意

您可以在控制平面 (CreateCodeInterpreter)、資料平面 (StartCodeInterpreterSession) 或兩者提供檔案系統組態，只要程式碼解譯器使用 VPC 網路模式，且 S3 檔案或 EFS 存取點已正確設定（掛載目標、IAM 許可和安全群組）。來自的組態會由每個工作階段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

範例

AWS CLI


aws bedrock-agentcore-control create-code-interpreter \
  --name "shared-tools-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 '[{
    "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"
    }
  }]'

AWS SDK

使用 boto3 建立具有 EFS 存取點的程式碼解譯器的 Python 範例。


import boto3

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

response = cp.create_code_interpreter(
    name="shared-tools-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=[
        {
            "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"
            }
        }
    ]
)

資料平面： 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	每個工作階段合併
Amazon S3 檔案存取點	2	2	4
Amazon 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._-]+/?
所有組態的每個掛載路徑都必須是唯一的。
掛載路徑不能是彼此的子目錄。

對檔案系統掛載進行故障診斷

當bring-your-own檔案系統掛載失敗時，會StartCodeInterpreterSession傳回錯誤，而且工作階段不會變成 READY。

徵狀	可能原因	快速修正
「拒絕存取」	執行角色遺失或 `ClientMount` `ClientWrite`	使用 `AccessPointArn`條件新增 IAM 許可
「ResourceNotFound」或「無法解析」	存取點或掛載目標已刪除或無法使用	確認 ARN 存在且掛載目標可用
掛載掛起後失敗	安全群組封鎖連接埠 2049，或工作階段可用區域中沒有掛載目標	允許 TCP 2049；驗證可用區域重疊
寫入的「拒絕許可」	遺失或 `ClientWrite` POSIX UID/GID 不相符	新增寫入許可或對齊存取點 POSIX 使用者

所有設定的檔案系統在工作階段開始時平行掛載 – 單一掛載失敗會導致工作階段開始失敗。

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

停止 AgentCore Code Interpreter 工作階段

API 參考範例