后端 - Docs by LangChain

Deep Agents 通过 ls、read_file、write_file、edit_file、glob 和 grep 等工具向代理暴露文件系统接口。这些工具通过一个可插拔的后端运行。read_file 工具在所有后端中都原生支持图像文件（.png、.jpg、.jpeg、.gif、.webp），并将其作为多模态内容块返回。 read_file 工具在所有后端中都原生支持二进制文件（图像、PDF、音频、视频），返回一个带有类型化 content 和 mimeType 的 ReadResult。沙箱和 LocalShellBackend 还提供了一个 execute 工具。本页解释了如何：

选择后端，
将不同路径路由到不同后端，
实现您自己的虚拟文件系统（例如 S3 或 Postgres），
设置权限以控制文件系统访问，
添加策略钩子，
处理二进制和多模态文件，
遵守后端协议，
以及将现有后端更新到 v2。

快速入门

以下是几个预构建的文件系统后端，您可以快速将其与您的 deep agent 一起使用：

内置后端	描述
默认	`agent = create_deep_agent(model="google_genai:gemini-3.1-pro-preview")` 临时存储在状态中。代理的默认文件系统后端存储在 `langgraph` 状态中。请注意，此文件系统仅在_单个线程内_持久化。
本地文件系统持久化	`agent = create_deep_agent(model="google_genai:gemini-3.1-pro-preview", backend=FilesystemBackend(root_dir="/Users/nh/Desktop/"))` 这使 deep agent 可以访问您本地机器的文件系统。您可以指定代理有权访问的根目录。请注意，任何提供的 `root_dir` 必须是绝对路径。
持久化存储（LangGraph 存储）	`agent = create_deep_agent(model="google_genai:gemini-3.1-pro-preview", backend=StoreBackend())` 这使代理可以访问_跨线程持久化_的长期存储。这对于存储长期记忆或适用于代理多次执行的指令非常有用。
沙箱	`agent = create_deep_agent(model="google_genai:gemini-3.1-pro-preview", backend=sandbox)` 在隔离环境中执行代码。沙箱提供文件系统工具以及用于运行 shell 命令的 `execute` 工具。可从 Modal、Daytona、Deno 或本地 VFS 中选择。
本地 shell	`agent = create_deep_agent(model="google_genai:gemini-3.1-pro-preview", backend=LocalShellBackend(root_dir=".", env={"PATH": "/usr/bin:/bin"}))` 直接在主机上进行文件系统和 shell 执行。无隔离——仅在受控开发环境中使用。请参阅下面的安全注意事项。
组合	默认为临时存储，`/memories/` 持久化。组合后端具有最大的灵活性。您可以指定文件系统中的不同路由指向不同的后端。请参阅下面的组合路由以获取可直接粘贴的示例。

内置后端

StateBackend（临时）

import { createDeepAgent, StateBackend } from "deepagents";

// 默认情况下，我们提供一个 StateBackend
const agent = createDeepAgent();

// 在底层，它看起来像这样
const agent2 = createDeepAgent({
  backend: new StateBackend(),
});

工作原理：

通过 StateBackend 将文件存储在当前线程的 LangGraph 代理状态中。
通过检查点在同一线程的多个代理轮次中持久化。

最适合：

代理用于写入中间结果的临时记事本。
自动清除大型工具输出，然后代理可以逐块读回。

请注意，此后端在主管代理和子代理之间共享，子代理写入的任何文件在子代理执行完成后仍会保留在 LangGraph 代理状态中。这些文件将继续对主管代理和其他子代理可用。

FilesystemBackend（本地磁盘）

FilesystemBackend 在可配置的根目录下读写真实文件。

此后端授予代理直接的文件系统读/写访问权限。请谨慎使用，仅在适当的环境中使用。适当的用例：

本地开发 CLI（编码助手、开发工具）
CI/CD 流水线（请参阅下面的安全注意事项）

不适当的用例：

Web 服务器或 HTTP API - 请改用 StateBackend、StoreBackend 或沙箱后端

安全风险：

代理可以读取任何可访问的文件，包括密钥（API 密钥、凭据、.env 文件）
结合网络工具，密钥可能通过 SSRF 攻击被窃取
文件修改是永久且不可逆的

推荐的安全措施：

