deep-agent-backends

Deep Agent Backends

Configure how your Deep Agent stores files and manages context. Backends determine where files live — in memory, on disk, in a database, or in a sandbox.

When to Use

• When choosing between ephemeral vs persistent storage
• When the agent needs local filesystem access
• When you need shell execution capability
• When routing different paths to different storage
• When running in sandboxed environments (Modal, Daytona)

Available Operations

1. Use StateBackend (ephemeral, default)
2. Use FilesystemBackend (local disk)
3. Use StoreBackend (persistent, cross-thread)
4. Use LocalShellBackend (filesystem + shell)
5. Use CompositeBackend (route paths to backends)
6. Use Sandboxes (isolated execution)

Multi-Step Workflow

Step 1: Choose Your Backend

Backend	Persistence	Shell	Use when
StateBackend	Ephemeral (1 thread)	No	Prototyping, stateless tasks
FilesystemBackend	Local disk	No	Read/write project files
StoreBackend	DB (cross-thread)	No	Persistent memory, multi-session
LocalShellBackend	Local disk	Yes	Full coding agent (like Claude Code)
CompositeBackend	Mixed	Mixed	Different storage per path
Sandboxes	Isolated	Yes	Untrusted code execution

Step 2: StateBackend (Default)

from deepagents import create_deep_agent

# Uses StateBackend automatically — files live in memory, gone after session
agent = create_deep_agent(model="anthropic:claude-sonnet-4-6")

Step 3: FilesystemBackend (Local Files)

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=".", virtual_mode=True)
)
# Agent can now read/write files in the project directory

Step 4: LocalShellBackend (Full Coding Agent)

from deepagents import create_deep_agent
from deepagents.backends import LocalShellBackend

# WARNING: Agent can execute shell commands on your machine
agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-6",
    backend=LocalShellBackend(
        root_dir=".",
        env={"PATH": "/usr/bin:/bin", "HOME": "/home/user"}
    )
)
# Agent can now: read/write files, run shell commands, install packages