在構建智能代理（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實現，滿足不同場景的需求：

1. FilesystemBackend - 本地文件系統

• 功能：直接操作本地磁盤文件
• 特點：持久化存儲，支持virtual_mode安全隔離
• 適用：需要文件持久化、與其他系統共享文件的場景

2. LocalShellBackend - 本地Shell執行

• 功能：文件操作 + 本地Shell命令執行
• 特點：支持運行腳本、調用系統工具（git、docker等）
• 適用：需要編譯代碼、運行腳本、執行復雜命令的場景

3. SandboxBackend - 遠程沙箱環境

• 功能：在隔離的沙箱環境中執行命令和操作文件
• 特點：完全隔離的執行環境，支持雲端沙箱（如OpenSandbox、Daytona）
• 子類實現：
  • OpenSandboxBackend：基於OpenSandbox的開源沙箱方案
  • DaytonaBackend：基於Daytona的雲沙箱方案
• 適用：需要高安全性隔離、運行不可信代碼、雲端執行場景

4. 自定義Backend - 完全靈活

• 功能：通過實現BackendProtocol接口自定義存儲邏輯
• 特點：可以對接任何存儲介質（內存、數據庫、雲存儲等）
• 示例：DictBackend（內存存儲）、RedisBackend（Redis存儲）等
• 適用：特殊需求、測試環境、自定義存儲邏輯

Backend類型對比

四個漸進式示例

示例一：無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，讓智能代理真正具備"動手"能力！