Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

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 sono necessari codice di montaggio personalizzato, contenitori privilegiati o orchestrazione dei download.

AgentCore Runtime supporta due categorie di configurazioni di file system:

Il tipo gestito dipende dal tipo di elaborazione del runtime. Utilizza l'archiviazione delle sessioni sui runtime MicroVM e i volumi dei provider di capacità sui runtime delle istanze. Sui runtime MicroVM, puoi combinare lo storage delle sessioni con i file system bring-your-own su un singolo runtime dell'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 brevi per la configurazione di ogni tipo di file system.

Archiviazione gestita delle sessioni (anteprima)

L'archiviazione delle sessioni è disponibile nei runtime MicroVM.

Volume del fornitore di capacità

I volumi dei fornitori di capacità sono disponibili nei runtime delle istanze.

Per la procedura dettagliata completa, consulta Guida introduttiva alle istanze utilizzando la CLI. AWS

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 sul 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 bring-your-own, 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 dei file Amazon S3

Quando si configura 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)

Mantieni lo stato della sessione stop/resume con una configurazione del file system utilizzando l'archiviazione delle sessioni gestita. AgentCore L'archiviazione delle sessioni gestita in runtime è una funzionalità completamente gestita dai servizi in cui AgentCore Runtime gestisce tutte le operazioni di archiviazione. L'agente legge e scrive su un file system mount 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 dell'agente diversi.

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

Semantica del file system

L'archiviazione delle sessioni fornisce un file system Linux standard nel percorso di montaggio configurato. Gli strumenti e le operazioni standard funzionano senza modifiche: ls catmkdir,git,npm,pip, e funzionano cargo tutti come previsto.

Operazioni supportate

File, directory e collegamenti simbolici regolari. Lettura, scrittura, ridenominazione, eliminazione, chmod chownstat, 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, vedi Limiti di archiviazione delle sessioni.

Operazioni non supportate

Le seguenti operazioni sul 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:

Usa DeleteAgentRuntime o DeleteAgentRuntimeEndpoint per eliminare tutti i dati di archiviazione della sessione associati al runtime o all'endpoint.

Volumi dei fornitori di capacità (istanze)

I volumi dei fornitori di capacità sono il tipo di storage gestito per i runtime che utilizzano il tipo di calcolo Instances. Invece di specificare lo storage nel runtime, definisci i volumi Amazon EBS denominati sul fornitore di capacità e il runtime li monta in base al nome logico. AgentCore crea, collega e conserva i volumi per te: non sei tu stesso a effettuare il provisioning o il montaggio dei volumi Amazon EBS.

Come lo storage delle sessioni, i volumi dei fornitori di capacità sono isolati per sessione e persistono per tutta la durata. stop/resume Poiché una sessione su Instances è un'istanza EC2 dedicata, il volume segue il ciclo di vita della sessione:

Il volume viene mantenuto per tutte queste interruzioni, anche quando una sessione raggiunge la sua durata massima. Viene eliminato solo quando si elimina la sessione o quando si elimina il fornitore di capacità (che ne elimina le sessioni e i relativi volumi).

Per informazioni sulla gestione dei dati su questi volumi, consulta Gestire i dati sulle istanze di runtime.

Gli agenti possono condividere un volume, ma la condivisione non è automatica. Affinché un volume venga montato per il runtime di un agente, tale runtime deve configurarlo autonomamente capacityProviderVolume (byvolumeName)filesystemConfigurations. Quando due di questi runtime vengono richiamati contemporaneamenteruntimeSessionId, vengono eseguiti sulla stessa istanza e ciascuno monta il volume condiviso, in modo che possano collaborare sugli stessi file. La configurazione capacityProviderVolume controlla quali volumi vengono AgentCore montati per un runtime; non isola di per sé i dati tra gli agenti in una sessione. Il limite di isolamento è la sessione. Per il modello di isolamento della sessione e dell'agente, consulta Modello di sicurezza e autorizzazioni per le istanze di runtime.

L'archiviazione delle sessioni gestita e i tipi bring-your-own non sono supportati nei runtime di Instances. Questi tipi sono,, e. sessionStorage s3FilesAccessPoint efsAccessPoint La specificazione di uno di essi insieme ha capacityProviderConfiguration esito negativo con unValidationException. Per informazioni su come definire i volumi su un fornitore di capacità e montarli, consulta Guida introduttiva alle istanze che utilizzano la AWS CLI e lo storage persistente tra le sessioni.

