As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Configurações do sistema de arquivos para AgentCore Runtime

AgentCore O Runtime oferece suporte a 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:

O tipo gerenciado depende do tipo de computação do seu tempo de execução. Use o armazenamento de sessão em tempos de execução de microVM e volumes de provedores de capacidade em tempos de execução de instâncias. Em tempos de execução de microVM, você pode combinar o armazenamento de sessões com sistemas de arquivos do tipo traga seus próprios sistemas de arquivos em um único tempo de execução de 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 resumidas para configurar cada tipo de sistema de arquivos.

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

O armazenamento de sessões está disponível em tempos de execução de microVM.

Volume do provedor de capacidade

Os volumes do provedor de capacidade estão disponíveis nos tempos de execução das instâncias.

Para ver o passo a passo completo, consulte Comece a usar instâncias usando a AWS CLI.

Bring-your-own sistema de arquivos

Ponto de acesso do 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 EFS

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

Persista o estado da sessão stop/resume com a configuração do sistema de arquivos usando o armazenamento gerenciado de sessões. AgentCore O armazenamento de sessão gerenciado 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 nem 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 que você especificar. O ciclo de vida funciona da seguinte maneira:

Semântica do sistema de arquivos

O armazenamento de sessão fornece um sistema de arquivos Linux padrão no 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 DeleteAgentRuntime ou DeleteAgentRuntimeEndpoint exclua todos os dados de armazenamento da sessão associados ao tempo de execução ou ao endpoint.

Volumes do provedor de capacidade (instâncias)

Os volumes do provedor de capacidade são o tipo de armazenamento gerenciado para tempos de execução que usam o tipo de computação Instâncias. Em vez de especificar o armazenamento no tempo de execução, você define volumes nomeados do Amazon EBS no provedor de capacidade, e o tempo de execução os monta pelo nome lógico. AgentCore cria, anexa e retém os volumes para você — você não provisiona nem monta volumes do Amazon EBS sozinho.

Assim como o armazenamento de sessões, os volumes do provedor de capacidade são isolados por sessão e persistem por toda stop/resume parte. Como uma sessão em Instâncias é uma instância EC2 dedicada, o volume segue o ciclo de vida dessa sessão:

O volume é retido durante essas paradas, inclusive quando uma sessão atinge sua vida útil máxima. Ele é excluído somente quando você exclui a sessão ou quando você exclui o provedor de capacidade (que exclui suas sessões e seus volumes).

Para obter informações sobre como gerenciar os dados nesses volumes, consulte Gerenciar seus dados em instâncias de tempo de execução.

Os agentes podem compartilhar um volume, mas o compartilhamento não é automático. Para que um volume seja montado para um tempo de execução do agente, esse tempo de execução deve configurar o mesmo capacityProviderVolume (byvolumeName) sozinhofilesystemConfigurations. Quando dois desses tempos de execução são invocados com o mesmoruntimeSessionId, eles são executados na mesma instância e cada um monta o volume compartilhado, para que possam colaborar nos mesmos arquivos. A configuração capacityProviderVolume controla quais volumes são AgentCore montados em um tempo de execução; ela não isola, por si só, os dados entre os agentes em uma sessão. O limite de isolamento é a sessão. Para o modelo de isolamento de sessão e agente, consulte Modelo de segurança e permissões para instâncias de tempo de execução.

O armazenamento gerenciado de sessões e os tipos traga seu próprio não são compatíveis com os tempos de execução de instâncias. Esses tipos são sessionStorages3FilesAccessPoint, efsAccessPoint e. A especificação de qualquer um deles ao lado capacityProviderConfiguration falha com umValidationException. Para saber como definir volumes em um provedor de capacidade e montá-los, consulte Comece a usar instâncias usando a AWS CLI e o armazenamento persistente em todas as sessões.

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

Antes de configurar um sistema de arquivos traga seu próprio, preencha os seguintes pré-requisitos.

Configuração de VPC

O tempo de execução do seu agente deve usarnetworkMode: VPC. As sub-redes que você especificar devem se sobrepor às zonas de disponibilidade de destino montadas no 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 seu 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 emfilesystemConfigurations. O tempo de execução do seu agente deve usar o modo de rede VPC.

Configurar o armazenamento gerenciado de sessões

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

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

Configurar um volume de provedor de capacidade

Para montar um volume do provedor de capacidade, primeiro defina o volume no provedor de capacidade. Em seguida, referencie-o pelo nome filesystemConfigurations ao criar o tempo de execução do agente. Isso se aplica aos tempos de execução que usam o tipo de computação Instances.

Eles volumeName devem corresponder a um volume definido no do provedor de capacidadeec2Configuration.volumes. Para ver as etapas para definir volumes no provedor de capacidade, consulte Introdução às instâncias usando a AWS CLI.

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 microVM. 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 o armazenamento persistente

Todos os sistemas de arquivos configurados estão disponíveis em seus caminhos de montagem quando seu agente é chamado. Bring-your-own os 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: Usando o 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 o deixou: os arquivos de origem, os pacotes instalados, os artefatos de compilação e o histórico.git estão todos intactos. Quando você reinicia 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.

As configurações totais, os arquivos do S3, o EFS e os limites de armazenamento da sessão se aplicam aos tempos de execução da microVM. O limite de volume do provedor de capacidade é definido no provedor de capacidade (ec2Configuration.volumes) e não por tempo de execução.

Restrições do caminho de montagem

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

Comportamento do ciclo de vida

A tabela a seguir compara o comportamento do ciclo de vida entre os tipos de sistema de arquivos gerenciado e do tipo traga seu próprio sistema de 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 todos os 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(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

Invoque o agente, interrompa a sessão e retome. Tanto os arquivos do projeto quanto o contexto da conversa persistem.

Invocar, parar 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 o armazenamento gerenciado de sessões quanto para os sistemas de arquivos do tipo traga seu próprio arquivo.

Rede gerenciada de armazenamento de sessões

Se o tempo de execução do seu 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 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 sistema 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 alvos de montagem do S3 Files:

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 processa 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 de montagem do seu sistema de arquivos.

Para identificar a 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 de 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 as sub-redes de tempo de execução do agente estejam em zonas de disponibilidade nas quais seu sistema de arquivos tenha destinos de montagem.

Para zonas de disponibilidade suportadas por região, consulte as 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.

Solucionar problemas de montagens do sistema de arquivos do tipo Bring Your-Own

Quando a montagem do sistema de arquivos tring-your-own falha, InvokeAgentRuntime retorna HTTP 424 (Dependência com falha).

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

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