什么是文件系统后端（Backends）

文件系统后端 = AI 智能体的文件存储仓库，决定 AI 的文件存在哪里、用什么方式读写，是 AI 操作文件的底层存储支撑。

分类	具体内容
核心类比	为 AI 智能体配备文件操作工具，等同于人类使用电脑文件管理器
AI 文件操作功能	1. `ls`：查看目录内容 2. `read_file`：读取文件 3. `write_file`：写入新文件 4. `edit_file`：编辑现有文件 5. `glob`：搜索文件 6. `grep`：文本搜索
文件系统后端定义	决定 AI 文件存储位置和访问方式的核心组件
通俗类比	类似电脑可将文件存储在本地硬盘、U 盘、云盘，AI 可选择不同存储后端

四种开箱即用的后端

1. StateBackend临时记忆后端（默认选择）

# 直接创建 AI 智能体
# 默认自动启用 StateBackend（临时记忆后端）
# 无需任何额外配置
agent = create_deep_agent()

StateBackend 是临时记忆后端，也是 AI 智能体的默认存储方式。
存储位置：所有文件、数据都保存在内存里。
生命周期：
- 对话运行中：文件可用
- 对话结束 / 智能体重启：数据全部自动清空
优点：开箱即用、不占硬盘、自动清理、无残留。
缺点：不能持久化，重启就丢数据。
适用场景：一次性任务、临时对话、不需要保存文件的场景。

2.FilesystemBackend本地磁盘后端-持久化存储

# 导入本地磁盘后端模块
from deepagents.backends import FilesystemBackend

# 示例1：让智能体直接访问电脑桌面文件夹（真实读写）
agent = create_deep_agent(
    backend=FilesystemBackend(root_dir="/Users/你的用户名/Desktop/")
)

# 示例2：推荐：安全沙箱模式，限制在指定目录内操作
agent = create_deep_agent(
    backend=FilesystemBackend(root_dir="D://fortest", virtual_mode=True)
)

本地磁盘后端（FilesystemBackend），属于持久化存储。
存储位置：文件直接保存在本机电脑硬盘上，真实物理存储。
两种模式
1. 普通模式：直接读写指定路径下的真实文件；
2. 沙箱模式（virtual_mode=True）：智能体只能访问你指定的文件夹，无法越权操作系统其他目录，安全性更高。
优点
- 文件永久保存在电脑，重启后数据不会丢失；
- 可直接和本地项目、文档联动，适合长期任务。
适用场景：项目开发、批量文件处理、需要长期保存文件的智能体任务。
通俗类比：就像把文件存在电脑硬盘里，关机重启文件都还在。

3.StoreBackend长期记忆后端-跨会话持久化

# 导入存储引擎与长期记忆后端
from langgraph.store.memory import InMemoryStore
from deepagents.backends import StoreBackend

# 创建启用长期记忆后端的智能体
agent = create_deep_agent(
    backend=lambda rt: StoreBackend(rt),  # 必须使用lambda函数传入
    store=InMemoryStore()  # 指定底层存储引擎
)

长期记忆后端（StoreBackend），核心能力是跨会话持久化。
核心特点
1. 支持跨对话保存文件、记忆、用户偏好，开启新对话也能读取历史数据；
2. 底层可对接 Redis、PostgreSQL 等专业数据库，适合生产环境；
3. 对接 LangSmith 云服务时可自动提供存储能力。
关键语法：backend 参数必须用 lambda rt: StoreBackend(rt) 这种匿名函数形式传入。
适用场景：需要长期记忆的智能体、保存用户偏好、多轮长期交互、多会话数据互通。
通俗类比：类似云盘，数据跨会话、跨环境同步留存。

4.CompositeBackend智能路由后端-混合存储

# 导入智能路由后端及前面3种存储后端
from deepagents.backends import CompositeBackend, StateBackend, StoreBackend, FilesystemBackend

