View a markdown version of this page

Ambiente e file system - Fondamento Amazon AgentCore
Esegui comandi sull'ambienteAmbiente personalizzato (immagini dei contenitori)Variabili di ambienteFile 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à.

Ambiente e file system

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

Esegui comandi sull'ambiente

Non tutto deve passare attraverso il ciclo degli agenti. InvokeAgentRuntimeCommandconsente di accedere direttamente dalla shell all'harness MicroVM: esecuzione deterministica dei comandi senza alcun ragionamento basato sui modelli, nessun costo in termini di token, nessuna ambiguità.

Usalo per:

  • Esegui script deterministici di pre-invocazione 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 di compilazione.

  • Ispeziona la VM durante lo sviluppo:ls,, catenv, python --version senza dover passare attraverso 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 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. Questo è analogo al root sulla tua istanza EC2: l'autorizzazione IAM è il gate di accesso, non il livello di privilegio in-VM. Se il tuo Dockerfile include una USER direttiva, questa si applica solo al processo dell'agente (il punto di ingresso principale del contenitore). InvokeAgentRuntimeCommandviene eseguito a un livello di privilegi più elevato per scopi operativi, in modo simile a come docker exec predefinito è root anche quando il contenitore viene eseguito come utente non root. Vedi Execute shell commands in AgentCore Runtime sessions per tutti i dettagli sulla sicurezza, sulla gestione degli errori e sulle best practice.

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ù, raccogli il codice sorgente, le dipendenze, i runtime e gli strumenti in un'immagine contenitore, inviala a ECR e fai riferimento ad essa sull'harness. Il tuo agente opera esattamente in quell'ambiente. Associa immagini personalizzate InvokeAgentRuntimeCommand per una configurazione specifica della sessione che varia in base alla chiamata.

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

Il cablaggio ha la precedenza su quello del container ENTRYPOINT e serve CMD a mantenerlo funzionante come ambiente. Il software installato, il file system e le variabili di ambiente 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 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 pull ECR. Per i dettagli, consulta la politica del ruolo di esecuzione.

AgentCore CLI

Crea un'imbracatura con un Dockerfile:

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

Al momento del deployment, la CLI crea l'immagine, la invia a ECR e la collega all'harness.

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

File system

L'harness monta l'archiviazione persistente nei percorsi specificati dall'utente. I file scritti su questi mount sopravvivono alla fine della sessione e sono visibili alle chiamate successive.

Un harness supporta tre tipi di file system:

  • Archiviazione delle sessioni: archiviazione per sessione gestita 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. VPC richiesto.

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

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

Configura l'ambiente e il file system nella CLI AgentCore

Esempio
Interactive

Esegui agentcore in una directory di progetto per aprire la TUI, seleziona aggiungi, quindi scegli Harness. La procedura guidata ti guida nell'ambiente di esecuzione e, nelle impostazioni avanzate, nel filesystem persistente.

  1. Nella fase Ambiente personalizzato, mantieni l'ambiente predefinito o scegli un'immagine del contenitore precompilata (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 Network che Filesystem Storage with Space, quindi premi Invio.

    Impostazioni avanzate con Network and Filesystem Storage abilitato

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

    Inserisci 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 nella fase successiva).

    Inserisci l'ARN del punto di accesso EFS

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

    Inserisci il punto di accesso S3 Files (ARN)

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

Memorizzazione delle sessioni

I file scritti nel percorso di montaggio persistono per più stop/resume cicli quando vengono richiamati 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 punto di accesso EFS ARN a un percorso di montaggio sottostante/mnt. I dati rimangono nel tuo account e possono essere condivisi con altri harness o runtime degli 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 punto di accesso EFS con as. --efs-access-point <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. Il flag è ripetibile (fino a 2 montaggi EFS); --network-mode VPC con --subnets ed --security-groups è richiesto per i montaggi di file EFS e S3.

Punto di accesso Amazon S3 Files

Collega un punto di accesso S3 Files ARN a un percorso di montaggio sotto. /mnt I file sul percorso di montaggio si sincronizzano in modo bidirezionale 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 access point ARN 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 in cui sono già configurati i filesystem, chiamate GetHarness prima, poi inviate l'elenco completo desiderato (le voci esistenti più quella nuova) in. UpdateHarness

Per saperne di più: configurazioni del file system per Runtime. AgentCore

Argomenti correlati