View a markdown version of this page

Configuraciones del sistema de archivos para AgentCore Code Interpreter - Base amazónica AgentCore
Las opciones de almacenamiento de un vistazoInicio rápidoFuncionamientoRequisitos previosConfigure los sistemas de archivosLímitesSolucione problemas de montaje en sistemas de archivos

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Configuraciones del sistema de archivos para AgentCore Code Interpreter

AgentCore Code Interpreter permite montar sus propios sistemas de archivos en sesiones de intérprete de código mediante el filesystemConfigurations parámetro. Cada configuración monta un punto de acceso de Amazon S3 Files o Amazon EFS en la ruta que especifique. No necesita un código de montaje personalizado, contenedores privilegiados ni una orquestación de descargas: AgentCore realiza todas las operaciones de montaje dentro del entorno limitado de la sesión.

Bring-your-own los sistemas de archivos son almacenamiento compartido: varias sesiones, varios intérpretes de código o aplicaciones externas pueden acceder al mismo punto de acceso simultáneamente. Los datos se conservan y se administran en su propia cuenta. AWS

Puedes proporcionarlos filesystemConfigurations cuando creas un intérprete de código con CreateCodeInterpreter (cada sesión iniciada desde ese intérprete de código hereda los montajes) o cuando inicias una sesión con StartCodeInterpreterSession (los montajes se aplican a esa sesión). El parámetro y la forma son idénticos en ambos lugares.

nota

A diferencia AgentCore de Runtime, AgentCore Code Interpreter no ofrece una opción de almacenamiento de sesiones administrado. Code Interpreter solo admite puntos de acceso para traer sus propios archivos de Amazon S3 y Amazon EFS.

Las opciones de almacenamiento de un vistazo

En la tabla siguiente se comparan los tipos de sistemas de archivos disponibles.

Tipo Aislamiento Persistencia Se requiere una VPC Lo mejor para

Amazon S3 Files

Compartido: varias sesiones e intérpretes de código acceden a los mismos datos

Customer-managed (permanente, se sincroniza con el bucket S3 de respaldo)

Sí

Conjuntos de datos y artefactos accesibles mediante operaciones de archivos estándar y mediante las API de S3

Amazon EFS

Compartido: varias sesiones e intérpretes de código acceden a los mismos datos

Customer-managed (permanente hasta que lo elimines)

Sí

Datos de referencia compartidos, descargas y colaboración de lectura y escritura entre sesiones

Inicio rápido

Las siguientes listas de comprobación proporcionan pasos resumidos para configurar cada tipo de sistema de archivos.

Punto de acceso a Amazon S3 Files

  1. s3files:ClientMountAñada s3files:ClientWrite y s3files:GetAccessPoint a su función de ejecución de intérprete de código con una s3files:AccessPointArn condición.

  2. Permita que el puerto TCP 2049 salga del grupo de seguridad del intérprete de código al grupo de seguridad de destino del montaje de archivos S3.

  3. Confirme que el destino de montaje de los archivos S3 esté en la misma VPC y zona de disponibilidad que las subredes de su intérprete de código.

  4. filesystemConfigurationsAñádalo con una s3FilesConfiguration entrada a su CreateCodeInterpreter o StartCodeInterpreterSession llame.

  5. Inicie una sesión. Los archivos de la ruta de montaje (por ejemplo/mnt/s3data) se sincronizan bidireccionalmente con el bucket S3 correspondiente.

Punto de acceso Amazon EFS

  1. Añada elasticfilesystem:ClientMount y elasticfilesystem:ClientWrite a su rol de ejecución de intérprete de código con una elasticfilesystem:AccessPointArn condición.

  2. Permita que el puerto TCP 2049 salga del grupo de seguridad del intérprete de código al grupo de seguridad de destino de montaje EFS.

  3. Confirme que el destino de montaje de EFS esté en la misma zona de disponibilidad que al menos una de las subredes de su intérprete de código.

  4. filesystemConfigurationsAñádalo con una efsConfiguration entrada a su CreateCodeInterpreter o StartCodeInterpreterSession llame.

  5. Inicie una sesión. Los archivos están disponibles en la ruta de montaje (por ejemplo,/mnt/efs).

Tanto los archivos S3 como EFS requieren conectividad de VPC en el intérprete de código.

Funcionamiento

