View a markdown version of this page

Configurações do sistema de arquivos para o navegador AgentCore - Base da Amazônia AgentCore
Visão geral das opções de armazenamentoInício rápidoComo funcionaPré-requisitosConfigurar sistemas de arquivosLimitesSolucionar problemas de montagens do sistema de arquivos

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 o navegador AgentCore

AgentCore O navegador suporta a montagem de seus próprios sistemas de arquivos em sessões do navegador 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 navegadores 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 navegador com CreateBrowser (cada sessão iniciada a partir desse navegador herda as montagens) ou ao iniciar uma sessão com StartBrowserSession (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 Browser não oferece uma opção gerenciada de armazenamento de sessão. O navegador oferece suporte somente para trazer seus próprios arquivos 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 navegadores 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 navegadores 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

  1. Adicione s3files:ClientMounts3files:ClientWrite, e s3files:GetAccessPoint à sua função de execução do navegador com uma s3files:AccessPointArn condição.

  2. Permita que a porta TCP 2049 saia do grupo de segurança do seu navegador para o grupo de segurança de destino do S3 Files mount.

  3. Confirme se o destino de montagem do S3 Files está na mesma VPC e zona de disponibilidade das sub-redes do seu navegador.

  4. Adicione filesystemConfigurations com uma s3FilesConfiguration entrada para o seu CreateBrowser ou StartBrowserSession ligue.

  5. 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

  1. Adicione elasticfilesystem:ClientMount e elasticfilesystem:ClientWrite à sua função de execução do navegador com uma elasticfilesystem:AccessPointArn condição.

  2. Permita que a porta TCP 2049 saia do grupo de segurança do navegador para o grupo de segurança de destino de montagem do EFS.

  3. Confirme se o destino de montagem do EFS está na mesma zona de disponibilidade de pelo menos uma das sub-redes do seu navegador.

  4. Adicione filesystemConfigurations com uma efsConfiguration entrada para o seu CreateBrowser ou StartBrowserSession ligue.

  5. 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 navegador.

Como funciona

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

  1. Você cria um sistema de arquivos do S3 Files (apoiado por um bucket do S3) e monta destinos na sua VPC.

  2. Você cria um ponto de acesso do S3 Files especificando o POSIX UID/GID e o diretório raiz.

  3. Você configura o navegador (ou sessão) com o ARN do ponto de acesso, o ARN do sistema de arquivos e o caminho de montagem.

  4. No início da sessão, AgentCore provisiona uma sandbox com acesso de rede à sua VPC.

  5. O sandbox monta o sistema de arquivos NFSv4.2 por meio de TLS com autenticação IAM (porta 2049) por meio de sua VPC.

  6. 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

  1. Você cria um sistema de arquivos EFS e monta destinos em sua VPC (um por zona de disponibilidade).

  2. Você cria um ponto de acesso EFS especificando o POSIX UID/GID e o diretório raiz.

  3. Você configura o navegador (ou sessão) com o ARN do ponto de acesso, o ARN do sistema de arquivos e o caminho de montagem.

  4. No início da sessão, AgentCore provisiona uma sandbox com acesso de rede à sua VPC.

  5. 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.

  6. 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 navegador 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 do navegador 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 o TCP de saída na porta 2049 do grupo de segurança do seu navegador para o grupo de segurança de destino de montagem. Permita TCP de entrada na porta 2049 no grupo de segurança de destino montado do grupo de segurança do navegador.

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 — CreateBrowser — As montagens são herdadas por cada sessão iniciada pelo navegador. O navegador deve usar o modo de rede VPC.

  • Plano de dados — StartBrowserSession — As montagens se aplicam a essa sessão específica.

nota

Você pode fornecer configurações do sistema de arquivos no plano de controle (CreateBrowser), no plano de dados (StartBrowserSession) ou em ambos, desde que o navegador 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 CreateBrowser são herdadas por cada sessão; as configurações do StartBrowserSession 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: CreateBrowser

exemplo
AWS CLI

  1. aws bedrock-agentcore-control create-browser \
  --name "data-browser" \
  --execution-role-arn "arn:aws:iam::<account-id>:role/BrowserExecutionRole" \
  --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

  1. Exemplo de Python usando boto3 para criar um navegador com um ponto de acesso do S3 Files.

    import boto3

cp = boto3.client("bedrock-agentcore-control", region_name="us-west-2")

response = cp.create_browser(
    name="data-browser",
    executionRoleArn="arn:aws:iam::<account-id>:role/BrowserExecutionRole",
    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: StartBrowserSession

exemplo
AWS CLI

  1. aws bedrock-agentcore start-browser-session \
  --browser-identifier "<browser-id>" \
  --name "byos-session" \
  --session-timeout-seconds 3600 \
  --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

  1. Exemplo de Python usando boto3 para iniciar uma sessão do navegador com um ponto de acesso do S3 Files.

    import boto3

dp = boto3.client("bedrock-agentcore", region_name="us-west-2")

response = dp.start_browser_session(
    browserIdentifier="<browser-id>",
    name="byos-session",
    sessionTimeoutSeconds=3600,
    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"
            }
        }
    ]
)

session_id = response["sessionId"]

Configurar um ponto de acesso do Amazon EFS

Plano de controle: CreateBrowser

exemplo
AWS CLI

  1. aws bedrock-agentcore-control create-browser \
  --name "shared-tools-browser" \
  --execution-role-arn "arn:aws:iam::<account-id>:role/BrowserExecutionRole" \
  --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

  1. Exemplo de Python usando boto3 para criar um navegador com um ponto de acesso EFS.

    import boto3

cp = boto3.client("bedrock-agentcore-control", region_name="us-west-2")

response = cp.create_browser(
    name="shared-tools-browser",
    executionRoleArn="arn:aws:iam::<account-id>:role/BrowserExecutionRole",
    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: StartBrowserSession

exemplo
AWS CLI

  1. aws bedrock-agentcore start-browser-session \
  --browser-identifier "<browser-id>" \
  --name "byos-session" \
  --session-timeout-seconds 3600 \
  --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

  1. Exemplo de Python usando boto3 para iniciar uma sessão do navegador com um ponto de acesso EFS.

    import boto3

dp = boto3.client("bedrock-agentcore", region_name="us-west-2")

response = dp.start_browser_session(
    browserIdentifier="<browser-id>",
    name="byos-session",
    sessionTimeoutSeconds=3600,
    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"
            }
        }
    ]
)

session_id = response["sessionId"]

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 GetBrowser para confirmar o filesystemConfigurations em um navegador e GetBrowserSession para confirmar as configurações efetivas em uma sessão em execução. As configurações definidas na criação do navegador 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. CreateBrowseras configurações são herdadas por cada sessão, e as StartBrowserSession 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 CreateBrowser Por StartBrowserSession 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 eCreateBrowser, em seguida, adicionar 1 ponto de acesso S3 Files e 1 ponto de acesso EFSStartBrowserSession, 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, StartBrowserSession 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.