Configurações do sistema de arquivos para AgentCore Runtime

AgentCore O Runtime suporta sistemas de arquivos persistentes por meio do filesystemConfigurations parâmetro. Cada configuração monta o armazenamento em um caminho que você especifica. Você não precisa de código de montagem personalizado, contêineres privilegiados ou orquestração de downloads.

AgentCore O Runtime oferece suporte a duas categorias de configurações do sistema de arquivos:

Você pode combinar as duas categorias em um único tempo de execução do agente (até 5 configurações no total).

Visão geral das opções de armazenamento

A tabela a seguir compara os tipos de configuração do sistema de arquivos disponíveis.

Início rápido

As listas de verificação a seguir fornecem etapas condensadas para configurar cada tipo de sistema de arquivos.

Armazenamento gerenciado de sessões (versão prévia)

Bring-your-own sistema de arquivos

Ponto de acesso ao Amazon S3 Files

Ponto de acesso Amazon EFS

Tanto o S3 Files quanto o EFS exigem conectividade VPC no tempo de execução do agente.

Como cada tipo funciona

As seções a seguir descrevem como cada tipo de sistema de arquivos opera no AgentCore Runtime.

Bring-your-own sistemas de arquivos

Quando você configura um sistema de arquivos “traga seu próprio”, o AgentCore Runtime monta o ponto de acesso especificado em cada sessão no caminho que você configura. Os dados são compartilhados — várias sessões, vários agentes ou aplicativos externos podem acessar o mesmo sistema de arquivos simultaneamente.

AgentCore processa todas as operações de montagem automaticamente. Você não precisa instalar auxiliares de montagem, gerenciar certificados TLS ou escrever código de montagem em seu agente.

Fluxo de montagem de arquivos do Amazon S3

Quando você configura um ponto de acesso do S3 Files, ocorre a seguinte sequência:

Semântica de arquivos S3

Fluxo de montagem do Amazon EFS

Quando você configura um ponto de acesso EFS, ocorre a seguinte sequência:

Semântica do EFS

Armazenamento gerenciado de sessões (versão prévia)

Mantenha o estado da sessão stop/resume com uma configuração de sistema de arquivos usando o armazenamento gerenciado da sessão. AgentCore O armazenamento de sessões gerenciadas em tempo de execução é um recurso totalmente gerenciado por serviços em que o AgentCore Runtime lida com todas as operações de armazenamento. Seu agente lê e grava em uma montagem de sistema de arquivos local e o ambiente de execução replica os dados de forma transparente para o armazenamento de serviços durante toda a duração da sessão.

O armazenamento da sessão é isolado por sessão — cada sessão só pode acessar seu próprio armazenamento e não pode ler ou gravar dados de outras sessões do mesmo tempo de execução do agente ou de sessões de diferentes tempos de execução do agente.

Quando você configura o armazenamento da sessão em um tempo de execução do agente, cada sessão obtém um diretório persistente no caminho de montagem especificado. O ciclo de vida funciona da seguinte forma:

Semântica do sistema de arquivos

O armazenamento de sessão fornece um sistema de arquivos Linux padrão em seu caminho de montagem configurado. As ferramentas e operações padrão funcionam sem modificações —ls,cat,mkdir,git,npm,pip, e cargo todas funcionam conforme o esperado.

Operações suportadas

Arquivos, diretórios e links simbólicos regulares. Leia, grave, renomeie, exclua,chmod, chownstat, e readdir — operações de arquivo POSIX padrão usadas por ferramentas de desenvolvimento comuns.

Limites

Para os limites de armazenamento da sessão, incluindo tamanho máximo de armazenamento, contagem de arquivos e profundidade do diretório, consulte Limites de armazenamento da sessão.

Operações não suportadas

As seguintes operações do sistema de arquivos não são suportadas:

Ciclo de vida do armazenamento de sessões

Os dados da sessão são excluídos (redefinidos para um estado limpo) nos seguintes cenários:

Use DeleteAgentRuntimeou DeleteAgentRuntimeEndpointexclua todos os dados de armazenamento da sessão associados ao tempo de execução ou ao endpoint.

Pré-requisitos para trazer seus próprios sistemas de arquivos

Antes de configurar um sistema de arquivos “traga seu próprio”, preencha os pré-requisitos a seguir.

Configuração de VPC

Seu tempo de execução do agente deve ser usadonetworkMode: VPC. As sub-redes que você especificar devem se sobrepor às zonas de disponibilidade de destino da montagem do sistema de arquivos.

Permissões do IAM

Sua função de execução de tempo de execução do agente deve incluir permissões para montar o sistema de arquivos.

Permissões do IAM para arquivos 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>"
    }
  }
}

Permissões do 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 se seu agente precisar apenas de acesso de leitura. A s3files:GetAccessPoint permissão é necessária para a validação do ponto de acesso do S3 Files durante a criação do tempo de execução do agente.

Grupos de segurança

Permita o TCP de saída na porta 2049 do grupo de segurança de tempo de execução do agente para o grupo de segurança de destino de montagem. Permita TCP de entrada na porta 2049 no grupo de segurança de destino de montagem do grupo de segurança de tempo de execução do agente.

Configurar sistemas de arquivos

As seções a seguir mostram como configurar cada tipo de sistema de arquivos.

Configurar um ponto de acesso do Amazon S3 Files

Para configurar um ponto de acesso do S3 Files, especifique o ARN do ponto de acesso e o caminho de montagem em. filesystemConfigurations O tempo de execução do agente deve usar o modo de rede VPC.

Configurar um ponto de acesso do Amazon EFS

