Wirtualny system plików oparty na MongoDB dla agentów głębokich LangChain

Oczekiwania wobec agentów AI wykraczają już poza prostą odpowiadanie na pytania. Od nich wymaga się wykonywania całych zadań: opracowywania wieloetapowych planów, analizowania plików źródłowych, tworzenia tymczasowych wyników oraz delegowania części zadań innym agentom, dzięki czemu to, co kiedyś zajmowało dni, teraz trwa godziny. Taka szybkość jest możliwa tylko wtedy, gdy agent może z pewnością poruszać się po swoim systemie plików, wyszukiwać, czytać i aktualizować pliki w trakcie pracy. Wirtualny system plików MongoDB (VFS) dla LangChain Deep Agents odpowiada na tę potrzebę. Łączy on znajomy interfejs systemu plików z usługą MongoDB Atlas oraz magazynem obiektów, takim jak kosz S3, dzięki czemu agenci mają dostęp do przestrzeni roboczej nadającej się do wyszukiwania, która przetrwa sesje, implementacje i podagenty. Programiści pracujący z Deep Agents mogą traktować Atlas jako platformę danych dla swoich agentów, z pełnotekstowym i wektorowym wyszukiwaniem w zasięgu ręki.

Poniższe sekcje wyjaśniają te dwa koncepcje, pokazują, jak backend MongoDB działa w aplikacjach agentów, oraz wskazują, w jakich przypadkach ten model nadaje się do systemów korporacyjnych.

Deep Agents i ich narzędzia do zarządzania plikami

Deep Agents stanowią warstwę nad LangChain i LangGraph, stworzoną do realizacji złożonych, wieloetapowych zadań. Wbudowane są funkcje planowania, subagentów oraz narzędzi w stylu systemu plików, które umożliwiają agentowi podzielenie dużego zadania na małe kroki zamiast umieszczania ich wszystkich w jednym oknie kontekstowym. Do wbudowanych operacji należą:

• ls wyświetla listę katalogów, dzięki czemu agent może zobaczyć, jak są one ułożone
• glob dopasowuje pliki według wzoru ścieżki
• grep przeszukuje zawartość plików
• read zwraca treść pliku
• write i edit tworzą lub modyfikują pliki

upload_files i download_files obsługują przenoszenie dużych ilości plików

Te narzędzia działają na podstawie umowy z backendem. Agent nie musi wiedzieć, czy pliki znajdują się na dysku lokalnym, w magazynie LangGraph, w systemie przechowywania obiektów, czy w jakiejś innej warstwie persistencji. Wykorzystuje tę samą interfejs systemu plików, a dane dostarcza konfigurowany backend.

Co dodaje wirtualny system plików

Wirtualny system plików prezentuje dane jako logiczne ścieżki, ukrywając jednocześnie miejsce ich fizycznego przechowywania. Agent może widzieć katalogi takie jak docs/, reports/ lub projects/customer-a/, chociaż rzeczywiste dane znajdują się w magazynie obiektów, a wersja nadająca się do wyszukiwania – w bazie danych.

Nawigacja w systemie plików odbywa się krok po kroku, co odpowiada potrzebom agentów. Pomijając polecenie dotyczące całego korpusu, agent wyświetla katalog, zawęża wyniki według wzorca nazwy pliku, szuka określonego pojęcia, otwiera odpowiedni plik i zapisuje uzyskane informacje jako nowy artefakt. Każdy krok dostarcza tylko to, co jest potrzebne, dzięki czemu agent pozostaje w granicach kontekstu i zużywa mniej zasobów. W tym kontekście wirtualny system plików stanowi narzędzie do zarządzania kontekstem podczas pracy agenta, a nie tylko warstwę przechowywania.

Pakiet i sposób jego działania

Pakiet langchain-mongodb-deepagents-vfs implementuje protokół BackendProtocol Deep Agents w sposób bezpośredni. Korpus oparty na magazynie obiektów jawi się agentowi jako system plików, a każde żądanie jest kierowane do systemu, który radzi sobie z nim najlepiej:

• Operacje skierowane na wyszukiwanie (grep, glob, ls) są wykonywane w MongoDB Atlas.
• Operacje na bajtach plików (read, write, edit, upload_files, download_files) trafiają bezpośrednio do magazynu obiektów.
• Warstwa synchronizacji w tle utrzymuje reprezentację przeznaczoną do wyszukiwania zgodną z treścią w magazynie obiektów.

