View a markdown version of this page

Ambiente e file system - Amazon Bedrock AgentCore
Esegui comandi nell'ambienteAmbiente personalizzato (immagini dei contenitori)Variabili di ambienteFilesystem

Ambiente e file system

Ogni sessione di cablaggio viene eseguita in una microVM isolata con il proprio filesystem e la propria shell. Questa pagina descrive la configurazione dell'ambiente di esecuzione (contenitore predefinito o personalizzato), l'esecuzione di comandi direttamente sulla macchina virtuale, l'impostazione delle variabili di ambiente e il montaggio di file system persistenti.

Esegui comandi nell'ambiente

Non tutto deve passare attraverso il ciclo degli agenti. InvokeAgentRuntimeCommandoffre accesso diretto tramite shell all'harness MicroVM: esecuzione deterministica dei comandi senza ragionamento del modello, nessun costo del token, nessuna ambiguità.

Usalo per:

  • Esegui script deterministici di preinvocazione o post-invocazione.

  • Prepara l'ambiente prima di una chiamata: clona un repository, installa le dipendenze, copia i file di input.

  • Agisci in base a ciò che l'agente ha prodotto: esegui test, esegui commit e push, estrai gli artefatti della build.

  • Ispeziona la macchina virtuale durante lo sviluppo:ls,cat,env, python --version senza ripetere il modello.

Esempio
AWS CLI/boto3
response = client.invoke_agent_runtime_command(
    agentRuntimeArn=HARNESS_ARN,
    runtimeSessionId=SESSION_ID,
    body={"command": "ls -la /workspace"},
)

for event in response["stream"]:
    chunk = event.get("chunk", {})
    if "contentDelta" in chunk:
        delta = chunk["contentDelta"]
        if "stdout" in delta:
            print(delta["stdout"], end="", flush=True)
        if "stderr" in delta:
            print(delta["stderr"], end="", flush=True)
    elif "contentStop" in chunk:
        print(f"\n[exit code: {chunk['contentStop']['exitCode']}]")
AgentCore CLI
# Install dependencies before the agent starts
agentcore invoke --exec --harness my-agent --session-id "$(uuidgen)" \
  "pip install pandas matplotlib"

# After the agent finishes, inspect what it created
agentcore invoke --exec --harness my-agent --session-id "$(uuidgen)" \
  "ls -la /tmp && cat /tmp/results.csv"
Nota

L'ambiente di base include Python e bash. Per strumenti come gitnode, o altri runtime, installali all'inizio della sessione (ad esempioapt-get install -y git) o usa un ambiente personalizzato.

Nella TUI, premi ! per accedere alla modalità exec ed eseguire i comandi in linea.

Vedi InvokeAgentRuntimeCommand API per i dettagli.

Nota

I comandi vengono eseguiti come root (uid 0) all'interno della microVM. È analogo al root sulla propria istanza EC2: l'autorizzazione IAM è la porta di accesso, non il livello di privilegio in-VM. Se il tuo Dockerfile include una USER direttiva, si applica solo al processo dell'agente (il punto di ingresso principale del contenitore). InvokeAgentRuntimeCommandviene eseguito con un livello di privilegio più elevato per scopi operativi, in modo simile a come docker exec impostazione predefinita è root anche quando il contenitore viene eseguito come utente non root. Vedi Esegui comandi di shell nelle sessioni AgentCore di runtime per tutti i dettagli sulla sicurezza, la gestione degli errori e le migliori pratiche.

Ambiente personalizzato (immagini dei contenitori)

L'ambiente di base include Python e bash, sufficienti per la maggior parte delle attività. Quando ne hai bisogno di più, impacchetta il codice sorgente, le dipendenze, i runtime e gli strumenti in un'immagine contenitore, inseriscila in ECR e fai riferimento ad essa sull'harness. Il tuo agente funziona esattamente in quell'ambiente. Associa immagini personalizzate InvokeAgentRuntimeCommand per una configurazione specifica della sessione che varia a seconda della chiamata.

Le immagini dei container devono essere create per la piattaforma. linux/arm64

Il cablaggio sostituisce quello del contenitore ENTRYPOINT e consente di CMD mantenerlo in esecuzione come ambiente. Il software, il file system e le variabili di ambiente installati sono disponibili per l'agente; il comando di avvio del contenitore non viene eseguito. Se hai bisogno di un processo in background (ad esempio un server di sviluppo), avvialo tramite InvokeAgentRuntimeCommand dopo l'inizio della sessione.

