Persist session state across stop/resume with a filesystem configuration (Preview)

Agents built on Amazon Bedrock AgentCore Runtime maintain their local state during the compute lifecycle and by default, the compute associated with a session is ephemeral. Every session boots into a clean filesystem, and if the session is stopped or terminated, invoking the same session again will get a new compute and a clean filesystem. Modern agents don't just chat — they write code, install packages, generate artifacts, and manage state through the filesystem.

AgentCore Runtime managed session storage changes this. Session storage is a fully service-managed capability where AgentCore Runtime handles all storage operations. Your agent reads and writes to a local filesystem mount and the runtime environment transparently replicates data to service storage throughout the session duration. Session storage is isolated per session — each session can only access its own storage and cannot read or write data from other sessions of the same agent runtime or sessions of different agent runtimes.

How session storage works

When you configure session storage on an agent runtime, each session gets a persistent directory at the mount path you specify. The lifecycle works as follows:

Configure session storage

Add filesystemConfigurations with a sessionStorage entry when creating or updating an agent runtime.

You can also add session storage to an existing agent runtime using UpdateAgentRuntime with the same filesystemConfigurations parameter.

Invoke with session storage

Invoke the agent with a runtimeSessionId. Everything your agent writes to the configured mount path persists across stop/resume cycles.

# 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"}'

The agent sees /mnt/workspace exactly as it left it. Source files, node_modules, build artifacts, .git history — everything. No re-installing packages. No re-generating boilerplate. No warm-up before the agent can do useful work.

The session's compute environment spun down hours ago. But the filesystem was already persisted. When you resume, a new compute environment mounts the same storage, and your agent picks up mid-thought.

Filesystem semantics

Session storage provides a standard Linux filesystem at your configured mount path. Standard tools and operations work without modification — ls, cat, mkdir, git, npm, pip, and cargo all work as expected.

Supported operations

Regular files, directories, and symlinks. Read, write, rename, delete, chmod, chown, stat, and readdir — standard POSIX file operations used by common development tools.

Limits

For session storage limits including maximum storage size, file count, and directory depth, see Session storage limits.

Unsupported operations

The following filesystem operations are not supported:

Session storage lifecycle

Session data is deleted (reset to a clean state) in the following scenarios:

Use DeleteAgentRuntime or DeleteAgentRuntimeEndpoint to delete all session storage data associated with the runtime or endpoint.

Use cases

Example: Coding agent with persistent workspace

This example shows a coding agent using Strands Agents with FileSessionManager for conversation history and session storage for project files. Both persist across stop/resume cycles.

Coding agent with session storage

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

Invoke the agent, stop the session, then resume. Both project files and conversation context persist.

Invoke, stop, and resume cycle

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)

The FileSessionManager stores conversation history to /mnt/workspace/.sessions/, enabling the agent to remember context across stop/resume cycles.

Networking requirements

If your agent runtime uses VPC mode with session storage, the agent will need network access to sync with remote storage. Session data is stored in AgentCore S3, so your VPC must allow outbound connectivity to S3. If you are using an S3 Gateway endpoint with a custom policy, you can scope access to your regional session storage bucket as follows:

"Resource": [
    "arn:aws:s3:::acr-storage-account-id-region-an",
    "arn:aws:s3:::acr-storage-account-id-region-an/*"
]

Replace region with your AWS Region (for example, us-west-2) and account-id with the account ID for your region from the table below. The required actions are s3:GetObject and s3:PutObject.