To zapewnia czyste rozdzielenie źródła prawdy od indeksu wyszukiwania. Magazyn obiektów przechowuje oryginalne dokumenty, natomiast Atlas zawiera fragmenty dostępne do wyszukiwania, embeddingi oraz metadane ścieżek, które umożliwiają znajdowanie treści w korpusie.

Można by zapytać, dlaczego wyszukiwanie powinno funkcjonować w oddzielnym systemie, a nie na platformie kompatybilnej z S3, która łączy wyszukiwanie tekstowe, wektorowe i hybrydowe w ramach tych samych danych. Taki podział jest celowy. Przechowywanie obiektów doskonale radzi sobie z trwałym, tanim przechowywaniem plików o długim okresie życia, ale nie zostało zaprojektowane do jednoczesnego utrzymywania aktualnych indeksów, rankowania zapytań hybrydowych oraz dostarczania szybkich wyników z metadanych strukturalnych. Atlas to baza danych operacyjna, w której wyszukiwanie, wyszukiwanie wektorowe i rankowanie hybrydowe od samego początku są cechami indeksowanymi. Dlatego mechanizm wyszukiwania działa w oprogramowaniu stworzonym specjalnie do tego celu, podczas gdy magazyn obiektów kontynuuje działanie w oparciu o swoje własne zalety.

Wyszukiwanie hybrydowe za grepem

Za grep pakiet łączy MongoDB Search z MongoDB Vector Search. Dopasowywanie pełnego tekstu sprawdza się doskonale przy dokładnych terminach, identyfikatorach, nazwach plików i rzadkich ciągach znaków, natomiast wektory są skuteczne przy parafrazach i pytaniach w języku naturalnym. Łączenie tych narzędzi umożliwia agentowi wyszukiwanie wartości dosłownych, takich jak MAX_RETRIES, lub pytanie o to, gdzie są konfigurowane próby ponowne, wszystko to przez jedną interfejs.

Dwie listy wyników są łączone na etapie agregacji $rankFusion w MongoDB. Ponieważ ranking pozostaje w bazie danych, nie jest potrzebny żaden narzędzie do ponownego rankowania po stronie klienta, a eliminuje się to również dodatkowe obciążenie związane z przesyłaniem danych między urządzeniami. Istnieje tu również szerszy kompromis. Na platformie kompatybilnej z S3 uzyskanie pełnotekstowego, wektorowego oraz hybrydowego rankingu zazwyczaj oznacza konieczność połączenia kilku specjalistycznych systemów: jednego silnika do przetwarzania tekstu, jednej bazy danych wektorowej do przechowywania embeddingów oraz warstwy do ponownego rankowania w celu ich połączenia, przy czym każdy z tych systemów posiada własny proces indeksowania, który musi śledzić dane źródłowe. W Atlasie jeden silnik obejmuje wszystkie trzy typy rankingu, a $rankFusion łączy je w jednej, natywnej zapytaniu.

Podział na fragmenty, formaty i embeddingi

Proces dzielenia na fragmenty uwzględnia strukturę tekstu. Obsługiwane są tekst prosty, Markdown, PDF, DOCX, XLSX, XLS, PPTX oraz PPT. Każdy fragment zachowuje metadane pozycyjne, mianowicie ścieżkę źródłową, numer stronę, odległości charakterów oraz informacje o liniach, co umożliwia otrzymanie wyników w formacie zorientowanym na linie, którego oczekują Deep Agents.

Domyślnie używane są embeddingi Amazon Bedrock; dostępna jest również opcja OpenAI poprzez pakiet extras, a aplikacja może bezpośrednio wprowadzić dowolną implementację embeddingów kompatybilną z LangChain. Typowa konfiguracja wygląda następująco:

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,
)

Następnie agent używa swoich standardowych narzędzi systemu plików, bez żadnych specjalnych narzędzi MongoDB lub S3 w swoim cyklu rozumowania.

Architektura dwóch poziomów

Można sobie wyobrazić system jako dwa poziomy. Przechowywanie obiektów stanowi poziom danych, który przechowuje bajty plików, natomiast MongoDB Atlas to poziom sterowania i wyszukiwania, który obsługuje metadane, fragmenty danych oraz indeksy wyszukiwania.

Rysunek pokazuje, w jaki sposób backend wysyła bajty plików za pośrednictwem przechowywania obiektów, a operacje wyszukiwania – przez Atlas.

