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 Runtime

AgentCore Runtime admite sistemas de archivos persistentes mediante el filesystemConfigurations parámetro. Cada configuración monta el almacenamiento en la ruta que usted especifique. No necesita un código de montaje personalizado, contenedores privilegiados ni una orquestación de descargas.

AgentCore Runtime admite dos categorías de configuraciones de sistemas de archivos:

El tipo administrado depende del tipo de procesamiento del tiempo de ejecución. Usa el almacenamiento de sesión en los tiempos de ejecución de microVM y los volúmenes del proveedor de capacidad en los tiempos de ejecución de las instancias. En los tiempos de ejecución de microVM, puede combinar el almacenamiento de sesiones con sus propios sistemas de archivos en un único tiempo de ejecución de agente (hasta 5 configuraciones en total).

Las opciones de almacenamiento de un vistazo

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

Inicio rápido

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

Almacenamiento de sesiones administrado (versión preliminar)

El almacenamiento de sesiones está disponible en tiempos de ejecución de microVM.

Volumen de proveedores de capacidad

Los volúmenes de los proveedores de capacidad están disponibles en los tiempos de ejecución de las instancias.

Para ver el tutorial completo, consulte Introducción a las instancias mediante la AWS CLI.

Bring-your-own sistema de archivos

Punto de acceso a Amazon S3 Files

Punto de acceso Amazon EFS

Tanto S3 Files como EFS requieren conectividad de VPC en el tiempo de ejecución del agente.

Cómo funciona cada tipo

En las siguientes secciones se describe cómo funciona cada tipo de sistema de archivos en AgentCore Runtime.

Bring-your-own sistemas de archivos

Al configurar un sistema de archivos personalizado, AgentCore Runtime monta el punto de acceso especificado en cada sesión en la ruta que configure. Los datos se comparten: varias sesiones, varios agentes o aplicaciones externas pueden acceder al mismo sistema de archivos de forma simultánea.

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

Flujo de montaje de archivos de Amazon S3

Al configurar un punto de acceso a S3 Files, se produce la siguiente secuencia:

Semántica de los archivos S3

Flujo de montaje de Amazon EFS

Al configurar un punto de acceso EFS, se produce la siguiente secuencia:

Semántica de EFS

Almacenamiento de sesiones administrado (vista previa)

Persiste el estado de la sesión en stop/resume una configuración de sistema de archivos mediante el almacenamiento de sesiones administrado. AgentCore El almacenamiento de sesiones gestionado en tiempo de ejecución es una capacidad totalmente gestionada por servicios en la que AgentCore Runtime gestiona todas las operaciones de almacenamiento. Su agente lee y escribe en un soporte de sistema de archivos local y el entorno de ejecución replica los datos de forma transparente en el almacenamiento del servicio durante toda la sesión.

El almacenamiento de las sesiones se aísla por sesión: cada sesión solo puede acceder a su propio almacenamiento y no puede leer ni escribir datos de otras sesiones del mismo tiempo de ejecución del agente o de sesiones de diferentes tiempos de ejecución de agentes.

Al configurar el almacenamiento de sesiones en el tiempo de ejecución de un agente, cada sesión obtiene un directorio persistente en la ruta de montaje que especifique. El ciclo de vida funciona de la siguiente manera:

Semántica del sistema de archivos

El almacenamiento de sesiones proporciona un sistema de archivos Linux estándar en la ruta de montaje configurada. Las herramientas y operaciones estándar funcionan sin modificaciones:ls,cat,mkdir,git,npm,pip, y cargo todas funcionan según lo esperado.

Operaciones compatibles

Archivos, directorios y enlaces simbólicos normales. Leer, escribir, cambiar el nombre chmod chownstat, eliminar yreaddir: operaciones de archivos POSIX estándar utilizadas por las herramientas de desarrollo comunes.

Límites

Para conocer los límites de almacenamiento de la sesión, incluidos el tamaño máximo de almacenamiento, el recuento de archivos y la profundidad del directorio, consulte los límites de almacenamiento de la sesión.

Operaciones no compatibles

No se admiten las siguientes operaciones del sistema de archivos:

Ciclo vital de almacenamiento de sesiones

Los datos de la sesión se eliminan (se restablecen a un estado limpio) en los siguientes escenarios:

Use DeleteAgentRuntime o DeleteAgentRuntimeEndpoint elimine todos los datos de almacenamiento de la sesión asociados al tiempo de ejecución o al punto final.

Volúmenes de proveedores de capacidad (instancias)

Los volúmenes del proveedor de capacidad son el tipo de almacenamiento administrado para los tiempos de ejecución que utilizan el tipo de procesamiento de las instancias. En lugar de especificar el almacenamiento en el tiempo de ejecución, usted define los volúmenes de Amazon EBS con nombre en el proveedor de capacidad y el tiempo de ejecución los monta por nombre lógico. AgentCore crea, adjunta y conserva los volúmenes por usted; los volúmenes de Amazon EBS no los aprovisiona ni los monta usted mismo.

