Skip to content
Strands Harness
PYPython SDKTSTypeScript SDK
Strands
EVEvalsSHShell
Organizations
strands-agentsstrands-labs

strands.storage.storage

Unified storage interface and key-normalization helpers.

Storage

Section titled “Storage”
@runtime_checkable
class Storage(Protocol[ListQuery])

Defined in: src/strands/storage/storage.py:69

A backend for storing and retrieving raw bytes under string keys.

The interface is deliberately minimal — four operations over opaque bytes values. Implementations must treat keys as opaque path-like strings (segments separated by ’/’) and must round-trip the bytes they are given unchanged.

The ListQuery type parameter controls what list accepts. It defaults to str (a key prefix), which every backend supports. Implementations may widen it to accept a richer query object while still accepting a plain string for SDK-internal callers.

Implement this to add a custom backend; the SDK ships :class:InMemoryStorage, :class:LocalFileStorage, and :class:S3Storage.

write

Section titled “write”
async def write(key: str, data: bytes) -> None

Defined in: src/strands/storage/storage.py:85

Store data under key, overwriting any existing value.

Arguments:

  • key - Opaque, ’/‘-separated key identifying the value.
  • data - Raw bytes to persist.

Raises:

  • StorageError - If the write fails.

read

Section titled “read”
async def read(key: str) -> bytes | None

Defined in: src/strands/storage/storage.py:97

Retrieve the bytes previously stored under key.

Arguments:

  • key - The key to read.

Returns:

The stored bytes, or None if no value exists for key.

Raises:

  • StorageError - If the read fails for a reason other than a missing key.

delete

Section titled “delete”
async def delete(key: str) -> None

Defined in: src/strands/storage/storage.py:111

Delete the value stored under key. A no-op if the key does not exist.

Arguments:

  • key - The key to delete.

Raises:

  • StorageError - If the delete fails.

list

Section titled “list”
async def list(query: ListQuery) -> builtins.list[str]

Defined in: src/strands/storage/storage.py:122

List keys matching the given prefix query.

Returns full keys (not the suffix after the prefix), sorted lexicographically. An empty string lists every key.

Arguments:

  • query - A string prefix to match.

Returns:

The matching keys, sorted ascending.

Raises:

  • StorageError - If the listing fails.

_NamespacedStorage

Section titled “_NamespacedStorage”
class _NamespacedStorage()

Defined in: src/strands/storage/storage.py:140

A storage view that prepends a prefix to all keys.

Composable — calling .namespace() on the result nests prefixes.

write

Section titled “write”
async def write(key: str, data: bytes) -> None

Defined in: src/strands/storage/storage.py:153

Store data under the prefixed key.

read

Section titled “read”
async def read(key: str) -> bytes | None

Defined in: src/strands/storage/storage.py:157

Read from the prefixed key.

delete

Section titled “delete”
async def delete(key: str) -> None

Defined in: src/strands/storage/storage.py:161

Delete the prefixed key.

list

Section titled “list”
async def list(query: str = "") -> builtins.list[str]

Defined in: src/strands/storage/storage.py:165

List keys under the prefix, stripping it from results.

namespace

Section titled “namespace”
def namespace(prefix: str) -> _NamespacedStorage

Defined in: src/strands/storage/storage.py:170

Return a further-scoped view by nesting prefixes.

for_sandbox

Section titled “for_sandbox”
def for_sandbox(sandbox: object) -> _NamespacedStorage

Defined in: src/strands/storage/storage.py:174

Delegate sandbox binding to the underlying storage and re-wrap.