View a markdown version of this page

Umgebung und Dateisystem - Amazon Grundgestein AgentCore
Befehle in der Umgebung ausführenBenutzerdefinierte Umgebung (Container-Images)UmgebungsvariablenDateisystem

Umgebung und Dateisystem

Jede Harness-Sitzung läuft auf einer isolierten MicroVM mit eigenem Dateisystem und eigener Shell. Diese Seite behandelt die Konfiguration der Ausführungsumgebung (Standard- oder benutzerdefinierter Container), das Ausführen von Befehlen direkt auf der VM, das Setzen von Umgebungsvariablen und das Mounten persistenter Dateisysteme.

Befehle in der Umgebung ausführen

Nicht alles muss die Agentenschleife durchlaufen. InvokeAgentRuntimeCommandbietet Ihnen direkten Shell-Zugriff auf die Harness-MicroVM: deterministische Befehlsausführung ohne Modellüberlegung, ohne Token-Kosten, ohne Mehrdeutigkeit.

Verwenden Sie es, um:

  • Führen Sie deterministische Skripten vor oder nach dem Aufruf aus.

  • Bereiten Sie die Umgebung vor einem Aufruf vor: Klonen Sie ein Repo, installieren Sie Abhängigkeiten, kopieren Sie Eingabedateien.

  • Handeln Sie nach dem, was der Agent produziert hat: Führen Sie Tests durch, führen Sie Commit und Push durch und extrahieren Sie Build-Artefakte.

  • Untersuchen Sie die virtuelle Maschine während der Entwicklung: lscat,env,, python --version ohne das Modell einmal durchgehen zu müssen.

Beispiel
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"
Anmerkung

Die Basisumgebung umfasst Python und Bash. Für Tools wie gitnode, oder andere Runtimes installieren Sie sie beim Sitzungsstart (z. B.apt-get install -y git) oder verwenden Sie eine benutzerdefinierte Umgebung.

Drücken Sie in der Benutzeroberfläche, ! um in den Exec-Modus zu wechseln und Befehle inline auszuführen.

Einzelheiten finden Sie unter InvokeAgentRuntimeCommand API.

Anmerkung

Befehle werden als Root (UID 0) innerhalb der MicroVM ausgeführt. Dies entspricht dem Rooten auf Ihrer eigenen EC2-Instanz — die IAM-Berechtigung ist das Zugriffstor, nicht die Rechtestufe innerhalb der VM. Wenn Ihr Dockerfile eine USER Direktive enthält, gilt diese nur für den Agent-Prozess (den Haupteinstiegspunkt des Containers). InvokeAgentRuntimeCommandwird für betriebliche Zwecke auf einer höheren Berechtigungsstufe ausgeführt, ähnlich der docker exec Standardeinstellung root, auch wenn der Container als Nicht-Root-Benutzer ausgeführt wird. Vollständige Informationen zu Sicherheit, Fehlerbehandlung und bewährten Methoden finden Sie unter Shell-Befehle in AgentCore Runtime-Sitzungen ausführen.

Benutzerdefinierte Umgebung (Container-Images)

Die Basisumgebung umfasst Python und Bash, genug für die meisten Aufgaben. Wenn Sie mehr benötigen, packen Sie Ihren Quellcode, Abhängigkeiten, Laufzeiten und Tools in ein Container-Image, übertragen Sie es in ECR und referenzieren Sie es im Harness. Ihr Agent wird in genau dieser Umgebung ausgeführt. Kombinieren Sie benutzerdefinierte Images mit InvokeAgentRuntimeCommand für eine sitzungsspezifische Einrichtung, die je nach Aufruf variiert.

Container-Images müssen für die Plattform erstellt werden. linux/arm64

Der Harness setzt den Ihres Containers außer Kraft ENTRYPOINT und sorgt CMD dafür, dass er als Umgebung am Laufen bleibt. Ihre installierte Software, das Dateisystem und die Umgebungsvariablen sind für den Agenten verfügbar; der Startbefehl Ihres Containers wird nicht ausgeführt. Wenn Sie einen Hintergrundprozess benötigen (z. B. einen Entwicklungsserver), starten Sie ihn über, InvokeAgentRuntimeCommand nachdem die Sitzung begonnen hat.

Beispiel
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."}]'

Die Ausführungsrolle benötigt ECR-Pull-Berechtigungen. Einzelheiten finden Sie in der Richtlinie für die Ausführungsrolle.

AgentCore CLI

Erstellen Sie ein Gerüst mit einem Dockerfile:

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

Bei der Bereitstellung erstellt die CLI das Image, überträgt es an ECR und hängt es an den Kabelbaum an.

Oder verweisen Sie auf ein vorgefertigtes Image:

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

Umgebungsvariablen

Legen Sie Umgebungsvariablen fest, die an den Runtime-Container übergeben werden. Umgebungsvariablen sind für den Agenten und jeden benutzerdefinierten Container verfügbar, der in der Sitzung ausgeführt wird.

Beispiel
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

Legen Sie Umgebungsvariablen fest inharness.json:

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

Zum agentcore deploy Anwenden ausführen.

Dateisystem

Das Harness mountet persistenten Speicher an von Ihnen angegebenen Pfaden. In diese Mounts geschriebene Dateien überstehen das Beenden der Sitzung und sind für spätere Aufrufe sichtbar.

