View a markdown version of this page

Configurations du système de fichiers pour l'interpréteur AgentCore de code - Base rocheuse de l'Amazonie AgentCore
Les options de rangement en un coup d'œilDémarrage rapideComment ça marcheConditions préalablesConfiguration des systèmes de fichiersRestrictionsRésoudre les problèmes de montage du système de fichiers

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 l'interpréteur AgentCore de code

AgentCore Code Interpreter prend en charge le montage de vos propres systèmes de fichiers dans des sessions d'interpréteur de code via le filesystemConfigurations paramètre. Chaque configuration monte un point d'accès Amazon S3 Files ou Amazon EFS 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 : toutes les opérations de AgentCore montage sont effectuées dans le sandbox de session.

Bring-your-own les systèmes de fichiers sont des espaces de stockage partagés : plusieurs sessions, plusieurs interpréteurs de code ou des applications externes peuvent accéder simultanément au même point d'accès. Les données sont conservées et gérées dans votre propre AWS compte.

Vous pouvez indiquer filesystemConfigurations quand vous créez un interpréteur de code avec CreateCodeInterpreter (chaque session démarrée à partir de cet interpréteur de code hérite des montages), ou lorsque vous démarrez une session avec StartCodeInterpreterSession (les montages s'appliquent à cette session). Le paramètre et la forme sont identiques aux deux endroits.

Note

Contrairement à AgentCore Runtime, AgentCore Code Interpreter ne propose pas d'option de stockage de session géré. Code Interpreter prend uniquement en charge les fichiers Amazon S3 à emporter et les points d'accès Amazon EFS.

Les options de rangement en un coup d'œil

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

Type Isolation Persistance VPC requis Idéal pour

Fichiers Amazon S3

Partagé : plusieurs sessions et interpréteurs de code accèdent aux mêmes données

Customer-managed (permanent, se synchronise avec le compartiment S3 de sauvegarde)

Oui

Ensembles de données et artefacts accessibles via des opérations de fichiers standard et des API S3

Amazon EFS

Partagé : plusieurs sessions et interpréteurs de code accèdent aux mêmes données

Customer-managed (permanent jusqu'à ce que vous le supprimiez)

Oui

Données de référence partagées, téléchargements, collaboration en lecture-écriture entre les sessions

Démarrage rapide

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

Point d'accès Amazon S3 Files

  1. Ajoutez s3files:ClientMounts3files:ClientWrite, et s3files:GetAccessPoint à votre rôle d'exécution d'interpréteur de code avec une s3files:AccessPointArn condition.

  2. Autorisez le port TCP 2049 sortant du groupe de sécurité de votre interpréteur de code vers votre groupe de sécurité cible de montage S3 Files.

  3. Vérifiez que la cible de montage de S3 Files se trouve dans le même VPC et la même zone de disponibilité que les sous-réseaux de votre interpréteur de code.

  4. Ajoutez filesystemConfigurations une s3FilesConfiguration entrée à votre StartCodeInterpreterSession appel CreateCodeInterpreter ou à votre appel.

  5. Démarrez une session. Les fichiers de votre chemin de montage (par exemple/mnt/s3data) sont synchronisés de manière bidirectionnelle avec le compartiment S3 de sauvegarde.

Point d'accès Amazon EFS

  1. Ajoutez elasticfilesystem:ClientMount et elasticfilesystem:ClientWrite à votre rôle d'exécution d'interpréteur de code avec une elasticfilesystem:AccessPointArn condition.

  2. Autorisez le port TCP 2049 sortant du groupe de sécurité de votre interpréteur de code vers votre groupe de sécurité cible de montage EFS.

  3. Vérifiez que la cible de montage EFS se trouve dans la même zone de disponibilité qu'au moins l'un de vos sous-réseaux d'interpréteur de code.

  4. Ajoutez filesystemConfigurations une efsConfiguration entrée à votre StartCodeInterpreterSession appel CreateCodeInterpreter ou à votre appel.

  5. Démarrez une session. Vos fichiers sont disponibles sur votre chemin de montage (par exemple,/mnt/efs).

Les fichiers S3 et EFS nécessitent une connectivité VPC sur l'interpréteur de code.

Comment ça marche

Lorsque vous configurez un système de fichiers à utiliser vous-même, AgentCore Code Interpreter monte le point d'accès spécifié dans le sandbox de session au chemin que vous avez configuré. Les données sont partagées : plusieurs sessions, plusieurs interpréteurs de code 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.

Note

Lorsque vous créez un point d'accès (fichiers S3 ou EFS), vous spécifiez un ID utilisateur POSIX (UID) et un ID de groupe (GID). Toutes les opérations sur les fichiers via le point d'accès s'exécutent sous cette identité.

Flux de montage des fichiers Amazon S3

  1. Vous créez un système de fichiers S3 Files (soutenu par un compartiment S3) et vous montez des cibles dans votre VPC.

  2. Vous créez un point d'accès S3 Files en spécifiant le répertoire POSIX UID/GID et le répertoire racine.

  3. Vous configurez l'interpréteur de code (ou session) avec l'ARN du point d'accès, l'ARN du système de fichiers et le chemin de montage.

  4. Au démarrage de la session, AgentCore configurez un bac à sable avec accès réseau à votre VPC.

  5. Le sandbox monte le système de fichiers NFSv4.2 via TLS avec authentification IAM (port 2049) via votre VPC.

  6. Votre agent lit et écrit des fichiers sur le chemin de montage. Les modifications sont automatiquement synchronisées avec le compartiment S3 de sauvegarde.

Flux de montage Amazon EFS

  1. Vous créez un système de fichiers EFS et montez des cibles dans votre VPC (une par zone de disponibilité).

  2. Vous créez un point d'accès EFS en spécifiant le répertoire POSIX UID/GID et le répertoire racine.

  3. Vous configurez l'interpréteur de code (ou session) avec l'ARN du point d'accès, l'ARN du système de fichiers et le chemin de montage.

  4. Au démarrage de la session, AgentCore configurez un bac à sable avec accès réseau à votre VPC.

  5. Le sandbox monte le système de fichiers NFSv4.1 via TLS (port 2049) via la cible de montage située dans la même zone de disponibilité.

  6. Votre agent lit et écrit les fichiers sur le chemin de montage à l'aide d'opérations de fichiers standard.

Conditions préalables

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

Configuration VPC

Votre interpréteur de code doit utiliser VPC le mode réseau. Les sous-réseaux que vous spécifiez doivent chevaucher les zones de disponibilité cibles de montage du système de fichiers.

Autorisations IAM

Votre rôle d'exécution d'interpréteur de code 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.

Groupes de sécurité

Autorisez le TCP sortant sur le port 2049 entre le groupe de sécurité de votre interpréteur de code 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é de l'interpréteur de code.

Configuration des systèmes de fichiers

Spécifiez chaque système de fichiers filesystemConfigurations comme étant un s3FilesConfiguration ou unefsConfiguration. Les deux nécessitent trois champs :

  • accessPointArn— L'ARN des fichiers S3 ou du point d'accès EFS à monter.

  • fileSystemArn— L'ARN du système de fichiers propriétaire du point d'accès. Ce champ est obligatoire.

  • mountPath— Le chemin absolu au sein de la session sur laquelle le point d'accès est monté (par exemple,/mnt/s3data).

Vous pouvez fournir filesystemConfigurations à deux endroits, en utilisant la même forme :

  • Plan de contrôle — CreateCodeInterpreter — Les montages sont hérités par chaque session démarrée depuis l'interpréteur de code. L'interpréteur de code doit utiliser le mode réseau VPC.

  • Plan de données — StartCodeInterpreterSession — Les montages s'appliquent à cette session spécifique.

Note

Vous pouvez fournir des configurations de système de fichiers sur le plan de contrôle (CreateCodeInterpreter), le plan de données (StartCodeInterpreterSession), ou les deux, à condition que l'interpréteur de code utilise le mode réseau VPC et que le point d'accès S3 Files ou EFS soit correctement configuré (cibles de montage, autorisations IAM et groupes de sécurité). Les configurations de CreateCodeInterpreter sont héritées par chaque session ; les configurations de StartCodeInterpreterSession s'appliquent à cette session. Lorsque les deux sont fournis, ils sont combinés pour la session et chaque chemin de montage doit être unique dans l'ensemble combiné.

Les sections suivantes présentent les deux appels d'API pour chaque type de système de fichiers.

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

Plan de commande : CreateCodeInterpreter

Exemple
AWS CLI

  1. aws bedrock-agentcore-control create-code-interpreter \
  --name "data-code-interpreter" \
  --execution-role-arn "arn:aws:iam::<account-id>:role/CodeInterpreterExecutionRole" \
  --network-configuration '{
    "networkMode": "VPC",
    "vpcConfig": {
      "subnets": ["<subnet-id-1>", "<subnet-id-2>"],
      "securityGroups": ["<security-group-id>"]
    }
  }' \
  --filesystem-configurations '[{
    "s3FilesConfiguration": {
      "accessPointArn": "arn:aws:s3files:<region>:<account-id>:file-system/<file-system-id>/access-point/<access-point-id>",
      "fileSystemArn": "arn:aws:s3files:<region>:<account-id>:file-system/<file-system-id>",
      "mountPath": "/mnt/s3data"
    }
  }]'
AWS SDK

  1. Exemple Python utilisant boto3 pour créer un interpréteur de code avec un point d'accès S3 Files.

    import boto3

cp = boto3.client("bedrock-agentcore-control", region_name="us-west-2")

response = cp.create_code_interpreter(
    name="data-code-interpreter",
    executionRoleArn="arn:aws:iam::<account-id>:role/CodeInterpreterExecutionRole",
    networkConfiguration={
        "networkMode": "VPC",
        "vpcConfig": {
            "subnets": ["<subnet-id-1>", "<subnet-id-2>"],
            "securityGroups": ["<security-group-id>"]
        }
    },
    filesystemConfigurations=[
        {
            "s3FilesConfiguration": {
                "accessPointArn": "arn:aws:s3files:<region>:<account-id>:file-system/<file-system-id>/access-point/<access-point-id>",
                "fileSystemArn": "arn:aws:s3files:<region>:<account-id>:file-system/<file-system-id>",
                "mountPath": "/mnt/s3data"
            }
        }
    ]
)

Plan de données : StartCodeInterpreterSession

Exemple
AWS CLI

  1. aws bedrock-agentcore start-code-interpreter-session \
  --code-interpreter-identifier "<code-interpreter-id>" \
  --name "byos-session" \
  --session-timeout-seconds 3600 \
  --filesystem-configurations '[{
    "s3FilesConfiguration": {
      "accessPointArn": "arn:aws:s3files:<region>:<account-id>:file-system/<file-system-id>/access-point/<access-point-id>",
      "fileSystemArn": "arn:aws:s3files:<region>:<account-id>:file-system/<file-system-id>",
      "mountPath": "/mnt/s3data"
    }
  }]'
