Backends

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 Types

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

Quick Examples

StateBackend (Default)

In-memory, ephemeral storage. Files are stored in the agent's state and lost when the agent ends.

import { createDeepAgent, StateBackend } from "deepagents";

const agent = createDeepAgent({
  backend: new StateBackend(),
});

StoreBackend

Persistent storage using LangGraph Store. Files persist across agent runs.

import { createDeepAgent, StoreBackend } from "deepagents";
import { InMemoryStore } from "@langchain/langgraph";

const store = new InMemoryStore();
const agent = createDeepAgent({
  backend: new StoreBackend({ store }),
});

FilesystemBackend

Store files on the actual filesystem. Useful for agents that need to interact with real files.

import { createDeepAgent, FilesystemBackend } from "deepagents";

const agent = createDeepAgent({
  backend: new FilesystemBackend({
    rootDir: "/path/to/workspace",
  }),
});

CompositeBackend

Combine multiple backends for layered storage strategies. Reads check backends in order; writes go to the primary backend.

import { createDeepAgent, CompositeBackend, StateBackend, FilesystemBackend } from "deepagents";

// State backend for scratch files, filesystem for persistent output
const agent = createDeepAgent({
  backend: new CompositeBackend({
    primary: new StateBackend(),
    fallbacks: [new FilesystemBackend({ rootDir: "/workspace" })],
  }),
});

Sandbox Backends

For agents that need to run shell commands in isolated environments, extend BaseSandbox to implement your own sandbox integration.

API Reference