View a markdown version of this page

Configurazioni del file system per Browser AgentCore - Fondamento Amazon AgentCore
Le opzioni di archiviazione a colpo d'occhioAvvio rapidoCome funzionaPrerequisitiConfigurare i file systemLimitsRisolvi i problemi relativi ai montaggi del file system

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Configurazioni del file system per Browser AgentCore

AgentCore Il browser supporta il montaggio dei propri file system nelle sessioni del browser tramite il filesystemConfigurations parametro. Ogni configurazione monta un access point Amazon S3 Files o Amazon EFS in un percorso specificato. Non hai bisogno di codice di montaggio personalizzato, contenitori privilegiati o orchestrazione dei download: AgentCore esegue tutte le operazioni di montaggio all'interno della sandbox della sessione.

Bring-your-own i file system sono sistemi di archiviazione condivisi: più sessioni, più browser o applicazioni esterne possono accedere contemporaneamente allo stesso punto di accesso. I dati vengono conservati e gestiti nel tuo AWS account.

Puoi fornire filesystemConfigurations quando crei un browser con CreateBrowser (ogni sessione avviata da quel browser eredita i supporti) o quando inizi una sessione con StartBrowserSession (i mount si applicano a quella sessione). Il parametro e la forma sono identici in entrambi i punti.

Nota

A differenza AgentCore di Runtime, AgentCore Browser non offre un'opzione di archiviazione delle sessioni gestita. Browser supporta solo Amazon S3 Files Bring Your Own e punti di accesso Amazon EFS.

Le opzioni di archiviazione a colpo d'occhio

La tabella seguente confronta i tipi di file system disponibili.

Tipo Isolamento Persistenza VPC richiesto Ideale per

File di Amazon S3

Condiviso: più sessioni e browser accedono agli stessi dati

Customer-managed (permanente, si sincronizza con il bucket S3 di supporto)

Sì

Set di dati e artefatti accessibili tramite operazioni sui file standard e API S3

Amazon EFS

Condiviso: più sessioni e browser accedono agli stessi dati

Customer-managed (permanente finché non lo elimini)

Sì

Dati di riferimento condivisi, download, collaborazione in lettura e scrittura tra le sessioni

Avvio rapido

Le seguenti liste di controllo forniscono passaggi brevi per la configurazione di ogni tipo di file system.

Punto di accesso Amazon S3 Files

  1. Aggiungi s3files:ClientMount e s3files:ClientWrite s3files:GetAccessPoint al ruolo di esecuzione del browser con una s3files:AccessPointArn condizione.

  2. Consenti l'uscita della porta TCP 2049 dal gruppo di sicurezza del browser al gruppo di sicurezza di destinazione S3 Files mount.

  3. Verifica che la destinazione di montaggio dei file S3 si trovi nello stesso VPC e nella stessa zona di disponibilità delle sottoreti del browser.

  4. Aggiungilo filesystemConfigurations con una s3FilesConfiguration voce alla tua chiamata. CreateBrowser StartBrowserSession

  5. Avvia una sessione. I file sul percorso di montaggio (ad esempio/mnt/s3data) si sincronizzano in modo bidirezionale con il bucket S3 di supporto.

Punto di accesso Amazon EFS

  1. Aggiungi elasticfilesystem:ClientMount e elasticfilesystem:ClientWrite al ruolo di esecuzione del browser con una elasticfilesystem:AccessPointArn condizione.

  2. Consenti l'uscita della porta TCP 2049 dal gruppo di sicurezza del browser al gruppo di sicurezza di destinazione con montaggio EFS.

  3. Verifica che la destinazione di montaggio EFS si trovi nella stessa zona di disponibilità di almeno una delle sottoreti del browser.

  4. Aggiungilo filesystemConfigurations inserendo una efsConfiguration voce alla tua chiamataCreateBrowser. StartBrowserSession

  5. Avvia una sessione. I tuoi file sono disponibili nel tuo percorso di montaggio (ad esempio,/mnt/efs).

Sia S3 Files che EFS richiedono la connettività VPC sul browser.

Come funziona

Quando si configura un file system bring-your-own, AgentCore Browser monta il punto di accesso specificato nella sandbox della sessione nel percorso configurato. I dati sono condivisi: più sessioni, più browser o applicazioni esterne possono accedere contemporaneamente allo stesso file system.

