后端（Backends）

为什么需要后端

你的 Agent 产生的文件应该存在哪里？不同的任务需要不同的答案

后端全景图

七种内置后端，覆盖从临时草稿到生产部署的全部场景

架构关系图

graph TB
    Tools[文件系统工具] --> Backend[后端]
    Backend --> State[State]
    Backend --> Disk[文件系统]
    Backend --> Store[Store]
    Backend --> ContextHub[Context Hub]
    Backend --> Sandbox[沙箱]
    Backend --> LocalShell[本地 Shell]
    Backend --> Composite[组合]
    Backend --> Custom[自定义]
    Composite --> Router{路由}
    Router --> State
    Router --> Disk
    Router --> Store
    Router --> ContextHub
    Sandbox --> Execute["+ execute 工具"]
    LocalShell --> Execute["+ execute 工具"]

StateBackend

默认后端——线程作用域的临时草稿本

白话：StateBackend 就像你桌面上的"草稿纸"——写在上面的东西，这条对话里随时能翻到，但换一个对话窗口就看不到了。

这是 Deep Agent 的默认文件系统后端。文件存储在当前线程的 LangGraph Agent 状态中，通过检查点在同一线程的多次交互间持久化。文件不会跨线程共享。

import { createDeepAgent, StateBackend } from "deepagents";

// 默认就是 StateBackend，无需显式指定
const agent = createDeepAgent();

// 等价于显式指定
const agent2 = createDeepAgent({
  backend: new StateBackend(),
});

FilesystemBackend

让 Agent 访问本地磁盘——真实文件的读写

白话：StateBackend 是草稿纸，FilesystemBackend 就是真实的文件夹。Agent 可以读你电脑上的文件、修改代码、保存结果——就像你亲手在做。

FilesystemBackend 在可配置的 root_dir 下读取和写入真实文件。你可以设置 virtualMode: true 来沙箱化路径，阻止 ..、~ 以及根目录外的绝对路径。

import { createDeepAgent, FilesystemBackend } from "deepagents";

const agent = createDeepAgent({
  model: "google-genai:gemini-3.1-pro-preview",
  backend: new FilesystemBackend({
    rootDir: ".",         // 根目录，Agent 的文件操作限制在此目录下
    virtualMode: true,    // 启用路径沙箱化，阻止 .. 和绝对路径逃逸
  }),
});

LocalShellBackend

在 FilesystemBackend 基础上增加 Shell 命令执行能力

LocalShellBackend 在 FilesystemBackend 之上扩展了 execute 工具，允许 Agent 在宿主机上运行 Shell 命令。命令通过 shell 执行（等价 Node.js child_process，无沙箱隔离）。

import { createDeepAgent, LocalShellBackend } from "deepagents";

const backend = new LocalShellBackend({
  workingDirectory: ".",   // Shell 命令的执行目录
  env: { PATH: "/usr/bin:/bin" },  // 限制可用的环境变量，避免泄露宿主环境
});
const agent = createDeepAgent({
  model: "google-genai:gemini-3.1-pro-preview",
  backend,  // Agent 获得文件读写 + Shell 命令执行能力
});

StoreBackend

跨线程持久化——Agent 的长期记忆存储

白话：如果说 StateBackend 是草稿纸，那 StoreBackend 就是文件柜——今天写进去的东西，明天打开另一个对话窗口还能读到。

StoreBackend 将文件存储在 LangGraph BaseStore 中，实现跨线程的持久化。非常适合存储长期记忆或在多次执行中适用的指令。

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

// 本地开发用 InMemoryStore（内存存储）；部署到 LangSmith 时自动提供
const store = new InMemoryStore();
const agent = createDeepAgent({
  model: "google-genai:gemini-3.1-pro-preview",
  backend: new StoreBackend({
    // namespace 工厂函数：按用户身份隔离，每个用户有独立存储空间
    namespace: (rt) => [rt.serverInfo.user.identity],
  }),
  store,  // 必须传入 store 实例，StoreBackend 依赖它读写数据
});

命名空间工厂