# 配置智能路由：混合多种存储策略
composite_backend = lambda rt: CompositeBackend(
    default=StateBackend(rt),  # 默认：使用临时内存存储
    routes={
        "/memories/": StoreBackend(rt),          # 记忆目录：长期跨会话持久化
        "/projects/": FilesystemBackend("./projects/")  # 项目目录：保存到本地磁盘
    }
)

# 创建使用混合存储的智能体
agent = create_deep_agent(backend=composite_backend)

智能路由后端（CompositeBackend），也叫混合存储后端，可以把前面 3 种存储方式组合使用。
路由规则（核心逻辑）
1. 默认文件（如 /scratch.txt）：走 StateBackend 临时存储，对话结束自动消失；
2. /memories/ 下的文件：走 StoreBackend 长期记忆后端，永久跨会话保存；
3. /projects/ 下的文件：走 FilesystemBackend 本地磁盘后端，存到电脑本地文件夹。
适用场景：复杂 AI 应用，需要区分临时文件、用户记忆、项目代码，对不同目录使用不同存储策略。
通俗类比：像电脑自动分类，草稿放内存、笔记存云盘、项目文件存本地硬盘，一套系统自动路由。

详细配置指南

方式一：直接使用实例（简单直接）

1
2
3

# 适用于不需要运行时信息的后端
backend = FilesystemBackend(root_dir=".")
agent = create_deep_agent(backend=backend)

使用场景：本地磁盘后端这类不需要获取智能体运行时状态的存储类型
特点：直接实例化后端对象，写法简单、直接，开箱即用

方式二：使用工厂函数（更灵活）

1
2
3

# 适用于需要访问运行时状态的后端
backend_factory = lambda rt: StateBackend(rt)
agent = create_deep_agent(backend=backend_factory)

使用场景：临时记忆后端、长期记忆后端、智能路由后端， 需要接收运行时上下文rt 的存储类型
特点：通过lambda匿名函数（工厂函数），在智能体运行时动态传入运行时参数，适配复杂存储逻辑，灵活性更高

实际应用场景配置

场景 1：个人助手（混合存储配置）

composite_backend = lambda rt: CompositeBackend(
    default=StateBackend(rt),  # 默认：内存临时存储，对话结束自动清理
    routes={
        "/notes/": FilesystemBackend("~/Documents/AI_Notes/"),  # 笔记类文件存本地电脑文档文件夹，永久保存
        "/memories/": StoreBackend(rt)  # 用户偏好、重要记忆跨会话长期持久化
    }
)

设计逻辑

临时草稿：内存存储，用完即清
个人笔记：本地磁盘持久保存
习惯记忆：长期记忆后端跨对话留存

场景 2：团队项目管理（企业级混合存储）

composite_backend = lambda rt: CompositeBackend(
    default=FilesystemBackend("/team_projects/current/"),  # 默认：当前项目文件存本地磁盘
    routes={
        "/archive/": FilesystemBackend("/team_projects/archive/"),  # 历史项目归档到本地磁盘
        "/shared/": S3Backend(bucket="team-shared-bucket")  # 共享文件存云对象存储（AWS S3），团队成员可访问
    }
)

设计逻辑

当前项目：本地磁盘快速读写
历史归档：本地磁盘长期留存
团队共享：云端对象存储，支持多人协作访问

构建自定义存储后端

为什么需要自定义后端（4 大场景）

对接企业内部存储

连接公司私有文件系统、内部数据库、内网文档库，实现 AI 智能体访问企业私有数据。
集成第三方云存储

对接 AWS S3、Google Drive、阿里云 OSS、腾讯云 COS 等公有云对象存储。
定制安全权限策略

自定义文件加密、权限校验、访问审计、敏感文件过滤等专属安全规则。
场景化性能优化

针对特定业务（大文件、高频读写、缓存加速）做性能调优。

简单来说：内置后端不够用时，自己写代码实现一套全新的存储逻辑，适配企业、云端、安全、性能等个性化需求。

示例代码：自定义 S3 云存储后端

