Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

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 monte 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 :

Le type géré dépend du type de calcul de votre environnement d'exécution. Utilisez le stockage de session sur les environnements d'exécution des microVM et les volumes des fournisseurs de capacité sur les environnements d'exécution des instances. Sur les environnements d'exécution MicroVM, vous pouvez combiner le stockage de session avec des systèmes de fichiers que vous pouvez utiliser vous-même sur un seul environnement d'exécution d'agent (jusqu'à 5 configurations au total).

Les options de rangement en un coup d'œil

Le tableau suivant compare les types de configuration de systèmes 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)

Le stockage de session est disponible sur les environnements d'exécution de MicroVM.

Volume des fournisseurs de capacité

Les volumes des fournisseurs de capacité sont disponibles sur les environnements d'exécution des instances.

Pour la procédure pas à pas complète, voir Commencer à utiliser les instances à l'aide de l' AWS interface de ligne de commande.

Bring-your-own système de fichiers

Point d'accès Amazon S3 Files

Point d'accès Amazon EFS

Les fichiers S3 et EFS nécessitent une connectivité VPC lors de l'exécution 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 à utiliser vous-même, AgentCore Runtime monte le point d'accès spécifié dans chaque session au niveau du chemin que vous configurez. Les données sont partagées : plusieurs sessions, plusieurs agents ou des applications externes peuvent accéder simultanément au même système de fichiers.

AgentCore gère automatiquement toutes les opérations de montage. Vous n'avez pas besoin d'installer des assistants de montage, de gérer des 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 EFS

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

Conservez l'état de session dans stop/resume une configuration de système de fichiers à l'aide d'un stockage de session géré. AgentCore Le stockage de session géré par Runtime est une fonctionnalité entièrement gérée par les 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 les données de manière transparente 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 de l'agent ou de sessions de différents environnements d'exécution de l'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 des systèmes 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 opérations standard fonctionnent sans modification — lscat,mkdir,git,npm,pip, et fonctionnent cargo tous comme prévu.

Opérations prises en charge

Fichiers, répertoires et liens symboliques classiques. 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 de stockage maximale, le nombre de fichiers et la profondeur de 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 DeleteAgentRuntime ou DeleteAgentRuntimeEndpoint pour supprimer toutes les données de stockage de session associées à l'environnement d'exécution ou au point de terminaison.

Volumes des fournisseurs de capacité (instances)

Les volumes du fournisseur de capacité sont le type de stockage géré pour les environnements d'exécution qui utilisent le type de calcul Instances. Au lieu de spécifier le stockage sur l'environnement d'exécution, vous définissez des volumes Amazon EBS nommés sur le fournisseur de capacité, et le moteur d'exécution les monte par nom logique. AgentCore crée, attache et conserve les volumes pour vous. Vous ne provisionnez ni ne montez les volumes Amazon EBS vous-même.

À l'instar du stockage de session, les volumes des fournisseurs de capacité sont isolés par session et persistent pendant toute la durée de la session stop/resume. Comme une session sur les instances est une instance EC2 dédiée, le volume suit le cycle de vie de cette session :

Le volume est conservé pendant ces arrêts, y compris lorsqu'une session atteint sa durée de vie maximale. Elle est supprimée uniquement lorsque vous supprimez la session ou lorsque vous supprimez le fournisseur de capacité (qui supprime ses sessions et leurs volumes).

Pour plus d'informations sur la gestion des données de ces volumes, voir Gérer vos données sur les instances d'exécution.

Les agents peuvent partager un volume, mais le partage n'est pas automatique. Pour qu'un volume soit monté pour un environnement d'exécution d'agent, ce moteur d'exécution doit le configurer lui-même capacityProviderVolume (byvolumeName)filesystemConfigurations. Lorsque deux environnements d'exécution de ce type sont invoqués avec le même nomruntimeSessionId, ils s'exécutent sur la même instance et chacun monte le volume partagé afin de pouvoir collaborer sur les mêmes fichiers. La configuration permet de capacityProviderVolume contrôler les AgentCore volumes à monter pour un environnement d'exécution ; elle n'isole pas à elle seule les données entre les agents au cours d'une session. La limite d'isolation est la session. Pour le modèle d'isolation des sessions et des agents, voir Modèle de sécurité et autorisations pour les instances d'exécution.

