Configurazioni del file system per AgentCore Runtime

AgentCore Runtime supporta i file system persistenti tramite il filesystemConfigurations parametro. Ogni configurazione monta lo storage in un percorso specificato dall'utente. Non è necessario un codice di montaggio personalizzato, contenitori privilegiati o un'orchestrazione dei download.

AgentCore Runtime supporta due categorie di configurazioni di file system:

È possibile combinare entrambe le categorie in un runtime di un singolo agente (fino a 5 configurazioni totali).

Le opzioni di archiviazione a colpo d'occhio

La tabella seguente confronta i tipi di configurazione del file system disponibili.

Avvio rapido

Le seguenti liste di controllo forniscono passaggi abbreviati per la configurazione di ogni tipo di file system.

Archiviazione gestita delle sessioni (anteprima)

Bring-your-own file system

Punto di accesso Amazon S3 Files

Punto di accesso Amazon EFS

Sia S3 Files che EFS richiedono la connettività VPC nel runtime dell'agente.

Come funziona ogni tipo

Le sezioni seguenti descrivono il funzionamento di ciascun tipo di file system all'interno di AgentCore Runtime.

Bring-your-own file system

Quando si configura un file system personalizzato, AgentCore Runtime monta il punto di accesso specificato in ogni sessione nel percorso configurato. I dati sono condivisi: più sessioni, più agenti o applicazioni esterne possono accedere contemporaneamente allo stesso file system.

AgentCore gestisce automaticamente tutte le operazioni di montaggio. Non è necessario installare gli helper di montaggio, gestire i certificati TLS o scrivere codice di montaggio nel proprio agente.

Flusso di montaggio di Amazon S3 Files

Quando configuri un punto di accesso S3 Files, si verifica la seguente sequenza:

Semantica dei file S3

Flusso di montaggio di Amazon EFS

Quando si configura un punto di accesso EFS, si verifica la seguente sequenza:

Semantica EFS

Archiviazione gestita delle sessioni (anteprima)

Persiste lo stato della sessione stop/resume con una configurazione del file system utilizzando l'archiviazione gestita delle sessioni. AgentCore Lo storage di sessione gestito in fase di esecuzione è una funzionalità completamente gestita dai servizi in cui AgentCore Runtime gestisce tutte le operazioni di storage. L'agente legge e scrive su un file system di montaggio locale e l'ambiente di runtime replica in modo trasparente i dati nello storage del servizio per tutta la durata della sessione.

L'archiviazione delle sessioni è isolata per sessione: ogni sessione può accedere solo alla propria memoria e non può leggere o scrivere dati da altre sessioni dello stesso runtime dell'agente o da sessioni di runtime di agenti diversi.

Quando si configura l'archiviazione delle sessioni su un runtime dell'agente, ogni sessione ottiene una directory persistente nel percorso di montaggio specificato. Il ciclo di vita funziona come segue:

Semantica del file system

Lo storage di sessione fornisce un file system Linux standard nel percorso di montaggio configurato. Gli strumenti e le operazioni standard funzionano senza modifiche: lscat,mkdir,git,npm,pip, e funzionano cargo tutti come previsto.

Operazioni supportate

File, directory e collegamenti simbolici regolari. Lettura, scrittura, ridenominazione chmod chownstat, eliminazione ereaddir: operazioni standard sui file POSIX utilizzate dai comuni strumenti di sviluppo.

Limiti

Per i limiti di archiviazione delle sessioni, tra cui la dimensione massima di archiviazione, il numero di file e la profondità della directory, consulta Limiti di archiviazione delle sessioni.

Operazioni non supportate

Le seguenti operazioni del file system non sono supportate:

ciclo di vita dello storage delle sessioni

I dati della sessione vengono eliminati (ripristinati allo stato pulito) nei seguenti scenari:

Utilizza DeleteAgentRuntimeo DeleteAgentRuntimeEndpointper eliminare tutti i dati di archiviazione della sessione associati al runtime o all'endpoint.