启用人在回路 (HITL) 中间件以审查敏感操作。
将密钥排除在可访问的文件系统路径之外（尤其是在 CI/CD 中）。
对于需要文件系统交互的生产环境，请使用沙箱后端。
始终使用 virtual_mode=True 和 root_dir 以启用基于路径的访问限制（阻止 ..、~ 和根目录外的绝对路径）。请注意，默认设置（virtual_mode=False）即使设置了 root_dir 也不提供安全性。

import { createDeepAgent, FilesystemBackend } from "deepagents";

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

工作原理：

在可配置的 root_dir 下读写真实文件。
您可以选择设置 virtual_mode=True 以在 root_dir 下沙箱化并规范化路径。
使用安全的路径解析，尽可能防止不安全的符号链接遍历，可以使用 ripgrep 进行快速 grep。

最适合：

您机器上的本地项目
CI 沙箱
挂载的持久卷

LocalShellBackend（本地 shell）

此后端授予代理直接的文件系统读/写访问权限以及在您的主机上不受限制的 shell 执行权限。请极其谨慎地使用，仅在适当的环境中使用。适当的用例：

本地开发 CLI（编码助手、开发工具）
您信任代理代码的个人开发环境
具有适当密钥管理的 CI/CD 流水线

不适当的用例：

生产环境（如 Web 服务器、API、多租户系统）
处理不受信任的用户输入或执行不受信任的代码

安全风险：

代理可以使用您的用户权限执行任意 shell 命令
代理可以读取任何可访问的文件，包括密钥（API 密钥、凭据、.env 文件）
密钥可能被暴露
文件修改和命令执行是永久且不可逆的
命令直接在您的主机系统上运行
命令可以消耗无限的 CPU、内存、磁盘

推荐的安全措施：

启用人在回路 (HITL) 中间件以在执行前审查和批准操作。强烈推荐。
仅在专用开发环境中运行。切勿在共享或生产系统上使用。
对于需要 shell 执行的生产环境，请使用沙箱后端。

注意： 启用 shell 访问后，virtual_mode=True 不提供安全性，因为命令可以访问系统上的任何路径。

import { createDeepAgent, LocalShellBackend } from "deepagents";

const backend = new LocalShellBackend({ workingDirectory: "." });
const agent = createDeepAgent({ backend });

这段代码展示了如何使用 deepagents 库创建一个深度代理（Deep Agent）。首先，从 deepagents 中导入 createDeepAgent 函数和 LocalShellBackend 类。接着，创建一个 LocalShellBackend 实例，指定工作目录为当前目录（"."）。最后，使用该后端实例调用 createDeepAgent 函数，生成一个代理对象。 工作原理：

扩展 FilesystemBackend，添加 execute 工具以在主机上运行 shell 命令。
命令直接在您的机器上使用 subprocess.run(shell=True) 运行，无沙箱化。
支持 timeout（默认 120 秒）、max_output_bytes（默认 100,000）、env 和 inherit_env 用于环境变量。
Shell 命令使用 root_dir 作为工作目录，但可以访问系统上的任何路径。

最适合：

本地编码助手和开发工具
在您信任代理时进行快速开发迭代

StoreBackend（LangGraph 存储）

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

const store = new InMemoryStore();  // 适用于本地开发；在LangSmith部署时省略
const agent = createDeepAgent({
  backend: new StoreBackend({
    namespace: (ctx) => [ctx.runtime.context.userId],
  }),
  store
});

部署到 LangSmith 部署时，请省略 store 参数。平台会自动为您的代理配置一个存储。

namespace 参数控制数据隔离。对于多用户部署，始终设置命名空间工厂以按用户或租户隔离数据。

工作原理：

StoreBackend 将文件存储在运行时提供的 LangGraph BaseStore 中，实现跨线程的持久化存储。

最适合：

当您已经使用配置好的 LangGraph 存储运行时（例如，Redis、Postgres 或 BaseStore 背后的云实现）。
当您通过 LangSmith Deployment 部署代理时（会自动为您的代理配置存储）。

命名空间工厂

命名空间工厂控制 StoreBackend 读写数据的位置。它接收一个 LangGraph Runtime 并返回一个字符串元组，用作存储命名空间。使用命名空间工厂在用户、租户或助手之间隔离数据。在构造 StoreBackend 时将命名空间工厂传递给 namespace 参数：

NamespaceFactory = Callable[[Runtime], tuple[str, ...]]

Runtime 提供：

