Dateisystemkonfigurationen für AgentCore Runtime

AgentCore Runtime unterstützt persistente Dateisysteme über den filesystemConfigurations Parameter. Bei jeder Konfiguration wird Speicher in einem von Ihnen angegebenen Pfad bereitgestellt. Sie benötigen keinen benutzerdefinierten Mount-Code, keine privilegierten Container oder Download-Orchestrierung.

AgentCore Runtime unterstützt zwei Kategorien von Dateisystemkonfigurationen:

Sie können beide Kategorien in einer einzigen Agent-Runtime kombinieren (bis zu 5 Gesamtkonfigurationen).

Speicheroptionen auf einen Blick

In der folgenden Tabelle werden die verfügbaren Dateisystem-Konfigurationstypen verglichen.

Schnellstart

Die folgenden Checklisten enthalten zusammengefasste Schritte zur Konfiguration der einzelnen Dateisystemtypen.

Verwalteter Sitzungsspeicher (Vorschau)

Bring-your-own Dateisystem

Zugriffspunkt für Amazon S3 S3-Dateien

Amazon EFS-Zugriffspunkt

Sowohl S3 Files als auch EFS erfordern VPC-Konnektivität in der Agent-Laufzeit.

So funktionieren die einzelnen Typen

In den folgenden Abschnitten wird beschrieben, wie die einzelnen Dateisystemtypen in AgentCore Runtime funktionieren.

Bring-your-own Dateisysteme

Wenn Sie ein Bring-Your-Own-Dateisystem konfigurieren, hängt AgentCore Runtime den angegebenen Access Point an dem von Ihnen konfigurierten Pfad in jede Sitzung ein. Daten werden gemeinsam genutzt — mehrere Sitzungen, mehrere Agenten oder externe Anwendungen können gleichzeitig auf dasselbe Dateisystem zugreifen.

AgentCore verarbeitet alle Mount-Operationen automatisch. Sie müssen keine Mount-Helper installieren, TLS-Zertifikate verwalten oder Mount-Code in Ihren Agenten schreiben.

Einhängeablauf für Amazon S3 S3-Dateien

Wenn Sie einen S3 Files-Zugriffspunkt konfigurieren, erfolgt die folgende Reihenfolge:

Semantik von S3-Dateien

Amazon EFS-Bereitstellungsablauf

Wenn Sie einen EFS-Zugriffspunkt konfigurieren, erfolgt die folgende Reihenfolge:

EFS-Semantik

Verwalteter Sitzungsspeicher (Vorschau)

Behalten Sie den Sitzungsstatus in stop/resume einer Dateisystemkonfiguration unter Verwendung von verwaltetem Sitzungsspeicher bei. AgentCore Runtime Managed Session Storage ist eine vollständig vom Service verwaltete Funktion, bei der AgentCore Runtime alle Speichervorgänge abwickelt. Ihr Agent liest und schreibt in ein lokales Dateisystem-Mount, und die Laufzeitumgebung repliziert Daten während der gesamten Sitzungsdauer transparent in den Servicespeicher.

Der Sitzungsspeicher ist pro Sitzung isoliert — jede Sitzung kann nur auf ihren eigenen Speicher zugreifen und kann keine Daten aus anderen Sitzungen derselben Agent-Laufzeit oder aus Sitzungen mit unterschiedlichen Agent-Laufzeiten lesen oder schreiben.

Wenn Sie den Sitzungsspeicher auf einer Agent-Laufzeit konfigurieren, erhält jede Sitzung ein persistentes Verzeichnis unter dem von Ihnen angegebenen Mountpfad. Der Lebenszyklus funktioniert wie folgt:

Semantik des Dateisystems

Der Sitzungsspeicher stellt ein standardmäßiges Linux-Dateisystem in Ihrem konfigurierten Mount-Pfad bereit. Standardtools und -operationen funktionieren ohne Änderungen —ls,cat,mkdir,git,npm,pip,, und cargo alle funktionieren wie erwartet.

Unterstützte Operationen

Reguläre Dateien, Verzeichnisse und Symlinks. Lesen, Schreiben, Umbenennen, Löschen,, chmod chownstat, und readdir — standardmäßige POSIX-Dateioperationen, die von gängigen Entwicklungstools verwendet werden.

Beschränkungen

Informationen zu Speicherbeschränkungen für Sitzungen, einschließlich maximaler Speichergröße, Dateianzahl und Verzeichnistiefe, finden Sie unter Speicherbeschränkungen für Sitzungen.

Nicht unterstützte Operationen

Die folgenden Dateisystemoperationen werden nicht unterstützt:

Lebenszyklus des Sitzungsspeichers

In den folgenden Szenarien werden Sitzungsdaten gelöscht (auf einen sauberen Zustand zurückgesetzt):