Para configurar um ponto de acesso EFS, especifique o ARN do ponto de acesso e o caminho de montagem em. filesystemConfigurations O tempo de execução do agente deve usar o modo de rede VPC.

Configurar o armazenamento gerenciado da sessão

Adicione filesystemConfigurations com uma sessionStorage entrada ao criar ou atualizar o tempo de execução de um agente.

Você também pode adicionar armazenamento de sessão a um tempo de execução de agente existente usando UpdateAgentRuntimeo mesmo filesystemConfigurations parâmetro.

Combine sistemas de arquivos

Você pode combinar o armazenamento gerenciado de sessões com seus próprios sistemas de arquivos em um único tempo de execução do agente. O exemplo a seguir configura todos os três 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"
            }
        }
    ]
)

Invoque e use armazenamento persistente

Todos os sistemas de arquivos configurados estão disponíveis em seus caminhos de montagem quando seu agente é chamado. Bring-your-own sistemas de arquivos (arquivos S3, EFS) podem ser acessados imediatamente em cada invocação. O armazenamento gerenciado de sessões persiste os dados em todos stop/resume os ciclos usando os mesmosruntimeSessionId.

Exemplo: uso do armazenamento de sessões em todos stop/resume os 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"}'

O agente vê /mnt/workspace exatamente como deixou: os arquivos de origem, os pacotes instalados, os artefatos de construção e o histórico.git estão todos intactos. Quando você retoma uma sessão, o novo ambiente computacional monta o armazenamento persistente. Seu agente pode continuar trabalhando sem reinstalar pacotes ou regenerar arquivos.

Limites

A tabela a seguir lista os limites das configurações do sistema de arquivos.

Restrições do caminho de montagem

Todas as configurações do sistema de arquivos devem seguir estas regras de caminho de montagem:

Comportamento do ciclo de vida

A tabela a seguir compara o comportamento do ciclo de vida entre o armazenamento gerenciado de sessões e os sistemas “traga seus próprios arquivos”.

Casos de uso

A tabela a seguir lista os padrões comuns e a configuração recomendada do sistema de arquivos para cada um.

Exemplo: agente de codificação com espaço de trabalho persistente

Este exemplo mostra um agente de codificação usando Strands Agents FileSessionManager para histórico de conversas e armazenamento de sessões para arquivos de projeto. Ambos persistem em stop/resume ciclos.

Agente de codificação com armazenamento de sessão

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

Chame o agente, interrompa a sessão e continue. Os arquivos do projeto e o contexto da conversa persistem.

Invocar, interromper e retomar o 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)

Ele FileSessionManager armazena o histórico de conversas em/mnt/workspace/.sessions/, permitindo que o agente se lembre do contexto em todos stop/resume os ciclos.

Requisitos de rede

Esta seção aborda os requisitos de rede tanto para armazenamento gerenciado de sessões quanto para sistemas de arquivos “traga seus próprios”.

Rede gerenciada de armazenamento de sessões

Se o tempo de execução do agente usa o modo VPC com armazenamento de sessão, o agente precisa de acesso à rede para sincronizar com o armazenamento remoto. Os dados da sessão são armazenados no AgentCore S3, portanto, sua VPC deve permitir a conectividade de saída com o S3. Se você estiver usando um endpoint do S3 Gateway com uma política personalizada, você pode definir o escopo do acesso ao seu bucket de armazenamento de sessão regional da seguinte forma:

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

regionSubstitua pela sua AWS região (por exemplo,us-west-2).

Bring-your-own rede de sistemas de arquivos

Bring-your-own os sistemas de arquivos exigem que sua rede VPC atenda aos seguintes requisitos para montagens bem-sucedidas.

Amazon EFS

Para verificar seus alvos de montagem do EFS:

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

Para obter informações completas sobre os destinos de montagem do EFS, consulte Como o Amazon EFS funciona.

Amazon S3 Files

Para verificar seus destinos de montagem de arquivos S3:

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

Para obter informações completas sobre a montagem de arquivos S3, consulte Montagem de sistemas de arquivos S3.

Requisitos compartilhados

Como AgentCore monta sistemas de arquivos

AgentCore manipula automaticamente a operação de montagem do NFS dentro da microVM:

Você não precisa instalar amazon-efs-utils/etc/fstab, configurar ou gerenciar certificados TLS. O tempo de execução do microVM lida com todas as operações de montagem, rotação de credenciais e monitoramento de integridade.

Seleção de sub-rede e zona de disponibilidade

Ao configurar as sub-redes VPC e as configurações do sistema de arquivos em um tempo de execução do agente, selecione sub-redes que se sobreponham às zonas de disponibilidade de destino da montagem do sistema de arquivos.

Para identificar o ID da zona de disponibilidade de suas sub-redes:

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

Para identificar a zona de disponibilidade dos seus destinos de montagem do EFS:

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

Certifique-se de que suas sub-redes de tempo de execução do agente estejam em zonas de disponibilidade nas quais seu sistema de arquivos tem destinos de montagem.

Para ver as zonas de disponibilidade suportadas por região, consulte o tópico Zonas de disponibilidade suportadas no tópico de configuração da VPC. Para a configuração do grupo de segurança, consulte Exemplo: conexão com arquivos do Amazon EFS ou do Amazon S3.

Solucione problemas de montagem do sistema de arquivos “traga seu próprio”

Quando uma montagem do sistema de arquivos traga seu próprio arquivo falha, InvokeAgentRuntime retorna HTTP 424 (Failed Dependency).

Cada montagem tem um tempo limite de 30 segundos. Todos os sistemas de arquivos configurados são montados paralelamente — uma única falha faz com que toda a invocação falhe.

Para obter mais informações, consulte Solucionar problemas de armazenamento BYO.