Prerequisiti per l'utilizzo di file system personalizzati

Prima di configurare un file system personalizzato, completate i seguenti prerequisiti.

Configurazione VPC

Il runtime dell'agente deve utilizzare. networkMode: VPC Le sottoreti specificate devono sovrapporsi alle zone di disponibilità di destinazione per il montaggio del file system.

autorizzazioni IAM

Il ruolo di esecuzione del runtime dell'agente deve includere le autorizzazioni per montare il file system.

Autorizzazioni IAM per i file S3

{
  "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>"
    }
  }
}

Autorizzazioni IAM per EFS

{
  "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>"
    }
  }
}

Omettilo ClientWrite se il tuo agente necessita solo dell'accesso in lettura. L's3files:GetAccessPointautorizzazione è richiesta per la convalida del punto di accesso di S3 Files durante la creazione del runtime dell'agente.

Gruppi di sicurezza

Consenti il protocollo TCP in uscita sulla porta 2049 dal gruppo di sicurezza Agent Runtime al gruppo di sicurezza di destinazione del montaggio. Consenti il protocollo TCP in entrata sulla porta 2049 sul gruppo di sicurezza target di montaggio del gruppo di sicurezza Agent Runtime.

Configura i file system

Le seguenti sezioni mostrano come configurare ogni tipo di file system.

Configurazione di un punto di accesso Amazon S3 Files

Per configurare un punto di accesso S3 Files, specifica l'ARN del punto di accesso e il percorso di montaggio in. filesystemConfigurations Il runtime dell'agente deve utilizzare la modalità di rete VPC.

Configurazione di un punto di accesso Amazon EFS

Per configurare un punto di accesso EFS, specificare l'ARN del punto di accesso e il percorso di montaggio in. filesystemConfigurations Il runtime dell'agente deve utilizzare la modalità di rete VPC.

Configura l'archiviazione gestita delle sessioni

Aggiungi filesystemConfigurations con una sessionStorage voce durante la creazione o l'aggiornamento di un runtime dell'agente.

È inoltre possibile aggiungere l'archiviazione della sessione a un runtime di agente esistente utilizzando lo stesso UpdateAgentRuntimeparametro. filesystemConfigurations

Combina i file system

È possibile combinare lo storage gestito delle sessioni con file system personalizzati in un runtime con un singolo agente. L'esempio seguente configura tutti e tre i tipi.

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"
            }
        }
    ]
)

Richiama e usa l'archiviazione persistente

Tutti i file system configurati sono disponibili nei rispettivi percorsi di montaggio quando viene richiamato l'agente. Bring-your-own i file system (S3 Files, EFS) sono accessibili immediatamente a ogni chiamata. L'archiviazione gestita delle sessioni mantiene i dati in modo persistente tra i stop/resume cicli utilizzando lo stesso. runtimeSessionId

Esempio: utilizzo dell'archiviazione delle sessioni tra cicli 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"}'

L'agente vede /mnt/workspace esattamente come l'aveva lasciato: i file sorgente, i pacchetti installati, gli elementi di build e la cronologia.git sono tutti intatti. Quando riprendi una sessione, il nuovo ambiente di elaborazione monta lo storage persistente. L'agente può continuare a lavorare senza reinstallare pacchetti o rigenerare i file.

Limits

La tabella seguente elenca i limiti per le configurazioni del file system.

Vincoli di percorso di montaggio

Tutte le configurazioni del file system devono seguire queste regole del percorso di montaggio:

Comportamento del ciclo di vita

La tabella seguente confronta il comportamento del ciclo di vita tra lo storage gestito delle sessioni e i file system personalizzati.

Casi d’uso

La tabella seguente elenca i modelli comuni e la configurazione del file system consigliata per ciascuno di essi.

Esempio: agente di codifica con area di lavoro persistente

Questo esempio mostra un agente di codifica che utilizza Strands Agents per la cronologia delle conversazioni e l'archiviazione delle sessioni FileSessionManager per i file di progetto. Entrambi persistono attraverso i cicli. stop/resume

