Visão geral das opções de armazenamento Início rápido Como funciona Pré-requisitos Configurar sistemas de arquivos Limites Solucionar problemas de montagens do sistema de arquivos

Configurações do sistema de arquivos para o AgentCore Code Interpreter

AgentCore O Code Interpreter suporta a montagem de seus próprios sistemas de arquivos em sessões de interpretador de código por meio do filesystemConfigurations parâmetro. Cada configuração monta um ponto de acesso do Amazon S3 Files ou do Amazon EFS em um caminho que você especificar. Você não precisa de código de montagem personalizado, contêineres privilegiados ou orquestração de download — AgentCore executa todas as operações de montagem dentro da sandbox da sessão.

Bring-your-own os sistemas de arquivos são armazenamento compartilhado: várias sessões, vários interpretadores de código ou aplicativos externos podem acessar o mesmo ponto de acesso simultaneamente. Os dados são mantidos e gerenciados em sua própria AWS conta.

Você pode fornecer filesystemConfigurations ao criar um interpretador de código com CreateCodeInterpreter (cada sessão iniciada a partir desse interpretador de código herda as montagens) ou ao iniciar uma sessão com StartCodeInterpreterSession (as montagens se aplicam a essa sessão). O parâmetro e a forma são idênticos nos dois lugares.

nota

Diferentemente do AgentCore Runtime, o AgentCore Code Interpreter não oferece uma opção gerenciada de armazenamento de sessão. O Code Interpreter oferece suporte somente para trazer seus próprios arquivos do Amazon S3 e pontos de acesso do Amazon EFS.

Visão geral das opções de armazenamento

A tabela a seguir compara os tipos de sistema de arquivos disponíveis.

Tipo	Isolamento	Persistência	VPC necessário	Melhor para
Amazon S3 Files	Compartilhado — várias sessões e intérpretes de código acessam os mesmos dados	Customer-managed (permanente, sincroniza com o bucket S3 de apoio)	Sim	Conjuntos de dados e artefatos acessíveis por meio de operações de arquivo padrão e APIs do S3
Amazon EFS	Compartilhado — várias sessões e intérpretes de código acessam os mesmos dados	Customer-managed (permanente até que você o exclua)	Sim	Dados de referência compartilhados, downloads, colaboração de leitura e gravação entre sessões

Início rápido

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

Ponto de acesso do Amazon S3 Files

Adicione s3files:ClientMounts3files:ClientWrite, e s3files:GetAccessPoint à sua função de execução de interpretador de código com uma s3files:AccessPointArn condição.
Permita a saída da porta TCP 2049 do seu grupo de segurança do interpretador de código para o grupo de segurança de destino do S3 Files mount.
Confirme se o destino de montagem do S3 Files está na mesma VPC e na mesma zona de disponibilidade das sub-redes do interpretador de código.
Adicione filesystemConfigurations com uma s3FilesConfiguration entrada para o seu CreateCodeInterpreter ou StartCodeInterpreterSession ligue.
Inicie uma sessão. Os arquivos em seu caminho de montagem (por exemplo,/mnt/s3data) são sincronizados bidirecionalmente com o bucket de suporte do S3.

Ponto de acesso Amazon EFS

Adicione elasticfilesystem:ClientMount e elasticfilesystem:ClientWrite à sua função de execução de interpretador de código com uma elasticfilesystem:AccessPointArn condição.
Permita a saída da porta TCP 2049 do grupo de segurança do interpretador de código para o grupo de segurança de destino de montagem do EFS.
Confirme se o destino de montagem do EFS está na mesma zona de disponibilidade de pelo menos uma de suas sub-redes de interpretador de código.
Adicione filesystemConfigurations com uma efsConfiguration entrada para o seu CreateCodeInterpreter ou StartCodeInterpreterSession ligue.
Inicie uma sessão. Seus arquivos estão disponíveis em seu caminho de montagem (por exemplo,/mnt/efs).

