构建智能代理（AI Agent）时，吾辈常需使Agent具读、写、索、辑之能。DeepAgents框架藉Backend（后端）之制，成此功能，为Agent设一安且可控之文操作境。是文将深究Backend之理、用法，并历四渐之例，以彰其伟力。

Backend者何？

Backend乃DeepAgents框架之枢要抽象，其定Agent与文系统相交之法。由Backend，Agent可：

• 列文与录（ls_info）
• 读文之容（read）
• 书于新文（write）
• 索文之实（grep_raw）
• 符通配以合文（glob_info）
• 修旧文（edit）

Backend之要，在于安泰与变通：此可限Agent之文件操作于特定目录，防越权而入，复支多种存储介质（本地文件系统、内存、云存储等）。

Backend之用场

1. 代码生成与编辑：使Agent于沙盒中编修代码
2. 数据分析：Agent读取、处理、生成数据之文
3. 文档处理：自动化文档之创与内容之新
4. 配置管理：动态生成、修易配置之文

DeepAgents所支Backend之类型

DeepAgents之框架，备诸般Backend之实现，应不同之境遇：

一、FilesystemBackend——本处之文件系统

• 其能：直操本处磁盘之文牍
• 其特：久存于世，支持virtual_mode之安全隔绝
• 其宜：需久存文件、与他系统共通文件之境遇

二、LocalShellBackend——本处Shell之执行

• 其能：操文牍兼行本处Shell之命
• 其特：可运行脚本，调用系统之具（如git、docker等）
• 适用：需编译代码、运行脚本、执行繁复之命者

3. SandboxBackend - 远程沙箱之境

• 其能：于隔离之沙箱中执行命，操弄其文
• 其特：全然隔离之执行境，支持云端沙箱（如OpenSandbox、Daytona）
• 子类之实：
  • OpenSandboxBackend：基于OpenSandbox之开源沙箱方案
  • DaytonaBackend：基于Daytona之云沙箱方案
• 适于：需高安隔离、运行不可信码、云上执行之境

4. 自定Backend - 活泼无拘

• 功能：通由实BackendProtocol接以自定存贮之理
• 特点：可接诸般存贮之器（如内存、数据库、云存等）
• 示例：DictBackend（内存存）、RedisBackend（Redis存）等
• 适于：特需之境、测试之境、自定存贮之理

后端类型之辨

四则渐次之例

例一：无Backend之基础Agent

至简之Agent配置，不恃Backend，惟恃工具调用以成事：

from deepagents import create_deep_agent
from langgraph.checkpoint.memory import InMemorySaver

# 创建内存检查点保存器
checkpointer = InMemorySaver()

# 创建基础Agent
agent = create_deep_agent(
    model=llm,
    tools=[web_search],
    #checkpointer=checkpointer,
    system_prompt='你是一个助手，请根据用户输入的指令，进行相应的操作。'
)

特性：

• 宜于但求调用外部API（如Web搜索）之境
• 不能为文件操作之事
• 配置简明，启动迅疾

例二：FilesystemBackend - 文件系统沙盒

若需Agent操作文件，FilesystemBackend此乃常用之选：

import os
from deepagents import create_deep_agent
from deepagents.backends import FilesystemBackend
from langgraph.checkpoint.memory import InMemorySaver

checkpointer = InMemorySaver()

# 创建Agent工作目录
temp_workspace = "./agent_workspace"
os.makedirs(temp_workspace, exist_ok=True)

agent = create_deep_agent(
    model=llm,
    tools=[web_search],
    checkpointer=checkpointer,
    backend=FilesystemBackend(
        root_dir=temp_workspace,
        virtual_mode=True,  # 防止Agent通过`../../`跳出根目录
    ),
    system_prompt='你是一个助手，请根据用户输入的指令，进行相应的操作。'
)

要旨参数：

• root_dir：指定Agent之工作根目录；
• virtual_mode=True：启用虚拟之模，以防路径穿越之攻（如../../etc/passwd）；

适用之境；：

• 需持久化存储文件；
• Agent生成之文件需存于磁盘；
• 需与他系统共享文件；

示例三：LocalShellBackend - 支持命令执行；

若Agent非惟操作文件，亦需执行shell命令，LocalShellBackend是更优之选：

import os
import sys
from deepagents import create_deep_agent
from deepagents.backends import FilesystemBackend, LocalShellBackend
from langgraph.checkpoint.memory import InMemorySaver

checkpointer = InMemorySaver()

temp_workspace = "./agent_workspace"
os.makedirs(temp_workspace, exist_ok=True)

agent = create_deep_agent(
    model=llm,
    tools=[web_search],
    checkpointer=checkpointer,
    backend=LocalShellBackend(
        root_dir=temp_workspace,
        virtual_mode=True,
        timeout=30,  # 命令执行超时时间（秒）
        max_output_bytes=50000,  # 命令输出最大字节数
        env={
            "PATH": f"{os.path.dirname(sys.executable)};{os.environ.get('PATH', '')}",
        },
    ),
    system_prompt='你是一个助手，请根据用户输入的指令，进行相应的操作。'
)

新增之功能：

• 可施以shell之命（如python script.py、ls -la），
• 可设超时与时量之限，以御恶命或惰命，
• 可自定境变，俾命得于正境而行，

适用之境：

• 需行脚本或编码，
• 需召系统之具（如git、docker），
• 需施繁复之数据处理之管，

例四：自定Backend - DictBackend，

DeepAgents之雄伟，在于其可延展。由施实现BackendProtocol之接口，吾辈可创全然自定之Backend：

