Un sistema de archivos virtuales basado en MongoDB para agentes avanzados de LangChain.

Las expectativas respecto a los agentes de IA han trascendido la simple respuesta a preguntas. Se les pide que realicen tareas completas: elaborar planes de múltiples pasos, estudiar archivos de origen, crear artefactos intermedios y delegar partes del problema a otros agentes, convirtiendo lo que antes llevaba días en horas. Tal velocidad solo es posible cuando el agente puede moverse con confianza por su sistema de archivos, buscando, leyendo y actualizando archivos en el proceso. El sistema de archivos virtual (VFS) de MongoDB para LangChain Deep Agents satisface esta necesidad. Conecta una vista de sistema de archivos familiar con MongoDB Atlas y un almacén de objetos subyacente, como un bucket de S3, de modo que los agentes cuentan con un espacio de trabajo buscable que perdura más allá de las sesiones, despliegues y subagentes. Los desarrolladores de Deep Agents pueden considerar a Atlas como la plataforma de datos para sus agentes, con búsquedas de texto completo y vectoriales al alcance de la mano.

Las secciones a continuación explican los dos conceptos, muestran cómo funciona el backend de MongoDB dentro de una aplicación de agentes y señalan en qué casos este patrón es adecuado para sistemas empresariales.

Agentes avanzados y sus herramientas de sistema de archivos

Los agentes avanzados constituyen una capa adicional sobre LangChain y LangGraph, diseñada para tareas complejas y de múltiples pasos. Incluyen funciones integradas de planificación, subagentes y herramientas al estilo de sistema de archivos, lo que permite a un agente dividir una tarea grande en acciones pequeñas en lugar de forzarla toda dentro de una sola ventana de contexto. Las operaciones integradas son:

• ls lista los directorios para que el agente pueda ver cómo están organizados
• glob busca archivos según patrones de ruta
• grep examina el contenido de los archivos
• read devuelve un archivo
• write y edit generan o modifican archivos

upload_files y download_files se encargan de las transferencias en masa

Estas herramientas operan bajo un contrato de backend. El agente no necesita saber si los archivos se encuentran en un disco local, en un almacén de LangGraph, en almacenamiento de objetos o en alguna otra capa de persistencia. Él llama a la misma interfaz de sistema de archivos, y el backend configurado proporciona los datos.

Qué agrega un sistema de archivos virtual

Un sistema de archivos virtual presenta los datos como rutas lógicas mientras oculta dónde se almacenan físicamente. Un agente puede ver directorios como docs/, reports/ o projects/customer-a/, aunque los bytes reales se encuentran en un almacén de objetos y la copia buscable está en una base de datos.

Navegar por un sistema de archivos se realiza en pequeños pasos, lo cual es adecuado para los agentes. Sin necesidad de utilizar la opción de procesar todo el corpus, un agente enumera un directorio, filtra según patrones de nombres de archivo, busca un concepto, abre el archivo relevante y registra sus hallazgos como un nuevo artefacto. Cada paso solo incluye lo necesario, de modo que el agente se mantiene dentro de los límites del contexto y gasta menos recursos. En este sentido, el sistema de archivos virtual es una herramienta para gestionar el contexto durante el trabajo del agente, más allá de ser simplemente una capa de almacenamiento.

El paquete y cómo funciona su enrutamiento

El paquete langchain-mongodb-deepagents-vfs implementa el BackendProtocol de Deep Agents de forma directa. El corpus respaldado por un almacén de objetos se presenta al agente como un sistema de archivos, y cada llamada se dirige al sistema que mejor puede manejarla:

• Las operaciones orientadas a búsquedas (grep, glob, ls) se ejecutan contra MongoDB Atlas.
• Las operaciones sobre los bytes de los archivos (read, write, edit, upload_files, download_files) van directamente al almacén de objetos.
• Una capa de sincronización en segundo plano mantiene la representación de búsqueda al día con el almacén de objetos.

Eso permite una separación clara entre la fuente de datos original y el índice de búsqueda. El almacén de objetos alberga los documentos originales, mientras que Atlas contiene los fragmentos buscables, las incrustaciones y la metadatos de rutas que hacen que el corpus sea discoverable.

Podría preguntarse por qué la búsqueda debería residir en un sistema separado y no en una plataforma compatible con S3 que combine búsquedas de texto, vectoriales e híbridas sobre los mismos datos. Esta separación es intencionada. El almacenamiento de objetos destaca por ofrecer bytes de archivo duraderos, económicos y de larga vida útil, pero no fue diseñado para mantener índices en tiempo real, clasificar consultas híbridas y proporcionar búsquedas de metadatos estructurados con baja latencia al mismo tiempo. Atlas es una base de datos operativa en la que la búsqueda, la búsqueda vectorial y la clasificación híbrida son características indexadas desde el principio. Por lo tanto, el plano de búsqueda funciona con software creado específicamente para esa función, mientras que el almacén de objetos sigue aprovechando sus propias ventajas.

