FileSystem Backend

💡Package: github.com/cloudwego/eino/adk/filesystem

Background and Purpose

AI Agents need to interact with file systems (read, search, edit, execute commands), but access methods vary significantly across different runtime environments: local disk, remote sandboxes, in-memory simulation, object storage, etc. If file operation logic is implemented separately for each environment, it couples Middleware/Agent code to the underlying storage.

The filesystem.Backend interface solves this problem — serving as a unified file system operation protocol:

1. Decouples storage from business logic — Middleware depends only on the interface, not the underlying implementation
2. Pluggable replacement — Switch Backend to run in different environments without modifying business code
3. Easy to test — Built-in InMemoryBackend requires no real disk I/O
4. Forward compatible — All methods use struct parameters; new fields don’t break existing implementations

Backend Interface

type Backend interface {
    LsInfo(ctx context.Context, req *LsInfoRequest) ([]FileInfo, error)
    Read(ctx context.Context, req *ReadRequest) (*FileContent, error)
    GrepRaw(ctx context.Context, req *GrepRequest) ([]GrepMatch, error)
    GlobInfo(ctx context.Context, req *GlobInfoRequest) ([]FileInfo, error)
    Write(ctx context.Context, req *WriteRequest) error
    Edit(ctx context.Context, req *EditRequest) error
}

LsInfo

[]FileInfo

Read

*FileContent

GrepRaw

[]GrepMatch

GlobInfo

[]FileInfo

Write

error

Edit

error

Extension Interfaces

Shell / StreamingShell

Backends can optionally implement command execution capabilities. When a Backend also implements Shell or StreamingShell, the Filesystem Middleware will additionally register an execute tool. These two are mutually exclusive and cannot be configured simultaneously.

type Shell interface {
    Execute(ctx context.Context, input *ExecuteRequest) (result *ExecuteResponse, err error)
}

type StreamingShell interface {
    ExecuteStreaming(ctx context.Context, input *ExecuteRequest) (result *schema.StreamReader[*ExecuteResponse], err error)
}

MultiModalReader

An optional extension interface that supports multi-modal file reading (images, PDFs, etc.), returning structured MultiFileContent.

type MultiModalReader interface {
    MultiModalRead(ctx context.Context, req *MultiModalReadRequest) (*MultiFileContent, error)
}

When the Backend implements this interface and the Middleware has UseMultiModalRead = true configured, the read_file tool will use multi-modal reading.

Core Data Types

Request Types

LsInfoRequest

Path string

ReadRequest

FilePath string

Offset int

Limit int

MultiModalReadRequest

ReadRequest

Pages string

GrepRequest

Pattern string

Path string

Glob string

FileType string

CaseInsensitive bool

EnableMultiline bool

AfterLines int

BeforeLines int

GlobInfoRequest

Pattern string

Path string

*

**

?

[abc]

WriteRequest

FilePath string

Content string

EditRequest

FilePath string

OldString string

NewString string

ReplaceAll bool

ExecuteRequest

Command string

RunInBackendGround bool

Response Types

FileInfo

Path string

IsDir bool

Size int64

ModifiedAt string

FileContent

Content string

MultiFileContent

*FileContent

Parts []FileContentPart

FileContentPart

Type FileContentPartType

MIMEType string

Data []byte

"image"

"pdf"

GrepMatch

Content string

Path string

Line int

ExecuteResponse

Output string

ExitCode *int

Truncated bool

Constants

type FileContentPartType string

const (
    FileContentPartTypeImage FileContentPartType = "image"
    FileContentPartTypePDF   FileContentPartType = "pdf"
)

Built-in Implementation: InMemoryBackend

InMemoryBackend stores files in an in-memory map, primarily used for:

• Unit testing — Test Agent/Middleware file operation logic without a real file system
• Lightweight scenarios — Temporary file operations that don’t require persistence
• Tool result offloading — The Filesystem Middleware’s large tool result offloading feature uses InMemoryBackend by default

Constructor

func NewInMemoryBackend() *InMemoryBackend

Zero-parameter constructor that returns an empty in-memory file system.

Usage Example

backend := filesystem.NewInMemoryBackend()
ctx := context.Background()

// Write
_ = backend.Write(ctx, &filesystem.WriteRequest{
    FilePath: "/example/test.txt",
    Content:  "Hello, World!\nLine 2\nLine 3",
})

// Read (paginated)
content, _ := backend.Read(ctx, &filesystem.ReadRequest{
    FilePath: "/example/test.txt",
    Offset:   1,
    Limit:    10,
})

// List directory
files, _ := backend.LsInfo(ctx, &filesystem.LsInfoRequest{Path: "/example"})

// Search (regex)
matches, _ := backend.GrepRaw(ctx, &filesystem.GrepRequest{
    Pattern:         "Hello",
    Path:            "/example",
    CaseInsensitive: true,
})

// Edit
_ = backend.Edit(ctx, &filesystem.EditRequest{
    FilePath:   "/example/test.txt",
    OldString:  "Hello",
    NewString:  "Hi",
    ReplaceAll: false,
})

Implementation Characteristics

• Thread-safe — Based on sync.RWMutex, read operations use read locks, write operations use write locks
• GrepRaw parallel processing — Launches up to 10 workers for parallel matching during multi-file searches
• Regex support — Supports full regex, case-insensitive ((?i) prefix), and multiline mode
• Context lines — GrepRaw supports BeforeLines/AfterLines to show context around matches
• Glob matching — Uses the doublestar library for ** recursive matching
• FileType mapping — Built-in mapping table of 70+ file types to extensions (go, py, ts, rust, etc.)
• Does not implement Shell — InMemoryBackend does not implement the Shell/StreamingShell interface

External Implementations

The following Backend implementations are located in the eino-ext repository:

• Local Backend (github.com/cloudwego/eino-ext/adk/backend/local) — Local file system implementation that directly operates on the local disk
• Ark Agentkit Sandbox (github.com/cloudwego/eino-ext/adk/backend/agentkit) — Volcengine Agentkit remote sandbox implementation

Implementation Comparison

Custom Implementation

Implement the Backend interface to integrate with custom storage. For command execution, additionally implement Shell or StreamingShell; for multi-modal reading, implement MultiModalReader.

type MyBackend struct { /* ... */ }

func (b *MyBackend) LsInfo(ctx context.Context, req *filesystem.LsInfoRequest) ([]filesystem.FileInfo, error) {
    // Custom implementation
}

func (b *MyBackend) Read(ctx context.Context, req *filesystem.ReadRequest) (*filesystem.FileContent, error) {
    // Custom implementation
}

func (b *MyBackend) GrepRaw(ctx context.Context, req *filesystem.GrepRequest) ([]filesystem.GrepMatch, error) {
    // Custom implementation
}

func (b *MyBackend) GlobInfo(ctx context.Context, req *filesystem.GlobInfoRequest) ([]filesystem.FileInfo, error) {
    // Custom implementation
}

func (b *MyBackend) Write(ctx context.Context, req *filesystem.WriteRequest) error {
    // Custom implementation
}

func (b *MyBackend) Edit(ctx context.Context, req *filesystem.EditRequest) error {
    // Custom implementation
}

// Optional: implement Shell
func (b *MyBackend) Execute(ctx context.Context, input *filesystem.ExecuteRequest) (*filesystem.ExecuteResponse, error) {
    // Custom implementation
}

// Optional: implement MultiModalReader
func (b *MyBackend) MultiModalRead(ctx context.Context, req *filesystem.MultiModalReadRequest) (*filesystem.MultiFileContent, error) {
    // Custom implementation
}