Verwenden Sie DeleteAgentRuntimeoder DeleteAgentRuntimeEndpoint, um alle Sitzungsspeicherdaten zu löschen, die der Laufzeit oder dem Endpunkt zugeordnet sind.

Voraussetzungen für das Mitbringen eigener Dateisysteme

Bevor Sie ein Bring-Your-Own-Dateisystem konfigurieren, müssen Sie die folgenden Voraussetzungen erfüllen.

VPC-Konfiguration

Ihre Agent-Runtime muss verwenden. networkMode: VPC Die von Ihnen angegebenen Subnetze müssen sich mit den Availability Zones der Ziel-Availability Zones des Dateisystems überschneiden.

IAM-Berechtigungen

Ihre Runtime-Ausführungsrolle für Agenten muss Berechtigungen zum Mounten des Dateisystems enthalten.

IAM-Berechtigungen für S3-Dateien

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

IAM-Berechtigungen für 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>"
    }
  }
}

Lassen Sie diese Option ausClientWrite, wenn Ihr Agent nur Lesezugriff benötigt. Die s3files:GetAccessPoint Berechtigung ist für die Validierung des S3 Files-Zugriffspunkts während der Erstellung der Agenten-Laufzeit erforderlich.

Sicherheitsgruppen

Erlauben Sie ausgehendes TCP auf Port 2049 von Ihrer Agent-Runtime-Sicherheitsgruppe zur Mount-Zielsicherheitsgruppe. Lassen Sie eingehendes TCP auf Port 2049 der Mount-Zielsicherheitsgruppe von der Runtime-Sicherheitsgruppe des Agenten zu.

Dateisysteme konfigurieren

In den folgenden Abschnitten wird gezeigt, wie die einzelnen Dateisystemtypen konfiguriert werden.

Konfigurieren Sie einen Amazon S3 Files-Zugriffspunkt

Um einen Zugriffspunkt für S3 Files zu konfigurieren, geben Sie den ARN und den Mountpfad des Zugriffspunkts in anfilesystemConfigurations. Ihre Agenten-Laufzeit muss den VPC-Netzwerkmodus verwenden.

Konfiguration eines Amazon EFS-Zugriffspunkts

Um einen EFS-Zugriffspunkt zu konfigurieren, geben Sie den Zugriffspunkt-ARN und den Mountpfad in anfilesystemConfigurations. Ihre Agenten-Laufzeit muss den VPC-Netzwerkmodus verwenden.

Konfigurieren Sie den verwalteten Sitzungsspeicher

Fügen Sie filesystemConfigurations beim Erstellen oder Aktualisieren einer Agenten-Laufzeit einen sessionStorage Eintrag hinzu.

Sie können auch Sitzungsspeicher zu einer vorhandenen Agenten-Laufzeit hinzufügen, indem Sie denselben UpdateAgentRuntimefilesystemConfigurationsParameter verwenden.

Kombinieren Sie Dateisysteme

Sie können verwalteten Sitzungsspeicher mit eigenen Dateisystemen in einer Runtime mit nur einem Agenten kombinieren. Im folgenden Beispiel werden alle drei Typen konfiguriert.

import boto3

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

response = client.create_agent_runtime(
    agentRuntimeName="full-stack-agent",
    roleArn="arn:aws:iam::<account-id>:role/AgentExecutionRole",
    networkConfiguration={
        "networkMode": "VPC",
        "networkModeConfig": {
            "subnets": ["<subnet-id-1>", "<subnet-id-2>"],
            "securityGroups": ["<security-group-id>"]
        }
    },
    agentRuntimeArtifact={
        "containerConfiguration": {
            "containerUri": "<account-id>.dkr.ecr.<region>.amazonaws.com/my-agent:latest"
        }
    },
    filesystemConfigurations=[
        {
            "s3FilesAccessPoint": {
                "accessPointArn": "arn:aws:s3files:<region>:<account-id>:file-system/<file-system-id>/access-point/<access-point-id>",
                "mountPath": "/mnt/datasets"
            }
        },
        {
            "efsAccessPoint": {
                "accessPointArn": "arn:aws:elasticfilesystem:<region>:<account-id>:access-point/<access-point-id>",
                "mountPath": "/mnt/tools"
            }
        },
        {
            "sessionStorage": {
                "mountPath": "/mnt/workspace"
            }
        }
    ]
)

Rufen Sie persistenten Speicher auf und verwenden Sie ihn

Alle konfigurierten Dateisysteme sind in ihren Mount-Pfaden verfügbar, wenn Ihr Agent aufgerufen wird. Bring-your-own Dateisysteme (S3-Dateien, EFS) sind bei jedem Aufruf sofort zugänglich. Der verwaltete Sitzungsspeicher speichert Daten stop/resume zyklusübergreifend und verwendet dasselbe. runtimeSessionId

Beispiel: Sitzungsspeicher zyklusübergreifend stop/resume verwenden

