FilesystemMiddleware(
self,
*,
backend: BACKEND_TYPES | None = None,
system_prompt: str | 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: None |
tool_token_limit_before_evict | int | None | Default: 20000 |
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.
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)])Optional custom tool descriptions override.
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.