Búsqueda híbrida detrás de grep

Detrás de grep, el paquete combina la búsqueda de MongoDB con la búsqueda vectorial de MongoDB. La coincidencia de texto completo es ideal para términos exactos, identificadores, nombres de archivos y cadenas poco comunes, mientras que los vectores son útiles para paráfrasis y preguntas en lenguaje natural. Al combinarlos, un agente puede buscar un término literal como MAX_RETRIES o preguntar dónde están configuradas las reintentos, todo a través de una misma interfaz.

Las dos listas de resultados se fusionan mediante la etapa de agregación $rankFusion en MongoDB. Dado que el ranking se realiza dentro de la base de datos, no se necesita un sistema de reclasificación en el lado del cliente, y desaparece el viaje adicional que requeriría un agente externo. Aquí también existe un equilibrio a considerar. En una plataforma compatible con S3, obtener un ranking de texto completo, vectorial e híbrido suele implicar la integración de varios sistemas especializados: un motor para el texto, una base de datos vectorial para los embeddings y una capa de reclasificación para fusionarlos, cada uno con un proceso de indexación que debe hacer seguimiento de los datos originales. En Atlas, un único motor cubre los tres tipos de ranking, y $rankFusion los fusiona en una sola consulta nativa.

Fragmentación, formatos e embeddings

El procesamiento en bloques tiene en cuenta los tokens. Los formatos de entrada soportados son texto plano, Markdown, PDF, DOCX, XLSX, XLS, PPTX y PPT. Cada bloque mantiene metadatos de posición, como la ruta de origen, el número de página, los desplazamientos de caracteres e información de línea, lo que permite que los resultados se devuelvan en el formato orientado a líneas que esperan los agentes profundos.

Los embeddings por defecto son de Amazon Bedrock; existe también una opción de OpenAI a través de los extras del paquete, y una aplicación puede insertar directamente cualquier implementación de embeddings compatible con LangChain. Una configuración típica se ve así:

from deepagents import create_deep_agent
from langchain_mongodb_deepagents_vfs import MongoFilesystemBackend

backend = MongoFilesystemBackend(
    s3_bucket_name="acme-docs",
    mongodb_connection_string="mongodb+srv://<user>:<password>@<cluster>/",
)

agent = create_deep_agent(
    tools=[],
    instructions="You are a research assistant over the ACME documents corpus.",
    backend=backend,
)

Después de eso, el agente utiliza sus herramientas habituales de sistema de archivos, sin herramientas personalizadas de MongoDB o S3 en su ciclo de razonamiento.

La arquitectura de dos planos

Imagínese el sistema como dos planos. El almacenamiento de objetos es el plano de datos que almacena los bytes de los archivos, mientras que MongoDB Atlas es el plano de control y búsqueda que gestiona los metadatos, los fragmentos y los índices de recuperación.

La figura muestra cómo el backend envía los bytes de los archivos a través del almacenamiento de objetos y las operaciones de búsqueda a través de Atlas.

Cuando se construye el objeto del backend, la inicialización continúa en segundo plano. La creación de índices, la primera sincronización y el inicio del monitor se ejecutan todos en un hilo de demonio. Las operaciones de archivo directas funcionan de inmediato, mientras que las operaciones de búsqueda esperan a que esté lista la sincronización inicial. La ingestión se lleva a cabo de la siguiente manera:

1. Enumerar los objetos dentro del bucket y prefijo de S3 configurados.
2. Descargar cada objeto que cumpla los requisitos.
3. Extraer el texto con el analizador correspondiente a ese formato.
4. Dividir el texto en fragmentos que contengan metadatos de posición.
5. Crear embeddings.
6. Insertar o actualizar los fragmentos y los metadatos en Atlas.
7. Proveer o verificar los índices de búsqueda y búsqueda vectorial.

Los fragmentos constan de 512 tokens con una superposición de 64 tokens. Los ETags hacen que la sincronización inicial y la incorporación por parte del monitor sean idempotentes, de modo que los objetos sin cambios se omiten y no se vuelven a descargar ni a procesar.

Aquí está lo que hace cada llamada. ls solicita a Atlas los metadatos de las rutas y los agrupa en entradas de directorio. glob utiliza reglas estándar de patrones de rutas para encontrar archivos que coincidan. grep hace que Atlas combine la búsqueda de texto completo con la búsqueda vectorial en el corpus en fragmentos y devuelva resultados clasificados por relevancia. read obtiene los bytes actuales del almacén de objetos en lugar del índice, y la diferencia es significativa, ya que los resultados de búsqueda sirven para el descubrimiento mientras que las lecturas proporcionan el documento original.

Existen dos modos de monitoreo. Un monitoreo por sondeo verifica periódicamente el almacén de objetos y no requiere infraestructura adicional de eventos de AWS. Un monitoreo mediante SQS consume notificaciones de eventos de S3 a través de Amazon SQS y es adecuado para una sincronización en producción con menor latencia.