控制 StoreBackend 数据隔离的关键机制

命名空间工厂接收 LangGraph Runtime 对象，返回字符串元组作为 store 命名空间。使用它在用户、租户或助手之间隔离数据。

import { StoreBackend } from "deepagents";

// 按用户隔离：每个用户独立的存储空间，多用户部署必须用这种方式
const byUser = new StoreBackend({
  namespace: (rt) => [rt.serverInfo.user.identity],  // 用用户 ID 作为命名空间
});

// 按助手隔离：同一助手的所有用户共享数据
const byAssistant = new StoreBackend({
  namespace: (rt) => [rt.serverInfo.assistantId],  // 用助手 ID 作为命名空间
});

// 按线程隔离：存储限定在单个对话范围，对话结束数据就不共享了
const byThread = new StoreBackend({
  namespace: (rt) => [rt.executionInfo.threadId],  // 用线程 ID 作为命名空间
});

ContextHubBackend

LangSmith Hub 仓库作为文件系统——无需额外配置 Store

ContextHubBackend 将文件存储在 LangSmith Hub 仓库中。使用 owner/name 或 name 格式的仓库标识符来构造它。无需配置单独的 LangGraph Store。

import { createDeepAgent, ContextHubBackend } from "deepagents";

const agent = createDeepAgent({
  model: "google-genai:gemini-3.1-pro-preview",
  // 传入 Hub 仓库名（owner/name 或 name 格式），无需额外配置 Store
  backend: new ContextHubBackend("my-agent"),
});

CompositeBackend

路由器——按路径前缀将文件操作分发到不同后端

CompositeBackend 是最灵活的后端。它根据路径前缀将文件操作路由到不同后端，让你同时使用多种存储策略。

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

const store = new InMemoryStore();
const agent = createDeepAgent({
  model: "google-genai:gemini-3.1-pro-preview",
  backend: new CompositeBackend(
    // 第一个参数：默认后端，未匹配路径前缀的文件操作走这里
    new StateBackend(),  // 线程作用域，临时草稿
    // 第二个参数：路由表，键是路径前缀，值是对应的后端
    {
      "/memories/": new StoreBackend({  // /memories/ 下的文件走跨线程持久化
        namespace: () => ["memories"],
      }),
    },
  ),
  store,  // StoreBackend 依赖的 LangGraph 存储
});

后端对比总结

一表看清七种后端的核心差异，帮你做出正确选择

指定后端

一个参数搞定——将后端实例传给 createDeepAgent

将后端实例传递给 createDeepAgent({ backend: ... }) 即可。文件系统中间件将其用于所有工具操作。如果省略，默认为 new StateBackend()。

// 方式 1：省略 backend 参数，默认使用 StateBackend（线程内临时存储）
const agent1 = createDeepAgent();

// 方式 2：指定 FilesystemBackend，访问本地磁盘文件
const agent2 = createDeepAgent({
  backend: new FilesystemBackend({ rootDir: ".", virtualMode: true }),
});

// 方式 3：使用 CompositeBackend 按路径路由到不同后端
const agent3 = createDeepAgent({
  backend: new CompositeBackend(
    new StateBackend(),  // 默认后端
    {
      "/memories/": new StoreBackend({  // /memories/ 走持久化存储
        namespace: () => ["memories"],
      }),
    },
  ),
  store,  // StoreBackend 需要 store 实例
});

虚拟文件系统

构建自定义后端，将 S3 或 Postgres 映射为文件系统

你可以构建自定义后端，将远程或数据库文件系统映射到 Agent 的工具命名空间。所有路径都是绝对路径（/x/y.txt），你决定如何映射到存储键或数据库行。

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 = "") {}

  // 将虚拟路径转为 S3 对象键，加上前缀
  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> {
    // 从 S3 获取对象内容；文本返回 string，二进制返回 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> {
    // 相对于 path 应用 glob 模式匹配；返回 { files: [...] }
  }

  async write(filePath: string, content: string): Promise<WriteResult> {
    // 写入对象；外部后端返回 { path, filesUpdate: null }
  }

  async edit(filePath: string, oldString: string, newString: string, replaceAll?: boolean): Promise<EditResult> {
    // 先 read → 替换 oldString 为 newString → write 回去
  }
}

