{
if (this.isDenied(filePath)) return { error: `Edits are not allowed under ${filePath}` };
return this.inner.edit(filePath, oldString, newString, replaceAll);
}
}
```
## 多模态和二进制文件
Multi-modal file support (PDFs, audio, video) requires `deepagents>=1.9.0`.
V2 后端原生支持二进制文件。 When `read()` encounters a binary file (determined by MIME type from the file extension), it returns a `ReadResult` with `Uint8Array` content and the corresponding `mimeType`. Text files return `string` content.
### 支持的 MIME 类型
| 类别 | 扩展名 | MIME 类型 |
| -- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| 图像 | `.png`, `.jpg`/`.jpeg`, `.gif`, `.webp`, `.svg`, `.heic`, `.heif` | `image/png`, `image/jpeg`, `image/gif`, `image/webp`, `image/svg+xml`, `image/heic`, `image/heif` |
| 音频 | `.mp3`, `.wav`, `.aiff`, `.aac`, `.ogg`, `.flac` | `audio/mpeg`, `audio/wav`, `audio/aiff`, `audio/aac`, `audio/ogg`, `audio/flac` |
| 视频 | `.mp4`, `.webm`, `.mpeg`/`.mpg`, `.mov`, `.avi`, `.flv`, `.wmv`, `.3gpp` | `video/mp4`, `video/webm`, `video/mpeg`, `video/quicktime`, `video/x-msvideo`, `video/x-flv`, `video/x-ms-wmv`, `video/3gpp` |
| 文档 | `.pdf`, `.ppt`, `.pptx` | `application/pdf`, `application/vnd.ms-powerpoint`, `application/vnd.openxmlformats-officedocument.presentationml.presentation` |
| 文本 | `.txt`, `.html`, `.json`, `.js`, `.ts`, `.py`, etc. | `text/plain`, `text/html`, `application/json`, etc. |
### 读取二进制文件
```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
const result = await backend.read("/workspace/screenshot.png");
if (result.error) {
console.error(result.error);
} else if (result.content instanceof Uint8Array) {
// Binary file — content is Uint8Array, mimeType is set
console.log(`Binary file: ${result.mimeType}`); // "image/png"
} else {
// Text file — content is string
console.log(`Text file: ${result.mimeType}`); // "text/plain"
}
```
### FileData 格式
`FileData` is the type used to store file content in state and store backends.
```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
type FileData =
// Current format (v2)
| {
content: string | Uint8Array; // string for text, Uint8Array for binary
mimeType: string; // e.g. "text/plain", "image/png"
created_at: string; // ISO 8601 timestamp
modified_at: string; // ISO 8601 timestamp
}
// Legacy format (v1)
| {
content: string[]; // array of lines
created_at: string; // ISO 8601 timestamp
modified_at: string; // ISO 8601 timestamp
};
```
后端在从状态或存储读取时可能遇到任一格式。 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" })`).
## 从后端工厂迁移
后端工厂模式已**弃用** as of `deepagents` 1.9.0. Pass pre-constructed backend instances directly instead of factory functions.
之前，`StateBackend` 和 `StoreBackend` 等后端需要一个工厂函数 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.
### 变更内容
| 之前（已弃用） | 之后 |
| -------------------------------------------------------------------- | ------------------------------------------------------- |
| `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()` |
### 已弃用的 API
| 已弃用 | 替代 |
| ------------------------------------------------------------ | ------------------------------------------------------ |
| `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 |
The factory pattern still works at runtime and emits a deprecation warning. Update your code to use direct instances before the next major version.
### 迁移示例
```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
// Before (deprecated)
import { createDeepAgent, CompositeBackend, StateBackend, StoreBackend } from "deepagents";
const agent = createDeepAgent({
backend: (config) => new CompositeBackend(
new StateBackend(config),
{ "/memories/": new StoreBackend(config, {
namespace: (rt) => [rt.serverInfo.user.identity],
}) },
),
});
// After
const agent = createDeepAgent({
backend: new CompositeBackend(
new StateBackend(),
{ "/memories/": new StoreBackend({
namespace: (rt) => [rt.serverInfo.user.identity],
}) },
),
});
```
### 从 `BackendContext` 迁移
In `deepagents>=0.5.2` (Python) and `deepagents>=1.9.1` (TypeScript), namespace factories receive a LangGraph [`Runtime`](https://reference.langchain.com/javascript/langchain/index/Runtime) directly instead of a `BackendContext` wrapper. The old `BackendContext` form still works via backwards-compatible `.runtime` and `.state` accessors, but those accessors emit a deprecation warning and will be removed in `deepagents>=0.7`.
**What changed:**
* The factory argument is now a `Runtime`, not a `BackendContext`.
* Drop the `.runtime` accessor — for example, `ctx.runtime.context.user_id` becomes `rt.server_info.user.identity`.
* There is no direct replacement for `ctx.state`. Namespace info should be read-only and stable for the lifetime of a run, whereas state is mutable and changes step-to-step—deriving a namespace from it risks data ending up under inconsistent keys. If you have a use case that requires reading agent state, please [open an issue](https://github.com/langchain-ai/deepagents/issues).
```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
// Before (deprecated, removed in v0.7)
new StoreBackend({
namespace: (ctx) => [ctx.runtime.context.userId], // [!code --]
});
// After
new StoreBackend({
namespace: (rt) => [rt.serverInfo.user.identity], // [!code ++]
});
```
## 协议参考
后端必须实现 [`BackendProtocol`](https://reference.langchain.com/javascript/deepagents/backends/BackendProtocol).
必需方法：
* `ls(path: str) -> LsResult`
* 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) -> ReadResult`
* Return file data on success. On missing file, return `ReadResult(error="Error: File '/x' not found")`.
* `grep(pattern: str, path: Optional[str] = None, glob: Optional[str] = None) -> GrepResult`
* Return structured matches. On error, return `GrepResult(error="...")` (do not raise).
* `glob(pattern: str, path: str = "/") -> GlobResult`
* 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.
辅助类型：
* `LsResult(error, entries)` — `entries` is a `list[FileInfo]` on success, `None` on failure.
* `ReadResult(error, file_data)` — `file_data` is a `FileData` dict on success, `None` on failure.
* `GrepResult(error, matches)` — `matches` is a `list[GrepMatch]` on success, `None` on failure.
* `GlobResult(error, matches)` — `matches` is a `list[FileInfo]` on success, `None` on failure.
* `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`.
* `FileData` with fields: `content` (str), `encoding` (`"utf-8"` or `"base64"`), `created_at`, `modified_at`.
:::
Backends implement `BackendProtocolV2`. All query methods return structured Result objects with `{ error?: string, ...data }`.
### 必需方法
* **`ls(path: string) → LsResult`**
* List files and directories in the specified directory (non-recursive). Directories have a trailing `/` in their path and `is_dir=true`. Include `is_dir`, `size`, `modified_at` when available.
* **`read(filePath: string, offset?: number, limit?: number) → ReadResult`**
* Read file content. For text files, content is paginated by line offset/limit (default offset 0, limit 500). For binary files, the full raw `Uint8Array` content is returned with the `mimeType` field set. On missing file, return `{ error: "File '/x' not found" }`.
* **`readRaw(filePath: string) → ReadRawResult`**
* Read file content as raw `FileData`. Returns the full file data including timestamps.
* **`grep(pattern: string, path?: string | null, glob?: string | null) → GrepResult`**
* Search file contents for a literal text pattern. Binary files (determined by MIME type) are skipped. On failure, return `{ error: "..." }`.
* **`glob(pattern: string, path?: string) → GlobResult`**
* Return files matching a glob pattern as `FileInfo` entries.
* **`write(filePath: string, content: string) → WriteResult`**
* Create-only semantics. On conflict, return `{ error: "..." }`. On success, set `path` and for state backends set `filesUpdate={...}`; external backends should use `filesUpdate=null`.
* **`edit(filePath: string, oldString: string, newString: string, replaceAll?: boolean) → EditResult`**
* Enforce uniqueness of `oldString` unless `replaceAll=true`. If not found, return error. Include `occurrences` on success.
### 可选方法
* **`uploadFiles(files: Array<[string, Uint8Array]>) → FileUploadResponse[]`** — Upload multiple files (for sandbox backends).
* **`downloadFiles(paths: string[]) → FileDownloadResponse[]`** — Download multiple files (for sandbox backends).
### 结果类型
| 类型 | 成功字段 | 错误字段 |
| --------------- | ----------------------------------------------------- | ------- |
| `ReadResult` | `content?: string \| Uint8Array`, `mimeType?: string` | `error` |
| `ReadRawResult` | `data?: FileData` | `error` |
| `LsResult` | `files?: FileInfo[]` | `error` |
| `GlobResult` | `files?: FileInfo[]` | `error` |
| `GrepResult` | `matches?: GrepMatch[]` | `error` |
| `WriteResult` | `path?: string` | `error` |
| `EditResult` | `path?: string`, `occurrences?: number` | `error` |
### 辅助类型
* **`FileInfo`** — `path` (required), optionally `is_dir`, `size`, `modified_at`.
* **`GrepMatch`** — `path`, `line` (1-indexed), `text`.
* **`FileData`** — File content with timestamps. See [FileData format](#filedata-format).
### 沙箱扩展
`SandboxBackendProtocolV2` extends `BackendProtocolV2` with:
* **`execute(command: string) → ExecuteResponse`** — Run a shell command in the sandbox.
* **`readonly id: string`** — Unique identifier for the sandbox instance.
## 将现有后端更新到 V2
### 方法重命名
| V1 方法 | V2 方法 | 返回类型变更 |
| ------------------------------- | ------------------------------- | -------------------------------------- |
| `lsInfo(path)` | `ls(path)` | `FileInfo[]` → `LsResult` |
| `read(filePath, offset, limit)` | `read(filePath, offset, limit)` | `string` → `ReadResult` |
| `readRaw(filePath)` | `readRaw(filePath)` | `FileData` → `ReadRawResult` |
| `grepRaw(pattern, path, glob)` | `grep(pattern, path, glob)` | `GrepMatch[] \| string` → `GrepResult` |
| `globInfo(pattern, path)` | `glob(pattern, path)` | `FileInfo[]` → `GlobResult` |
| `write(...)` | `write(...)` | Unchanged (`WriteResult`) |
| `edit(...)` | `edit(...)` | Unchanged (`EditResult`) |
### 类型重命名
| V1 类型 | V2 类型 |
| ------------------------ | -------------------------- |
| `BackendProtocol` | `BackendProtocolV2` |
| `SandboxBackendProtocol` | `SandboxBackendProtocolV2` |
### 适配工具
If you have existing V1 backends that you need to use with V2-only code, use the adaptation functions:
```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import { adaptBackendProtocol, adaptSandboxProtocol } from "deepagents";
// Adapt a V1 backend to V2
const v2Backend = adaptBackendProtocol(v1Backend);
// Adapt a V1 sandbox to V2
const v2Sandbox = adaptSandboxProtocol(v1Sandbox);
```
The framework auto-adapts V1 backends passed to `createDeepAgent()`. Manual adaptation is only needed when calling protocol methods directly.
***
[将这些文档连接](/use-these-docs)到 Claude、VSCode 等，通过 MCP 获取实时答案。
[在 GitHub 上编辑此页面](https://github.com/langchain-ai/docs/edit/main/src/oss/deepagents/backends.mdx)或[提交 issue](https://github.com/langchain-ai/docs/issues/new/choose)。