Configurations du système de fichiers pour AgentCore Runtime

AgentCore Runtime prend en charge les systèmes de fichiers persistants via le filesystemConfigurations paramètre. Chaque configuration installe le stockage sur un chemin que vous spécifiez. Vous n'avez pas besoin de code de montage personnalisé, de conteneurs privilégiés ou d'orchestration des téléchargements.

AgentCore Runtime prend en charge deux catégories de configurations de systèmes de fichiers :

Vous pouvez combiner les deux catégories sur un seul environnement d'exécution d'agent (jusqu'à 5 configurations au total).

Les options de stockage en un coup d'œil

Le tableau suivant compare les types de configuration de système de fichiers disponibles.

Démarrage rapide

Les listes de contrôle suivantes fournissent des étapes condensées pour configurer chaque type de système de fichiers.

Stockage de session géré (version préliminaire)

Bring-your-own système de fichiers

Point d'accès Amazon S3 Files

Point d'accès Amazon EFS

S3 Files et EFS nécessitent une connectivité VPC sur le runtime de l'agent.

Comment fonctionne chaque type

Les sections suivantes décrivent le fonctionnement de chaque type de système de fichiers dans AgentCore Runtime.

Bring-your-own systèmes de fichiers

Lorsque vous configurez un système de fichiers personnalisé, AgentCore Runtime monte le point d'accès spécifié dans chaque session sur le chemin que vous avez configuré. Les données sont partagées : plusieurs sessions, plusieurs agents ou applications externes peuvent accéder simultanément au même système de fichiers.

AgentCore gère automatiquement toutes les opérations de montage. Il n'est pas nécessaire d'installer des aides au montage, de gérer les certificats TLS ou d'écrire du code de montage dans votre agent.

Flux de montage des fichiers Amazon S3

Lorsque vous configurez un point d'accès S3 Files, la séquence suivante se produit :

Sémantique des fichiers S3

Flux de montage Amazon EFS

Lorsque vous configurez un point d'accès EFS, la séquence suivante se produit :

Sémantique de l'EFS

Stockage de session géré (version préliminaire)

Conservez l'état de session dans toute la configuration stop/resume d'un système de fichiers à l'aide du stockage de session géré. AgentCore Le stockage de session géré par Runtime est une fonctionnalité entièrement gérée par des services dans laquelle AgentCore Runtime gère toutes les opérations de stockage. Votre agent lit et écrit sur un support de système de fichiers local et l'environnement d'exécution réplique de manière transparente les données vers le stockage du service pendant toute la durée de la session.

Le stockage de session est isolé par session : chaque session ne peut accéder qu'à son propre stockage et ne peut ni lire ni écrire de données provenant d'autres sessions du même environnement d'exécution d'agent ou de sessions de différents environnements d'exécution d'agent.

Lorsque vous configurez le stockage de session sur un environnement d'exécution d'agent, chaque session obtient un répertoire persistant sur le chemin de montage que vous spécifiez. Le cycle de vie fonctionne comme suit :

Sémantique du système de fichiers

Le stockage de session fournit un système de fichiers Linux standard sur le chemin de montage que vous avez configuré. Les outils et les opérations standard fonctionnent sans modification : lscat,mkdir,git,npm,pip,, et cargo tous fonctionnent comme prévu.

Opérations prises en charge

Fichiers, répertoires et liens symboliques ordinaires. Lire, écrire, renommer, supprimer,, chmod chownstat, et readdir : opérations de fichiers POSIX standard utilisées par les outils de développement courants.

Restrictions

Pour les limites de stockage de session, y compris la taille maximale de stockage, le nombre de fichiers et la profondeur du répertoire, voir Limites de stockage de session.

Opérations non prises en charge

Les opérations de système de fichiers suivantes ne sont pas prises en charge :

Cycle de vie du stockage des sessions

Les données de session sont supprimées (réinitialisées à un état propre) dans les scénarios suivants :

Utilisez DeleteAgentRuntimeou DeleteAgentRuntimeEndpointpour supprimer toutes les données de stockage de session associées à l'environnement d'exécution ou au point de terminaison.

Conditions requises pour apporter vos propres systèmes de fichiers

Avant de configurer un système de fichiers personnalisé, remplissez les conditions préalables suivantes.

Configuration VPC

Le runtime de votre agent doit utilisernetworkMode: VPC. Les sous-réseaux que vous spécifiez doivent se chevaucher avec les zones de disponibilité cibles du système de fichiers.

Autorisations IAM

Le rôle d'exécution du runtime de votre agent doit inclure des autorisations pour monter le système de fichiers.

Autorisations IAM pour les fichiers 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>"
    }
  }
}

Autorisations IAM pour 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>"
    }
  }
}

Omettez cette option ClientWrite si votre agent n'a besoin que d'un accès en lecture. L's3files:GetAccessPointautorisation est requise pour la validation du point d'accès S3 Files lors de la création de l'exécution de l'agent.

Groupes de sécurité

Autorisez le TCP sortant sur le port 2049 depuis le groupe de sécurité d'exécution de votre agent vers le groupe de sécurité cible du montage. Autorisez le TCP entrant sur le port 2049 du groupe de sécurité cible du montage à partir du groupe de sécurité d'exécution de l'agent.

Configuration des systèmes de fichiers

Les sections suivantes montrent comment configurer chaque type de système de fichiers.

Configuration d'un point d'accès Amazon S3 Files

Pour configurer un point d'accès S3 Files, spécifiez l'ARN du point d'accès et le chemin de montagefilesystemConfigurations. Le runtime de votre agent doit utiliser le mode réseau VPC.

Configuration d'un point d'accès Amazon EFS

Pour configurer un point d'accès EFS, spécifiez l'ARN du point d'accès et le chemin de montagefilesystemConfigurations. Le runtime de votre agent doit utiliser le mode réseau VPC.