AWS SDK

  1. Exemple Python utilisant boto3 pour démarrer une session d'interpréteur de code avec un point d'accès S3 Files.

    import boto3

dp = boto3.client("bedrock-agentcore", region_name="us-west-2")

response = dp.start_code_interpreter_session(
    codeInterpreterIdentifier="<code-interpreter-id>",
    name="byos-session",
    sessionTimeoutSeconds=3600,
    filesystemConfigurations=[
        {
            "s3FilesConfiguration": {
                "accessPointArn": "arn:aws:s3files:<region>:<account-id>:file-system/<file-system-id>/access-point/<access-point-id>",
                "fileSystemArn": "arn:aws:s3files:<region>:<account-id>:file-system/<file-system-id>",
                "mountPath": "/mnt/s3data"
            }
        }
    ]
)

session_id = response["sessionId"]

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

Plan de commande : CreateCodeInterpreter

Exemple
AWS CLI

  1. aws bedrock-agentcore-control create-code-interpreter \
  --name "shared-tools-code-interpreter" \
  --execution-role-arn "arn:aws:iam::<account-id>:role/CodeInterpreterExecutionRole" \
  --network-configuration '{
    "networkMode": "VPC",
    "vpcConfig": {
      "subnets": ["<subnet-id-1>", "<subnet-id-2>"],
      "securityGroups": ["<security-group-id>"]
    }
  }' \
  --filesystem-configurations '[{
    "efsConfiguration": {
      "accessPointArn": "arn:aws:elasticfilesystem:<region>:<account-id>:access-point/<access-point-id>",
      "fileSystemArn": "arn:aws:elasticfilesystem:<region>:<account-id>:file-system/<file-system-id>",
      "mountPath": "/mnt/efs"
    }
  }]'