AgentCore gestisce automaticamente tutte le operazioni di montaggio. Non è necessario installare gli helper di montaggio, gestire i certificati TLS o scrivere codice di montaggio.

Nota

Quando si crea un punto di accesso (file S3 o EFS), si specifica un ID utente POSIX (UID) e un ID di gruppo (GID). Tutte le operazioni sui file tramite il punto di accesso vengono eseguite con questa identità.

Flusso di montaggio dei file Amazon S3

  1. Crei un file system S3 Files (supportato da un bucket S3) e monti le destinazioni nel tuo VPC.

  2. Crei un punto di accesso S3 Files specificando il POSIX e la directory principale. UID/GID

  3. Si configura il browser (o la sessione) con l'ARN del punto di accesso, l'ARN del file system e il percorso di montaggio.

  4. All'inizio della sessione, effettua il AgentCore provisioning di una sandbox con accesso di rete al tuo VPC.

  5. La sandbox monta il file system NFSv4.2 tramite TLS con autenticazione IAM (porta 2049) tramite il tuo VPC.

  6. L'agente legge e scrive i file nel percorso di montaggio. Le modifiche si sincronizzano automaticamente con il bucket S3 di supporto.

Flusso di montaggio di Amazon EFS

  1. Crei un file system EFS e monti i target nel tuo VPC (uno per zona di disponibilità).

  2. Create un punto di accesso EFS specificando il POSIX UID/GID e la directory principale.

  3. Si configura il browser (o la sessione) con l'ARN del punto di accesso, l'ARN del file system e il percorso di montaggio.

  4. All'inizio della sessione, effettua il AgentCore provisioning di una sandbox con accesso di rete al tuo VPC.

  5. La sandbox monta il file system NFSv4.1 tramite TLS (porta 2049) tramite la destinazione di montaggio nella stessa zona di disponibilità.

  6. L'agente legge e scrive i file nel percorso di montaggio utilizzando operazioni standard sui file.

Prerequisiti

Prima di configurare un file system bring-your-own, completate i seguenti prerequisiti.

Configurazione VPC

Il browser deve utilizzare la modalità di rete. VPC Le sottoreti specificate devono sovrapporsi alle zone di disponibilità della destinazione di montaggio del file system.

autorizzazioni IAM

Il ruolo di esecuzione del browser deve includere le autorizzazioni per montare il file system.

Autorizzazioni IAM per i file 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>"
    }
  }
}

Autorizzazioni IAM per 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>"
    }
  }
}

Ometti ClientWrite se il tuo agente necessita solo dell'accesso in lettura.

Gruppi di sicurezza

Consenti il protocollo TCP in uscita sulla porta 2049 dal gruppo di sicurezza del browser al gruppo di sicurezza mount target. Consenti il TCP in entrata sulla porta 2049 del gruppo di sicurezza mount target dal gruppo di sicurezza del browser.

Configurare i file system

Specifica ogni file system filesystemConfigurations come un s3FilesConfiguration o unefsConfiguration. Entrambi richiedono tre campi:

  • accessPointArn— L'ARN dei file S3 o del punto di accesso EFS da montare.

  • fileSystemArn— L'ARN del file system proprietario del punto di accesso. Questo campo è obbligatorio.

  • mountPath— Il percorso assoluto all'interno della sessione in cui è montato il punto di accesso (ad esempio,/mnt/s3data).

È possibile rifornire filesystemConfigurations in due punti, utilizzando la stessa forma:

  • Piano di controllo CreateBrowser — — I montaggi vengono ereditati da ogni sessione avviata dal browser. Il browser deve utilizzare la modalità di rete VPC.

  • Piano dati: StartBrowserSession — I montaggi si applicano a quella sessione specifica.

Nota

È possibile fornire configurazioni del file system sul piano di controllo (CreateBrowser), sul piano dati (StartBrowserSession) o su entrambi, a condizione che il browser utilizzi la modalità di rete VPC e l'access point S3 Files o EFS sia configurato correttamente (obiettivi di montaggio, autorizzazioni IAM e gruppi di sicurezza). Le configurazioni di CreateBrowser vengono ereditate da ogni sessione; le configurazioni da si applicano a quella sessione. StartBrowserSession Quando vengono forniti entrambi, vengono combinati per la sessione e ogni percorso di montaggio deve essere univoco all'interno del set combinato.

