AgentCore 執行期的檔案系統組態

AgentCore Runtime 透過 filesystemConfigurations 參數支援持久性檔案系統。每個組態都會在您指定的路徑掛載儲存體。您不需要自訂掛載程式碼、特殊權限容器或下載協同運作。

AgentCore 執行期支援兩種類型的檔案系統組態：

您可以在單一代理程式執行時間結合這兩個類別 （最多總共 5 個組態）。

儲存選項一目了然

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

快速入門

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

受管工作階段儲存體 （預覽版）

Bring-your-own檔案系統

Amazon S3 檔案存取點

Amazon EFS 存取點

S3 檔案和 EFS 都需要代理程式執行時間的 VPC 連線。

每種類型的運作方式

下列各節說明每個檔案系統類型如何在 AgentCore 執行期中運作。

Bring-your-own檔案系統

當您設定bring-your-own檔案系統時，AgentCore 執行期會將指定的存取點掛載到您設定路徑的每個工作階段。共用資料 – 多個工作階段、多個客服人員或外部應用程式可以同時存取相同的檔案系統。

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

Amazon S3 檔案掛載流程

當您設定 S3 檔案存取點時，會發生下列序列：

S3 檔案語意

Amazon EFS 掛載流程

當您設定 EFS 存取點時，會發生下列序列：

EFS 語意

受管工作階段儲存體 （預覽版）

透過使用受管工作階段儲存體的檔案系統組態，跨停止/繼續維持工作階段狀態。AgentCore 執行期受管工作階段儲存是一種全服務受管功能，AgentCore 執行期可處理所有儲存操作。您的代理程式會讀取和寫入本機檔案系統掛載，而執行時間環境會在整個工作階段期間透明地將資料複寫至服務儲存體。

每個工作階段會隔離工作階段儲存 – 每個工作階段只能存取自己的儲存體，而且無法從相同代理執行時間的其他工作階段或不同代理執行時間的工作階段讀取或寫入資料。

當您在代理程式執行時間設定工作階段儲存體時，每個工作階段都會在您指定的掛載路徑取得持久性目錄。生命週期的運作方式如下：

檔案系統語意

工作階段儲存會在您設定的掛載路徑提供標準 Linux 檔案系統。標準工具和操作無需修改即可運作 – ls、cat、mkdir、pip、、 git npm和 cargo皆如預期般運作。

支援的操作

一般檔案、目錄和符號連結。讀取、寫入、重新命名、刪除、chmod、stat、 chown和 readdir- 常用開發工具所使用的標準 POSIX 檔案操作。

限制

如需工作階段儲存限制，包括儲存大小上限、檔案計數和目錄深度，請參閱工作階段儲存限制。

不支援的操作

不支援下列檔案系統操作：

工作階段儲存生命週期

在下列案例中，工作階段資料會被刪除 （重設為清除狀態）：

使用 DeleteAgentRuntime 或 DeleteAgentRuntimeEndpoint 刪除與執行時間或端點相關聯的所有工作階段儲存資料。

bring-your-own檔案系統的先決條件

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

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 如果您的代理程式只需要讀取存取權，請省略 。在建立代理程式執行時間期間，S3 檔案存取點驗證需要 s3files:GetAccessPoint許可。

Security groups (安全群組)

允許連接埠 2049 上的傳出 TCP 從代理程式執行時間安全群組傳出至掛載目標安全群組。允許從代理程式執行時間安全群組掛載目標安全群組上連接埠 2049 上的傳入 TCP。

設定檔案系統

下列各節說明如何設定每個檔案系統類型。

設定 Amazon S3 檔案存取點

若要設定 S3 檔案存取點，請在 中指定存取點 ARN 和掛載路徑filesystemConfigurations。您的代理程式執行時間必須使用 VPC 網路模式。

設定 Amazon EFS 存取點

若要設定 EFS 存取點，請在 中指定存取點 ARN 和掛載路徑filesystemConfigurations。您的代理程式執行時間必須使用 VPC 網路模式。

設定受管工作階段儲存

在建立或更新代理程式執行時間時，filesystemConfigurations使用sessionStorage項目新增 。

您也可以使用 UpdateAgentRuntime 搭配相同的參數，將工作階段儲存新增至現有的代理程式執行期。 filesystemConfigurations

合併檔案系統

您可以在單一代理程式執行時間，將受管工作階段儲存與bring-your-own檔案系統結合。下列範例會設定這三種類型。

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)。受管工作階段儲存會使用相同的 在停止/繼續週期之間保留資料runtimeSessionId。

範例：跨停止/繼續週期使用工作階段儲存

# 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 歷史記錄都保持不變。當您繼續工作階段時，新的運算環境會掛載保留的儲存體。您的代理程式可以繼續運作，而無需重新安裝套件或重新產生檔案。

限制

下表列出檔案系統組態的限制。

掛載路徑限制條件

所有檔案系統組態必須遵循下列掛載路徑規則：

生命週期行為

下表比較受管工作階段儲存與bring-your-own檔案系統之間的生命週期行為。

使用案例

下表列出常見的模式，以及每個模式的建議檔案系統組態。

範例：使用持久性工作區編碼代理程式

此範例顯示使用 Strands Agents 搭配 的編碼代理程式FileSessionManager，用於專案檔案的對話歷史記錄和工作階段儲存。兩者會在停止/繼續週期之間持續存在。

使用工作階段儲存體來編碼代理程式

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/，讓客服人員記住停止/繼續週期的內容。

網路要求

本節涵蓋受管工作階段儲存和bring-your-own檔案系統的聯網需求。

受管工作階段儲存聯網

如果您的代理程式執行期使用 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"
    }
}

將區域取代為您的 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 檔案。

針對bring-your-own檔案系統掛載進行故障診斷

當bring-your-own檔案系統掛載失敗時， InvokeAgentRuntime會傳回 HTTP 424 （失敗相依性）。

每個掛載都有 30 秒的逾時。所有設定的檔案系統平行掛載 – 單一失敗會導致整個調用失敗。

如需詳細資訊，請參閱疑難排解 BYO 儲存。