FileSystem Backend

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

Background and Goals

AI Agents need to interact with file systems (read, search, edit, execute commands), but different runtime environments have very different access methods: local disk, remote sandbox, in-memory simulation, object storage, etc. If each environment independently implements file operation logic, it leads to coupling between Middleware/Agent code and the underlying storage.

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

1. Decouple storage from business logic — Middleware depends only on the interface, not the underlying implementation
2. Pluggable replacement — Switching Backends enables running in different environments without modifying business code
3. Testability — Built-in InMemoryBackend requires no real disk I/O
4. Forward compatibility — All methods use struct parameters; adding new fields does not 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 implements Shell or StreamingShell, the Filesystem Middleware additionally registers the execute tool. The 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 supporting multi-modal file reading (images, PDFs, etc.), returning structured MultiFileContent.

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

When a Backend implements this interface and the Middleware is configured with UseMultiModalRead = true, 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, 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 Features

• 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), multiline mode
• Context lines — GrepRaw supports BeforeLines/AfterLines to show context around matches
• Glob matching — Uses the doublestar library to support ** 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 interfaces

External Implementations

The following Backend implementations reside in the eino-ext repository:

• Local Backend (github.com/cloudwego/eino-ext/adk/backend/local) — Local file system implementation, directly operates on the host 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 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
}