# 1. 导入依赖库
import boto3  # AWS官方SDK，用于操作S3
from deepagents.backends.protocol import BackendProtocol, WriteResult  # 框架后端协议、写入返回类
from deepagents.backends.utils import FileInfo  # 文件信息工具类（路径、大小、修改时间）

# 2. 自定义S3后端类：必须继承BackendProtocol（框架强制协议）
class S3Backend(BackendProtocol):
    # 初始化：连接S3，绑定存储桶bucket、路径前缀prefix
    def __init__(self, bucket_name, prefix=""):
        self.s3 = boto3.client('s3')
        self.bucket = bucket_name
        self.prefix = prefix

    # 方法1：ls_info —— 列出S3指定目录下的文件（对应ls命令）
    def ls_info(self, path: str) -> list[FileInfo]:
        response = self.s3.list_objects_v2(
            Bucket=self.bucket,
            Prefix=f"{self.prefix}{path.lstrip('/')}"
        )
        files = []
        # 把S3文件信息转为框架标准FileInfo格式
        for obj in response.get('Contents', []):
            files.append(FileInfo(
                path=f"/{obj['Key']}",      # 文件路径
                size=obj['Size'],           # 文件大小
                modified_at=obj['LastModified']  # 修改时间
            ))
        return files

    # 方法2：read —— 读取S3文件内容，支持分页读取
    def read(self, file_path: str, offset: int = 0, limit: int = 2000) -> str:
        key = f"{self.prefix}{file_path.lstrip('/')}"
        response = self.s3.get_object(Bucket=self.bucket, Key=key)
        content = response['Body'].read().decode('utf-8')
        return content[offset:offset+limit]

    # 方法3：write —— 写入文件到S3
    def write(self, file_path: str, content: str) -> WriteResult:
        key = f"{self.prefix}{file_path.lstrip('/')}"
        self.s3.put_object(Bucket=self.bucket, Key=key, Body=content)
        return WriteResult(path=file_path, files_update=None)

# 补充：还需实现 grep_raw、glob_info、edit 等剩余文件操作方法

关键规则（开发自定义后端必须遵守）

必须继承 BackendProtocol：这是 DeepAgents 框架的强制接口协议，不继承无法被智能体识别；
必须实现核心文件操作方法：
- ls_info：列出文件
- read：读取文件
- write：写入文件
- 还需补充：grep_raw(文本搜索)、glob_info(文件搜索)、edit(编辑文件)
标准化返回格式：文件信息用 FileInfo、写入结果用 WriteResult，和框架内置后端格式统一。
作用与使用场景
- 实现 AI 智能体直接操作云端对象存储（AWS S3、阿里云 OSS、腾讯云 COS 都可照此仿写）；
- 多用于团队协作、云端项目、跨设备访问的企业级 AI 应用。

安全与权限控制

基础权限控制：禁止写入敏感目录

# 继承本地磁盘后端，实现只读权限控制
class ReadOnlyBackend(FilesystemBackend):
    def __init__(self, read_only_paths,** kwargs):
        super().__init__(**kwargs)
        self.read_only_paths = read_only_paths  # 定义禁止修改的敏感目录列表

    # 重写写入方法：禁止向只读目录写入文件
    def write(self, file_path: str, content: str) -> WriteResult:
        for path in self.read_only_paths:
            if file_path.startswith(path):
                return WriteResult(error=f"禁止写入只读目录: {file_path}")
        return super().write(file_path, content)

    # 重写编辑方法：禁止修改只读目录内文件
    def edit(self, file_path: str, old_string: str, new_string: str, replace_all: bool = False):
        for path in self.read_only_paths:
            if file_path.startswith(path):
                return EditResult(error=f"禁止编辑只读目录文件: {file_path}")
        return super().edit(file_path, old_string, new_string, replace_all)

功能定位

这是安全权限控制的示例，基于本地磁盘后端 FilesystemBackend 二次开发，实现敏感目录只读保护，防止 AI 智能体误删、篡改重要系统 / 业务文件。

实现逻辑