后端协议详解

BackendProtocolV2 规定的七个必需方法

import { adaptBackendProtocol, adaptSandboxProtocol } from "deepagents";

// 将 V1 后端适配为 V2，使旧实现可以在新框架中使用
const v2Backend = adaptBackendProtocol(v1Backend);
const v2Sandbox = adaptSandboxProtocol(v1Sandbox);

权限控制

声明式控制 Agent 可以读写哪些文件和目录

权限应用于内置的文件系统工具，并在后端被调用之前进行评估。这意味着即使后端支持访问，权限规则也能阻止不安全的操作。

策略钩子：子类

通过子类化后端来实现自定义验证逻辑

当权限的"允许/拒绝"不够用时，你可以通过子类化后端来拦截写操作、添加审计日志或执行内容检查。以下示例阻止选定前缀下的写入和编辑：

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

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

  constructor({ denyPrefixes, ...options }) {
    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: `Writes are not allowed under ${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: `Edits are not allowed under ${filePath}` };
    }
    return super.edit(filePath, oldString, newString, replaceAll);  // 通过检查，调用父类
  }
}

策略钩子：包装器

通用包装器——适用于任何后端的策略拦截

如果你需要在任意后端上应用策略，包装器模式比子类更灵活。它不依赖具体的后端实现，可以组合使用。

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

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

  // inner 是被包装的后端实例，可以是任何实现了 BackendProtocolV2 的后端
  constructor(private inner: BackendProtocolV2, denyPrefixes = []) {
    this.denyPrefixes = denyPrefixes.map(
      p => p.endsWith("/") ? p : p + "/"
    );
  }

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

  // 读取类方法直接透传给内部后端，不加任何拦截
  ls(path) { return this.inner.ls(path); }
  read(filePath, offset?, limit?) { return this.inner.read(filePath, offset, limit); }
  grep(pattern, path?, glob?) { return this.inner.grep(pattern, path, glob); }
  glob(pattern, path?) { return this.inner.glob(pattern, path); }

  // 写入类方法加拦截：检查路径是否在禁止列表中
  async write(filePath, content): Promise<WriteResult> {
    if (this.isDenied(filePath)) return { error: "Writes not allowed" };
    return this.inner.write(filePath, content);  // 未被禁止，委托给内部后端
  }
  async edit(filePath, old, newStr, replaceAll?): Promise<EditResult> {
    if (this.isDenied(filePath)) return { error: "Edits not allowed" };
    return this.inner.edit(filePath, old, newStr, replaceAll);
  }
}

多模态文件支持

V2 后端原生支持图片、音频、视频、PDF 等二进制文件

当 read() 遇到二进制文件（通过扩展名判断 MIME 类型）时，返回包含 Uint8Array 内容和相应 mimeType 的 ReadResult。文本文件返回 string 内容。

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

if (result.error) {
  console.error(result.error);  // 读取失败，输出错误信息
} else if (result.content instanceof Uint8Array) {
  // 二进制文件 —— content 是 Uint8Array，mimeType 标识文件类型
  console.log(`Binary file: ${result.mimeType}`);  // 例如 "image/png"
} else {
  // 文本文件 —— content 是 string 类型
  console.log(`Text file: ${result.mimeType}`);     // 例如 "text/plain"
}

type FileData =
  // 当前格式 (v2)
  | {
      content: string | Uint8Array; // string 用于文本，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 时间戳
    };

迁移指南

从后端工厂模式迁移到直接实例模式

从 deepagents 1.9.0 起，后端工厂模式已弃用。现在后端通过内部辅助函数解析运行时上下文，你可以直接传递实例。

// 工厂函数包装
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],
      }),
    },
  ),
});

已弃用的 API

本章回顾

后端是 Deep Agents 文件系统的灵魂——你控制数据存在哪里

延伸阅读