# First invocation — agent sets up the project
aws bedrock-agentcore invoke-agent-runtime \
  --agent-runtime-arn "arn:aws:bedrock-agentcore:us-west-2:111122223333:agent-runtime/coding-agent" \
  --runtime-session-id "session-001" \
  --payload '{"prompt": "Set up the project and install dependencies in /mnt/workspace"}'

# Stop the session
aws bedrock-agentcore stop-runtime-session \
  --agent-runtime-arn "arn:aws:bedrock-agentcore:us-west-2:111122223333:agent-runtime/coding-agent" \
  --runtime-session-id "session-001"

# Resume later — the project is exactly where the agent left it
aws bedrock-agentcore invoke-agent-runtime \
  --agent-runtime-arn "arn:aws:bedrock-agentcore:us-west-2:111122223333:agent-runtime/coding-agent" \
  --runtime-session-id "session-001" \
  --payload '{"prompt": "Run the tests and fix any failures"}'

Der Agent sieht /mnt/workspace genau so, wie er es verlassen hat — Quelldateien, installierte Pakete, Build-Artefakte und der .git-Verlauf sind alle intakt. Wenn Sie eine Sitzung wieder aufnehmen, hängt die neue Rechenumgebung den persistenten Speicher ein. Ihr Agent kann weiterarbeiten, ohne Pakete neu zu installieren oder Dateien neu zu generieren.

Einschränkungen

In der folgenden Tabelle sind die Grenzwerte für Dateisystemkonfigurationen aufgeführt.

Einschränkungen für den Mount-Pfad

Alle Dateisystemkonfigurationen müssen diesen Mount-Pfadregeln entsprechen:

Verhalten im Lebenszyklus

In der folgenden Tabelle wird das Lebenszyklusverhalten zwischen verwaltetem Sitzungsspeicher und Bring-Your-Own-Dateisystemen verglichen.

Anwendungsfälle

In der folgenden Tabelle sind die gängigen Muster und die jeweils empfohlene Dateisystemkonfiguration aufgeführt.

Beispiel: Codierungsagent mit persistentem Workspace

Dieses Beispiel zeigt einen Codierungsagenten, der Strands Agents FileSessionManager für den Konversationsverlauf und die Sitzungsspeicherung für Projektdateien verwendet. Beide bleiben stop/resume zyklusübergreifend bestehen.

Codierungsagent mit Sitzungsspeicher

import os

# Enable non-interactive mode for strands tools
os.environ["BYPASS_TOOL_CONSENT"] = "true"

from strands import Agent
from strands.session import FileSessionManager
from strands.models import BedrockModel
from strands_tools import file_read, file_write, shell
from bedrock_agentcore.runtime import BedrockAgentCoreApp

app = BedrockAgentCoreApp()
WORKSPACE = "/mnt/workspace"

model = BedrockModel(model_id="us.anthropic.claude-sonnet-4-20250514-v1:0")
tools = [file_read, file_write, shell]

@app.entrypoint
def handle_request(payload):
    session_id = payload.get("session_id", "default")

    # Persist conversation history alongside project files
    session_manager = FileSessionManager(
        session_id=session_id,
        storage_dir=f"{WORKSPACE}/.sessions"
    )

    agent = Agent(
        model=model,
        tools=tools,
        session_manager=session_manager,
        system_prompt="You are a coding assistant. Project files are in /mnt/workspace."
    )

    response = agent(payload.get("prompt"))
    return {"response": response.message["content"][0]["text"]}

if __name__ == "__main__":
    app.run()

requirements.txt

strands-agents
strands-agents-tools
bedrock-agentcore
boto3

Rufen Sie den Agenten auf, beenden Sie die Sitzung und setzen Sie sie dann fort. Sowohl die Projektdateien als auch der Konversationskontext bleiben bestehen.

Zyklus aufrufen, beenden und fortsetzen

import boto3, json

client = boto3.client("bedrock-agentcore")
agent_arn = "arn:aws:bedrock-agentcore:us-west-2:111122223333:agent-runtime/coding-agent"
session_id = "project-xyz-001"

def invoke(prompt):
    resp = client.invoke_agent_runtime(
        agentRuntimeArn=agent_arn,
        runtimeSessionId=session_id,
        payload=json.dumps({"prompt": prompt, "session_id": "conv-001"}).encode()
    )
    return json.loads(b"".join(resp["response"]))["response"]

# First invoke: Create a simple script
invoke("Write a Python script called calculator.py with add and subtract functions.")

# Stop session — compute terminates, storage persists
client.stop_runtime_session(agentRuntimeArn=agent_arn, runtimeSessionId=session_id)

# Resume same session — new compute, but files and conversation history restored
invoke("Add a multiply function to the script you created.")
# Agent knows it created calculator.py (conversation history)
# AND finds existing file (file persistence)

