Switching an Agent’s File System Like Building Blocks with Deep Agents Backend

Backend Overview

In Deep Agents, a Backend implements the BackendProtocol, a unified IO interface that provides file‑system‑like operations ( ls, read_file, write_file, edit_file, glob, grep) and command execution ( execute). The upper‑level Agent calls these tools without needing to know whether the underlying storage is in‑memory, local disk, a LangGraph Store, or a remote sandbox.

Official Backend Options

StateBackend

Persistence: No

Cross‑process: No

Typical use: demos, unit tests, quick prototypes where files may disappear after the process ends.

FilesystemBackend

Persistence: Yes (local disk)

Cross‑process: No

Typical use: local development, single‑service CI artifacts.

StoreBackend

Persistence: Yes (LangGraph Store)

Cross‑process: Yes

Typical use: multi‑instance services, long‑term memory, production persistence.

LocalShellBackend

Persistence: Yes (local disk)

Cross‑process: No

Typical use: executing commands on the host shell without isolation.

LangSmithSandbox

Persistence: Remote‑hosted

Cross‑process: Depends on platform

Typical use: hosted sandbox execution environments.

CompositeBackend

Persistence & cross‑process behavior: Determined by routing configuration.

Typical use: projects where different path prefixes map to different storage backends.

StateBackend vs FilesystemBackend

If no backend is supplied, StateBackend is used by default. Example:

from deepagents import create_deep_agent

agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-6",
)

This backend stores files only in memory; they disappear when the process exits.

To write files to a real directory, instantiate FilesystemBackend with a root_dir. Setting virtual_mode=True maps virtual paths (e.g., /foo.txt) to real locations under root_dir:

from deepagents import create_deep_agent
from deepagents.backends import FilesystemBackend

agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-6",
    backend=FilesystemBackend(
        root_dir="/tmp/project",
        virtual_mode=True,
    ),
)

root_dir

is not a security boundary; virtual_mode merely controls path translation.

StoreBackend for Production Persistence

StoreBackend

delegates file operations to a LangGraph Store. During development an InMemoryStore can be used; in production it can be swapped for a persistent store such as Postgres.

from deepagents import create_deep_agent
from deepagents.backends import StoreBackend
from langgraph.store.memory import InMemoryStore

store = InMemoryStore()
agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-6",
    backend=StoreBackend(store=store),
)

The key difference from FilesystemBackend is cross‑process sharing: the same Store can be accessed by multiple Agent processes, enabling multi‑worker workloads, long‑running tasks, or user sessions that need shared output.

CompositeBackend as Path Router

CompositeBackend

lets different path prefixes route to distinct backends. Example configuration:

from deepagents.backends import CompositeBackend, StateBackend, StoreBackend, FilesystemBackend

backend = CompositeBackend(
    default=StateBackend(),
    routes={
        "/memories/": StoreBackend(store=...),
        "/workspace/": FilesystemBackend(root_dir="/tmp/workspace", virtual_mode=True),
    },
)

Typical routing semantics: /tmp/ → temporary intermediate state →

StateBackend

/memories/

→ long‑term rules & preferences →

StoreBackend

/workspace/

→ code and artifacts → FilesystemBackend Trailing slashes matter; /memories and /memories/ are distinct. Sub‑Agents inherit the parent’s backend unless they explicitly override it.

LocalShellBackend and Isolation

When an Agent needs to run commands such as pytest, ruff, npm build, or git, LocalShellBackend executes them directly on the host shell without process isolation.

Suitable scenarios:

Personal local development

Temporary CI workspaces

Controlled internal automation tasks

Unsuitable scenarios:

Public user‑provided input

Multi‑tenant code execution

Untrusted code

Tasks requiring strict network or file isolation

For true isolation, switch to containers, VMs, or remote sandboxes; the Backend itself does not provide security guarantees.

Selection Order

Development phase: use StateBackend for fast iteration without persisting files.

When output inspection is needed: switch to FilesystemBackend to store artifacts on disk.

Multi‑instance or long‑term storage: adopt StoreBackend so files and memory are shared across processes.

When command execution is required: consider LocalShellBackend for local development; use a sandbox or container in production.

Complex path semantics: employ CompositeBackend to separate temporary files, long‑term memory, and workspace storage.

Additional Notes

The BackendProtocol follows a duck‑typing style: any object that implements the required read/write/retrieve/execute methods can be used as a backend. Implementing a custom S3 or MinIO backend is straightforward if the built‑in options do not meet a specific need.