AWS SDK

  1. Exemple Python utilisant boto3 pour créer un interpréteur de code avec un point d'accès EFS.

    import boto3

cp = boto3.client("bedrock-agentcore-control", region_name="us-west-2")

response = cp.create_code_interpreter(
    name="shared-tools-code-interpreter",
    executionRoleArn="arn:aws:iam::<account-id>:role/CodeInterpreterExecutionRole",
    networkConfiguration={
        "networkMode": "VPC",
        "vpcConfig": {
            "subnets": ["<subnet-id-1>", "<subnet-id-2>"],
            "securityGroups": ["<security-group-id>"]
        }
    },
    filesystemConfigurations=[
        {
            "efsConfiguration": {
                "accessPointArn": "arn:aws:elasticfilesystem:<region>:<account-id>:access-point/<access-point-id>",
                "fileSystemArn": "arn:aws:elasticfilesystem:<region>:<account-id>:file-system/<file-system-id>",
                "mountPath": "/mnt/efs"
            }
        }
    ]
)

Plan de données : StartCodeInterpreterSession

Exemple
AWS CLI

  1. aws bedrock-agentcore start-code-interpreter-session \
  --code-interpreter-identifier "<code-interpreter-id>" \
  --name "byos-session" \
  --session-timeout-seconds 3600 \
  --filesystem-configurations '[{
    "efsConfiguration": {
      "accessPointArn": "arn:aws:elasticfilesystem:<region>:<account-id>:access-point/<access-point-id>",
      "fileSystemArn": "arn:aws:elasticfilesystem:<region>:<account-id>:file-system/<file-system-id>",
      "mountPath": "/mnt/efs"
    }
  }]'