继承原生后端：复用 FilesystemBackend 原有读写逻辑，仅重写危险操作；
指定只读路径：初始化传入禁止修改的目录列表 read_only_paths；
拦截写入操作：重写 write()，若文件路径在只读目录内，直接返回错误，拒绝写入；
拦截编辑操作：重写 edit()，禁止修改只读目录内文件内容；
放行正常操作：非只读目录，沿用父类原有逻辑正常读写。

核心作用

限制 AI 权限，禁止修改系统配置、核心业务文件、隐私数据；
属于沙箱安全策略，防止 AI 越权操作、误删关键文件；
可扩展：继续重写删除、重命名等方法，实现更严格的权限管控。

企业级权限包装器

class EnterprisePolicyWrapper:
    def __init__(self, inner_backend, user_role):
        self.inner = inner_backend          # 被包装的底层存储后端
        self.user_role = user_role          # 当前用户角色
        self.setup_policies()

    def setup_policies(self):
        # 根据用户角色，分配可访问路径
        if self.user_role == "admin":
            self.allowed_paths = ["/"]  # 管理员：可访问全部路径
        elif self.user_role == "developer":
            self.allowed_paths = ["/projects/", "/docs/"]  # 开发者：仅项目、文档目录
        else:
            self.allowed_paths = ["/public/"]  # 普通用户：仅公开目录

    def check_permission(self, path):
        # 校验路径是否在允许范围内
        return any(path.startswith(allowed) for allowed in self.allowed_paths)

    def write(self, file_path: str, content: str) -> WriteResult:
        # 写入前校验权限
        if not self.check_permission(file_path):
            return WriteResult(error="权限不足：无法写入该路径")
        return self.inner.write(file_path, content)

    # 后续需要继续封装 read、edit、ls_info 等全部文件操作方法

功能定位

企业级权限包装器，用装饰器 / 包装器模式，给任意存储后端叠加基于角色 (RBAC) 的权限控制，适配企业多用户、分级权限的场景。

核心逻辑

包装模式：不修改原有存储后端代码，在外层套一层权限校验，兼容临时 / 本地 / 云存储等所有后端；
角色分级
- 管理员 admin：可访问系统全部文件；
- 开发者 developer：仅访问项目、文档目录；
- 普通用户：只能访问公开目录；

权限校验：所有文件操作（写入、读取、编辑）前，先判断路径是否在角色允许范围内；
放行底层执行：权限通过后，交给内部真实后端执行操作。

适用场景

企业多角色 AI 智能体平台、多用户文件隔离、精细化权限管控，实现不同用户只能访问自己对应目录。

后端协议规范详解

所有自定义后端必须实现以下6个核心方法

1. ls_info(path)-列出目录内容

功能：对应 Linux ls 命令，列出指定目录下的文件和文件夹信息

def ls_info(self, path: str) -> list[FileInfo]:
    # 返回示例
    return [
        FileInfo(path="/file1.txt", size=1024, is_dir=False),
        FileInfo(path="/folder/", is_dir=True)
    ]

返回格式：必须返回 FileInfo 对象列表 ，FileInfo 是框架规定的标准文件信息结构
字段含义
- path：文件 / 文件夹路径
- size：文件大小（文件夹可省略）
- is_dir：True= 文件夹，False= 普通文件

2.read (file_path, offset, limit) — 读取文件

参数说明

offset：开始读取的位置
limit：最大读取长度
文件不存在时返回错误字符串

def read(self, file_path: str, offset: int = 0, limit: int = None) -> str:
    # 模拟读取文件，支持分片读取
    content = "hello world sample content"
    return content[offset:offset+limit] if limit else content[offset:]

3.grep_raw (pattern, path, glob) — 文本搜索

功能说明

支持正则表达式搜索
可指定搜索路径或通配符

1
2
3

def grep_raw(self, pattern: str, paths: list[str]) -> list[str]:
    # 模拟正则文本搜索，返回匹配行
    return ["匹配行1：hello", "匹配行2：world"]

4. glob_info (pattern, path) — 文件搜索

功能说明

使用通配符查找文件（如 *.py）

