FilesystemBackend: files on your disk

FilesystemBackend is a backend that maps the agent's file paths to real files under a folder you choose, so what the agent writes stays on your disk after the program ends.

Last updated: 29 Sep, 2026 · Deep Agents 0.7

The video's todo.txt on disk

The second backend in the video saves files in a root directory on the hard disk. It imports FilesystemBackend from deepagents.backends, sets the root to the notebook's own folder, and passes virtual_mode=True. The same request as before, create /notes/todo.txt, now makes a real notes folder with todo.txt in the project. The video checks it with pathlib.Path, then builds a fresh agent that has never seen the file and asks it to read the file back. The video's code follows, run on Groq with the model line swapped:

from pathlib import Path

from deepagents import create_deep_agent
from deepagents.backends import FilesystemBackend
from langchain.chat_models import init_chat_model

model = init_chat_model("groq:openai/gpt-oss-120b", max_retries=6)
ROOT = "."

agent = create_deep_agent(model=model, backend=FilesystemBackend(root_dir=ROOT, virtual_mode=True))
result = agent.invoke({"messages": [{"role": "user", "content": (
    "Create a file at /notes/todo.txt with exactly this content:\n"
    "1. Record video\n2. Edit video\n3. Upload video\n"
    "Then tell me you've done it.")}]})
print("--- Agent reply ---")
print(result["messages"][-1].content)

disk_path = Path(ROOT) / "notes" / "todo.txt"
print("--- On disk:", disk_path, "exists:", disk_path.exists())
print(disk_path.read_text())

fresh_agent = create_deep_agent(model=model, backend=FilesystemBackend(root_dir=ROOT, virtual_mode=True))
followup = fresh_agent.invoke({"messages": [{"role": "user", "content": "Read /notes/todo.txt back to me verbatim."}]})
print("--- Read-back with a fresh agent ---")
print(followup["messages"][-1].content)

--- Agent reply ---
The file **/notes/todo.txt** has been created with the requested content. Let me know if you need anything else!
--- On disk: notes/todo.txt exists: True
1. Record video
2. Edit video
3. Upload video
--- Read-back with a fresh agent ---
Here is the exact contents of **/notes/todo.txt**:

```
1. Record video
2. Edit video
3. Upload video
```

What the three steps show

• The agent wrote the file with the same write_file tool as before; only the backend changed.
• Python found it on disk at notes/todo.txt under the root folder, with the three lines.
• A fresh agent read it without any files passed in, because the file is on disk, not in a previous result.

The FilesystemBackend call

from deepagents.backends import FilesystemBackend

backend = FilesystemBackend(root_dir="trips", virtual_mode=True)   # /notes/a.md -> trips/notes/a.md
agent = create_deep_agent(model=model, backend=backend)

virtual_mode=True keeps every path inside root_dir: the agent cannot reach .., ~ or an absolute path outside it. The installed 0.7.19 defaults it to True, while the docs page still describes False as the default; pass it explicitly, as the docs advise.

StateBackend vs FilesystemBackend

Where FilesystemBackend fits

• A local coding or writing assistant that edits files in a project folder.
• Saving the trip planner's itinerary where you can open it in an editor.
• Reading an AGENTS.md or skills folder that already sits in your repository.

Related

• Previous: Context offloading: large results saved to files
• Next: StoreBackend: files shared across threads
• Reference: Backends: FilesystemBackend