FileSessionManagerSpeichert den Konversationsverlauf unter/mnt/workspace/.sessions/, sodass sich der Agent den Kontext stop/resume zyklusübergreifend merken kann.

Netzwerkanforderungen

In diesem Abschnitt werden die Netzwerkanforderungen für verwaltete Sitzungsspeicher und Bring-Your-Own-Dateisysteme behandelt.

Netzwerke mit verwaltetem Sitzungsspeicher

Wenn Ihre Agenten-Laufzeit den VPC-Modus mit Sitzungsspeicher verwendet, benötigt der Agent Netzwerkzugriff, um mit dem Remotespeicher zu synchronisieren. Sitzungsdaten werden in AgentCore S3 gespeichert, daher muss Ihre VPC ausgehende Konnektivität zu S3 zulassen. Wenn Sie einen S3-Gateway-Endpunkt mit einer benutzerdefinierten Richtlinie verwenden, können Sie den Zugriff auf Ihren regionalen Sitzungsspeicher-Bucket wie folgt einschränken:

"Action": [
    "s3:GetObject",
    "s3:PutObject",
    "s3:ListBucket"
],
"Resource": [
    "arn:aws:s3:::acr-storage-*-region-an",
    "arn:aws:s3:::acr-storage-*-region-an/*"
],
"Condition": {
    "StringEquals": {
        "aws:PrincipalServiceName": "bedrock-agentcore.amazonaws.com"
    }
}

regionErsetzen Sie es durch Ihre AWS Region (z. B.us-west-2).

Bring-your-own Dateisystem-Netzwerke

Bring-your-own Dateisysteme erfordern, dass Ihr VPC-Netzwerk die folgenden Anforderungen für erfolgreiche Mounts erfüllt.

Amazon EFS

So überprüfen Sie Ihre EFS-Mount-Ziele:

aws efs describe-mount-targets --file-system-id fs-0123456789abcdef0 --region us-west-2

Vollständige Informationen zu EFS-Mount-Zielen finden Sie unter So funktioniert Amazon EFS.

Amazon S3 Files

So überprüfen Sie Ihre S3-Files-Mount-Ziele:

aws s3files list-mount-targets --file-system-id fs-0123456789abcdef0 --region us-west-2

Vollständige Informationen zum Mounten von S3-Dateien finden Sie unter Mounten von S3-Dateisystemen.

Gemeinsame Anforderungen

Wie hängt AgentCore Dateisysteme ein

AgentCore wickelt den NFS-Mount-Vorgang innerhalb der MicroVM automatisch ab:

Sie müssen TLS-Zertifikate nicht installieren amazon-efs-utils/etc/fstab, konfigurieren oder verwalten. Die MicroVM-Runtime verarbeitet alle Mount-Operationen, die Rotation der Anmeldeinformationen und die Zustandsüberwachung.

Auswahl von Subnetz und Availability Zone

Wenn Sie sowohl VPC-Subnetze als auch Dateisystemkonfigurationen auf einer Agent-Runtime konfigurieren, wählen Sie Subnetze aus, die sich mit Ihren Dateisystem-Mount-Ziel-Availability Zones überschneiden.

So ermitteln Sie die Availability Zone-ID Ihrer Subnetze:

aws ec2 describe-subnets \
  --subnet-ids subnet-0123456789abcdef0 \
  --query 'Subnets[0].AvailabilityZoneId'

So identifizieren Sie die Availability Zone Ihrer EFS-Mount-Ziele:

aws efs describe-mount-targets \
  --file-system-id fs-0123456789abcdef0 \
  --query 'MountTargets[*].[AvailabilityZoneId, LifeCycleState]' \
  --output table

Stellen Sie sicher, dass sich Ihre Agent-Runtime-Subnetze in Availability Zones befinden, in denen Ihr Dateisystem Mount-Ziele hat.

Informationen zu unterstützten Availability Zones nach Regionen finden Sie unter Unterstützte Availability Zones im Thema VPC-Konfiguration. Informationen zur Konfiguration von Sicherheitsgruppen finden Sie unter Beispiel: Verbindung zu Amazon EFS- oder Amazon S3 S3-Dateien herstellen.

Beheben Sie Fehler beim Einhängen von Dateisystemen, bei denen Sie Ihr eigenes System mitbringen

Wenn das Einhängen eines Dateisystems, bei dem Sie Ihr eigenes System verwenden, fehlschlägt, wird HTTP 424 (Failed Dependency) zurückgegeben. InvokeAgentRuntime

Jeder Mount hat einen Timeout von 30 Sekunden. Alle konfigurierten Dateisysteme werden parallel bereitgestellt — ein einziger Fehler führt dazu, dass der gesamte Aufruf fehlschlägt.

Weitere Informationen finden Sie unter Problembehandlung bei BYO-Speicher.