AWS SDK

  1. Exemple Python utilisant boto3 pour démarrer une session d'interpréteur de code avec un point d'accès EFS.

    import boto3

dp = boto3.client("bedrock-agentcore", region_name="us-west-2")

response = dp.start_code_interpreter_session(
    codeInterpreterIdentifier="<code-interpreter-id>",
    name="byos-session",
    sessionTimeoutSeconds=3600,
    filesystemConfigurations=[
        {
            "efsConfiguration": {
                "accessPointArn": "arn:aws:elasticfilesystem:<region>:<account-id>:access-point/<access-point-id>",
                "fileSystemArn": "arn:aws:elasticfilesystem:<region>:<account-id>:file-system/<file-system-id>",
                "mountPath": "/mnt/efs"
            }
        }
    ]
)

session_id = response["sessionId"]

Combiner des systèmes de fichiers

Vous pouvez associer plusieurs points d'accès (dans les limites indiquées ci-dessous) en un seul appel en y ajoutant d'autres entréesfilesystemConfigurations. Chaque entrée doit utiliser un chemin de montage unique.

filesystemConfigurations=[
    {
        "s3FilesConfiguration": {
            "accessPointArn": "arn:aws:s3files:<region>:<account-id>:file-system/<file-system-id>/access-point/<access-point-id>",
            "fileSystemArn": "arn:aws:s3files:<region>:<account-id>:file-system/<file-system-id>",
            "mountPath": "/mnt/s3data"
        }
    },
    {
        "efsConfiguration": {
            "accessPointArn": "arn:aws:elasticfilesystem:<region>:<account-id>:access-point/<access-point-id>",
            "fileSystemArn": "arn:aws:elasticfilesystem:<region>:<account-id>:file-system/<file-system-id>",
            "mountPath": "/mnt/efs"
        }
    }
]

Confirmez les systèmes de fichiers montés

GetCodeInterpreterUtilisez-le pour confirmer l'filesystemConfigurationsexistence d'un interpréteur de code et GetCodeInterpreterSession pour confirmer les configurations efficaces sur une session en cours d'exécution. Les configurations définies lors de la création de l'interpréteur de code et au démarrage de la session apparaissent toutes deux dans la réponse de session.

Restrictions

Les limites de configuration du système de fichiers sont appliquées par demande. CreateCodeInterpreterles configurations sont héritées par chaque session, et les StartCodeInterpreterSession configurations s'appliquent à cette session. Les supports efficaces d'une session sont la combinaison des deux.

Type de configuration Par CreateCodeInterpreter Par StartCodeInterpreterSession Combiné par session

Points d'accès à Amazon S3 Files

2

2

4

Points d'accès Amazon EFS

2

2

4

Configurations totales du système de fichiers

4

4

8

Par exemple, vous pouvez configurer 1 point d'accès S3 Files et 1 point d'accès EFS activéCreateCodeInterpreter, puis ajouter 1 point d'accès S3 Files et 1 point d'accès EFS activéStartCodeInterpreterSession, pour un total de 4 montages au cours de la session. Chaque chemin de montage doit être unique dans l'ensemble combiné.

Contraintes relatives au chemin de montage

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

  • Doit être inférieur /mnt/ à exactement un niveau de sous-répertoire (par exemple/mnt/data,/mnt/s3data).

  • Modèle : /mnt/[a-zA-Z0-9._-]+/?

  • Chaque chemin de montage doit être unique dans toutes les configurations.

  • Les chemins de montage ne peuvent pas être des sous-répertoires les uns des autres.

Résoudre les problèmes de montage du système de fichiers

Lorsqu'un montage de système de fichiers avec votre propre système de fichiers échoue, StartCodeInterpreterSession renvoie une erreur et la session ne le devient pas. READY

Symptôme Cause probable Solution rapide

« Accès refusé »

Rôle d'exécution manquant ClientMount ou ClientWrite

Ajoutez des autorisations IAM avec la condition AccessPointArn

« ResourceNotFound » ou « Impossible de résoudre »

Point d'accès ou cible de montage supprimé ou indisponible

Vérifiez que l'ARN existe et que les cibles de montage sont disponibles

Le montage se bloque puis échoue

Groupe de sécurité bloquant le port 2049, ou aucune cible de montage dans la zone de disponibilité de la session

Autoriser le protocole TCP 2049 ; vérifier le chevauchement des zones de disponibilité

« Autorisation refusée » sur les écrits

Manquant ClientWrite ou non-concordance POSIX UID/GID

Ajoutez une autorisation d'écriture ou alignez l'utilisateur POSIX du point d'accès

Tous les systèmes de fichiers configurés sont montés en parallèle au démarrage de la session. Un seul échec de montage entraîne l'échec du démarrage de la session.