Ein Harness unterstützt drei Dateisystemtypen:

  • Sitzungsspeicher — vom Service verwalteter, sitzungsspezifischer Speicher, der über mehrere stop/resume Zyklen hinweg für dieselbe gespeichert wird. runtimeSessionId Keine VPC erforderlich.

  • Amazon EFS Access Point — bringen Sie Ihr eigenes EFS-Dateisystem mit, das von mehreren Sitzungen und Agenten gemeinsam genutzt wird. VPC erforderlich.

  • Amazon S3 Files Access Point — bringen Sie Ihr eigenes S3 Files-Dateisystem mit, das bidirektional mit einem S3-Bucket synchronisiert wird. VPC erforderlich.

Informationen zu den Voraussetzungen (VPC-Netzwerk, IAM-Berechtigungen, Sicherheitsgruppen), Typvergleich, Beschränkungen und Lebenszyklusverhalten finden Sie unter Dateisystemkonfigurationen für AgentCore Runtime. Die gleichen Anforderungen gelten für Kabelbäume.

Konfiguration der Umgebung und des Dateisystems in der CLI AgentCore

Beispiel
Interactive

Führen Sie es agentcore in einem Projektverzeichnis aus, um die TUI zu öffnen, wählen Sie Hinzufügen und dann Harness aus. Der Assistent führt Sie durch die Ausführungsumgebung und, in den erweiterten Einstellungen, durch das persistente Dateisystem.

  1. Behalten Sie im Schritt Benutzerdefinierte Umgebung die Standardumgebung bei oder wählen Sie ein vorgefertigtes Container-Image (ECR-URI) oder ein Dockerfile aus.

    Assistent zum Hinzufügen von Harness: benutzerdefinierte Umgebung

  2. Dateisystem-Mounts erfordern den VPC-Modus. Aktivieren Sie daher in den erweiterten Einstellungen sowohl Netzwerk - als auch Dateisystemspeicher mit Leertaste und drücken Sie dann die Eingabetaste.

    Erweiterte Einstellungen bei aktiviertem Netzwerk- und Dateisystemspeicher

  3. Wählen Sie den VPC-Netzwerkmodus und geben Sie dann die Subnetze und Sicherheitsgruppen für den Harness an.

    Wählen Sie den VPC-Netzwerkmodus

  4. Legen Sie den Mountpfad für den Sitzungsspeicher fest (unter/mnt).

    Geben Sie den Mountpfad für den Sitzungsspeicher ein

  5. Um ein Amazon EFS-Dateisystem anzuhängen, geben Sie den ARN des EFS-Zugriffspunkts (und im nächsten Schritt seinen Mountpfad) ein.

    Geben Sie den ARN des EFS-Zugangspunkts ein

  6. Um Amazon S3 S3-Dateien anzuhängen, geben Sie den ARN des S3 Files-Zugriffspunkts (und seinen Bereitstellungspfad) ein.

    Geben Sie den ARN für den S3 Files-Zugriffspunkt ein

Bestätigen Sie den Assistenten und führen Sie ihn dann aus, agentcore deploy um die Anwendung durchzuführen.

Sitzungsspeicher

Dateien, die in den Mount-Pfad geschrieben wurden, bleiben stop/resume zyklusübergreifend bestehen, wenn Sie sie mit demselben aufrufen. runtimeSessionId

Beispiel
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

Amazon EFS-Zugriffspunkt

Hängen Sie einen EFS-Zugriffspunkt-ARN an einen Mountpfad unter an/mnt. Die Daten verbleiben in Ihrem Konto und können mit anderen Kabelbäumen oder Agentenlaufzeiten geteilt werden, die denselben Access Point bereitstellen.

Beispiel
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

Verbinden Sie einen EFS-Zugriffspunkt mit --efs-access-point as<accessPointArn>:<mountPath>. EFS erfordert den VPC-Netzwerkmodus:

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
Anmerkung

Der Bereitstellungspfad muss unter /mnt liegen. Das Flag ist wiederholbar (bis zu 2 EFS-Mounts); --network-mode VPC mit --subnets und --security-groups ist für EFS- und S3-Files-Mounts erforderlich.

Zugriffspunkt für Amazon S3 S3-Dateien

Hängen Sie einen S3 Files Access Point ARN an einen Mountpfad unter an/mnt. Dateien im Mount-Pfad werden bidirektional mit dem unterstützenden S3-Bucket synchronisiert.

Beispiel
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

Hängen Sie einen Zugriffspunkt für S3-Dateien mit --s3-access-point as an. <accessPointArn>:<mountPath> Für S3 Files ist der VPC-Netzwerkmodus erforderlich:

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
Anmerkung

Der ARN des Access Points selbst enthält Doppelpunkte; der Mountpfad stammt aus dem Segment nach dem letzten Doppelpunkt. Das Flag ist wiederholbar (bis zu 2 S3-Files-Mounts).

Wichtig

UpdateHarnessersetzt die gesamte filesystemConfigurations Liste. Um einem Kabelbaum, für den bereits Dateisysteme konfiguriert sind, einen neuen Mount hinzuzufügen, rufen Sie GetHarness zuerst auf und senden Sie dann die vollständige gewünschte Liste (bestehende Einträge plus die neue) ein. UpdateHarness

Erfahren Sie mehr: Dateisystemkonfigurationen für AgentCore Runtime.

Verwandte Themen