rt.context — 通过 LangGraph 的上下文模式传递的用户提供的上下文（例如，user_id）
rt.serverInfo — 在 LangGraph Server 上运行时的服务器特定元数据（助手 ID、图 ID、已认证用户）
rt.executionInfo — 执行身份信息（线程 ID、运行 ID、检查点 ID）

Runtime 参数在 deepagents>=1.9.1 中可用。早期的 1.9.x 版本传递的是 BackendContext — 请参阅下面的从 BackendContext 迁移。rt.serverInfo 和 rt.executionInfo 需要 deepagents>=1.9.0。

常见的命名空间模式：

import { StoreBackend } from "deepagents";

// 按用户：每个用户获得自己的隔离存储
const backend = new StoreBackend({
  namespace: (rt) => [rt.serverInfo.user.identity],
});

// 按助手：同一助手的所有用户共享存储
const backend = new StoreBackend({
  namespace: (rt) => [rt.serverInfo.assistantId],
});

// 按线程：存储范围限定在单个对话中
const backend = new StoreBackend({
  namespace: (rt) => [rt.executionInfo.threadId],
});

您可以组合多个组件以创建更具体的范围——例如，(user_id, thread_id) 用于按用户按对话隔离，或附加后缀如 "filesystem" 以在相同范围使用多个存储命名空间时消除歧义。命名空间组件只能包含字母数字字符、连字符、下划线、点、@、+、冒号和波浪号。通配符（*、?）会被拒绝以防止 glob 注入。

namespace 参数在 v1.9.0 中将是必需的。对于新代码，请始终显式设置它。

当未提供命名空间工厂时，旧版默认使用 LangGraph 配置元数据中的 assistant_id。这意味着同一助手的所有用户共享相同的存储。对于多用户投入生产，请始终提供命名空间工厂。

CompositeBackend（路由器）

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

const store = new InMemoryStore();
const agent = createDeepAgent({
  backend: new CompositeBackend(
    new StateBackend(),
    {
      "/memories/": new StoreBackend(),
    }
  ),
  store,
});

工作原理：

CompositeBackend 根据路径前缀将文件操作路由到不同的后端。
在列表和搜索结果中保留原始路径前缀。

最适合：

当您想为代理提供临时和跨线程存储时，CompositeBackend 允许您同时提供 StateBackend 和 StoreBackend
当您有多个信息源想要作为单个文件系统的一部分提供给代理时。
- 例如，您在一个存储中将长期记忆存储在 /memories/ 下，同时还有一个自定义后端，其文档可在 /docs/ 访问。

指定一个后端

将后端实例传递给 createDeepAgent({ backend: ... })。文件系统中间件将其用于所有工具。
后端必须实现 AnyBackendProtocol（BackendProtocolV1 或 BackendProtocolV2）——例如，new StateBackend()、new FilesystemBackend({ rootDir: "." })、new StoreBackend()。
如果省略，默认为 new StateBackend()。

在 1.9.0 版本之前，仅支持 BackendProtocol，现在它是 BackendProtocolV1。V1 后端在运行时通过 adaptBackendProtocol() 自动适配到 V2。无需更改代码即可继续使用现有的 V1 后端。要更新到 v2，请参阅将现有后端更新到 v2。

路由到不同后端