Prerequisiti per i file system bring-your-own

Prima di configurare un file system bring-your-own, completate i seguenti prerequisiti.

Configurazione VPC

Il runtime dell'agente deve utilizzare. networkMode: VPC Le sottoreti specificate devono sovrapporsi alle zone di disponibilità della destinazione di 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>"
    }
  }
}

Ometti 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 del runtime dell'agente al gruppo di sicurezza mount target. Consenti il TCP in ingresso sulla porta 2049 del gruppo di sicurezza mount target dal gruppo di sicurezza di runtime dell'agente.

Configurare i file system

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

Configura 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. filesystemConfigurations Il runtime dell'agente deve utilizzare la modalità di rete VPC.

Configura un punto di accesso Amazon EFS

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

Configurare l'archiviazione gestita delle sessioni

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

È inoltre possibile aggiungere l'archiviazione della sessione a un runtime dell'agente esistente utilizzando lo stesso UpdateAgentRuntime parametro. filesystemConfigurations

Configurare un volume del fornitore di capacità

Per montare un volume del fornitore di capacità, definisci innanzitutto il volume sul fornitore di capacità. Quindi fai riferimento ad esso per nome filesystemConfigurations quando crei il runtime dell'agente. Questo vale per i runtime che utilizzano il tipo di calcolo Instances.

volumeNameDeve corrispondere a un volume definito in quello del fornitore di capacità. ec2Configuration.volumes Per i passaggi per definire i volumi sul fornitore di capacità, consulta Guida introduttiva alle istanze utilizzando la AWS CLI.

Combina i file system

È possibile combinare lo storage delle sessioni gestito con i file system bring-your-own su un singolo runtime dell'agente MicroVM. 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. Lo storage delle sessioni gestite mantiene i dati su più stop/resume cicli utilizzando gli stessi dati. runtimeSessionId

Esempio: utilizzo dell'archiviazione delle sessioni su più 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'ha lasciato: i file sorgente, i pacchetti installati, gli artefatti di compilazione e la cronologia del file .git sono tutti intatti. Quando si riprende una sessione, il nuovo ambiente di elaborazione monta lo storage persistente. L'agente può continuare a lavorare senza reinstallare i pacchetti o rigenerare i file.

Limits

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

Le configurazioni totali, i file S3, l'EFS e i limiti di archiviazione delle sessioni si applicano ai runtime di MicroVM. Il limite di volume del fornitore di capacità è definito in base al fornitore di capacità () anziché per runtime. ec2Configuration.volumes

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 i tipi di file system gestiti e bring-your-own.

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 spazio di lavoro persistente

Questo esempio mostra un agente di codifica che utilizza Strands Agents with FileSessionManager per la cronologia delle conversazioni e l'archiviazione delle sessioni 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(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

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 per /mnt/workspace/.sessions/ consentire 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 delle sessioni gestite che per i file system bring-your-own.

Rete per lo storage delle sessioni gestite

Se il runtime dell'agente utilizza la modalità VPC con archiviazione delle sessioni, l'agente deve accedere alla rete per sincronizzarsi con l'archiviazione remota. 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'ambito di accesso al bucket di archiviazione delle sessioni regionale 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"
    }
}

Sostituisci region 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 una corretta installazione.

Amazon EFS

Per controllare i target di montaggio EFS:

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

Per informazioni complete sui target di montaggio EFS, consulta Come funziona Amazon EFS.

File di Amazon S3

Per verificare le destinazioni di montaggio dei file S3:

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

Per informazioni complete sul montaggio dei file S3, vedi 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 dell'agente, seleziona le sottoreti che si sovrappongono alle zone di disponibilità di destinazione per il 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 dell'agente si trovino nelle zone di disponibilità in cui il file system ha destinazioni di montaggio.

Per le zone di disponibilità supportate per regione, consulta le zone di disponibilità supportate nell'argomento sulla configurazione del VPC. Per la configurazione dei gruppi di sicurezza, consulta Esempio: connessione a file Amazon EFS o Amazon S3.

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

Quando il montaggio di un file system bring-your-own 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.