Backends control how deep agents store files and manage state. Choose a backend based on your persistence and isolation requirements.
Learn more: For detailed guidance on choosing and configuring backends, see the Backends documentation.
| Backend | Persistence | Use Case |
|---|---|---|
StateBackend |
Ephemeral (in-memory) | Default; files lost when agent ends |
StoreBackend |
Persistent | Files persist across agent runs using LangGraph Store |
FilesystemBackend |
Persistent | Real filesystem access for file-based workflows |
CompositeBackend |
Mixed | Layer multiple backends for complex strategies |
from deepagents import create_deep_agent
# StateBackend is used by default
agent = create_deep_agent()from deepagents import create_deep_agent
from deepagents.backends import StoreBackend
from langgraph.store.memory import InMemoryStore
agent = create_deep_agent(
backend=StoreBackend,
store=InMemoryStore(),
)from deepagents import create_deep_agent
from deepagents.backends import FilesystemBackend
agent = create_deep_agent(
backend=FilesystemBackend(root_dir="./agent-workspace"),
)For agents that need to execute shell commands in isolated environments, extend the BaseSandbox class to implement your own sandbox integration.
Backend that stores files in agent state (ephemeral).
Backend that stores files in LangGraph's BaseStore (persistent).
Backend that reads and writes files directly from the filesystem.
Routes file operations to different backends by path prefix.
Base sandbox implementation with execute() as abstract method.
Extension of BackendProtocol that adds shell command execution.
Protocol for pluggable memory backends (single, unified).
Sanitize tool_call_id to prevent path traversal and separator issues.
Format file content with line numbers (cat -n style).
Check if content is empty and return warning message.
Convert FileData to plain string content.
Create a FileData object with timestamps.
Update FileData with new content, preserving creation timestamp.
Format file data for read response with line numbers.
Perform string replacement with occurrence validation.
Truncate list or string result if it exceeds token limit (rough estimate: 4 chars/token).
Validate and normalize file path for security.
Return structured grep matches from an in-memory files mapping.
Group structured matches into the legacy dict form used by formatters.
Format structured grep matches using existing formatting logic.