from deepagents.backends.protocol import BackendProtocol, WriteResult, EditResult
from deepagents.backends.utils import FileInfo, GrepMatch
from datetime import datetime
import re

class DictBackend(BackendProtocol):
    """将文件存储在内存字典中的自定义后端"""
    
    def __init__(self):
        self.files = {}  # 路径 -> 内容
        self.metadata = {}  # 路径 -> 元数据
    
    def ls_info(self, path: str) -> list[FileInfo]:
        """列出文件和目录信息"""
        result = []
        seen_dirs = set()
        for file_path in self.files.keys():
            if file_path.startswith(path):
                remaining = file_path[len(path):]
                if '/' in remaining:
                    dir_name = path + remaining.split('/')[0] + '/'
                    if dir_name not in seen_dirs:
                        seen_dirs.add(dir_name)
                        result.append(FileInfo(path=dir_name, is_dir=True))
                else:
                    meta = self.metadata.get(file_path, {})
                    result.append(FileInfo(
                        path=file_path,
                        is_dir=False,
                        size=meta.get('size', 0),
                        modified_at=meta.get('modified_at')
                    ))
        return result
    
    def read(self, file_path: str, offset: int = 0, limit: int = 2000) -> str:
        """读取文件内容，支持分页"""
        if file_path not in self.files:
            return f"Error: File '{file_path}' not found"
        content = self.files[file_path]
        lines = content.splitlines(keepends=True)
        start_line = offset
        end_line = start_line + limit if limit > 0 else len(lines)
        selected_lines = lines[start_line:end_line]
        result = ''.join(f"{start_line + i + 1}: {line}" for i, line in enumerate(selected_lines))
        return result if result else "(end of file)"
    
    def write(self, file_path: str, content: str) -> WriteResult:
        """写入新文件（仅创建，不覆盖）"""
        if file_path in self.files:
            return WriteResult(error=f"File '{file_path}' already exists (create-only).")
        self.files[file_path] = content
        self.metadata[file_path] = {
            'size': len(content),
            'modified_at': datetime.now().isoformat()
        }
        return WriteResult(path=file_path, files_update=None)
    
    def grep_raw(self, pattern: str, path: str | None = None, glob: str | None = None) -> list[GrepMatch] | str:
        """正则表达式搜索文件内容"""
        try:
            re.compile(pattern)
        except re.error as e:
            return f"Invalid regex pattern: {e}"
        matches = []
        for file_path, content in self.files.items():
            for i, line in enumerate(content.splitlines()):
                if re.search(pattern, line):
                    matches.append(GrepMatch(path=file_path, line=i+1, text=line))
        return matches
    
    def glob_info(self, pattern: str, path: str = "/") -> list[FileInfo]:
        """通配符匹配文件"""
        import fnmatch
        all_files = [
            FileInfo(path=p, is_dir=False, size=self.metadata[p]['size'], 
                    modified_at=self.metadata[p]['modified_at']) 
            for p in self.files.keys() if p.startswith(path)
        ]
        matched = [fi for fi in all_files if fnmatch.fnmatch(fi.path, path.rstrip('/') + '/' + pattern)]
        return matched
    
    def edit(self, file_path: str, old_string: str, new_string: str, replace_all: bool = False) -> EditResult:
        """编辑文件内容"""
        if file_path not in self.files:
            return EditResult(error=f"File '{file_path}' not found")
        content = self.files[file_path]
        if replace_all:
            new_content = content.replace(old_string, new_string)
            occurrences = content.count(old_string)
        else:
            if content.count(old_string) != 1:
                return EditResult(error=f"Found {content.count(old_string)} occurrences. For safety, edit requires exactly one match unless replace_all=True.")
            new_content = content.replace(old_string, new_string, 1)
            occurrences = 1
        if new_content == content:
            return EditResult(error=f"String '{old_string}' not found.")
        self.files[file_path] = new_content
        self.metadata[file_path]['size'] = len(new_content)
        self.metadata[file_path]['modified_at'] = datetime.now().isoformat()
        return EditResult(path=file_path, files_update=None, occurrences=occurrences)

欲用自定Backend：

from deepagents import create_deep_agent
from deepagents.backends import FilesystemBackend, LocalShellBackend
from langgraph.checkpoint.memory import InMemorySaver

from my_backend import DictBackend

checkpointer = InMemorySaver()

agent = create_deep_agent(
    model=llm,
    tools=[web_search],
    checkpointer=checkpointer,
    backend=DictBackend(),
    system_prompt='你是一个助手，请根据用户输入的指令，进行相应的操作。'
)

自定Backend之利：

• 尽得掌控：可定任何存理（数据库、云存、加密存等）
• 安隔离：Agent操作尽在内存，不扰真文件系
• 可测性：便於单元测与调
• 性能优：针对特定境优读写能

Backend之择指南

至善之术

1. 恒启virtual_mode：御路径穿袭之患，保Agent于沙盒之中操持
2. 设适中超时与节制：杜恶意或低效命令之耗，免资源过竭
3. 用checkpointer存其状：助对话史之复，行断点续传
4. 自定Backend时践其全法：使诸术皆得善施，防运行之失
5. 录Backend之操，记其日志：便於調試與審計Agent行為

總結

Backend者，DeepAgents框架之橋也，連AI Agent與文件系統。選擇或自定Backend，可為Agent營造安全、高效、可控之文件操作境。自簡單無Backend之配置，至功能強大之LocalShellBackend，復至完全自定之DictBackend，DeepAgents供豐富選項，以應萬般應用之場。

善用Backend，將助君構築更強大、更實用之AI Agent，使智能代理得具「動手」之能！