Backends

​

Quickstart

​

Built-in backends

​

StateBackend (ephemeral)

import { createDeepAgent, StateBackend } from "deepagents";

// By default we provide a StateBackend
const agent = createDeepAgent();

// Under the hood, it looks like
const agent2 = createDeepAgent({
  backend: (rt) => new StateBackend(rt),   // Note that the tools access State through the runtime.state
});

• Stores files in LangGraph agent state for the current thread.
• Persists across multiple agent turns on the same thread via checkpoints.

• A scratch pad for the agent to write intermediate results.
• Automatic eviction of large tool outputs which the agent can then read back in piece by piece.

​

FilesystemBackend (local disk)

import { createDeepAgent, FilesystemBackend } from "deepagents";

const agent = createDeepAgent({
  backend: new FilesystemBackend({ rootDir: ".", virtualMode: true }),
});

• Reads/writes real files under a configurable root_dir.
• You can optionally set virtual_mode=True to sandbox and normalize paths under root_dir.
• Uses secure path resolution, prevents unsafe symlink traversal when possible, can use ripgrep for fast grep.

• Local projects on your machine
• CI sandboxes
• Mounted persistent volumes

​

StoreBackend (LangGraph Store)

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

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

• Stores files in a LangGraph BaseStore provided by the runtime, enabling cross‑thread durable storage.

• When you already run with a configured LangGraph store (for example, Redis, Postgres, or cloud implementations behind BaseStore).
• When you’re deploying your agent through LangSmith Deployments (a store is automatically provisioned for your agent).

​

CompositeBackend (router)

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

const compositeBackend = (rt) => new CompositeBackend(
  new StateBackend(rt),
  {
    "/memories/": new StoreBackend(rt),
  }
);

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

• Routes file operations to different backends based on path prefix.
• Preserves the original path prefixes in listings and search results.

• When you want to give your agent both ephemeral and cross-thread storage, a CompositeBackend allows you provide both a StateBackend and StoreBackend
• When you have multiple sources of information that you want to provide to your agent as part of a single filesystem.
  • e.g. You have long-term memories stored under /memories/ in one Store and you also have a custom backend that has documentation accessible at /docs/.

​

Specify a backend

• Pass a backend to create_deep_agent(backend=...). The filesystem middleware uses it for all tooling.
• You can pass either:
  • An instance implementing BackendProtocol (for example, FilesystemBackend(root_dir=".")), or
  • A factory BackendFactory = Callable[[ToolRuntime], BackendProtocol] (for backends that need runtime like StateBackend or StoreBackend).
• If omitted, the default is lambda rt: StateBackend(rt).

​

Route to different backends

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

const compositeBackend = (rt) => new CompositeBackend(
  new StateBackend(rt),
  {
    "/memories/": new FilesystemBackend({ rootDir: "/deepagents/myagent", virtualMode: true }),
  },
);

const agent = createDeepAgent({ backend: compositeBackend });

• /workspace/plan.md → StateBackend (ephemeral)
• /memories/agent.md → FilesystemBackend under /deepagents/myagent
• ls, glob, grep aggregate results and show original path prefixes.

• Longer prefixes win (for example, route "/memories/projects/" can override "/memories/").
• For StoreBackend routing, ensure the agent runtime provides a store (runtime.store).

​

Use a virtual filesystem

• Paths are absolute (/x/y.txt). Decide how to map them to your storage keys/rows.
• Implement ls_info and glob_info efficiently (server-side listing where available, otherwise local filter).
• Return user-readable error strings for missing files or invalid regex patterns.
• For external persistence, set files_update=None in results; only in-state backends should return a files_update dict.

• Table files(path text primary key, content text, created_at timestamptz, modified_at timestamptz)
• Map tool operations onto SQL:
  • ls_info uses WHERE path LIKE $1 || '%'
  • glob_info filter in SQL or fetch then apply glob in Python
  • grep_raw can fetch candidate rows by extension or last modified time, then scan lines

​

Add policy hooks

​

Protocol reference

• ls_info(path: str) -> list[FileInfo]
  • Return entries with at least path. Include is_dir, size, modified_at when available. Sort by path for deterministic output.
• read(file_path: str, offset: int = 0, limit: int = 2000) -> str
  • Return numbered content. On missing file, return "Error: File '/x' not found".
• grep_raw(pattern: str, path: Optional[str] = None, glob: Optional[str] = None) -> list[GrepMatch] | str
  • Return structured matches. For an invalid regex, return a string like "Invalid regex pattern: ..." (do not raise).
• glob_info(pattern: str, path: str = "/") -> list[FileInfo]
  • Return matched files as FileInfo entries (empty list if none).
• write(file_path: str, content: str) -> WriteResult
  • Create-only. On conflict, return WriteResult(error=...). On success, set path and for state backends set files_update={...}; external backends should use files_update=None.
• edit(file_path: str, old_string: str, new_string: str, replace_all: bool = False) -> EditResult
  • Enforce uniqueness of old_string unless replace_all=True. If not found, return error. Include occurrences on success.

• WriteResult(error, path, files_update)
• EditResult(error, path, files_update, occurrences)
• FileInfo with fields: path (required), optionally is_dir, size, modified_at.
• GrepMatch with fields: path, line, text.