Esempio
AWS CLI/boto3
aws bedrock-agentcore-control create-harness \
  --harness-name "CodingAgent" \
  --execution-role-arn "arn:aws:iam::123456789012:role/MyHarnessRole" \
  --environment-artifact '{"containerConfiguration": {"containerUri": "123456789012.dkr.ecr.us-west-2.amazonaws.com/my-dev-env:latest"}}' \
  --system-prompt '[{"text": "You are an expert TypeScript developer."}]'

Il ruolo di esecuzione richiede i permessi di pull ECR. Consulta la politica del ruolo di esecuzione per i dettagli.

AgentCore CLI

Raccogli un cablaggio con un Dockerfile:

agentcore create --name coding-agent --container ./Dockerfile
agentcore deploy

Al momento dell'implementazione, la CLI crea l'immagine, la invia all'ECR e la collega al cablaggio.

Oppure fai riferimento a un'immagine predefinita:

agentcore create --name node-agent \
  --container public.ecr.aws/docker/library/node:slim
agentcore deploy

Variabili di ambiente

Imposta le variabili di ambiente che vengono passate al contenitore di runtime. Le variabili di ambiente sono disponibili per l'agente e per qualsiasi contenitore personalizzato in esecuzione nella sessione.

Esempio
AWS CLI/boto3
aws bedrock-agentcore-control create-harness \
  --harness-name "MyHarness" \
  --execution-role-arn "arn:aws:iam::123456789012:role/MyHarnessRole" \
  --environment-variables '{"MY_API_URL": "https://api.example.com", "LOG_LEVEL": "debug"}'
AgentCore CLI

Imposta le variabili di ambiente inharness.json:

{
  "environmentVariables": {
    "MY_API_URL": "https://api.example.com",
    "LOG_LEVEL": "debug"
  }
}

Esegui agentcore deploy per applicare.

Filesystem

Il cablaggio monta lo storage persistente nei percorsi specificati dall'utente. I file scritti su questi mount sopravvivono alla chiusura della sessione e sono visibili alle chiamate successive.

Un harness supporta tre tipi di file system:

  • Storage di sessione: storage per sessione gestito dal servizio che persiste per più cicli per la stessa sessione. stop/resume runtimeSessionId Non è richiesto alcun VPC.

  • Punto di accesso Amazon EFS: crea il tuo file system EFS, condiviso tra sessioni e agenti. È richiesto un VPC.

  • Punto di accesso Amazon S3 Files: crea il tuo file system S3 Files che si sincronizza bidirezionalmente con un bucket S3. È richiesto un VPC.

Per i prerequisiti (rete VPC, autorizzazioni IAM, gruppi di sicurezza), il confronto dei tipi, i limiti e il comportamento del ciclo di vita, consulta Configurazioni del file system per Runtime. AgentCore Gli stessi requisiti si applicano ai cablaggi.

Configurazione dell'ambiente e del file system nella CLI AgentCore

Esempio
Interactive

Esegui agentcore in una directory di progetto per aprire il TUI, seleziona aggiungi, quindi scegli Harness. La procedura guidata illustra l'ambiente di esecuzione e, nelle impostazioni avanzate, il filesystem persistente.

  1. Nella fase Ambiente personalizzato, mantieni l'ambiente predefinito o scegli un'immagine contenitore predefinita (URI ECR) o un Dockerfile.

    Add Harness wizard: ambiente personalizzato

  2. I montaggi dei file system richiedono la modalità VPC, quindi nelle impostazioni avanzate abilita sia l'archiviazione di rete che quella del file system con spazio, quindi premi Invio.

    Impostazioni avanzate con Network e Filesystem Storage abilitati

  3. Scegli la modalità di rete VPC, quindi fornisci le sottoreti e i gruppi di sicurezza per il cablaggio.

    Seleziona la modalità di rete VPC

  4. Imposta il percorso di montaggio dell'archiviazione della sessione (sotto/mnt).

    Immettere il percorso di montaggio dell'archiviazione della sessione

  5. Per collegare un file system Amazon EFS, inserisci l'ARN del punto di accesso EFS (e il relativo percorso di montaggio nel passaggio successivo).

    Immettere l'ARN del punto di accesso EFS

  6. Per allegare file Amazon S3, inserisci l'ARN del punto di accesso S3 Files (e il relativo percorso di montaggio).

    Inserisci l'ARN del punto di accesso S3 Files

Conferma la procedura guidata, quindi agentcore deploy esegui per applicare.

Archiviazione della sessione

I file scritti nel percorso di montaggio persistono tra i stop/resume cicli quando si richiama con lo stesso. runtimeSessionId