Consistencia eventual para búsquedas

La búsqueda es deliberadamente consistente de forma eventual. Una escritura tiene éxito primero en S3, luego el monitor detecta el cambio, divide el objeto en fragmentos y lo vuelve a incrustar, actualizando así los índices. Por lo tanto, las lecturas muestran inmediatamente el estado de S3, mientras que grep, glob y ls pueden tardar hasta que se complete la sincronización y el indexado.

Existen algunas reglas prácticas para el trabajo compartido: lea directamente cuando los datos están en uso activo y son compartidos, confíe en edit para la concurrencia optimista sobre archivos compartidos, y reserve la búsqueda para encontrar elementos una vez que el corpus esté estable. Al asignar a cada agente su propio espacio de nombres de salida, como shared/outputs//, se reducen aún más los conflictos entre los trabajadores en paralelo.

Dónde encaja este patrón

Exploración de código. En lugar de recibir un gran volumen de código, un agente de programación puede recorrer un repositorio extenso: listar su estructura, localizar archivos con glob, ejecutar búsquedas híbridas con grep para encontrar un concepto o identificador, leer el archivo correspondiente y realizar ediciones protegidas por ETag. Los usos típicos incluyen la adaptación al uso de un repositorio, la investigación de incidentes, el análisis de dependencias y configuraciones, la localización de pruebas que requieran correcciones específicas, y la generación de documentación a partir del código.

Corpus de documentos. Las políticas, contratos, procedimientos, guías de operación, documentos del producto y archivos de clientes suelen acumularse en almacenamiento de objetos, y la capa posterior ofrece a un agente una forma similar a un sistema de archivos para acceder a ellos. Un agente de documentos podría buscar la política de reembolso para clientes empresariales, mostrar pasajes redactados de manera diferente, abrir el PDF o DOCX original y escribir un resumen con referencias a otra ruta. Esto es adecuado para la generación mejorada por recuperación de información cuando se necesita navegación, no solo una búsqueda simple.

Equipos de múltiples agentes. Un coordinador puede asignar tareas específicas a subagentes especializados sobre un corpus compartido. Un agente de seguridad busca patrones de código riesgosos, un agente de documentación recopila pasos de despliegue y referencias de configuración, un agente de pruebas encuentra archivos de prueba relevantes y escribe notas de cobertura, y un agente de síntesis lee todo y elabora un informe. Todos comparten un espacio de nombres, con Atlas como capa de descubrimiento.

Almacenes de documentos dinámicos. El contenido empresarial está en constante cambio: llegan informes, se modifican políticas y se actualizan los documentos operativos. Dado que el monitor mantiene a Atlas alineado con el almacén de objetos, un agente iniciado posteriormente busca el contenido actual sin tener que reconstruir un índice en cada ejecución. Esto facilita el uso de asistentes de manuales de operaciones, la supervisión del cumplimiento y de las políticas, el trabajo de asistentes de investigación con datos constantemente actualizados, el apoyo de agentes con documentos de productos y solución de problemas, y el trabajo de asistentes de socios a partir de artefactos de implementación compartidos.

Espacios de trabajo duraderos. Los Deep Agents pueden guardar planes, notas rápidas, resúmenes y entregables finales como archivos. Al almacenarlos en el almacén de objetos e indexarlos en Atlas, se obtiene un espacio de trabajo que sobrevive a los reinicios y que personas u otros agentes pueden inspeccionar.

Límites de producción y puntos de extensión

El uso en producción requiere que el control de acceso, el aislamiento de usuarios, la residencia de datos, las reglas de retención y auditoría sean aplicados por la aplicación, la configuración de almacenamiento y el modelo de metadatos. El propio paquete es responsable del contrato del sistema de archivos de Deep Agents y de la ruta desde el almacén de objetos hasta la búsqueda en Atlas.

Hay espacio para ampliarlo: más almacenes de objetos como Azure Blob Storage o Google Cloud Storage, más proveedores de integración y estrategias configurables, analizadores de documentos adicionales y una ingesta más rápida, monitores más robustos con funcionalidad de relleno y datos más actualizados, mejor calidad de búsqueda, filtros, clasificación y metadatos, además de ejemplos más completos, pruebas de rendimiento y consejos de despliegue. Una buena regla es mantener todo lo específico del almacenamiento detrás de la interfaz del almacén de objetos, de modo que el procesador de datos, el integrador, la lógica de sincronización y el enrutador de búsqueda solo se ocupen de rutas, bytes, metadatos y búsquedas, nunca de la API de un proveedor en particular.

La separación de responsabilidades es la idea central. Los agentes ven un único sistema de archivos virtual simple; las aplicaciones almacenan documentos grandes y variados en almacenamiento de objetos como fuente de verdad para los datos, Atlas los convierte en una capa buscable con metadatos, clasificación de texto completo, vectorial e híbrida, y la capa de sincronización mantiene que el descubrimiento esté alineado con el corpus en tiempo real.