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.
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,
max_execute_timeout: int = 3600
)Example:
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)])| Name | Type | Description |
|---|---|---|
backend | BACKEND_TYPES | None | Default: NoneBackend for file storage and optional execution. If not provided, defaults to For persistent storage or hybrid setups, use For execution support, use a backend that implements |
system_prompt | str | None | Default: NoneOptional custom system prompt override. |
custom_tool_descriptions | dict[str, str] | None | Default: NoneOptional custom tool descriptions override. |
tool_token_limit_before_evict | int | None | Default: 20000Token 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. |
Update the system prompt and filter tools based on backend capabilities.
(async) Update the system prompt and filter tools based on backend capabilities.
Check the size of the tool call result and evict to filesystem if too large.
(async)Check the size of the tool call result and evict to filesystem if too large.