Al igual que el almacenamiento de sesiones, los volúmenes de los proveedores de capacidad se aíslan por sesión y persisten en toda la sesión. stop/resume Como una sesión en las instancias es una instancia EC2 dedicada, el volumen sigue el ciclo de vida de esa sesión:

El volumen se conserva durante estas paradas, incluso cuando una sesión alcanza su duración máxima. Solo se elimina cuando se elimina la sesión o cuando se elimina el proveedor de capacidad (que elimina sus sesiones y sus volúmenes).

Para obtener información sobre la administración de los datos de estos volúmenes, consulte Administrar los datos en instancias en tiempo de ejecución.

Los agentes pueden compartir un volumen, pero el uso compartido no es automático. Para montar un volumen para el tiempo de ejecución de un agente, ese tiempo de ejecución debe configurar el mismo capacityProviderVolume (porvolumeName) por sí solofilesystemConfigurations. Cuando dos de estos tiempos de ejecución se invocan de la misma maneraruntimeSessionId, se ejecutan en la misma instancia y cada uno monta el volumen compartido para que puedan colaborar en los mismos archivos. La configuración capacityProviderVolume controla qué volúmenes se AgentCore montan para un tiempo de ejecución; por sí sola, no aísla los datos entre los agentes de una sesión. El límite de aislamiento es la sesión. Para ver el modelo de aislamiento de sesiones y agentes, consulte el modelo de seguridad y los permisos para las instancias en tiempo de ejecución.

En los tiempos de ejecución de las instancias, no se admiten el almacenamiento de sesiones administrado ni el tipo «traiga su propio tipo». Estos tipos son, y. sessionStorage s3FilesAccessPoint efsAccessPoint Si se especifica cualquiera de ellos al lado, se produce un capacityProviderConfiguration error con unValidationException. Para saber cómo definir volúmenes en un proveedor de capacidad y montarlos, consulte Cómo empezar a utilizar instancias mediante la AWS CLI y el almacenamiento persistente entre sesiones.

Requisitos previos para crear sus propios sistemas de archivos

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

Configuración de la VPC

El tiempo de ejecución de su agente debe usar. networkMode: VPC Las subredes que especifique deben superponerse con las zonas de disponibilidad de destino del montaje del sistema de archivos.

Permisos de IAM

La función de ejecución del agente en tiempo de ejecución 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. El s3files:GetAccessPoint permiso es necesario para validar el punto de acceso de S3 Files durante la creación del agente en tiempo de ejecución.

Grupos de seguridad

Permita el TCP saliente en el puerto 2049 desde el grupo de seguridad en tiempo de ejecución del agente 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 en tiempo de ejecución del agente.

Configure los sistemas de archivos

En las siguientes secciones se muestra cómo configurar cada tipo de sistema de archivos.

Configure un punto de acceso a Amazon S3 Files

Para configurar un punto de acceso a S3 Files, especifique el ARN del punto de acceso y la ruta de montaje. filesystemConfigurations El tiempo de ejecución del agente debe utilizar el modo de red de VPC.

Configure un punto de acceso de Amazon EFS

Para configurar un punto de acceso EFS, especifique el ARN del punto de acceso y la ruta de montaje. filesystemConfigurations El tiempo de ejecución del agente debe utilizar el modo de red de VPC.

Configure el almacenamiento de sesiones administrado

filesystemConfigurationsAñádalo con una sessionStorage entrada al crear o actualizar el tiempo de ejecución de un agente.

También puede agregar almacenamiento de sesión a un tiempo de ejecución de agente existente utilizando UpdateAgentRuntime el mismo filesystemConfigurations parámetro.

Configure un volumen de proveedor de capacidad

Para montar un volumen de proveedor de capacidad, primero defina el volumen en el proveedor de capacidad. A continuación, haga referencia a él por su nombre filesystemConfigurations cuando cree el tiempo de ejecución del agente. Esto se aplica a los tiempos de ejecución que utilizan el tipo de procesamiento de las instancias.

volumeNameDebe coincidir con un volumen definido en el del proveedor de capacidad. ec2Configuration.volumes Para ver los pasos para definir los volúmenes en el proveedor de capacidad, consulte Introducción a las instancias mediante la AWS CLI.

Combine los sistemas de archivos

Puede combinar el almacenamiento de sesiones gestionado con sistemas de archivos personalizados en un único entorno de ejecución de agente de microVM. En el siguiente ejemplo, se configuran los tres tipos.

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

Invoca y usa el almacenamiento persistente

Todos los sistemas de archivos configurados están disponibles en sus rutas de montaje cuando se invoca al agente. Bring-your-own se puede acceder inmediatamente a los sistemas de archivos (archivos S3, EFS) en cada invocación. El almacenamiento de sesiones administradas conserva los datos a lo largo de stop/resume los ciclos con el mismo runtimeSessionId uso.