将命名空间的部分路由到不同的后端。通常用于持久化 /memories/* 并保持其他所有内容为临时存储。

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

const agent = createDeepAgent({
  backend: new CompositeBackend(
    new StateBackend(),
    {
      "/memories/": new FilesystemBackend({ rootDir: "/deepagents/myagent", virtualMode: true }),
    },
  ),
});

行为：

/workspace/plan.md → StateBackend（临时）
/memories/agent.md → FilesystemBackend 在 /deepagents/myagent 下
ls、glob、grep 聚合结果并显示原始路径前缀。

注意：

更长的前缀优先（例如，路由 "/memories/projects/" 可以覆盖 "/memories/"）。
对于 StoreBackend 路由，请确保通过 create_deep_agent(model=..., store=...) 提供存储或由平台配置。

使用虚拟文件系统

构建自定义后端以将远程或数据库文件系统（例如 S3 或 Postgres）投影到工具命名空间中。设计指南：

路径是绝对的（/x/y.txt）。决定如何将它们映射到您的存储键/行。
高效实现 ls 和 glob（尽可能使用服务器端过滤，否则使用本地过滤）。
对于外部持久化（S3、Postgres 等），在写入/编辑结果中返回 files_update=None（Python）或省略 filesUpdate（JS）——只有内存状态后端需要返回文件更新字典。
使用 ls 和 glob 作为方法名。
所有查询方法（ls、read、readRaw、grep、glob）必须返回结构化的 Result 对象（例如，LsResult、ReadResult），其中包含可选的 error 字段。
在 read() 中支持二进制文件，返回带有适当 mimeType 的 Uint8Array 内容。

S3 风格大纲：

import {
  type BackendProtocolV2,
  type LsResult,
  type ReadResult,
  type ReadRawResult,
  type GrepResult,
  type GlobResult,
  type WriteResult,
  type EditResult,
} from "deepagents";

class S3Backend implements BackendProtocolV2 {
  constructor(private bucket: string, private prefix: string = "") {
    this.prefix = prefix.replace(/\/$/, "");
  }

  private key(path: string): string {
    return `${this.prefix}${path}`;
  }

  async ls(path: string): Promise<LsResult> {
    // 列出 key(path) 下的对象；返回 { files: [...] }
    ...
  }

  async read(filePath: string, offset?: number, limit?: number): Promise<ReadResult> {
    // 获取对象；返回 { content, mimeType }
    // 对于二进制文件，返回 Uint8Array 内容
    ...
  }

  async readRaw(filePath: string): Promise<ReadRawResult> {
    // 返回 { data: FileData }
    ...
  }

  async grep(pattern: string, path?: string | null, glob?: string | null): Promise<GrepResult> {
    // 搜索文本文件；跳过二进制文件；返回 { matches: [...] }
    ...
  }

  async glob(pattern: string, path = "/"): Promise<GlobResult> {
    // 应用相对于路径的 glob；返回 { files: [...] }
    ...
  }

  async write(filePath: string, content: string): Promise<WriteResult> {
    // 强制执行仅创建语义；返回 { path: filePath, filesUpdate: null }
    ...
  }

  async edit(filePath: string, oldString: string, newString: string, replaceAll?: boolean): Promise<EditResult> {
    // 读取 → 替换 → 写入 → 返回 { path, occurrences }
    ...
  }
}

Postgres 风格大纲：

表 files(path text primary key, content text, mime_type text, created_at timestamptz, modified_at timestamptz)
将工具操作映射到 SQL：
- ls 使用 WHERE path LIKE $1 || '%' → 返回 LsResult
- glob 在 SQL 中过滤或获取后在本地应用 glob → 返回 GlobResult
- grep 可以按扩展名或最后修改时间获取候选行，然后扫描行（跳过 mime_type 为二进制的行）→ 返回 GrepResult

权限

使用权限来声明式地控制代理可以读取或写入哪些文件和目录。权限适用于内置的文件系统工具，并在调用后端之前进行评估。有关完整选项集，包括规则排序、子代理权限和组合后端交互，请参阅权限指南。

添加策略钩子

对于超出基于路径的允许/拒绝规则（速率限制、审计日志记录、内容检查）的自定义验证逻辑，通过子类化或包装后端来强制执行企业规则。阻止在选定前缀下的写入/编辑（子类化）：

import { FilesystemBackend, type WriteResult, type EditResult } from "deepagents";

class GuardedBackend extends FilesystemBackend {
  private denyPrefixes: string[];

  constructor({ denyPrefixes, ...options }: { denyPrefixes: string[]; rootDir?: string }) {
    super(options);
    this.denyPrefixes = denyPrefixes.map(p => p.endsWith("/") ? p : p + "/");
  }

  async write(filePath: string, content: string): Promise<WriteResult> {
    if (this.denyPrefixes.some(p => filePath.startsWith(p))) {
      return { error: `不允许在 ${filePath} 下写入` };
    }
    return super.write(filePath, content);
  }

  async edit(filePath: string, oldString: string, newString: string, replaceAll = false): Promise<EditResult> {
    if (this.denyPrefixes.some(p => filePath.startsWith(p))) {
      return { error: `不允许在 ${filePath} 下编辑` };
    }
    return super.edit(filePath, oldString, newString, replaceAll);
  }
}

通用包装器（适用于任何后端）：

import {
  type BackendProtocolV2,
  type LsResult,
  type ReadResult,
  type ReadRawResult,
  type GrepResult,
  type GlobResult,
  type WriteResult,
  type EditResult,
} from "deepagents";

class PolicyWrapper implements BackendProtocolV2 {
  private denyPrefixes: string[];

  constructor(private inner: BackendProtocolV2, denyPrefixes: string[] = []) {
    this.denyPrefixes = denyPrefixes.map(p => p.endsWith("/") ? p : p + "/");
  }

  private isDenied(path: string): boolean {
    return this.denyPrefixes.some(p => path.startsWith(p));
  }

  ls(path: string): Promise<LsResult> { return this.inner.ls(path); }
  read(filePath: string, offset?: number, limit?: number): Promise<ReadResult> { return this.inner.read(filePath, offset, limit); }
  readRaw(filePath: string): Promise<ReadRawResult> { return this.inner.readRaw(filePath); }
  grep(pattern: string, path?: string | null, glob?: string | null): Promise<GrepResult> { return this.inner.grep(pattern, path, glob); }
  glob(pattern: string, path?: string): Promise<GlobResult> { return this.inner.glob(pattern, path); }

  async write(filePath: string, content: string): Promise<WriteResult> {
    if (this.isDenied(filePath)) return { error: `不允许在 ${filePath} 下写入` };
    return this.inner.write(filePath, content);
  }

  async edit(filePath: string, oldString: string, newString: string, replaceAll = false): Promise<EditResult> {
    if (this.isDenied(filePath)) return { error: `不允许在 ${filePath} 下编辑` };
    return this.inner.edit(filePath, oldString, newString, replaceAll);
  }
}

多模态和二进制文件

多模态文件支持（PDF、音频、视频）需要 deepagents>=1.9.0。

V2 后端原生支持二进制文件。当 read() 遇到二进制文件（由文件扩展名的 MIME 类型确定）时，它返回一个带有 Uint8Array 内容和相应 mimeType 的 ReadResult。文本文件返回 string 内容。

支持的 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` 等	`text/plain`、`text/html`、`application/json` 等

读取二进制文件

const result = await backend.read("/workspace/screenshot.png");

if (result.error) {
  console.error(result.error);
} else if (result.content instanceof Uint8Array) {
  // 二进制文件 — 内容是 Uint8Array，mimeType 已设置
  console.log(`二进制文件：${result.mimeType}`); // "image/png"
} else {
  // 文本文件 — 内容是字符串
  console.log(`文本文件：${result.mimeType}`); // "text/plain"
}

FileData 格式

FileData 是用于在状态和存储后端中存储文件内容的类型。

type FileData =
  // 当前格式 (v2)
  | {
      content: string | Uint8Array; // 文本为字符串，二进制为 Uint8Array
      mimeType: string;             // 例如 "text/plain"、"image/png"
      created_at: string;           // ISO 8601 时间戳
      modified_at: string;          // ISO 8601 时间戳
    }
  // 旧版格式 (v1)
  | {
      content: string[];            // 行数组
      created_at: string;           // ISO 8601 时间戳
      modified_at: string;          // ISO 8601 时间戳
    };

后端在从状态或存储读取时可能会遇到任一格式。框架透明地处理两者。新写入默认为 v2 格式。在滚动部署期间，如果旧版读取器需要旧版格式，请将 fileFormat: "v1" 传递给后端构造函数（例如，new StoreBackend({ fileFormat: "v1" })）。

从后端工厂迁移

自 deepagents 1.9.0 起，后端工厂模式已弃用。请直接传递预构建的后端实例，而不是工厂函数。

以前，像 StateBackend 和 StoreBackend 这样的后端需要一个接收运行时对象的工厂函数，因为它们需要运行时上下文（状态、存储）来操作。现在后端通过 LangGraph 的 get_config()、get_store() 和 get_runtime() 辅助函数内部解析此上下文，因此您可以直接传递实例。

变更内容

之前（已弃用）	之后
`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` 类型	直接传递后端实例
`BackendRuntime` 接口	后端内部解析上下文
`StateBackend(runtime, options?)` 构造函数重载	`new StateBackend(options?)`
`StoreBackend(stateAndStore, options?)` 构造函数重载	`new StoreBackend(options?)`
`WriteResult` 和 `EditResult` 上的 `filesUpdate` 字段	状态写入现在由后端内部处理

工厂模式在运行时仍然有效，但会发出弃用警告。请在下一个主要版本之前更新您的代码以使用直接实例。

迁移示例

// 之前（已弃用）
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],
    }) },
  ),
});

// 之后
const agent = createDeepAgent({
  backend: new CompositeBackend(
    new StateBackend(),
    { "/memories/": new StoreBackend({
      namespace: (rt) => [rt.serverInfo.user.identity],
    }) },
  ),
});

从 `BackendContext` 迁移

在 deepagents>=0.5.2（Python）和 deepagents>=1.9.1（TypeScript）中，命名空间工厂直接接收 LangGraph Runtime，而不是 BackendContext 包装器。旧的 BackendContext 形式仍然通过向后兼容的 .runtime 和 .state 访问器工作，但这些访问器会发出弃用警告，并将在 deepagents>=0.7 中移除。 变更内容：

工厂参数现在是 Runtime，而不是 BackendContext。
删除 .runtime 访问器——例如，ctx.runtime.context.user_id 变为 rt.server_info.user.identity。
ctx.state 没有直接替代方案。命名空间信息应该是只读的，并且在运行生命周期内保持稳定，而状态是可变的并且会逐步变化——从中派生命名空间可能会导致数据最终位于不一致的键下。如果您有需要读取代理状态的用例，请提交 issue。

// 之前（已弃用，在 v0.7 中移除）
new StoreBackend({
  namespace: (ctx) => [ctx.runtime.context.userId],
});

// 之后
new StoreBackend({
  namespace: (rt) => [rt.serverInfo.user.identity],
});

协议参考

后端必须实现 BackendProtocol。必需方法：

ls(path: str) -> LsResult
- 返回至少包含 path 的条目。在可用时包含 is_dir、size、modified_at。按 path 排序以获得确定性输出。
read(file_path: str, offset: int = 0, limit: int = 2000) -> ReadResult
- 成功时返回文件数据。文件缺失时，返回 ReadResult(error="Error: File '/x' not found")。
grep(pattern: str, path: Optional[str] = None, glob: Optional[str] = None) -> GrepResult
- 返回结构化匹配项。出错时，返回 GrepResult(error="...")（不要引发异常）。
glob(pattern: str, path: str = "/") -> GlobResult
- 将匹配的文件作为 FileInfo 条目返回（如果没有则为空列表）。
write(file_path: str, content: str) -> WriteResult
- 仅创建。冲突时，返回 WriteResult(error=...)。成功时，设置 path，对于状态后端设置 files_update={...}；外部后端应使用 files_update=None。
edit(file_path: str, old_string: str, new_string: str, replace_all: bool = False) -> EditResult
- 除非 replace_all=True，否则强制 old_string 的唯一性。如果未找到，返回错误。成功时包含 occurrences。

支持类型：

LsResult(error, entries) — 成功时 entries 是 list[FileInfo]，失败时为 None。
ReadResult(error, file_data) — 成功时 file_data 是 FileData 字典，失败时为 None。
GrepResult(error, matches) — 成功时 matches 是 list[GrepMatch]，失败时为 None。
GlobResult(error, matches) — 成功时 matches 是 list[FileInfo]，失败时为 None。
WriteResult(error, path, files_update)
EditResult(error, path, files_update, occurrences)
FileInfo 字段：path（必需），可选 is_dir、size、modified_at。
GrepMatch 字段：path、line、text。
FileData 字段：content（str）、encoding（"utf-8" 或 "base64"）、created_at、modified_at。 :::

后端实现 BackendProtocolV2。所有查询方法返回带有 { error?: string, ...data } 的结构化 Result 对象。

必需方法

ls(path: string) → LsResult
- 列出指定目录中的文件和目录（非递归）。目录的路径以 / 结尾，is_dir=true。在可用时包含 is_dir、size、modified_at。
read(filePath: string, offset?: number, limit?: number) → ReadResult
- 读取文件内容。对于文本文件，内容按行偏移量/限制分页（默认偏移量 0，限制 500）。对于二进制文件，返回完整的原始 Uint8Array 内容，并设置 mimeType 字段。文件缺失时，返回 { error: "File '/x' not found" }。
readRaw(filePath: string) → ReadRawResult
- 将文件内容作为原始 FileData 读取。返回包含时间戳的完整文件数据。
grep(pattern: string, path?: string | null, glob?: string | null) → GrepResult
- 搜索文件内容中的字面文本模式。二进制文件（由 MIME 类型确定）被跳过。失败时，返回 { error: "..." }。
glob(pattern: string, path?: string) → GlobResult
- 将匹配 glob 模式的文件作为 FileInfo 条目返回。
write(filePath: string, content: string) → WriteResult
- 仅创建语义。冲突时，返回 { error: "..." }。成功时，设置 path，对于状态后端设置 filesUpdate={...}；外部后端应使用 filesUpdate=null。
edit(filePath: string, oldString: string, newString: string, replaceAll?: boolean) → EditResult
- 除非 replaceAll=true，否则强制 oldString 的唯一性。如果未找到，返回错误。成功时包含 occurrences。

可选方法

uploadFiles(files: Array<[string, Uint8Array]>) → FileUploadResponse[] — 上传多个文件（用于沙箱后端）。
downloadFiles(paths: string[]) → FileDownloadResponse[] — 下载多个文件（用于沙箱后端）。

结果类型

类型	成功字段	错误字段
`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（必需），可选 is_dir、size、modified_at。
GrepMatch — path、line（从 1 开始）、text。
FileData — 带时间戳的文件内容。请参阅 FileData 格式。

沙箱扩展

SandboxBackendProtocolV2 扩展了 BackendProtocolV2，增加了：

execute(command: string) → ExecuteResponse — 在沙箱中运行 shell 命令。
readonly id: string — 沙箱实例的唯一标识符。

将现有后端更新到 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(...)`	未变更（`WriteResult`）
`edit(...)`	`edit(...)`	未变更（`EditResult`）

类型重命名

V1 类型	V2 类型
`BackendProtocol`	`BackendProtocolV2`
`SandboxBackendProtocol`	`SandboxBackendProtocolV2`

适配工具

如果您有需要与仅 V2 代码一起使用的现有 V1 后端，请使用适配函数：

import { adaptBackendProtocol, adaptSandboxProtocol } from "deepagents";

// 将 V1 后端适配到 V2
const v2Backend = adaptBackendProtocol(v1Backend);

// 将 V1 沙箱适配到 V2
const v2Sandbox = adaptSandboxProtocol(v1Sandbox);

框架会自动适配传递给 createDeepAgent() 的 V1 后端。仅在直接调用协议方法时才需要手动适配。

将这些文档连接到 Claude、VSCode 等，通过 MCP 获取实时答案。

在 GitHub 上编辑此页面或提交 issue。

Get started

Deployment

Core capabilities

Frontend

Protocols

Command line interface

后端

快速入门

内置后端

StateBackend（临时）

FilesystemBackend（本地磁盘）

LocalShellBackend（本地 shell）

StoreBackend（LangGraph 存储）

命名空间工厂

CompositeBackend（路由器）

指定一个后端

路由到不同后端

使用虚拟文件系统

权限

添加策略钩子

多模态和二进制文件

支持的 MIME 类型

读取二进制文件

FileData 格式

从后端工厂迁移

变更内容

已弃用的 API

迁移示例

从 `BackendContext` 迁移

协议参考

必需方法

可选方法

结果类型

支持类型

沙箱扩展

将现有后端更新到 V2

方法重命名

类型重命名

适配工具

​快速入门

​内置后端

​StateBackend（临时）

​FilesystemBackend（本地磁盘）

​LocalShellBackend（本地 shell）

​StoreBackend（LangGraph 存储）

​命名空间工厂

​CompositeBackend（路由器）

​指定一个后端

​路由到不同后端

​使用虚拟文件系统

​权限

​添加策略钩子

​多模态和二进制文件

​支持的 MIME 类型

​读取二进制文件

​FileData 格式

​从后端工厂迁移

​变更内容

​已弃用的 API

​迁移示例

​从 BackendContext 迁移

​协议参考

​必需方法

​可选方法

​结果类型

​支持类型

​沙箱扩展

​将现有后端更新到 V2

​方法重命名

​类型重命名

​适配工具

快速入门

内置后端

StateBackend（临时）

FilesystemBackend（本地磁盘）

LocalShellBackend（本地 shell）

StoreBackend（LangGraph 存储）

命名空间工厂

CompositeBackend（路由器）

指定一个后端

路由到不同后端

使用虚拟文件系统

权限

添加策略钩子

多模态和二进制文件

支持的 MIME 类型

读取二进制文件

FileData 格式

从后端工厂迁移

变更内容

已弃用的 API

迁移示例

从 `BackendContext` 迁移

协议参考

必需方法

可选方法

结果类型

支持类型

沙箱扩展

将现有后端更新到 V2

方法重命名

类型重命名

适配工具