View a markdown version of this page

Configurazioni del file system per AgentCore Code Interpreter - 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 AgentCore Code Interpreter

AgentCore Code Interpreter supporta il montaggio dei propri file system in sessioni di interprete di codice tramite il parametro. filesystemConfigurations 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ù interpreti di codice o applicazioni esterne possono accedere contemporaneamente allo stesso punto di accesso. I dati vengono conservati e gestiti nel tuo account. AWS

Puoi fornire filesystemConfigurations quando crei un interprete di codice con CreateCodeInterpreter (ogni sessione avviata da quell'interprete di codice eredita i mount) o quando inizi una sessione con StartCodeInterpreterSession (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 Code Interpreter non offre un'opzione di archiviazione delle sessioni gestita. Code Interpreter supporta solo i file Amazon S3 Bring Your Own e i 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 interpreti di codice 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 interpreti di codice 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:ClientMounts3files:ClientWrite, e s3files:GetAccessPoint al tuo ruolo di interprete di codice di esecuzione con una s3files:AccessPointArn condizione.

  2. Consenti l'uscita della porta TCP 2049 dal gruppo di sicurezza dell'interprete di codice 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 dell'interprete di codice.

  4. Aggiungilo filesystemConfigurations con una s3FilesConfiguration voce alla tua chiamata. CreateCodeInterpreter StartCodeInterpreterSession

  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 tuo ruolo di esecuzione dell'interprete di codice con una elasticfilesystem:AccessPointArn condizione.

  2. Consenti l'uscita della porta TCP 2049 dal gruppo di sicurezza dell'interprete di codice al gruppo di sicurezza di destinazione del montaggio EFS.

  3. Verifica che la destinazione di montaggio EFS si trovi nella stessa zona di disponibilità di almeno una delle sottoreti dell'interprete di codice.

  4. Aggiungilo filesystemConfigurations con una efsConfiguration voce alla tua CreateCodeInterpreter chiamata. StartCodeInterpreterSession

  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 sull'interprete di codice.

Come funziona

Quando si configura un file system bring-your-own, AgentCore Code Interpreter monta il punto di accesso specificato nella sandbox della sessione nel percorso configurato. I dati sono condivisi: più sessioni, più interpreti di codice 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 l'interprete del codice (o 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 l'interprete del codice (o 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

L'interprete di codice 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 dell'interprete di codice 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 dell'interprete di codice al gruppo di sicurezza mount target. Consenti il TCP in ingresso sulla porta 2049 del gruppo di sicurezza mount target dal gruppo di sicurezza dell'interprete del codice.

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 — CreateCodeInterpreter — I montaggi vengono ereditati da ogni sessione avviata dall'interprete del codice. L'interprete di codice deve utilizzare la modalità di rete VPC.

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

Nota

È possibile fornire configurazioni del file system sul piano di controllo (CreateCodeInterpreter), sul piano dati (StartCodeInterpreterSession) o su entrambi, a condizione che l'interprete del codice 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 CreateCodeInterpreter vengono ereditate da ogni sessione; le configurazioni da si applicano a quella sessione. StartCodeInterpreterSession 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: CreateCodeInterpreter

Esempio
AWS CLI

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

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

Piano dati: StartCodeInterpreterSession

Esempio
AWS CLI

  1. aws bedrock-agentcore start-code-interpreter-session \
  --code-interpreter-identifier "<code-interpreter-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 di interprete di codice con un punto di accesso S3 Files.

    import boto3

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

response = dp.start_code_interpreter_session(
    codeInterpreterIdentifier="<code-interpreter-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: CreateCodeInterpreter

Esempio
AWS CLI

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

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

Piano dati: StartCodeInterpreterSession

Esempio
AWS CLI

  1. aws bedrock-agentcore start-code-interpreter-session \
  --code-interpreter-identifier "<code-interpreter-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 di interprete di codice con un punto di accesso EFS.

    import boto3

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

response = dp.start_code_interpreter_session(
    codeInterpreterIdentifier="<code-interpreter-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

Usalo GetCodeInterpreter per confermarlo filesystemConfigurations su un interprete di codice e GetCodeInterpreterSession per confermare le configurazioni effettive durante una sessione in esecuzione. Le configurazioni impostate alla creazione dell'interprete di codice e all'inizio della sessione vengono entrambe visualizzate nella risposta della sessione.

Limits

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

Tipo di configurazione Per CreateCodeInterpreter Per StartCodeInterpreterSession 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 EFSCreateCodeInterpreter, quindi aggiungere 1 punto di accesso S3 Files e 1 punto di accesso EFS attiviStartCodeInterpreterSession, 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, StartCodeInterpreterSession 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.