Ejemplo: uso del almacenamiento de sesiones en varios stop/resume ciclos

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

El agente lo ve /mnt/workspace exactamente como lo dejó: los archivos fuente, los paquetes instalados, los artefactos de compilación y el historial.git permanecen intactos. Al reanudar una sesión, el nuevo entorno informático monta el almacenamiento persistente. Su agente puede seguir trabajando sin tener que volver a instalar paquetes ni regenerar archivos.

Límites

En la siguiente tabla se enumeran los límites de las configuraciones del sistema de archivos.

Los límites totales de almacenamiento de configuraciones, archivos S3, EFS y sesiones se aplican a los tiempos de ejecución de las microVM. El límite de volumen del proveedor de capacidad se define en función del proveedor de capacidad (ec2Configuration.volumes) y no por tiempo de ejecución.

Restricciones de ruta de montaje

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

Comportamiento del ciclo

En la siguiente tabla, se compara el comportamiento del ciclo de vida entre los tipos de sistemas de archivos gestionados y de tipo «traiga su propio sistema».

Casos de uso

En la siguiente tabla se enumeran los patrones comunes y la configuración del sistema de archivos recomendada para cada uno de ellos.

Ejemplo: agente de codificación con espacio de trabajo persistente

En este ejemplo, se muestra a un agente de codificación que utiliza agentes de Strands FileSessionManager para almacenar el historial de conversaciones y las sesiones de los archivos de proyectos. Ambos persisten a lo largo de stop/resume los ciclos.

Agente de codificación con almacenamiento de sesiones

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

Invoca al agente, detiene la sesión y, a continuación, reanuda. Tanto los archivos del proyecto como el contexto de la conversación persisten.

Invoca, detiene y reanuda el 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)

También FileSessionManager almacena el historial de conversaciones/mnt/workspace/.sessions/, lo que permite al agente recordar el contexto a lo largo de stop/resume los ciclos.

Requisitos de red

En esta sección se describen los requisitos de red tanto para el almacenamiento de sesiones gestionadas como para los sistemas de archivos personalizados.

Redes de almacenamiento de sesiones administradas

Si el tiempo de ejecución del agente usa el modo VPC con el almacenamiento de sesiones, el agente necesita acceso a la red para sincronizarse con el almacenamiento remoto. Los datos de la sesión se almacenan en AgentCore S3, por lo que la VPC debe permitir la conectividad saliente a S3. Si utilizas un punto de enlace de S3 Gateway con una política personalizada, puedes limitar el acceso a tu depósito de almacenamiento de sesión regional de la siguiente manera:

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

regionSustitúyalo por su AWS región (por ejemplo,us-west-2).

Bring-your-own redes de sistemas de archivos

Bring-your-own los sistemas de archivos requieren que la red de VPC cumpla los siguientes requisitos para que el montaje se realice correctamente.

Amazon EFS

Para comprobar los objetivos de montaje de EFS:

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

Para obtener información completa sobre los objetivos de montaje de EFS, consulte Cómo funciona Amazon EFS.

Amazon S3 Files

Para comprobar los objetivos de montaje de tus archivos S3:

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

Para obtener información completa sobre el montaje de archivos S3, consulte Montaje de sistemas de archivos S3.

Requisitos compartidos

¿Cómo AgentCore monta los sistemas de archivos

AgentCore gestiona automáticamente la operación de montaje de NFS dentro de la microVM:

No es necesario instalaramazon-efs-utils, configurar ni administrar los /etc/fstab certificados TLS. El motor de ejecución de la microVM gestiona todas las operaciones de montaje, la rotación de credenciales y la supervisión del estado.

Selección de subredes y zonas de disponibilidad

Al configurar las subredes de la VPC y las configuraciones del sistema de archivos en el tiempo de ejecución de un agente, seleccione las subredes que se superpongan con las zonas de disponibilidad de destino del montaje del sistema de archivos.

Para identificar el identificador de zona de disponibilidad de tus subredes:

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

Para identificar la zona de disponibilidad de sus destinos de montaje de EFS:

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

Asegúrese de que las subredes de ejecución de los agentes estén en las zonas de disponibilidad en las que el sistema de archivos tenga objetivos de montaje.

Para ver las zonas de disponibilidad compatibles por región, consulte las zonas de disponibilidad compatibles en el tema de configuración de la VPC. Para ver la configuración del grupo de seguridad, consulte Ejemplo: conexión a archivos de Amazon EFS o Amazon S3.

Solucione problemas relacionados con los montajes del sistema de archivos «traiga su propio sistema de archivos»

Cuando se produce un error en el montaje del sistema de archivos «traiga su propio sistema de archivos», devuelve HTTP 424 (dependencia fallida). InvokeAgentRuntime

Cada montura tiene un tiempo de espera de 30 segundos. Todos los sistemas de archivos configurados se montan en paralelo; una sola falla hace que falle toda la invocación.

Para obtener más información, consulte Solucionar problemas de almacenamiento BYO.