Gdy obiekt backendu zostanie utworzony, inicjalizacja trwa dalej w tle. Tworzenie indeksów, pierwsza synchronizacja oraz uruchomienie mechanizmu monitorowania działają wszystkie na wątku daemon. Operacje plikowe typu pass-through działają natychmiast, natomiast operacje wyszukiwania czekają, aż zakończy się początkowa synchronizacja. Proces pobierania danych przebiega w następujący sposób:

1. Wylistowanie obiektów w skonfigurowanym buforze S3 oraz przedrostku.
2. Pobierz każdy dostępny obiekt.
3. Wyodrębnij tekst za pomocą parsera odpowiedniego dla tego formatu.
4. Rozdziel tekst na fragmenty zawierające metadane pozycyjne.
5. Stwórz embeddingi.
6. Wpisz fragmenty oraz metadane do Atlas.
7. Utwórz lub sprawdź indeksy wyszukiwania oraz wyszukiwania wektorowego.

Fragmenty składają się z 512 tokenów, przy czym istnieje przerzut 64 tokenów między nimi. ETags zapewniają, że początkowa synchronizacja oraz przetwarzanie danych są idempotentne, dzięki czemu niezmienione obiekty są pomijane i nie są ponownie pobierane ani przetwarzane.

Oto, co robi każda z tych funkcji. ls prosi Atlas o metadane ścieżek i grupuje je w wpisy katalogowe. glob wykorzystuje standardowe reguły wzorów ścieżek do znajdowania odpowiadających plików. grep sprawia, że Atlas łączy wyszukiwanie pełnego tekstu z wyszukiwaniem wektorowym w korpusie fragmentów i zwraca wyniki uszeregowane według priorytetu. read pobiera aktualne dane z magazynu obiektów zamiast z indeksu, a różnica ta ma znaczenie, ponieważ wyniki wyszukiwania służą odkrywaniu informacji, natomiast operacje odczytu dostarczają oryginalne dokumenty.

Istnieją dwa tryby monitorowania. Monitor typu polling sprawdza regularnie magazyn obiektów i nie wymaga dodatkowej infrastruktury zdarzeń AWS. Monitor typu SQS przetwarza powiadomienia o zdarzeniach S3 za pośrednictwem Amazon SQS i nadaje się do synchronizacji w środowiskach produkcyjnych wymagających niższej latencji.

Konsystencja ostateczna w wyszukiwaniu

Wyszukiwanie jest celowo zgodne z zasadą spójności w czasie. Zapis odbywa się najpierw pomyślnie w S3, następnie nadzorca wykrywa zmianę, dzieli obiekt na fragmenty i ponownie go umieszcza, a także aktualizuje indeksy. Dlatego odczyty od razu pokazują stan S3, podczas gdy grep, glob i ls mogą wykazywać opóźnienia aż do zakończenia synchronizacji i indeksowania.

W przypadku wspólnej pracy obowiązują kilka zasad praktycznych: czytaj bezpośrednio, gdy dane są często używane i udostępniane, polegaj na funkcji edit dla optymistycznego zarządzania jednoczesnym edytowaniem plików współdzielonych, a do wyszukiwania informacji używaj funkcji wyszukiwania, gdy zbiór danych stanie się stabilny. Przyznanie każdemu agentowi własnego przestrzeni nazw wyjść, na przykład shared/outputs//, dodatkowo zmniejsza konflikty między równoległymi procesami.

Gdzie ten model się sprawdza

Eksploracja kodu. Zamiast otrzymać ogromną ilość kodu, agent programistyczny może przeglądać duży repozytorium: wyświetlać jego strukturę, lokalizować pliki za pomocą glob, wykonywać hybrydowy grep w celu znalezienia określonego pojęcia lub identyfikatora, czytać konkretny plik i dokonywać edycji chronionej za pomocą ETag. Typowe zastosowania to wprowadzanie użytkowników do repozytorium, badanie incydentów, analiza zależności i konfiguracji, znajdowanie testów wymagających określonych poprawek oraz generowanie dokumentacji na podstawie kodu.