def glob_info(self, pattern: str) -> list[FileInfo]:
    # 通配符搜索文件，返回FileInfo列表
    return [
        FileInfo(path="/demo.py", size=2048, is_dir=False),
        FileInfo(path="/test.py", size=1024, is_dir=False)
    ]

5. write (file_path, content) — 创建文件

功能说明

文件已存在则返回错误
成功返回 WriteResult

1
2
3

def write(self, file_path: str, content: str) -> WriteResult:
    # 模拟写入文件
    return WriteResult(path=file_path, files_update=None)

6.edit (file_path, old_string, new_string, replace_all) — 编辑文件

参数说明

replace_all=False：只替换第一个匹配
replace_all=True：替换所有匹配

1
2
3

def edit(self, file_path: str, old_string: str, new_string: str, replace_all: bool = False):
    # 模拟文本替换编辑
    return EditResult(path=file_path, success=True)

实践总结

后端选型策略指南（直接照抄配置即可

使用场景	推荐后端	配置示例
简单测试 / 演示	`StateBackend`（默认）	`create_deep_agent()`，零配置开箱即用
个人项目开发	`FilesystemBackend`	`FilesystemBackend("./workspace/")`，本地磁盘持久存储
生产环境长期记忆	`StoreBackend`	搭配 Redis / PostgreSQL 数据库，实现跨会话持久化
复杂企业应用	`CompositeBackend`	混合多种存储策略，按路径自动路由

安全建议（生产环境必遵守）

强制开启沙箱模式：使用本地磁盘后端时，必须设置 virtual_mode=True，限制智能体只能访问指定目录，防止越权
禁止访问系统根目录：隔离系统敏感文件，避免 AI 篡改系统配置
分级权限管控：基于用户角色（管理员 / 开发者 / 普通用户）限制文件读写、编辑权限
定期备份重要数据：内存型后端数据重启丢失，重要文件务必做备份

性能优化技巧

大文件分页读取：使用 offset（偏移量）+ limit（读取长度）参数，分片读取超大文件，避免一次性加载占用内存
云存储服务端筛选：对接 S3、阿里云 OSS 等云存储时，在云服务端提前过滤搜索结果，减少网络传输
常用数据缓存：对高频访问的文件、配置添加缓存层，提升读写速度

常见问题

问题	答案
可以同时使用多个后端吗？	可以，使用 CompositeBackend 实现多后端混合，按路径自动路由
文件路径有什么限制？	1. 必须是绝对路径，以 `/` 开头 2. 不同后端存储空间相互隔离
如何处理文件冲突？	1. `write` 仅用于新建，文件已存在会报错 2. 修改文件必须用 `edit` 方法
自定义后端复杂吗？	不复杂，只需实现6 个核心方法，对接云存储可直接用官方 SDK

Jean's Blog

DeepAgents的“记忆宫殿”--Backends

什么是文件系统后端（Backends）

四种开箱即用的后端

1. StateBackend临时记忆后端（默认选择）

2.FilesystemBackend本地磁盘后端-持久化存储

3.StoreBackend长期记忆后端-跨会话持久化

4.CompositeBackend智能路由后端-混合存储

详细配置指南

方式一：直接使用实例（简单直接）

方式二：使用工厂函数（更灵活）

实际应用场景配置

场景 1：个人助手（混合存储配置）

场景 2：团队项目管理（企业级混合存储）

构建自定义存储后端

为什么需要自定义后端（4 大场景）

示例代码：自定义 S3 云存储后端

安全与权限控制

基础权限控制：禁止写入敏感目录

企业级权限包装器

后端协议规范详解

1. ls_info(path)-列出目录内容

2.read (file_path, offset, limit) — 读取文件

3.grep_raw (pattern, path, glob) — 文本搜索

4. glob_info (pattern, path) — 文件搜索

5. write (file_path, content) — 创建文件

6.edit (file_path, old_string, new_string, replace_all) — 编辑文件

实践总结

后端选型策略指南（直接照抄配置即可

安全建议（生产环境必遵守）

性能优化技巧

常见问题