Choose and configure filesystem backends for Deep Agents. You can specify routes to different backends, implement virtual filesystems, and enforce policies.
Deep Agents expose a filesystem surface to the agent via tools like ls, read_file, write_file, edit_file, delete, glob, and grep. These tools operate through a pluggable backend. The read_file tool natively supports image files (.png, .jpg, .jpeg, .gif, .webp) across all backends, returning them as multimodal content blocks.Sandboxes and the LocalShellBackend also provide an execute tool.
This page explains how to:
When you deploy on LangSmith Deployment, a store is provisioned automatically. Use LangSmith tracing to debug file paths, permission denials, and cross-thread storage. Follow the observability quickstart to get set up.We recommend you also set up LangSmith Engine, which monitors your traces, detects issues, and proposes fixes.
agent = create_deep_agent(model="google_genai:gemini-3.5-flash") Thread-scoped. The default filesystem backend for an agent is stored in langgraph state. Files persist across turns within a thread (via your checkpointer) and are not shared across threads.
agent = create_deep_agent(model="google_genai:gemini-3.5-flash", backend=FilesystemBackend(root_dir="/Users/nh/Desktop/")) This gives the deep agent access to your local machine’s filesystem. You can specify the root directory that the agent has access to. Note that any provided root_dir must be an absolute path. Typically, wrap in a CompositeBackend to keep internal agent data (offloaded tool results, conversation history) separate from your project files.
agent = create_deep_agent(model="google_genai:gemini-3.5-flash", backend=StoreBackend()) This gives the agent access to long-term storage that is persisted across threads. This is great for storing longer term memories or instructions that are applicable to the agent over multiple executions.
agent = create_deep_agent(model="google_genai:gemini-3.5-flash", backend=ContextHubBackend("my-agent")) Stores files durably in a LangSmith Hub repo, without provisioning a separate LangGraph store.
agent = create_deep_agent(model="google_genai:gemini-3.5-flash", backend=sandbox) Execute code in isolated environments. Sandboxes provide filesystem tools plus the execute tool for running shell commands. Choose from LangSmith, AgentCore, Daytona, Deno, E2B, Modal, Runloop, or local VFS.
agent = create_deep_agent(model="google_genai:gemini-3.5-flash", backend=LocalShellBackend(root_dir=".", env={"PATH": "/usr/bin:/bin"})) Filesystem and shell execution directly on the host. No isolation—use only in controlled development environments. See security considerations below.
Thread-scoped by default, /memories/ persisted across threads. The Composite backend is maximally flexible. You can specify different routes in the filesystem to point towards different backends. See Composite routing below for a ready-to-paste example.
from deepagents import create_deep_agentfrom deepagents.backends import StateBackend# By default we provide a StateBackendagent = create_deep_agent(model="google_genai:gemini-3.5-flash")# Under the hood, it looks likeagent2 = create_deep_agent( model="openai:gpt-5.5", backend=StateBackend(),)
from deepagents import create_deep_agentfrom deepagents.backends import StateBackend# By default we provide a StateBackendagent = create_deep_agent(model="openai:gpt-5.5")# Under the hood, it looks likeagent2 = create_deep_agent( model="openai:gpt-5.5", backend=StateBackend(),)
from deepagents import create_deep_agentfrom deepagents.backends import StateBackend# By default we provide a StateBackendagent = create_deep_agent(model="anthropic:claude-sonnet-4-6")# Under the hood, it looks likeagent2 = create_deep_agent( model="openai:gpt-5.5", backend=StateBackend(),)
from deepagents import create_deep_agentfrom deepagents.backends import StateBackend# By default we provide a StateBackendagent = create_deep_agent(model="openrouter:z-ai/glm-5.2")# Under the hood, it looks likeagent2 = create_deep_agent( model="openai:gpt-5.5", backend=StateBackend(),)
from deepagents import create_deep_agentfrom deepagents.backends import StateBackend# By default we provide a StateBackendagent = create_deep_agent(model="fireworks:accounts/fireworks/models/glm-5p2")# Under the hood, it looks likeagent2 = create_deep_agent( model="openai:gpt-5.5", backend=StateBackend(),)
from deepagents import create_deep_agentfrom deepagents.backends import StateBackend# By default we provide a StateBackendagent = create_deep_agent(model="baseten:zai-org/GLM-5.2")# Under the hood, it looks likeagent2 = create_deep_agent( model="openai:gpt-5.5", backend=StateBackend(),)
from deepagents import create_deep_agentfrom deepagents.backends import StateBackend# By default we provide a StateBackendagent = create_deep_agent(model="ollama:north-mini-code-1.0")# Under the hood, it looks likeagent2 = create_deep_agent( model="openai:gpt-5.5", backend=StateBackend(),)
How it works:
Stores files in LangGraph agent state for the current thread via StateBackend.
Persists across multiple agent turns on the same thread via checkpoints. Files are not shared across threads.
Designed to be used from within a graph. Calling backend methods (e.g., state_backend.upload_files(...)) outside of a graph run won’t take effect until the graph executes.
Best for:
A scratch pad for the agent to write intermediate results.
Automatic eviction of large tool outputs which the agent can then read back in piece by piece.
Note that this backend is shared between the supervisor agent and subagents, and any files a subagent writes will remain in the LangGraph agent state
even after that subagent’s execution is complete. Those files will continue to be available to the supervisor agent and other subagents.
Exclude secrets from accessible filesystem paths (especially in CI/CD).
Use a sandbox backend for production environments requiring filesystem interaction.
Always use virtual_mode=True with root_dir to enable path-based access restrictions (blocks .., ~, and absolute paths outside root).Note that the default (virtual_mode=False) provides no security even with root_dir set.
Reads/writes real files under a configurable root_dir.
You can optionally set virtual_mode=True to sandbox and normalize paths under root_dir.
Uses secure path resolution, prevents unsafe symlink traversal when possible, can use ripgrep for fast grep.
Best for:
Local projects on your machine
CI sandboxes
Mounted persistent volumes
Wrap FilesystemBackend in a CompositeBackend for most use cases. Deep Agents automatically write internal data to the backend, including offloaded large tool results (under /large_tool_results/) and conversation history (under /conversation_history/). When you use FilesystemBackend alone, these internal files are written to real disk under root_dir, mixing agent artifacts with your project files.Use a CompositeBackend to route your project directory to FilesystemBackend while keeping internal paths in ephemeral StateBackend storage:
This way, agent reads and writes under /workspace/ go to real disk, while offloaded tool results and other internal data stay in ephemeral state. See Route to different backends for more routing patterns.
This backend grants agents direct filesystem read/write access and unrestricted shell execution on your host.
Use with extreme caution and only in appropriate environments.Appropriate use cases:
Local development CLIs (coding assistants, development tools)
Personal development environments where you trust the agent’s code
CI/CD pipelines with proper secret management
Inappropriate use cases:
Production environments (such as web servers, APIs, multi-tenant systems)
Processing untrusted user input or executing untrusted code
Security risks:
Agents can execute arbitrary shell commands with your user’s permissions
Agents can read any accessible file, including secrets (API keys, credentials, .env files)
Secrets may be exposed
File modifications and command execution are permanent and irreversible
A namespace factory controls where StoreBackend reads and writes data. It receives a LangGraph Runtime and returns a tuple of strings used as the store namespace. Use namespace factories to isolate data between users, tenants, or assistants.Pass the namespace factory to the namespace parameter when constructing a StoreBackend:
rt.context — User-supplied context passed via LangGraph’s context schema (for example, user_id)
rt.server_info — Server-specific metadata when running on LangGraph Server (assistant ID, graph ID, authenticated user)
rt.execution_info — Execution identity information (thread ID, run ID, checkpoint ID)
The Runtime argument is available in deepagents>=0.5.2. Earlier 0.5.x releases passed a BackendContext instead — see migrating from BackendContext below. rt.server_info and rt.execution_info require deepagents>=0.5.0.
Common namespace patterns:
from deepagents.backends import StoreBackend# Per-user: each user gets their own isolated storagebackend = StoreBackend( namespace=lambda rt: (rt.server_info.user.identity,), )# Per-assistant: all users of the same assistant share storagebackend = StoreBackend( namespace=lambda rt: ( rt.server_info.assistant_id, ),)# Per-thread: storage scoped to a single conversationbackend = StoreBackend( namespace=lambda rt: ( rt.execution_info.thread_id, ),)
You can combine multiple components to create more specific scopes — for example, (user_id, thread_id) for per-user per-conversation isolation, or append a suffix like "filesystem" to disambiguate when the same scope uses multiple store namespaces.Namespace components must contain only alphanumeric characters, hyphens, underscores, dots, @, +, colons, and tildes. Wildcards (*, ?) are rejected to prevent glob injection.
The namespace parameter will be required in v0.5.0. Always set it explicitly for new code.
When no namespace factory is provided, the legacy default uses the assistant_id from LangGraph config metadata. This means all users of the same assistant share the same storage. For multi-user going to production, always provide a namespace factory.
Before you begin:ContextHubBackend requires a Context Hub repo set up in LangSmith. Read the Context Hub concepts page first if you’re unfamiliar with agent repos and skill repos.
ContextHubBackend stores your agent’s filesystem in a LangSmith Context Hub repo. It can use a standalone repo or an agent repo that links out to skill repos.Repo structure: In the Context Hub, an agent repo holds the agent’s top-level instructions and configuration (for example, AGENTS.md, tools.json). It can link to one or more skill repos, each packaged as a reusable capability (for example, a SKILL.md with instructions for email formatting or code review). When you pass ContextHubBackend("my-agent"), the backend mounts the agent repo at the filesystem root; linked skill repos appear as subdirectories under /skills/.This means your agent’s context is intentionally spread across repos: one repo per agent, separate repos per skill. That separation lets skills be versioned, shared, and reused across multiple agents independently. If this feels fragmented, see Linked repos for the rationale.
from deepagents import create_deep_agentfrom deepagents.backends import CompositeBackend, StateBackend, StoreBackendfrom langgraph.store.memory import InMemoryStoreagent = create_deep_agent( model="google_genai:gemini-3.5-flash", backend=CompositeBackend( default=StateBackend(), routes={ "/memories/": StoreBackend(namespace=lambda _rt: ("memories",)), }, ), store=InMemoryStore(), # Store passed to create_deep_agent, not backend)
from deepagents import create_deep_agentfrom deepagents.backends import CompositeBackend, StateBackend, StoreBackendfrom langgraph.store.memory import InMemoryStoreagent = create_deep_agent( model="openai:gpt-5.5", backend=CompositeBackend( default=StateBackend(), routes={ "/memories/": StoreBackend(namespace=lambda _rt: ("memories",)), }, ), store=InMemoryStore(), # Store passed to create_deep_agent, not backend)
from deepagents import create_deep_agentfrom deepagents.backends import CompositeBackend, StateBackend, StoreBackendfrom langgraph.store.memory import InMemoryStoreagent = create_deep_agent( model="anthropic:claude-sonnet-4-6", backend=CompositeBackend( default=StateBackend(), routes={ "/memories/": StoreBackend(namespace=lambda _rt: ("memories",)), }, ), store=InMemoryStore(), # Store passed to create_deep_agent, not backend)
from deepagents import create_deep_agentfrom deepagents.backends import CompositeBackend, StateBackend, StoreBackendfrom langgraph.store.memory import InMemoryStoreagent = create_deep_agent( model="openrouter:z-ai/glm-5.2", backend=CompositeBackend( default=StateBackend(), routes={ "/memories/": StoreBackend(namespace=lambda _rt: ("memories",)), }, ), store=InMemoryStore(), # Store passed to create_deep_agent, not backend)
from deepagents import create_deep_agentfrom deepagents.backends import CompositeBackend, StateBackend, StoreBackendfrom langgraph.store.memory import InMemoryStoreagent = create_deep_agent( model="fireworks:accounts/fireworks/models/glm-5p2", backend=CompositeBackend( default=StateBackend(), routes={ "/memories/": StoreBackend(namespace=lambda _rt: ("memories",)), }, ), store=InMemoryStore(), # Store passed to create_deep_agent, not backend)
from deepagents import create_deep_agentfrom deepagents.backends import CompositeBackend, StateBackend, StoreBackendfrom langgraph.store.memory import InMemoryStoreagent = create_deep_agent( model="baseten:zai-org/GLM-5.2", backend=CompositeBackend( default=StateBackend(), routes={ "/memories/": StoreBackend(namespace=lambda _rt: ("memories",)), }, ), store=InMemoryStore(), # Store passed to create_deep_agent, not backend)
from deepagents import create_deep_agentfrom deepagents.backends import CompositeBackend, StateBackend, StoreBackendfrom langgraph.store.memory import InMemoryStoreagent = create_deep_agent( model="ollama:north-mini-code-1.0", backend=CompositeBackend( default=StateBackend(), routes={ "/memories/": StoreBackend(namespace=lambda _rt: ("memories",)), }, ), store=InMemoryStore(), # Store passed to create_deep_agent, not backend)
How it works:
CompositeBackend routes file operations to different backends based on path prefix.
Preserves the original path prefixes in listings and search results.
Best for:
When you want to give your agent both thread-scoped and cross-thread storage, a CompositeBackend allows you provide both a StateBackend and StoreBackend
When you have multiple sources of information that you want to provide to your agent as part of a single filesystem.
e.g. You have long-term memories stored under /memories/ in one Store and you also have a custom backend that has documentation accessible at /docs/.
Pass a backend instance to create_deep_agent(model=..., backend=...). The filesystem middleware uses it for all tooling.
The backend must implement BackendProtocol (for example, StateBackend(), FilesystemBackend(root_dir="."), StoreBackend(), ContextHubBackend("my-agent")).
/memories/agent.md → FilesystemBackend under /deepagents/myagent
ls, glob, grep aggregate results and show original path prefixes.
Notes:
Longer prefixes win (for example, route "/memories/projects/" can override "/memories/").
For StoreBackend routing, ensure a store is provided via create_deep_agent(model=..., store=...) or provisioned by the platform.
Deep Agents write internal data (offloaded tool results, conversation history) to the default backend. Use StateBackend as the default to keep these artifacts ephemeral and avoid writing them to disk or a persistent store. See the FilesystemBackend tip for a complete example.
Implement a custom backend to connect Deep Agents to storage systems such as databases, object stores, and remote filesystems. See community-built backends for examples.
Optional. Remove a file or, recursively, a directory. If the backend does not support deletion, the tool is automatically hidden from the model at request time.
To also support the execute tool (running shell commands), implement SandboxBackendProtocol instead, which extends BackendProtocol with an execute method.Always return structured result types with an error field for failure cases. Do not raise exceptions.
Example: S3-style backend skeleton
This skeleton maps filesystem paths to object keys. Fill in each method with your storage client’s list, read, search, upload, and read-modify-write operations.
Use permissions to declaratively control which files and directories the agent can read or write. Permissions apply to the built-in filesystem tools and are evaluated before the backend is called.
For custom validation logic beyond path-based allow/deny rules (rate limiting, audit logging, content inspection), enforce enterprise rules by subclassing or wrapping a backend.Block writes/edits under selected prefixes (subclass):
from deepagents.backends.filesystem import FilesystemBackendfrom deepagents.backends.protocol import WriteResult, EditResultclass GuardedBackend(FilesystemBackend): def __init__(self, *, deny_prefixes: list[str], **kwargs): super().__init__(**kwargs) self.deny_prefixes = [p if p.endswith("/") else p + "/" for p in deny_prefixes] def write(self, file_path: str, content: str) -> WriteResult: if any(file_path.startswith(p) for p in self.deny_prefixes): return WriteResult(error=f"Writes are not allowed under {file_path}") return super().write(file_path, content) def edit(self, file_path: str, old_string: str, new_string: str, replace_all: bool = False) -> EditResult: if any(file_path.startswith(p) for p in self.deny_prefixes): return EditResult(error=f"Edits are not allowed under {file_path}") return super().edit(file_path, old_string, new_string, replace_all)
Generic wrapper (works with any backend):
from deepagents.backends.protocol import ( BackendProtocol, WriteResult, EditResult, LsResult, ReadResult, GrepResult, GlobResult,)class PolicyWrapper(BackendProtocol): def __init__(self, inner: BackendProtocol, deny_prefixes: list[str] | None = None): self.inner = inner self.deny_prefixes = [p if p.endswith("/") else p + "/" for p in (deny_prefixes or [])] def _deny(self, path: str) -> bool: return any(path.startswith(p) for p in self.deny_prefixes) def ls(self, path: str) -> LsResult: return self.inner.ls(path) def read(self, file_path: str, offset: int = 0, limit: int = 2000) -> ReadResult: return self.inner.read(file_path, offset=offset, limit=limit) def grep(self, pattern: str, path: str | None = None, glob: str | None = None) -> GrepResult: return self.inner.grep(pattern, path, glob) def glob(self, pattern: str, path: str | None = None) -> GlobResult: return self.inner.glob(pattern, path) def write(self, file_path: str, content: str) -> WriteResult: if self._deny(file_path): return WriteResult(error=f"Writes are not allowed under {file_path}") return self.inner.write(file_path, content) def edit(self, file_path: str, old_string: str, new_string: str, replace_all: bool = False) -> EditResult: if self._deny(file_path): return EditResult(error=f"Edits are not allowed under {file_path}") return self.inner.edit(file_path, old_string, new_string, replace_all)
The backend factory pattern is deprecated as of deepagents 0.5.0. Pass pre-constructed backend instances directly instead of factory functions.
Previously, backends like StateBackend and StoreBackend required a factory function that received a runtime object, because they needed runtime context (state, store) to operate. Backends now resolve this context internally via LangGraph’s get_config(), get_store(), and get_runtime() helpers, so you can pass instances directly.
In deepagents>=0.5.2 (Python) and deepagents>=1.9.1 (TypeScript), namespace factories receive a LangGraph Runtime directly instead of a BackendContext wrapper. The old BackendContext form still works via backwards-compatible .runtime and .state accessors, but those accessors emit a deprecation warning and will be removed in deepagents>=0.7.What changed:
The factory argument is now a Runtime, not a BackendContext.
Drop the .runtime accessor — for example, ctx.runtime.context.user_id becomes rt.server_info.user.identity.
There is no direct replacement for ctx.state. Namespace info should be read-only and stable for the lifetime of a run, whereas state is mutable and changes step-to-step—deriving a namespace from it risks data ending up under inconsistent keys. If you have a use case that requires reading agent state, please open an issue.
# Before (deprecated, removed in v0.7)StoreBackend( namespace=lambda ctx: (ctx.runtime.context.user_id,), )# AfterStoreBackend( namespace=lambda rt: (rt.server_info.user.identity,), )
Create-only. On conflict, return WriteResult(error=...). On success, set path and for state backends set files_update={...}; external backends should use files_update=None.