Tanto o S3 Files quanto o EFS exigem conectividade VPC no interpretador de código.

Como funciona

Quando você configura um sistema de arquivos traga seu próprio, o AgentCore Code Interpreter monta o ponto de acesso especificado na sandbox da sessão no caminho que você configura. Os dados são compartilhados — várias sessões, vários interpretadores de código 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.

nota

Ao criar um ponto de acesso (arquivos S3 ou EFS), você especifica uma ID de usuário (UID) POSIX e uma ID de grupo (GID). Todas as operações de arquivo por meio do ponto de acesso são executadas com essa identidade.

Fluxo de montagem de arquivos do Amazon S3

Você cria um sistema de arquivos do S3 Files (apoiado por um bucket do S3) e monta destinos na sua VPC.
Você cria um ponto de acesso do S3 Files especificando o POSIX UID/GID e o diretório raiz.
Você configura o interpretador de código (ou sessão) com o ARN do ponto de acesso, o ARN do sistema de arquivos e o caminho de montagem.
No início da sessão, AgentCore provisiona uma sandbox com acesso de rede à sua VPC.
O sandbox monta o sistema de arquivos NFSv4.2 por meio de TLS com autenticação IAM (porta 2049) por meio de sua VPC.
Seu agente lê e grava arquivos no caminho de montagem. As alterações são sincronizadas automaticamente com o bucket de apoio do S3.

Fluxo de montagem do Amazon EFS

Você cria um sistema de arquivos EFS e monta destinos em sua VPC (um por zona de disponibilidade).
Você cria um ponto de acesso EFS especificando o POSIX UID/GID e o diretório raiz.
Você configura o interpretador de código (ou sessão) com o ARN do ponto de acesso, o ARN do sistema de arquivos e o caminho de montagem.
No início da sessão, AgentCore provisiona uma sandbox com acesso de rede à sua VPC.
O sandbox monta o sistema de arquivos NFSv4.1 por meio de TLS (porta 2049) por meio do destino de montagem na mesma zona de disponibilidade.
Seu agente lê e grava arquivos no caminho de montagem usando operações de arquivo padrão.

Pré-requisitos

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

Configuração de VPC

Seu interpretador de código deve usar o modo VPC de rede. 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 intérprete de código 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.

Grupos de segurança

Permita TCP de saída na porta 2049 do seu grupo de segurança do interpretador de código 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 do interpretador de código.

Configurar sistemas de arquivos

Especifique cada sistema de arquivos filesystemConfigurations como um s3FilesConfiguration ou umefsConfiguration. Ambos exigem três campos:

accessPointArn— O ARN do ponto de acesso S3 Files ou EFS a ser montado.
fileSystemArn— O ARN do sistema de arquivos que possui o ponto de acesso. Esse campo é obrigatório.
mountPath— O caminho absoluto dentro da sessão em que o ponto de acesso está montado (por exemplo,/mnt/s3data).

Você pode fornecer filesystemConfigurations em dois lugares, usando a mesma forma:

Plano de controle — CreateCodeInterpreter — As montagens são herdadas por cada sessão iniciada pelo interpretador de código. O interpretador de código deve usar o modo de rede VPC.
Plano de dados — StartCodeInterpreterSession — As montagens se aplicam a essa sessão específica.

nota

Você pode fornecer configurações do sistema de arquivos no plano de controle (CreateCodeInterpreter), no plano de dados (StartCodeInterpreterSession) ou em ambos, desde que o interpretador de código use o modo de rede VPC e o ponto de acesso S3 Files ou EFS esteja configurado corretamente (destinos de montagem, permissões do IAM e grupos de segurança). As configurações do CreateCodeInterpreter são herdadas por cada sessão; as configurações do StartCodeInterpreterSession se aplicam a essa sessão. Quando ambos são fornecidos, eles são combinados para a sessão, e cada caminho de montagem deve ser exclusivo no conjunto combinado.

