Modern AI agents are no longer expected to answer a question alone. They're expected to complete real work: plan a multi-step task, inspect source material, produce intermediate artifacts, and hand off pieces of the problem to other agents, compressing work that used to take days into hours. That shift raises the bar on what an agent needs underneath it. An agent can only plan and execute at that speed if it can reliably navigate, search, read, and update the filesystem it's working with along the way.
The MongoDB virtual filesystem (VFS) for LangChain Deep Agents connects that filesystem experience to MongoDB Atlas and your underlying object store (e.g., S3 bucket). It gives Deep Agents a familiar virtual filesystem, providing agents with a searchable workspace that persists across sessions, deployments, and sub-agents. Developers building on Deep Agents can now use MongoDB Atlas as the data platform for their agents, including MongoDB Search, Vector Search, and hybrid search, without changing how their agent code reads or writes files. This architecture lets an agent plan, inspect source material, create intermediate artifacts, and return to work that may span hours or days without loading an entire corpus into its context window.
This post explains what Deep Agents and a virtual filesystem are, how the MongoDB backend integration works in an agentic application, and where the pattern can be useful in enterprise agent systems.
How LangChain Deep Agents use a virtual filesystem
What are LangChain Deep Agents?
LangChain Deep Agents are an agent harness built on LangChain and LangGraph for complex, multi-step work. They add capabilities such as planning, subagents, and filesystem-oriented tools, so an agent can break a large task into smaller actions rather than trying to solve everything in a single context window.
A Deep Agent can work with operations such as:
Is to understand the directory structure
glob to find files by path pattern
grep to search file content
read to retrieve a file
write and edit to create or modify artifacts
upload_files and download_files for bulk file movement
These tools are exposed through a backend contract. The agent does not need to know whether the files live on a local filesystem, in a LangGraph store, in an object storage, or behind another persistence layer. It calls the same filesystem interface, and the configured backend supplies the data.
For MongoDB-specific LangChain integrations, see the Integrate MongoDB with LangChain - Atlas documentation.
What is a virtual filesystem?
A virtual filesystem is a logical, path-based view of data whose physical storage is abstracted away. An agent may see paths such as docs/, reports/, or projects/customer-a/, even when the underlying bytes reside in an object store and the searchable representation is stored in a database.
This abstraction matters for agents because filesystem navigation is naturally incremental. Instead of loading an entire corpus into the prompt, an agent can first list a directory, narrow the search with a filename pattern, search for a concept, read the relevant file, and then write its findings back as an artifact. This helps agents stay within context limits and reduce costs, since each step pulls in only the slice of the corpus it actually needs rather than the entire corpus.
The virtual filesystem is therefore more than a storage abstraction. It is a context-management interface for agentic work.
What is the MongoDB virtual filesystem for LangChain Deep Agents?
The langchain-mongodb-deepagents-vfs package is a drop-in implementation of Deep Agents’ BackendProtocol. It presents an object store-backed corpus as a filesystem to the agent and routes operations to the system that is best suited for them:
Search-oriented operations: grep, glob, and ls run with MongoDB Atlas.
File-byte operations: read, write, edit, upload_files, and download_files go directly to your object store.
A background synchronization layer keeps the MongoDB Search representation aligned with your object store.
The result is a clean separation between the source of truth and the search index. Your object store owns the original documents. MongoDB Atlas stores the searchable chunks, embeddings, and path metadata needed to make the corpus discoverable.
It's worth asking why the search plane should be a separate system like Atlas rather than an S3-compatible platform that also offers search, vector search, and hybrid search on the same data. The two-plane split isn't a limitation; it's the point. Object storage is optimized for durable, low-cost, long-term storage of file bytes; it isn't built to maintain live indexes, rank hybrid queries, or serve low-latency structured metadata queries simultaneously. Atlas is built as an operational database with Search, Vector Search, and hybrid ranking as first-class, indexed capabilities, so the search plane runs on a system designed for exactly that job, while the object store keeps doing what it's already good at.
Hybrid search for agent queries
The package uses MongoDB Search and MongoDB Vector Search together for grep. Full-text search is good at exact terms, identifiers, filenames, and rare strings. Vector search is good at paraphrases and natural-language questions. Combining both signals lets an agent search for a literal token, such as MAX_RETRIES, or a conceptual question, such as "where is retry behavior configured?", through the same interface.
The package combines the full-text and vector results with MongoDB’s $rankFusion aggregation stage. This keeps ranking on the database side and avoids a separate client-side reranking layer, which would add an extra round trip between the agent and a separate reranking step. This also reflects a broader tradeoff in how the search plane is built. Getting full-text, vector, and hybrid ranking on an S3-compatible platform usually means wiring together separate specialized systems, a search engine for full-text, a vector database for embeddings, and a reranking layer to merge the two, each with its own indexing pipeline to keep in sync with the source data. Atlas runs all three in one engine, so $rankFusion can combine full-text and vector results natively in a single query instead of coordinating results across systems that don't know about each other.
The current implementation uses a token-aware chunking pipeline. Supported document formats include plain text and Markdown, PDFs, DOCX, XLSX, XLS, PPTX, and PPT. Chunks retain positional metadata such as source path, page number, character offsets, and line information, so results can be returned in a Deep Agents-compatible, line-oriented shape.
The default embedding path uses Amazon Bedrock embeddings, with an OpenAI option available through the package extras. Applications can also inject a LangChain-compatible embedding implementation directly.
A typical integration looks like this:
The agent can now use its normal filesystem tools without custom MongoDB or S3 tools in its reasoning loop.
How the MongoDB VFS Backend separates storage and search
The architecture can be understood as a two-plane system: object storage is the data plane for file bytes, while MongoDB Atlas is the control and search plane for metadata, chunks, and retrieval indexes.
Figure 1. How the LangChain Deep Agents VFS backend routes file bytes through object storage and search operations through MongoDB Atlas.
How the backend ingests files into MongoDB Atlas
When MongoFilesystemBackend is constructed, initialization begins in the background. Index provisioning, the initial synchronization, and watcher startup run on a daemon thread. Pass-through file operations can be used immediately, while search operations wait until the initial synchronization is ready.
The ingestion path is:
List objects in the configured S3 bucket and prefix.
Download each eligible object.
Extract text using the format-specific parser.
Split the text into chunks with positional metadata.
Generate embeddings.
Upsert chunks and metadata into MongoDB Atlas.
Provision or verify the MongoDB Search and Vector Search indexes.
The current chunking strategy uses 512-token chunks with a 64-token overlap. ETags make initial sync and watcher ingestion idempotent: unchanged objects can be skipped rather than re-downloaded and re-embedded.
How the backend routes file and search operations
When the agent calls ls, the backend queries Atlas for path metadata and groups the results as directory entries. When it calls glob, the backend applies standard path-pattern semantics to find matching files. When it calls grep, Atlas combines full-text and vector retrieval over the chunk corpus and returns ranked matches.
When the agent calls read, the backend retrieves the current bytes from the object store rather than from the search index. That distinction is important: search results are optimized for discovery, while reads return the source document.
How watchers keep the MongoDB Search Index current
The package supports two watcher modes:
Polling watcher: periodically checks the object store and requires no additional AWS event infrastructure.
SQS watcher: consumes S3 event notifications through Amazon SQS and is intended for lower-latency production synchronization.
The architecture is intentionally eventually consistent for search. A successful write reaches S3 first; the watcher then detects the change, re-chunks and re-embeds the object, and updates search indexes. As a result, read reflects the S3 state immediately, while grep, glob, and ls may lag until synchronization and search indexes are completed.
For collaborative workflows, this suggests a practical rule: use direct reads for hot shared state, use edit for optimistic concurrency on shared files, and use search for discovery across a settled corpus. Namespacing agent outputs, for example, shared/outputs/
Enterprise use cases for a virtual filesystem backend
Codebase-aware coding agents
A coding agent can explore a large repository progressively rather than receive a massive code dump. It can list the project structure, locate files with glob, search for a concept or identifier with hybrid grep, read the exact file, and apply an ETag-protected edit.
This pattern is useful for:
Repository onboarding and code navigation
Incident investigation
Dependency and configuration analysis
Test discovery and targeted remediation
Documentation generation from source code
Private document intelligence
Organizations often have large collections of policies, contracts, procedures, runbooks, product documents, and customer artifacts sitting in object storage. The backend provides an agent with a filesystem-like interface to that corpus.
For example, a document agent can search for "refund policy for enterprise customers," locate the relevant passages even when the wording differs, read the source PDF or DOCX, and write a citation-ready summary or review artifact to a separate path.
This is a natural fit for retrieval-augmented generation (RAG), where the agent needs to navigate rather than perform only one retrieval step.
Multi-agent research and analysis
A coordinator can delegate focused work to specialized subagents that share a common corpus:
A security agent searches for dangerous code patterns.
A documentation agent finds deployment steps and configuration references.
A test agent locates relevant test files and produces coverage notes.
A synthesis agent reads the outputs and writes a consolidated report.
The shared filesystem provides each subagent with a consistent namespace, while MongoDB provides an intelligent discovery layer over the corpus.
Long-running monitoring over changing data
Enterprise document stores are not static. New reports arrive, policies change, and operational artifacts are updated. The watcher keeps the MongoDB Search representation aligned with the underlying object store, so an agent invoked later can search the current corpus without rebuilding an index for every run.
This can support:
Operational runbook assistants
Compliance and policy monitoring
Research assistants over continuously refreshed datasets
Support agents over product and troubleshooting documentation
Partner solution assistants over shared implementation artifacts
Durable workspaces for agent applications
Deep Agents can create plans, intermediate notes, summaries, and generated deliverables as files. Persisting those artifacts in the object store while indexing them in Atlas gives an application a durable workspace that can survive process restarts and be inspected by people or other agents.
For production systems, access control, tenant isolation, data residency, retention, and audit requirements should be enforced through the application, storage configuration, and the metadata model. The current package’s core responsibilities are the Deep Agents-compatible filesystem contract and the Object Store-to-Atlas search path.
How to contribute to the LangChain MongoDB integration
The package lives in the langchain-mongodb repository, and contributions are welcome. Start with the repository contribution guidelines, then explore the package tests and the existing backend boundaries.
Potential contribution areas include:
Additional object-store backends, such as Azure Blob Storage or Google Cloud Storage
New embedding providers and configurable embedding strategies
Additional document parsers and ingestion optimizations
Watcher reliability, backfill, and freshness improvements
Search quality, filtering, ranking, and metadata enhancements
Better examples, documentation, benchmarks, and deployment guidance
A useful design principle is to keep storage-specific behavior behind the object-store interface. That allows the chunker, embedder, synchronization logic, and search router to remain focused on paths, bytes, metadata, and search rather than a particular cloud storage API.
Key takeaways: A persistent virtual filesystem for LangChain Deep Agents
LangChain Deep Agents provide an agent-native way to plan, delegate, navigate files, and produce durable work. The MongoDB virtual filesystem for LangChain Deep Agents connects that experience to an enterprise-friendly storage pattern: your object store remains the source of truth for file bytes, while MongoDB Atlas provides the metadata, full-text search, vector search, and hybrid ranking that agents need to find the right context.
The most important idea is the separation of concerns. Agents see one simple virtual filesystem. Applications can store large, heterogeneous documents in object storage. Atlas turns those documents into a searchable knowledge surface, and the synchronization layer keeps discovery aligned with the live corpus.
Next Steps
Explore the implementation, examples, and contribution path in the LangChain Deep Agents VFS Backend for MongoDB package.
Ready to start building? Register for Atlas and get started for free today.