# FilesystemMiddleware

> **Class** in `deepagents`

📖 [View in docs](https://reference.langchain.com/python/deepagents/middleware/filesystem/FilesystemMiddleware)

Middleware for providing filesystem and optional execution tools to an agent.

This middleware adds filesystem tools to the agent: `ls`, `read_file`, `write_file`,
`edit_file`, `glob`, and `grep`.

Files can be stored using any backend that implements the `BackendProtocol`.

If the backend implements `SandboxBackendProtocol`, an `execute` tool is also added
for running shell commands.

This middleware also automatically evicts large tool results to the file system when
they exceed a token threshold, preventing context window saturation.

## Signature

```python
FilesystemMiddleware(
    self,
    *,
    backend: BACKEND_TYPES | None = None,
    system_prompt: str | None = None,
    custom_tool_descriptions: dict[str, str] | None = None,
    tool_token_limit_before_evict: int | None = 20000,
    human_message_token_limit_before_evict: int | None = 50000,
    max_execute_timeout: int = 3600,
)
```

## Description

**Example:**

```python
from deepagents.middleware.filesystem import FilesystemMiddleware
from deepagents.backends import StateBackend, StoreBackend, CompositeBackend
from langchain.agents import create_agent

# Ephemeral storage only (default, no execution)
agent = create_agent(middleware=[FilesystemMiddleware()])

# With hybrid storage (ephemeral + persistent /memories/)
backend = CompositeBackend(default=StateBackend(), routes={"/memories/": StoreBackend()})
agent = create_agent(middleware=[FilesystemMiddleware(backend=backend)])

# With sandbox backend (supports execution)
from my_sandbox import DockerSandboxBackend

sandbox = DockerSandboxBackend(container_id="my-container")
agent = create_agent(middleware=[FilesystemMiddleware(backend=sandbox)])
```

## Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `backend` | `BACKEND_TYPES \| None` | No | Backend for file storage and optional execution.  If not provided, defaults to `StateBackend` (ephemeral storage in agent state).  For persistent storage or hybrid setups, use `CompositeBackend` with custom routes.  For execution support, use a backend that implements `SandboxBackendProtocol`. (default: `None`) |
| `system_prompt` | `str \| None` | No | Optional custom system prompt override. (default: `None`) |
| `custom_tool_descriptions` | `dict[str, str] \| None` | No | Optional custom tool descriptions override. (default: `None`) |
| `tool_token_limit_before_evict` | `int \| None` | No | Token limit before evicting a tool result to the filesystem.  When exceeded, writes the result using the configured backend and replaces it with a truncated preview and file reference. (default: `20000`) |

## Extends

- `AgentMiddleware[FilesystemState, ContextT, ResponseT]`

## Constructors

```python
__init__(
    self,
    *,
    backend: BACKEND_TYPES | None = None,
    system_prompt: str | None = None,
    custom_tool_descriptions: dict[str, str] | None = None,
    tool_token_limit_before_evict: int | None = 20000,
    human_message_token_limit_before_evict: int | None = 50000,
    max_execute_timeout: int = 3600,
) -> None
```

| Name | Type |
|------|------|
| `backend` | `BACKEND_TYPES \| None` |
| `system_prompt` | `str \| None` |
| `custom_tool_descriptions` | `dict[str, str] \| None` |
| `tool_token_limit_before_evict` | `int \| None` |
| `human_message_token_limit_before_evict` | `int \| None` |
| `max_execute_timeout` | `int` |


## Properties

- `state_schema`
- `backend`
- `tools`

## Methods

- [`wrap_model_call()`](https://reference.langchain.com/python/deepagents/middleware/filesystem/FilesystemMiddleware/wrap_model_call)
- [`awrap_model_call()`](https://reference.langchain.com/python/deepagents/middleware/filesystem/FilesystemMiddleware/awrap_model_call)
- [`wrap_tool_call()`](https://reference.langchain.com/python/deepagents/middleware/filesystem/FilesystemMiddleware/wrap_tool_call)
- [`awrap_tool_call()`](https://reference.langchain.com/python/deepagents/middleware/filesystem/FilesystemMiddleware/awrap_tool_call)

---

[View source on GitHub](https://github.com/langchain-ai/deepagents/blob/a9e6e4f7ad7fe161dd9affc3d74bb19784aca70b/libs/deepagents/deepagents/middleware/filesystem.py#L522)