feat: update to use new backend APIs (#3417)

Author: sydney-runkle

src/oss/deepagents/acp.mdx

@@ -368,7 +368,7 @@ await server.start();
 | `tools`        | `StructuredTool[]`                             | Custom LangChain tools                            |
 | `systemPrompt` | `string`                                       | Custom system prompt                              |
 | `middleware`    | `AgentMiddleware[]`                            | Custom middleware                                 |
-| `backend`      | `AnyBackendProtocol \| BackendFactory`         | Filesystem backend                                |
+| `backend`      | `AnyBackendProtocol`                           | Filesystem backend                                |
 | `skills`       | `string[]`                                     | Skill source paths                                |
 | `memory`       | `string[]`                                     | Memory source paths (AGENTS.md)                   |
 | `interruptOn`  | `Record<string, boolean \| InterruptOnConfig>` | Tools requiring user approval (HITL)              |
@@ -479,7 +479,7 @@ const server = new DeepAgentsServer({
           prefix: "/workspace",
           backend: new FilesystemBackend({ rootDir: "./workspace" }),
         },
-        { prefix: "/", backend: (config) => new StateBackend(config) },
+        { prefix: "/", backend: new StateBackend() },
       ],
     }),
   },

src/oss/deepagents/backends.mdx

@@ -63,7 +63,7 @@ Here are a few prebuilt filesystem backends that you can quickly use with your d
 |---|---|
 | [Default](#statebackend-ephemeral) | `agent = create_deep_agent()` <br></br> Ephemeral in state. The default filesystem backend for an agent is stored in `langgraph` state. Note that this filesystem only persists _for a single thread_. |
 | [Local filesystem persistence](#filesystembackend-local-disk) | `agent = create_deep_agent(backend=FilesystemBackend(root_dir="/Users/nh/Desktop/"))` <br></br>This gives the deep agent access to your local machine's filesystem. You can specify the root directory that the agent has access to. Note that any provided `root_dir` must be an absolute path. |
-| [Durable store (LangGraph store)](#storebackend-langgraph-store) | `agent = create_deep_agent(backend=lambda rt: StoreBackend(rt))` <br></br>This gives the agent access to long-term storage that is _persisted across threads_. This is great for storing longer term memories or instructions that are applicable to the agent over multiple executions. |
+| [Durable store (LangGraph store)](#storebackend-langgraph-store) | `agent = create_deep_agent(backend=StoreBackend())` <br></br>This gives the agent access to long-term storage that is _persisted across threads_. This is great for storing longer term memories or instructions that are applicable to the agent over multiple executions. |
 | [Sandbox](/oss/deepagents/sandboxes) | `agent = create_deep_agent(backend=sandbox)` <br></br>Execute code in isolated environments. Sandboxes provide filesystem tools plus the `execute` tool for running shell commands. Choose from Modal, Daytona, Deno, or local VFS. |
 | [Local shell](#localshellbackend-local-shell) | `agent = create_deep_agent(backend=LocalShellBackend(root_dir=".", env={"PATH": "/usr/bin:/bin"}))` <br></br>Filesystem and shell execution directly on the host. No isolation—use only in controlled development environments. See [security considerations](#localshellbackend-local-shell) below. |
 | [Composite](#compositebackend-router) | Ephemeral by default, `/memories/` persisted. The Composite backend is maximally flexible. You can specify different routes in the filesystem to point towards different backends. See Composite routing below for a ready-to-paste example. |
@@ -212,6 +212,8 @@ Use with extreme caution and only in appropriate environments.
 
 A namespace factory controls where `StoreBackend` reads and writes data. It receives a `BackendContext` and returns a tuple of strings used as the store namespace. Use namespace factories to isolate data between users, tenants, or assistants.
 
+Pass the namespace factory to the `namespace` parameter when constructing a `StoreBackend`:
+
 ```python
 NamespaceFactory = Callable[[BackendContext], tuple[str, ...]]
 ```
@@ -230,22 +232,19 @@ from langgraph.config import get_config
 from deepagents.backends import StoreBackend
 
 # Per-user: each user gets their own isolated storage
-backend = lambda rt: StoreBackend(
-    rt,
+backend = StoreBackend(
     namespace=lambda ctx: (ctx.runtime.context.user_id,),
 )
 
 # Per-assistant: all users of the same assistant share storage
-backend = lambda rt: StoreBackend(
-    rt,
+backend = StoreBackend(
     namespace=lambda ctx: (
         get_config()["metadata"]["assistant_id"],
     ),
 )
 
 # Per-thread: storage scoped to a single conversation
-backend = lambda rt: StoreBackend(
-    rt,
+backend = StoreBackend(
     namespace=lambda ctx: (
         get_config()["configurable"]["thread_id"],
     ),
@@ -259,20 +258,20 @@ import { getConfig } from "@langchain/langgraph";
 import { StoreBackend } from "deepagents";
 
 // Per-user: each user gets their own isolated storage
-const backend = (rt) => new StoreBackend(rt, {
+const backend = new StoreBackend({
   namespace: (ctx) => [ctx.runtime.context.userId],
 });
 
 // Per-assistant: all users of the same assistant share storage
-const backend = (rt) => new StoreBackend(rt, {
+const backend = new StoreBackend({
   namespace: (ctx) => {
     const config = getConfig();
     return [config.metadata.assistantId];
   },
 });
 
 // Per-thread: storage scoped to a single conversation
-const backend = (rt) => new StoreBackend(rt, {
+const backend = new StoreBackend({
   namespace: (ctx) => {
     const config = getConfig();
     return [config.configurable.threadId];
@@ -322,19 +321,15 @@ Namespace components must contain only alphanumeric characters, hyphens, undersc
 ## Specify a backend
 
 :::python
-- 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)`.
+- Pass a backend instance to `create_deep_agent(backend=...)`. The filesystem middleware uses it for all tooling.
+- The backend must implement `BackendProtocol` (for example, `StateBackend()`, `FilesystemBackend(root_dir=".")`, `StoreBackend()`).
+- If omitted, the default is `StateBackend()`.
 :::
 
 :::js
-- Pass a backend to `createDeepAgent({ backend: ... })`. The filesystem middleware uses it for all tooling.
-- You can pass either:
-    - An instance implementing `AnyBackendProtocol` (`BackendProtocolV1` or `BackendProtocolV2`) — for example, `new FilesystemBackend({ rootDir: "." })`, or
-    - A `BackendFactory` function `(stateAndStore: StateAndStore) => AnyBackendProtocol` — for backends that need runtime state or a store, like `StateBackend` or `StoreBackend`.
-- If omitted, the default is `(config) => new StateBackend(config)`.
+- Pass a backend instance to `createDeepAgent({ backend: ... })`. The filesystem middleware uses it for all tooling.
+- The backend must implement `AnyBackendProtocol` (`BackendProtocolV1` or `BackendProtocolV2`) — for example, `new StateBackend()`, `new FilesystemBackend({ rootDir: "." })`, `new StoreBackend()`.
+- If omitted, the default is `new StateBackend()`.
 
 <Note>
 Before version 1.9.0, only `BackendProtocol` was supported which is now `BackendProtocolV1`. V1 backends are automatically adapted to V2 at runtime via `adaptBackendProtocol()`. No code changes are required to keep using existing V1 backends. To update to v2, see [update existing backends to v2](#update-existing-backends-to-v2).
@@ -351,29 +346,29 @@ Route parts of the namespace to different backends. Commonly used to persist `/m
 from deepagents import create_deep_agent
 from deepagents.backends import CompositeBackend, StateBackend, FilesystemBackend
 
-composite_backend = lambda rt: CompositeBackend(
-    default=StateBackend(rt),
-    routes={
-        "/memories/": FilesystemBackend(root_dir="/deepagents/myagent", virtual_mode=True),
-    },
+agent = create_deep_agent(
+    backend=CompositeBackend(
+        default=StateBackend(),
+        routes={
+            "/memories/": FilesystemBackend(root_dir="/deepagents/myagent", virtual_mode=True),
+        },
+    )
 )
-
-agent = create_deep_agent(backend=composite_backend)
 ```
 :::
 
 :::js
 ```typescript
 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 });
+const agent = createDeepAgent({
+  backend: new CompositeBackend(
+    new StateBackend(),
+    {
+      "/memories/": new FilesystemBackend({ rootDir: "/deepagents/myagent", virtualMode: true }),
+    },
+  ),
+});
 ```
 :::
 
@@ -384,7 +379,7 @@ Behavior:
 
 Notes:
 - Longer prefixes win (for example, route `"/memories/projects/"` can override `"/memories/"`).
-- For StoreBackend routing, ensure the agent runtime provides a store (`runtime.store`).
+- For StoreBackend routing, ensure a store is provided via `create_deep_agent(store=...)` or provisioned by the platform.
 
 ## Use a virtual filesystem
 
@@ -716,7 +711,106 @@ type FileData =
     };
 ```
 
-Backends may encounter either format when reading from state or store. The framework handles both transparently. New writes default to the v2 format. During rolling deployments where older readers need the legacy format, pass `fileFormat: "v1"` to the backend constructor (e.g., `new StoreBackend(rt, { fileFormat: "v1" })`).
+Backends may encounter either format when reading from state or store. The framework handles both transparently. New writes default to the v2 format. During rolling deployments where older readers need the legacy format, pass `fileFormat: "v1"` to the backend constructor (e.g., `new StoreBackend({ fileFormat: "v1" })`).
+:::
+
+## Migrate from backend factories
+
+<Warning>
+The backend factory pattern is **deprecated**. Pass pre-constructed backend instances directly instead of factory functions.
+</Warning>
+
+Previously, backends like `StateBackend` and `StoreBackend` required a factory function that received a runtime object, because they needed runtime context (state, store) to operate. Backends now resolve this context internally via LangGraph's `get_config()`, `get_store()`, and `get_runtime()` helpers, so you can pass instances directly.
+
+### What changed
+
+| Before (deprecated) | After |
+|---|---|
+| `backend=lambda rt: StateBackend(rt)` | `backend=StateBackend()` |
+| `backend=lambda rt: StoreBackend(rt)` | `backend=StoreBackend()` |
+| `backend=lambda rt: CompositeBackend(default=StateBackend(rt), ...)` | `backend=CompositeBackend(default=StateBackend(), ...)` |
+| `backend: (config) => new StateBackend(config)` | `backend: new StateBackend()` |
+| `backend: (config) => new StoreBackend(config)` | `backend: new StoreBackend()` |
+
+### Deprecated APIs
+
+:::python
+
+| Deprecated | Replacement |
+|---|---|
+| Passing a callable to `backend=` in `create_deep_agent` | Pass a backend instance directly |
+| `runtime` constructor argument on `StateBackend(runtime)` | `StateBackend()` (no arguments needed) |
+| `runtime` constructor argument on `StoreBackend(runtime)` | `StoreBackend()` or `StoreBackend(namespace=..., store=...)` |
+| `files_update` field on `WriteResult` and `EditResult` | State writes are now handled internally by the backend |
+| `Command` wrapping in middleware write/edit tools | Tools return plain strings; no `Command(update=...)` needed |
+
+:::
+
+:::js
+
+| Deprecated | Replacement |
+|---|---|
+| `BackendFactory` type | Pass a backend instance directly |
+| `BackendRuntime` interface | Backends resolve context internally |
+| `StateBackend(runtime, options?)` constructor overload | `new StateBackend(options?)` |
+| `StoreBackend(stateAndStore, options?)` constructor overload | `new StoreBackend(options?)` |
+| `filesUpdate` field on `WriteResult` and `EditResult` | State writes are now handled internally by the backend |
+
+:::
+
+<Note>
+The factory pattern still works at runtime and emits a deprecation warning. Update your code to use direct instances before the next major version.
+</Note>
+
+### Migration example
+
+:::python
+```python
+# Before (deprecated)
+from deepagents import create_deep_agent
+from deepagents.backends import CompositeBackend, StateBackend, StoreBackend
+
+agent = create_deep_agent(
+    backend=lambda rt: CompositeBackend(
+        default=StateBackend(rt),
+        routes={"/memories/": StoreBackend(rt, namespace=lambda ctx: (ctx.runtime.context.user_id,))},
+    ),
+)
+
+# After
+agent = create_deep_agent(
+    backend=CompositeBackend(
+        default=StateBackend(),
+        routes={"/memories/": StoreBackend(namespace=lambda ctx: (ctx.runtime.context.user_id,))},
+    ),
+)
+```
+:::
+
+:::js
+```typescript
+// Before (deprecated)
+import { createDeepAgent, CompositeBackend, StateBackend, StoreBackend } from "deepagents";
+
+const agent = createDeepAgent({
+  backend: (config) => new CompositeBackend(
+    new StateBackend(config),
+    { "/memories/": new StoreBackend(config, {
+      namespace: (ctx) => [ctx.runtime.context.userId],
+    }) },
+  ),
+});
+
+// After
+const agent = createDeepAgent({
+  backend: new CompositeBackend(
+    new StateBackend(),
+    { "/memories/": new StoreBackend({
+      namespace: (ctx) => [ctx.runtime.context.userId],
+    }) },
+  ),
+});
+```
 :::
 
 ## Protocol reference

src/oss/deepagents/context-engineering.mdx

@@ -466,9 +466,9 @@ import { InMemoryStore } from "@langchain/langgraph-checkpoint";
 const agent = await createDeepAgent({
   model: "claude-sonnet-4-6",
   store: new InMemoryStore(),
-  backend: (config) => new CompositeBackend(
-    new StateBackend(config),
-    { "/memories/": new StoreBackend(config) },
+  backend: new CompositeBackend(
+    new StateBackend(),
+    { "/memories/": new StoreBackend() },
   ),
   systemPrompt: `When users tell you their preferences, save them to /memories/user_preferences.txt so you remember them in future conversations.`,
 });

src/oss/deepagents/customization.mdx

@@ -665,7 +665,7 @@ You can pass one or more file paths to the `memory` parameter when creating your
     )
 
     agent = create_deep_agent(
-        backend=(lambda rt: StoreBackend(rt)),
+        backend=StoreBackend(),
         store=store,
         memory=[
             "/AGENTS.md"
@@ -771,7 +771,6 @@ You can pass one or more file paths to the `memory` parameter when creating your
     import {
       InMemoryStore,
       MemorySaver,
-      type BaseStore,
     } from "@langchain/langgraph";
 
     const AGENTS_MD_URL =
@@ -803,15 +802,8 @@ You can pass one or more file paths to the `memory` parameter when creating your
 
     const checkpointer = new MemorySaver();
 
-    const backendFactory = (config: { state: unknown; store?: BaseStore }) => {
-      return new StoreBackend({
-        state: config.state,
-        store: config.store ?? store,
-      });
-    };
-
     const agent = await createDeepAgent({
-      backend: backendFactory,
+      backend: new StoreBackend(),
       store: store,
       checkpointer: checkpointer,
       memory: ["/AGENTS.md"],
@@ -839,8 +831,7 @@ You can pass one or more file paths to the `memory` parameter when creating your
     const checkpointer = new MemorySaver();
 
     const agent = await createDeepAgent({
-      backend: (config) =>
-        new FilesystemBackend({ rootDir: "/Users/user/{project}" }),
+      backend: new FilesystemBackend({ rootDir: "/Users/user/{project}" }),
       memory: ["./AGENTS.md", "./.deepagents/AGENTS.md"],
       interruptOn: {
         read_file: true,