As seções a seguir mostram as duas chamadas de API para cada tipo de sistema de arquivos.

Configurar um ponto de acesso do Amazon S3 Files

Plano de controle: CreateCodeInterpreter

exemplo

AWS CLI


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

Exemplo de Python usando boto3 para criar um interpretador de código com um ponto de acesso do 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 dados: StartCodeInterpreterSession

exemplo

Configurar um ponto de acesso do Amazon EFS

Plano de controle: CreateCodeInterpreter

exemplo

AWS CLI


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

Exemplo de Python usando boto3 para criar um interpretador de código com um ponto de acesso 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 dados: StartCodeInterpreterSession

exemplo

Combine sistemas de arquivos

Você pode conectar vários pontos de acesso (até os limites abaixo) em uma única chamada adicionando mais entradas filesystemConfigurations a. Cada entrada deve usar um caminho de montagem exclusivo.


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 os sistemas de arquivos montados

Use GetCodeInterpreter para confirmar o filesystemConfigurations em um interpretador de código e GetCodeInterpreterSession para confirmar as configurações efetivas em uma sessão em execução. As configurações definidas na criação do interpretador de código e no início da sessão aparecem na resposta da sessão.

Limites

Os limites de configuração do sistema de arquivos são impostos por solicitação. CreateCodeInterpreteras configurações são herdadas por cada sessão, e as StartCodeInterpreterSession configurações se aplicam a essa sessão. As montagens efetivas de uma sessão são a combinação de ambas.

Tipo de configuração	Por CreateCodeInterpreter	Por StartCodeInterpreterSession	Combinado por sessão
Pontos de acesso do Amazon S3 Files	2	2	4
Pontos de acesso do Amazon EFS	2	2	4
Total de configurações do sistema de arquivos	4	4	8

Por exemplo, você pode configurar 1 ponto de acesso S3 Files e 1 ponto de acesso EFS ativados eCreateCodeInterpreter, em seguida, adicionar 1 ponto de acesso S3 Files e 1 ponto de acesso EFSStartCodeInterpreterSession, totalizando 4 montagens na sessão. Cada caminho de montagem deve ser exclusivo no conjunto combinado.

Restrições do caminho de montagem

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

Deve estar abaixo /mnt/ com exatamente um nível de subdiretório (por exemplo,/mnt/data,/mnt/s3data).
Padrão: /mnt/[a-zA-Z0-9._-]+/?
Cada caminho de montagem deve ser exclusivo em todas as configurações.
Os caminhos de montagem não podem ser subdiretórios uns dos outros.

Solucionar problemas de montagens do sistema de arquivos

Quando a montagem do sistema de arquivos traga seu próprio falha, StartCodeInterpreterSession retorna um erro e a sessão não se torna. READY

Sintomas	Causa provável	Solução rápida
“Acesso negado”	Função de execução ausente `ClientMount` ou `ClientWrite`	Adicione permissões do IAM com a `AccessPointArn` condição
“ResourceNotFound" ou “Falha na resolução”	Ponto de acesso ou alvo de montagem excluído ou indisponível	Verifique se o ARN existe e se os destinos de montagem estão disponíveis
A montagem trava e depois falha	Porta 2049 de bloqueio de grupos de segurança ou nenhum destino de montagem na zona de disponibilidade da sessão	Permitir TCP 2049; verificar a sobreposição da zona de disponibilidade
“Permissão negada” em gravações	Ausência `ClientWrite` ou incompatibilidade POSIX UID/GID	Adicione permissão de gravação ou alinhe o usuário POSIX do ponto de acesso

Todos os sistemas de arquivos configurados são montados em paralelo no início da sessão — uma única falha na montagem faz com que o início da sessão falhe.

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

AgentCore Interrompendo uma sessão do Code Interpreter

Exemplos de referência de API