Le sezioni seguenti mostrano entrambe le chiamate API per ogni tipo di file system.

Configura un punto di accesso Amazon S3 Files

Piano di controllo: CreateBrowser

Esempio
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. Esempio di Python che utilizza boto3 per creare un browser con un punto di accesso 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"
            }
        }
    ]
)

Piano dati: StartBrowserSession

Esempio
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. Esempio di Python che utilizza boto3 per avviare una sessione del browser con un punto di accesso 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"]

Configura un punto di accesso Amazon EFS

Piano di controllo: CreateBrowser

Esempio
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. Esempio di Python che utilizza boto3 per creare un browser con un punto di accesso 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"
            }
        }
    ]
)

Piano dati: StartBrowserSession

Esempio
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. Esempio di Python che utilizza boto3 per avviare una sessione del browser con un punto di accesso 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"]

Combina i file system

Puoi collegare più punti di accesso (fino ai limiti seguenti) in una singola chiamata aggiungendo più voci afilesystemConfigurations. Ogni voce deve utilizzare un percorso di montaggio univoco.

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

Conferma i file system montati

GetBrowserUtilizzato per confermare la configurazione filesystemConfigurations su un browser e GetBrowserSession per confermare le configurazioni effettive durante una sessione in esecuzione. Le configurazioni impostate alla creazione del browser e all'avvio della sessione vengono entrambe visualizzate nella risposta della sessione.

Limits

I limiti di configurazione del file system vengono applicati per richiesta. CreateBrowserle configurazioni vengono ereditate da ogni sessione e le StartBrowserSession configurazioni si applicano a quella sessione. I montaggi effettivi di una sessione sono la combinazione di entrambi.

Tipo di configurazione Per CreateBrowser Per StartBrowserSession Combinato per sessione

Punti di accesso Amazon S3 Files

2

2

4

Punti di accesso Amazon EFS

2

2

4

Configurazioni totali del file system

4

4

8

Ad esempio, è possibile configurare 1 punto di accesso S3 Files e 1 punto di accesso EFSCreateBrowser, quindi aggiungere 1 punto di accesso S3 Files e 1 punto di accesso EFS attiviStartBrowserSession, per un totale di 4 montaggi nella sessione. Ogni percorso di montaggio deve essere univoco all'interno del set combinato.

Vincoli del percorso di montaggio

Tutte le configurazioni del file system devono seguire queste regole del percorso di montaggio:

  • Deve avere esattamente /mnt/ un livello di sottodirectory (ad esempio,/mnt/data,/mnt/s3data).

  • Modello: /mnt/[a-zA-Z0-9._-]+/?

  • Ogni percorso di montaggio deve essere univoco in tutte le configurazioni.

  • I percorsi di montaggio non possono essere sottodirectory l'uno dell'altro.

Risolvi i problemi relativi ai montaggi del file system

Quando il montaggio del file system bring-your-own non riesce, StartBrowserSession restituisce un errore e la sessione non viene ripristinata. READY

Caratteristiche Causa probabile Correzione rapida

«Accesso negato»

Ruolo di esecuzione mancante ClientMount o ClientWrite

Aggiungi le autorizzazioni IAM con la condizione AccessPointArn

ResourceNotFound"o «Risoluzione non riuscita»

Punto di accesso o destinazione di montaggio eliminati o non disponibili

Verifica che l'ARN esista e che le destinazioni di montaggio siano disponibili

Il montaggio si blocca quindi non riesce

Gruppo di sicurezza che blocca la porta 2049 o nessun target di montaggio nella zona di disponibilità della sessione

Consenti TCP 2049; verifica la sovrapposizione delle zone di disponibilità

«Autorizzazione negata» in fase di scrittura

Mancante ClientWrite o mancata corrispondenza in formato POSIX UID/GID

Aggiungi l'autorizzazione di scrittura o allinea l'utente POSIX del punto di accesso

Tutti i file system configurati vengono montati in parallelo all'inizio della sessione: un singolo errore di montaggio causa il fallimento dell'avvio della sessione.