Configuration du stockage de session géré

Ajoutez filesystemConfigurations avec une sessionStorage entrée lors de la création ou de la mise à jour d'un environnement d'exécution d'agent.

Vous pouvez également ajouter un stockage de session à un environnement d'exécution d'agent existant à l'UpdateAgentRuntimeaide du même filesystemConfigurations paramètre.

Combinez les systèmes de fichiers

Vous pouvez combiner le stockage de sessions géré avec des systèmes de fichiers personnalisés sur un seul environnement d'exécution d'agent. L'exemple suivant configure les trois types.

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

Invoquer et utiliser le stockage persistant

Tous les systèmes de fichiers configurés sont disponibles sur leur chemin de montage lorsque votre agent est appelé. Bring-your-own les systèmes de fichiers (S3 Files, EFS) sont accessibles immédiatement à chaque appel. Le stockage de session géré conserve les données d'un stop/resume cycle à l'autre en les utilisantruntimeSessionId.

Exemple : utilisation du stockage de session sur plusieurs stop/resume cycles

# 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'agent voit /mnt/workspace exactement ce qu'il a laissé : les fichiers source, les packages installés, les artefacts de compilation et l'historique .git sont tous intacts. Lorsque vous reprenez une session, le nouvel environnement informatique monte le stockage persistant. Votre agent peut continuer à travailler sans réinstaller de packages ni régénérer de fichiers.

Restrictions

Le tableau suivant répertorie les limites des configurations de systèmes de fichiers.

Contraintes relatives au chemin de montage

Toutes les configurations de système de fichiers doivent respecter les règles de chemin de montage suivantes :

Comportement du cycle

Le tableau suivant compare le comportement du cycle de vie entre le stockage de session géré et les systèmes de fichiers « Bring-your-own ».

Cas d’utilisation

Le tableau suivant répertorie les modèles courants et la configuration de système de fichiers recommandée pour chacun d'entre eux.

Exemple : agent de codage avec espace de travail persistant

Cet exemple montre un agent de codage utilisant des agents Strands FileSessionManager pour l'historique des conversations et le stockage de sessions pour les fichiers de projet. Les deux persistent au fil stop/resume des cycles.

Agent de codage avec stockage de session

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

Appelez l'agent, arrêtez la session, puis reprenez-la. Les fichiers de projet et le contexte de conversation sont conservés.

Cycle d'appel, d'arrêt et de reprise

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)

Il FileSessionManager enregistre l'historique des conversations/mnt/workspace/.sessions/, ce qui permet à l'agent de se souvenir du contexte au fil stop/resume des cycles.

Exigences liées à la mise en réseau

Cette section couvre les exigences réseau pour le stockage de sessions géré et les systèmes de fichiers « Bring-your-own ».

Réseau de stockage de session géré

Si le runtime de votre agent utilise le mode VPC avec stockage de session, l'agent a besoin d'un accès réseau pour se synchroniser avec le stockage distant. Les données de session étant stockées dans AgentCore S3, votre VPC doit autoriser la connectivité sortante vers S3. Si vous utilisez un point de terminaison S3 Gateway doté d'une politique personnalisée, vous pouvez définir l'accès à votre bucket de stockage de session régional comme suit :

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

Remplacez region par votre AWS région (par exemple,us-west-2).

Bring-your-own mise en réseau de systèmes de fichiers

Bring-your-own les systèmes de fichiers nécessitent que votre réseau VPC réponde aux exigences suivantes pour des montages réussis.

Amazon EFS

Pour vérifier vos cibles de montage EFS :

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

Pour obtenir des informations complètes sur les cibles de montage EFS, consultez Comment fonctionne Amazon EFS.

Fichiers Amazon S3

Pour vérifier les cibles de montage de vos fichiers S3 :

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

Pour des informations complètes sur le montage de fichiers S3, voir Montage de systèmes de fichiers S3.

Besoins partagés

Comment AgentCore monte les systèmes de fichiers

AgentCore gère automatiquement l'opération de montage NFS à l'intérieur de la microVM :

Il n'est pas nécessaire d'installeramazon-efs-utils, de configurer /etc/fstab ou de gérer les certificats TLS. Le moteur d'exécution MicroVM gère toutes les opérations de montage, la rotation des identifiants et la surveillance de l'état de santé.

Sélection du sous-réseau et de la zone de disponibilité

Lorsque vous configurez à la fois des sous-réseaux VPC et des configurations de système de fichiers sur un environnement d'exécution d'agent, sélectionnez les sous-réseaux qui chevauchent les zones de disponibilité cibles de montage de votre système de fichiers.

Pour identifier l'ID de zone de disponibilité de vos sous-réseaux :

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

Pour identifier la zone de disponibilité de vos cibles de montage EFS :

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

Assurez-vous que les sous-réseaux d'exécution de votre agent se trouvent dans les zones de disponibilité où votre système de fichiers possède des cibles de montage.

Pour connaître les zones de disponibilité prises en charge par région, consultez les zones de disponibilité prises en charge dans la rubrique relative à la configuration du VPC. Pour la configuration du groupe de sécurité, consultez Exemple : connexion à Amazon EFS ou à Amazon S3 Files.

Résoudre les problèmes de montage du système de fichiers « Bring-your-own »

En cas d'échec du montage d'un système de fichiers « Bring-your-own », InvokeAgentRuntime renvoie HTTP 424 (Failed Dependency).

Chaque montage a un délai d'expiration de 30 secondes. Tous les systèmes de fichiers configurés sont montés en parallèle : une seule défaillance entraîne l'échec complet de l'invocation.

Pour plus d'informations, consultez la section Résolution des problèmes de stockage BYO.