Inside Deep Agents' FilesystemMiddleware: 6 Tools, 2 Hooks & Multi-Backend Architecture

1. Filesystem Tools

FilesystemMiddleware

creates seven tools; the first six follow a consistent factory pattern. Each tool receives a ToolRuntime injected by LangChain, enabling state access. The pattern: fetch custom description or use default, define sync/async wrappers that resolve a backend via _get_backend(runtime), validate paths with _validate_path, execute the backend method, and return processed results wrapped in StructuredTool.

1.1 ls

Lists directory contents. Parameter: path (absolute). Uses truncate_if_too_long() with threshold TOOL_RESULT_TOKEN_LIMIT (default 20000); truncation notice: "... [results truncated, try being more specific with your parameters]".

1.2 read_file

Reads file content with pagination and multimodal image support. Parameters: file_path (absolute), offset (default 0), limit (default 100). Returns ToolMessage with content_blocks for images. Truncation uses tool_token_limit_before_evict (default 20000) with a detailed hint suggesting jq for JSON or formatting tools for other large files.

1.3 write_file

Creates a new file. Parameters: file_path (absolute), content (text).

1.4 edit_file

Edits via exact string replacement. Parameters: file_path, old_string, new_string, replace_all (default false).

1.5 glob

Finds files by glob pattern. Parameters: pattern (e.g., "**/*.py"), path (default "/"). Uses truncate_if_too_long().

1.6 grep

Searches text across files. Parameters: pattern (literal string), path (optional), glob (optional filter), output_mode ("files_with_matches" | "content" | "count", default "files_with_matches"). Uses truncate_if_too_long(). Output modes: file paths only, matching lines with line numbers, or per-file match counts.

2. Middleware Hooks

Four hook methods collapse to two essential ones: wrap_model_call and wrap_tool_call.

2.1 wrap_model_call — System Prompt Injection

Injects a default system prompt listing the six tools, mandating absolute paths (starting with "/"), and giving concise usage guidance for each tool.

2.2 wrap_tool_call — Result Eviction to Filesystem

Intercepts tool outputs exceeding _tool_token_limit_before_evict (estimated via NUM_CHARS_PER_TOKEN). The six filesystem tools are in TOOLS_EXCLUDED_FROM_EVICTION; the hook primarily protects against execute and inner middlewares like SubAgentMiddleware. Core logic in _process_large_message:

def _process_large_message(message, resolved_backend) -> tuple[ToolMessage, dict | None]:
    if len(content_str) <= NUM_CHARS_PER_TOKEN * self._tool_token_limit_before_evict:
        return message, None
    sanitized_id = sanitize_tool_call_id(message.tool_call_id)
    file_path = f"/large_tool_results/{sanitized_id}"
    result = resolved_backend.write(file_path, content_str)
    content_sample = _create_content_preview(content_str)
    replacement_text = TOO_LARGE_TOOL_MSG.format(
        tool_call_id=message.tool_call_id,
        file_path=file_path,
        content_sample=content_sample,
    )
    processed_message = ToolMessage(
        content=replacement_text,
        tool_call_id=message.tool_call_id,
        name=message.name,
    )
    return processed_message, result.files_update

Original content saved to /large_tool_results/{sanitized_id}. The replacement message tells the LLM: which tool call overflowed, where the full result is stored, how to read it incrementally via read_file with offset/limit, and shows a head/tail preview with omission markers.

3. BackendProtocol Implementations

Deep Agents abstracts storage via BackendProtocol. Four implementations covered:

3.1 Three Backend Implementations Compared

FilesystemBackend : Storage location: disk /path/to/file; write() returns WriteResult(files_update=None); lifecycle: persistent until deleted; path safety: needs virtual_mode protection.

StateBackend : Storage location: runtime.state["files"]; write() returns WriteResult(files_update={...}); lifecycle: disappears with session; path safety: natural isolation (memory).

StoreBackend : Storage location: runtime.store.put(); write() returns WriteResult(files_update=None); lifecycle: cross-session persistence; path safety: natural isolation (namespaces). FilesystemBackend suits local development, StateBackend temporary files, StoreBackend persistent storage. Real scenarios often need combinations, leading to CompositeBackend.

3.2 CompositeBackend — Routing & Composition

Routing rules: (1) longest-prefix match wins; (2) matched prefix stripped before delegating to child backend (e.g., "/memories/notes.txt" → "/notes.txt"); (3) root "/" aggregates all backends. Core routing code:

def _get_backend_and_key(self, key: str) -> tuple[BackendProtocol, str]:
    for prefix, backend in self.sorted_routes:
        if key.startswith(prefix):
            suffix = key[len(prefix):]
            stripped_key = f"/{suffix}" if suffix else "/"
            return backend, stripped_key
    return self.default, key

4. Deep Research Example

Using FilesystemBackend instead of default StateBackend, the workflow produces mcp_research_request.md with a research plan. The Status line is repeatedly edited via edit_file to track progress: "Research in progress" → "Research request saved, delegating to sub-agent" → "Research completed by sub-agent, synthesizing findings" → "Research completed and final report written to /final_report.md". Full trace at LangSmith (746b70fb-430c-439c-8935-1037ca898a47).