Esempio
AWS CLI/boto3
aws bedrock-agentcore-control update-harness \
  --harness-id "MyHarness-UuFdkQoXSL" \
  --environment '{"agentCoreRuntimeEnvironment": {"filesystemConfigurations": [{"sessionStorage": {"mountPath": "/mnt/data/"}}]}}'
AgentCore CLI
# At create time
agentcore create --name myagent --session-storage-mount-path /mnt/data/

# Or add to an existing harness
agentcore add harness --name my-agent --session-storage /mnt/data/
agentcore deploy

Punto di accesso Amazon EFS

Collega un ARN del punto di accesso EFS a un percorso di montaggio sotto. /mnt I dati persistono nell'account e possono essere condivisi con altri cablaggi o runtime di agenti che montano lo stesso punto di accesso.

Esempio
AWS CLI/boto3
aws bedrock-agentcore-control create-harness \
  --harness-name "SharedToolsAgent" \
  --execution-role-arn "arn:aws:iam::123456789012:role/MyHarnessRole" \
  --environment '{
    "agentCoreRuntimeEnvironment": {
      "networkConfiguration": {
        "networkMode": "VPC",
        "networkModeConfig": {
          "subnets": ["subnet-abc123", "subnet-def456"],
          "securityGroups": ["sg-abc123"]
        }
      },
      "filesystemConfigurations": [
        {
          "efsAccessPoint": {
            "accessPointArn": "arn:aws:elasticfilesystem:us-west-2:123456789012:access-point/fsap-0123456789abcdef0",
            "mountPath": "/mnt/efs"
          }
        }
      ]
    }
  }'
AgentCore CLI

Collega un access point EFS con --efs-access-point as<accessPointArn>:<mountPath>. EFS richiede la modalità di rete VPC:

agentcore add harness --name shared-tools-agent \
  --network-mode VPC \
  --subnets subnet-abc123,subnet-def456 \
  --security-groups sg-abc123 \
  --efs-access-point arn:aws:elasticfilesystem:us-west-2:123456789012:access-point/fsap-0123456789abcdef0:/mnt/efs
agentcore deploy
Nota

Il percorso di montaggio deve essere inferiore /mnt a. Il flag è ripetibile (fino a 2 montaggi EFS); --network-mode VPC con --subnets ed --security-groups è necessario per i montaggi EFS e S3 Files.

Punto di accesso Amazon S3 Files

Collega un ARN del punto di accesso S3 Files a un percorso di montaggio sotto. /mnt I file sul percorso di montaggio si sincronizzano bidirezionalmente con il bucket S3 di supporto.

Esempio
AWS CLI/boto3
aws bedrock-agentcore-control create-harness \
  --harness-name "DataAgent" \
  --execution-role-arn "arn:aws:iam::123456789012:role/MyHarnessRole" \
  --environment '{
    "agentCoreRuntimeEnvironment": {
      "networkConfiguration": {
        "networkMode": "VPC",
        "networkModeConfig": {
          "subnets": ["subnet-abc123", "subnet-def456"],
          "securityGroups": ["sg-abc123"]
        }
      },
      "filesystemConfigurations": [
        {
          "s3FilesAccessPoint": {
            "accessPointArn": "arn:aws:s3files:us-west-2:123456789012:file-system/fs-0123456789abcdef0/access-point/fsap-0123456789abcdef0",
            "mountPath": "/mnt/s3data"
          }
        }
      ]
    }
  }'
AgentCore CLI

Collega un punto di accesso S3 Files con as. --s3-access-point <accessPointArn>:<mountPath> S3 Files richiede la modalità di rete VPC:

agentcore add harness --name data-agent \
  --network-mode VPC \
  --subnets subnet-abc123,subnet-def456 \
  --security-groups sg-abc123 \
  --s3-access-point arn:aws:s3files:us-west-2:123456789012:file-system/fs-0123456789abcdef0/access-point/fsap-0123456789abcdef0:/mnt/s3data
agentcore deploy
Nota

Lo stesso ARN del punto di accesso contiene due punti; il percorso di montaggio viene preso dal segmento dopo i due punti finali. Il flag è ripetibile (vengono montati fino a 2 file S3).

Importante

UpdateHarnesssostituisce l'intero elenco. filesystemConfigurations Per aggiungere un nuovo mount a un harness su cui sono già configurati i filesystem, chiamate GetHarness prima, poi inviate l'elenco completo desiderato (le voci esistenti più quella nuova). UpdateHarness

Per saperne di più: Configurazioni dei file system per Runtime. AgentCore

Argomenti correlati