Korpora dokumentów. Polityki, umowy, procedury, instrukcje obsługi, dokumentacja produktów oraz pliki klientów często gromadzą się w systemach przechowywania obiektów, a warstwa backendowa umożliwia agentowi dostęp do nich w sposób przypominający system plików. Agent zajmujący się dokumentami może wyszukiwać politykę zwrotów pieniędzy dotyczącą klientów korporacyjnych, wydobywać fragmenty sformułowane inaczej, otwierać oryginalne pliki PDF lub DOCX oraz tworzyć streszczenie z odniesieniami do innych lokalizacji. To sprawdza się przy generowaniu treści wzbogaconym o informacje z wyszukiwania, gdy potrzebna jest nawigacja, a nie tylko pojedyncze wyszukiwanie.

Zespoły wielu agentów. Koordynator może przydzielać specyficzne zadania specjalistycznym podagentom w ramach jednego wspólnego korpusu danych. Agent bezpieczeństwa szuka ryzykownych wzorców kodu, agent dokumentacji zbiera kroki implementacji oraz odniesienia konfiguracyjne, agent testowy znajduje odpowiednie pliki testowe i pisze notatki dotyczące stopnia pokrycia, natomiast agent syntezy czyta wszystko i sporządza raport. Wszystkie one korzystają z jednego przestrzeni nazw, przy czym Atlas pełni rolę warstwy odkrywania informacji.

Przechowywanie dokumentów żywych. Treści korporacyjne stale się zmieniają: pojawiają się raporty, zmieniają się zasady, a artefakty operacyjne są aktualizowane. Ponieważ mechanizm monitorowania utrzymuje Atlas w zgodności z przechowalnią obiektów, agenci uruchamiani później mogą wyszukiwać aktualne treści bez konieczności ponownego tworzenia indeksu przy każdym uruchomieniu. Dzięki temu asystenci do tworzenia procedur, systemy monitorowania zgodności i zasad, asystenci badawczy mogą korzystać z ciągle aktualizowanych danych, a agenci obsługi klienta z dokumentacją produktu i rozwiązywania problemów, a także asystenci partnerów z wspólnymi artefaktami implementacji.

Trwałe przestrzenie robocze. Agenci typu Deep mogą zapisywać plany, notatki, streszczenia oraz ostateczne wyniki w formie plików. Przechowywanie ich w przechowalni obiektów oraz indeksowanie w Atlasie umożliwia tworzenie przestrzeni roboczych, które przetrwają restarty i które mogą być sprawdzane przez ludzi lub inne agenty.

Ograniczenia produkcyjne i punkty rozszerzeń

Do użycia w produkcji konieczne jest wdrożenie kontroli dostępu, izolacji użytkowników, zasad dotyczących lokalizacji danych, przechowywania i audytu, które muszą być realizowane przez aplikację, konfigurację przechowywania oraz model metadanych. Sam pakiet jest odpowiedzialny za spełnianie warunków określonych w kontrakcie systemu plików Deep Agents oraz za przekierowanie danych z magazynu obiektów do narzędzia wyszukiwania Atlas.

Istnieje możliwość jego rozbudowy: dodatkowe magazyny obiektów takie jak Azure Blob Storage czy Google Cloud Storage, więcej dostawców funkcji embedding oraz konfigurowalnych strategii, dodatkowe narzędzia do analizy dokumentów i szybsze procesy ich przetwarzania, bardziej niezawodne mechanizmy monitorowania z funkcją uzupełniania brakujących danych oraz nowsze informacje, poprawiona jakość wyszukiwania, funkcje filtrowania, rankingu i zarządzania metadanami, a także bardziej szczegółowe przykłady, testy wydajności i wskazówki dotyczące wdrażania. Dobrą zasadą jest przechowywanie wszystkiego, co jest specyficzne dla systemów przechowywania, poza interfejsem magazynu obiektów, aby mechanizmy dzielenia na fragmenty, wstawiania danych, logiki synchronizacji i przekierowywania zapytań wyszukiwania zajmowały się wyłącznie ścieżkami, danymi binarnymi, metadanami i procesem wyszukiwania, a nie API konkretnego dostawcy.

Główną zasadą jest separacja zadań. Agenci widzą pojedynczy, prosty wirtualny system plików, aplikacje przechowują duże i zróżnicowane dokumenty w systemach przechowywania obiektów jako źródło prawdy dotyczącej danych, Atlas przekształca je w warstwę umożliwiającą wyszukiwanie z metadanymi, pełnym tekstem, rankingiem wektorowym i hybrydowym, natomiast warstwa synchronizacji zapewnia, że odkrywanie danych jest zgodne z aktualnym zbiorem danych.