Al configurar un sistema de archivos personalizado, AgentCore Code Interpreter monta el punto de acceso especificado en el entorno limitado de la sesión, en la ruta que configure. Los datos se comparten: varias sesiones, varios intérpretes de código o aplicaciones externas pueden acceder al mismo sistema de archivos de forma simultánea.

AgentCore gestiona todas las operaciones de montaje automáticamente. No es necesario instalar los ayudantes de montaje, gestionar los certificados TLS ni escribir código de montaje.

nota

Cuando creas un punto de acceso (archivos S3 o EFS), especificas un ID de usuario POSIX (UID) y un ID de grupo (GID). Todas las operaciones de archivos a través del punto de acceso se ejecutan con esta identidad.

Flujo de montaje de archivos de Amazon S3

  1. Usted crea un sistema de archivos de S3 Files (respaldado por un bucket de S3) y monta los destinos en su VPC.

  2. Creas un punto de acceso a S3 Files especificando el POSIX UID/GID y el directorio raíz.

  3. Configura el intérprete de código (o sesión) con el ARN del punto de acceso, el ARN del sistema de archivos y la ruta de montaje.

  4. Al iniciar la sesión, AgentCore aprovisione un entorno aislado con acceso de red a su VPC.

  5. El entorno limitado monta el sistema de archivos mediante TLS con autenticación de IAM (puerto 2049) a NFSv4.2 través de su VPC.

  6. Su agente lee y escribe archivos en la ruta de montaje. Los cambios se sincronizan automáticamente con el bucket S3 correspondiente.

Flujo de montaje de Amazon EFS

  1. Cree un sistema de archivos EFS y monte los destinos en su VPC (uno por zona de disponibilidad).

  2. Crea un punto de acceso EFS especificando el POSIX UID/GID y el directorio raíz.

  3. El intérprete de código (o sesión) se configura con el ARN del punto de acceso, el ARN del sistema de archivos y la ruta de montaje.

  4. Al iniciar la sesión, AgentCore aprovisione un entorno aislado con acceso de red a su VPC.

  5. El entorno limitado monta el sistema de archivos mediante NFSv4.1 TLS (puerto 2049) mediante el destino de montaje en la misma zona de disponibilidad.

  6. Su agente lee y escribe archivos en la ruta de montaje mediante operaciones de archivos estándar.

Requisitos previos

Antes de configurar un sistema de archivos personalizado, complete los siguientes requisitos previos.

Configuración de la VPC

El intérprete de código debe utilizar el modo de red. VPC Las subredes que especifique deben superponerse con las zonas de disponibilidad de destino del sistema de archivos.

Permisos de IAM

Su función de ejecución como intérprete de código debe incluir permisos para montar el sistema de archivos.

Permisos de IAM para los archivos 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>"
    }
  }
}

Permisos de IAM para 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>"
    }
  }
}

Omita ClientWrite si su agente solo necesita acceso de lectura.

Grupos de seguridad

Permita el TCP saliente en el puerto 2049 desde el grupo de seguridad de su intérprete de código al grupo de seguridad de destino del montaje. Permita el TCP entrante en el puerto 2049 del grupo de seguridad de destino de montaje desde el grupo de seguridad del intérprete de código.

Configure los sistemas de archivos

Especifique cada sistema de archivos filesystemConfigurations como un s3FilesConfiguration o unefsConfiguration. Ambos requieren tres campos:

  • accessPointArn— El ARN de los archivos S3 o del punto de acceso EFS que se va a montar.

  • fileSystemArn— El ARN del sistema de archivos que posee el punto de acceso. Este campo es obligatorio.

  • mountPath— La ruta absoluta dentro de la sesión en la que está montado el punto de acceso (por ejemplo,/mnt/s3data).

Puede suministrarla filesystemConfigurations en dos lugares con la misma forma:

  • Plano de control CreateCodeInterpreter — — Cada sesión iniciada desde el intérprete de código hereda los montajes. El intérprete de código debe usar el modo de red VPC.

  • Plano de datos: StartCodeInterpreterSession — Los montajes se aplican a esa sesión específica.

nota

Puede proporcionar las configuraciones del sistema de archivos en el plano de control (CreateCodeInterpreter), el plano de datos (StartCodeInterpreterSession) o ambos, siempre que el intérprete de código utilice el modo de red VPC y el punto de acceso EFS o los archivos S3 estén configurados correctamente (objetivos de montaje, permisos de IAM y grupos de seguridad). Las configuraciones de CreateCodeInterpreter se heredan en cada sesión; las configuraciones de StartCodeInterpreterSession se aplican a esa sesión. Cuando se suministran ambas, se combinan para la sesión y cada ruta de montaje debe ser única en el conjunto combinado.

