Configuraciones del sistema de archivos para AgentCore Runtime

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

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

Puede combinar ambas categorías en un único entorno de ejecución del agente (hasta 5 configuraciones en total).

Las opciones de almacenamiento de un vistazo

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

Inicio rápido

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

Almacenamiento de sesiones gestionado (versión preliminar)

Bring-your-own sistema de archivos

Punto de acceso Amazon S3 Files

Punto de acceso Amazon EFS

Tanto los archivos S3 como los 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 tipo bring-your-own, 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 simultáneamente.

AgentCore gestiona todas las operaciones de montaje automáticamente. No necesita instalar asistentes de montaje, administrar los certificados TLS ni escribir código de montaje en su agente.

Flujo de montaje de Amazon S3 Files

Al configurar un punto de acceso de 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 gestionado (versión preliminar)

Mantenga el estado de la sesión en stop/resume una configuración de sistema de archivos mediante el almacenamiento de sesiones gestionado. AgentCore El almacenamiento de sesiones gestionado en tiempo de ejecución es una capacidad totalmente gestionada por el servicio en la que AgentCore Runtime gestiona todas las operaciones de almacenamiento. El agente lee y escribe en un sistema de archivos local montado 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 está aislado 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 del agente.

Al configurar el almacenamiento de sesiones en un entorno 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: lscat,mkdir,git, npmpip, y cargo todas funcionan según lo previsto.

Operaciones compatibles

Archivos, directorios y enlaces simbólicos normales. Lectura, escritura, cambio de nombre, eliminación, chmod chownstat, yreaddir: operaciones estándar de archivos POSIX 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 número de archivos y la profundidad del directorio, consulte Límites de almacenamiento de la sesión.

Operaciones no compatibles

No se admiten las siguientes operaciones del sistema de archivos:

Ciclo de vida del almacenamiento de

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

Use DeleteAgentRuntimeo DeleteAgentRuntimeEndpointelimine todos los datos de almacenamiento de la sesión asociados al tiempo de ejecución o al punto final.

Requisitos previos para crear sus propios sistemas de archivos

Antes de configurar un sistema de archivos tipo «traiga sus propios archivos», complete los siguientes requisitos previos.

Configuración de la VPC

Debe usar el motor de ejecución de su agente. networkMode: VPC Las subredes que especifique deben superponerse con las zonas de disponibilidad de destino montadas en el 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 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 que el TCP saliente en el puerto 2049 desde el grupo de seguridad en tiempo de ejecución del agente se dirija al grupo de seguridad de destino montado. Permita el TCP entrante en el puerto 2049 del grupo de seguridad de destino del agente en tiempo de ejecución.

Configure los sistemas de archivos

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

Configuración de un punto de acceso de Amazon S3 Files

Para configurar un punto de acceso de 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.

Configuración de un punto de acceso 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 gestionado

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

También puede añadir almacenamiento de sesiones a un entorno de ejecución de agente existente utilizando UpdateAgentRuntimeel mismo filesystemConfigurations parámetro.

Combine sistemas de archivos

Puede combinar el almacenamiento de sesiones gestionado con sistemas de archivos personalizados en un único entorno de ejecución de agente. El siguiente ejemplo configura 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 el agente. Bring-your-own Se puede acceder inmediatamente a los sistemas de archivos (S3 Files, EFS) en cada invocación. El almacenamiento de sesiones gestionado conserva los datos a lo largo de stop/resume los ciclos utilizando los mismosruntimeSessionId.

Ejemplo: usar el almacenamiento de sesiones a lo largo de stop/resume los 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 ve /mnt/workspace exactamente como lo dejó: los archivos fuente, los paquetes instalados, los artefactos de compilación y el historio.git están intactos. Al reanudar una sesión, el nuevo entorno informático monta el almacenamiento persistente. El agente puede seguir trabajando sin tener que volver a instalar los paquetes ni regenerar los archivos.

Límites

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

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 el almacenamiento de sesiones gestionado y los sistemas de archivos tipo bring-your-own.

Casos de uso

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

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

Este ejemplo muestra un agente de codificación que utiliza Strands Agents FileSessionManager para el historial de conversaciones y el almacenamiento de sesiones para los archivos del proyecto. 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(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

Invoque el agente, detenga la sesión y, a continuación, reanude. 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)

FileSessionManagerAlmacena el historial de conversaciones/mnt/workspace/.sessions/, lo que permite al agente recordar el contexto en todos stop/resume los ciclos.

Requisitos de red

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

Almacenamiento de sesiones gestionado y redes

Si el tiempo de ejecución del agente utiliza el modo VPC con almacenamiento de sesión, 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 su VPC debe permitir la conectividad saliente a S3. Si utilizas un terminal de S3 Gateway con una política personalizada, puedes limitar el acceso a tu depósito de almacenamiento de sesiones 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 tu 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 los montajes se realicen correctamente.

Amazon EFS

Para comprobar sus objetivos de montaje 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 los 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 del NFS dentro de la microVM:

No necesita instalaramazon-efs-utils, configurar ni administrar los /etc/fstab certificados TLS. El entorno de ejecución de 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 VPC y las configuraciones del sistema de archivos en un entorno de ejecución del agente, seleccione las subredes que se superpongan con las zonas de disponibilidad de destino del sistema de archivos.

Para identificar el ID de la zona de disponibilidad de sus subredes:

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

Para identificar la zona de disponibilidad de sus objetivos 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 tiempo de ejecución del agente estén en las zonas de disponibilidad en las que el sistema de archivos tenga los 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 Amazon EFS o Amazon S3 Files.

Solucione problemas con los montajes de sistemas de archivos propios

Cuando se produce un error al montar un sistema de archivos tipo «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: un solo error provoca un error en toda la invocación.

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