Le stockage de session géré et les types Bring-Your-Own ne sont pas pris en charge sur les environnements d'exécution des instances. Ces types sont sessionStorages3FilesAccessPoint, etefsAccessPoint. La spécification de l'un d'entre eux à côté capacityProviderConfiguration échoue avec unValidationException. Pour savoir comment définir des volumes sur un fournisseur de capacité et les monter, consultez Commencer à utiliser les instances à l'aide de la AWS CLI et du stockage persistant entre les sessions.

Prérequis pour les systèmes de fichiers à emporter soi-même

Avant de configurer un système de fichiers que vous pouvez utiliser vous-même, remplissez les conditions préalables suivantes.

Configuration VPC

L'environnement d'exécution de votre agent doit utilisernetworkMode: VPC. Les sous-réseaux que vous spécifiez doivent chevaucher les zones de disponibilité cibles de montage du système de fichiers.

Autorisations IAM

Le rôle d'exécution de votre agent d'exécution 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 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 entre le groupe de sécurité d'exécution de votre agent et 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. L'environnement d'exécution 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. L'environnement d'exécution de votre agent doit utiliser le mode réseau VPC.

Configuration du stockage de session géré

Ajoutez une sessionStorage entrée lors filesystemConfigurations 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 UpdateAgentRuntime en utilisant le même filesystemConfigurations paramètre.

Configuration d'un volume de fournisseur de capacité

Pour monter un volume de fournisseur de capacité, définissez d'abord le volume sur le fournisseur de capacité. Référencez-le ensuite par son nom filesystemConfigurations lorsque vous créez l'environnement d'exécution de l'agent. Cela s'applique aux environnements d'exécution qui utilisent le type de calcul Instances.

volumeNameIl doit correspondre à un volume défini dans celui du fournisseur de capacitéec2Configuration.volumes. Pour connaître les étapes à suivre pour définir les volumes sur le fournisseur de capacité, consultez la section Commencer à utiliser les instances à l'aide de l' AWS interface de ligne de commande.

Combiner des systèmes de fichiers

Vous pouvez combiner un stockage de session géré avec des systèmes de fichiers que vous pouvez utiliser vous-même sur un seul environnement d'exécution de l'agent MicroVM. 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 dans leur chemin de montage lorsque votre agent est appelé. Bring-your-own les systèmes de fichiers (fichiers S3, EFS) sont accessibles immédiatement à chaque appel. Le stockage des sessions gérées permet de conserver les données d'un stop/resume cycle à l'autre en utilisant les mêmes donnéesruntimeSessionId.

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 comme il l'a laissé : les fichiers sources, les packages installés, les artefacts de construction et l'historique du fichier .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 les packages ni régénérer les fichiers.

Restrictions

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

Les limites de configuration totale, de fichiers S3, d'EFS et de stockage de session s'appliquent aux environnements d'exécution MicroVM. La limite de volume du fournisseur de capacité est définie sur le fournisseur de capacité (ec2Configuration.volumes) plutôt que par exécution.

Contraintes relatives au chemin de montage

Toutes les configurations de systèmes 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 les types de systèmes de fichiers gérés et ceux que vous pouvez utiliser vous-même.

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 Strands Agents FileSessionManager pour l'historique des conversations et le stockage des sessions pour les fichiers de projet. Les deux persistent d'un stop/resume cycle à l'autre.

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(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

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

Invoquer, arrêter et reprendre le cycle

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 stocke l'historique des conversations/mnt/workspace/.sessions/, ce qui permet à l'agent de se souvenir du contexte à travers les stop/resume cycles.

Exigences liées à la mise en réseau

Cette section couvre les exigences réseau à la fois pour le stockage de session géré et pour les systèmes de fichiers à emporter vous-même.

Réseau de stockage de session géré

Si l'environnement d'exécution 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 sont stockées dans AgentCore S3. Votre VPC doit donc autoriser la connectivité sortante à S3. Si vous utilisez un point de terminaison S3 Gateway avec une politique personnalisée, vous pouvez définir l'accès à votre compartiment 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 des 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 que les montages soient 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, consultez la section Montage de systèmes de fichiers S3.

Des exigences partagées

Comment AgentCore monte les systèmes de fichiers

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

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

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 des groupes de sécurité, voir Exemple : connexion à Amazon EFS ou à Amazon S3 Files.

Résoudre les problèmes de montage des systèmes de fichiers à utiliser soi-même

En cas d'échec du montage d'un système de fichiers à utiliser soi-même, InvokeAgentRuntime renvoie le protocole HTTP 424 (Failed Dependency).

Chaque montage a un délai d'attente 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 de l'invocation complète.

Pour plus d'informations, voir Résoudre les problèmes liés au stockage BYO.