En las siguientes secciones se muestran ambas llamadas a la API para cada tipo de sistema de archivos.

Configure un punto de acceso a Amazon S3 Files

Plano de control: CreateCodeInterpreter

ejemplo
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. Ejemplo de Python en el que se usa boto3 para crear un intérprete de código con un punto de acceso a 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"
            }
        }
    ]
)

Plano de datos: StartCodeInterpreterSession

ejemplo
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. Ejemplo de Python en el que se usa boto3 para iniciar una sesión de intérprete de código con un punto de acceso a 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"]

Configure un punto de acceso de Amazon EFS

Plano de control: CreateCodeInterpreter

ejemplo
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. Ejemplo de Python en el que se utiliza boto3 para crear un intérprete de código con un punto de acceso 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"
            }
        }
    ]
)

Plano de datos: StartCodeInterpreterSession

ejemplo
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. Ejemplo de Python en el que se utiliza boto3 para iniciar una sesión de intérprete de código con un punto de acceso 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"]

Combine sistemas de archivos

Puedes conectar varios puntos de acceso (hasta los límites que se indican a continuación) en una sola llamada añadiendo más entradas afilesystemConfigurations. Cada entrada debe utilizar una ruta de montaje única.

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

Confirme los sistemas de archivos montados

GetCodeInterpreterUtilícelo para confirmarlo filesystemConfigurations en un intérprete de código y GetCodeInterpreterSession para confirmar las configuraciones efectivas en una sesión en ejecución. Las configuraciones establecidas al crear el intérprete de código y al iniciar la sesión aparecen en la respuesta de la sesión.

Límites

Los límites de configuración del sistema de archivos se aplican por solicitud. CreateCodeInterpreterLas configuraciones se heredan en cada sesión y StartCodeInterpreterSession las configuraciones se aplican a esa sesión. Los montajes efectivos de una sesión son la combinación de ambos.

Tipo de configuración Por CreateCodeInterpreter Por StartCodeInterpreterSession Combinado por sesión

Puntos de acceso a Amazon S3 Files

2

2

4

Puntos de acceso de Amazon EFS

2

2

4

Total de configuraciones del sistema de archivos

4

4

8

Por ejemplo, puede configurar 1 punto de acceso a los archivos S3 y 1 punto de acceso EFS y, a continuaciónCreateCodeInterpreter, agregar 1 punto de acceso a los archivos S3 y 1 punto de acceso EFSStartCodeInterpreterSession, para un total de 4 montajes en la sesión. Cada ruta de montaje debe ser única en el conjunto combinado.

Restricciones de ruta de montaje

Todas las configuraciones del sistema de archivos deben seguir estas reglas de ruta de montaje:

  • Debe estar debajo /mnt/ de exactamente un nivel de subdirectorio (por ejemplo,/mnt/data,/mnt/s3data).

  • Patrón: /mnt/[a-zA-Z0-9._-]+/?

  • Cada ruta de montaje debe ser única en todas las configuraciones.

  • Las rutas de montaje no pueden ser subdirectorios entre sí.

Solucione problemas de montaje en sistemas de archivos

Cuando se produce un error en el montaje de un sistema de archivos basado en la opción «traiga su propio sistema de archivos», se produce un StartCodeInterpreterSession error y la sesión deja de funcionar. READY

Síntoma Causa probable Solución rápida

«Acceso denegado»

Falta el rol de ejecución ClientMount o ClientWrite

Agregue los permisos de IAM con la condición AccessPointArn

«ResourceNotFound» o «No se pudo resolver»

El punto de acceso o el objetivo de montaje se eliminaron o no están disponibles

Compruebe que el ARN existe y que los objetivos de montaje están disponibles

El montaje se bloquea y luego falla

El grupo de seguridad bloquea el puerto 2049 o no hay ningún objetivo de montaje en la zona de disponibilidad de la sesión

Permita el TCP 2049; verifique la superposición de las zonas de disponibilidad

«Permiso denegado» al escribir

Falta ClientWrite o el POSIX UID/GID no coincide

Agregue el permiso de escritura o alinee el usuario POSIX del punto de acceso

Todos los sistemas de archivos configurados se montan en paralelo al inicio de la sesión; un solo error de montaje provoca un error en el inicio de la sesión.