Agente di codifica con archiviazione delle sessioni

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

Richiama l'agente, interrompi la sessione, quindi riprendi. Sia i file di progetto che il contesto della conversazione persistono.

Richiama, interrompi e riprendi il ciclo

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)

FileSessionManagerMemorizza la cronologia delle conversazioni/mnt/workspace/.sessions/, permettendo all'agente di ricordare il contesto tra i stop/resume cicli.

Requisiti di rete

Questa sezione descrive i requisiti di rete sia per l'archiviazione gestita delle sessioni che per i file system personalizzati.

Rete di archiviazione gestita delle sessioni

Se il runtime dell'agente utilizza la modalità VPC con archiviazione delle sessioni, l'agente necessita dell'accesso alla rete per la sincronizzazione con lo storage remoto. I dati della sessione sono archiviati in AgentCore S3, quindi il tuo VPC deve consentire la connettività in uscita a S3. Se utilizzi un endpoint S3 Gateway con una policy personalizzata, puoi definire l'accesso al tuo bucket di archiviazione delle sessioni regionali come segue:

"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"
    }
}

regionSostituiscilo con la tua AWS regione (ad esempio,). us-west-2

Bring-your-own rete di file system

Bring-your-own i file system richiedono che la rete VPC soddisfi i seguenti requisiti per un montaggio corretto.

Amazon EFS

Per verificare gli obiettivi di montaggio EFS:

aws efs describe-mount-targets --file-system-id fs-0123456789abcdef0 --region us-west-2

Per informazioni complete sugli obiettivi di montaggio EFS, consulta Come funziona Amazon EFS.

File di Amazon S3

Per verificare gli obiettivi di montaggio dei tuoi file S3:

aws s3files list-mount-targets --file-system-id fs-0123456789abcdef0 --region us-west-2

Per informazioni complete sul montaggio dei file S3, consultate Montaggio dei file system S3.

Requisiti condivisi

Come AgentCore monta i file system

AgentCore gestisce automaticamente l'operazione di montaggio NFS all'interno della microVM:

Non è necessario installareamazon-efs-utils, configurare o gestire i /etc/fstab certificati TLS. Il runtime MicroVM gestisce tutte le operazioni di montaggio, la rotazione delle credenziali e il monitoraggio dello stato.

Selezione della sottorete e della zona di disponibilità

Quando configuri sia le sottoreti VPC che le configurazioni del file system su un runtime di agente, seleziona le sottoreti che si sovrappongono alle zone di disponibilità di destinazione di montaggio del file system.

Per identificare l'ID della zona di disponibilità delle sottoreti:

aws ec2 describe-subnets \
  --subnet-ids subnet-0123456789abcdef0 \
  --query 'Subnets[0].AvailabilityZoneId'

Per identificare la zona di disponibilità dei target di montaggio EFS:

aws efs describe-mount-targets \
  --file-system-id fs-0123456789abcdef0 \
  --query 'MountTargets[*].[AvailabilityZoneId, LifeCycleState]' \
  --output table

Assicurati che le sottoreti di runtime degli agenti si trovino nelle zone di disponibilità in cui il file system ha obiettivi di montaggio.

Per le zone di disponibilità supportate per regione, consulta le Zone di disponibilità supportate nell'argomento Configurazione VPC. Per la configurazione del gruppo di sicurezza, consulta Esempio: connessione ad Amazon EFS o Amazon S3 Files.

Risolvi i problemi relativi ai montaggi del file system «bring-your-own»

Quando il montaggio di un file system personalizzato fallisce, restituisce HTTP 424 (Failed Dependency). InvokeAgentRuntime

Ogni montaggio ha un timeout di 30 secondi. Tutti i file system configurati vengono montati in parallelo: un singolo errore causa il fallimento dell'intera chiamata.

Per ulteriori informazioni, consulta Risoluzione dei problemi di archiviazione BYO.