LangChain با FilesystemBackend دسترسی عامل‌های هوش مصنوعی به دیسک محلی را ممکن

تصور کنید یک عامل هوشمند که فراتر از چت کردن، مانند یک مدیر فضای کاری دائمی عمل می‌کند و قدرت تغییر فایل‌های واقعی سیستم‌عامل شما را دارد. از ۲۴ ژوئیه ۲۰۲۶، توسعه‌دهندگان LangChain می‌توانند با پیاده‌سازی این تغییر، از محدودیت گفتگوهای موقت عبور کنند و عامل‌هایی بسازند که در محیط عملیاتی سیستم اثر بگذارند.

تا پیش از این، اکثر عامل‌ها به ذخیره‌سازی مبتنی بر وضعیت (State-based storage) وابسته بودند؛ یعنی فایل‌ها فقط در طول یک رشته گفتگو (Conversation Thread) خاص زنده می‌ماندند. اگر اسکریپت خود را ری‌استارت می‌کردید، تمامی فایل‌ها ناپدید می‌شدند. اما با معرفی FilesystemBackend، شرکت LangChain به عامل‌ها اجازه می‌دهد فایل‌های Markdown، اسکریپت‌های پایتون و پوشه‌های کامل پروژه ایجاد کنند که مدت‌ها پس از پایان پردازش پایتون، روی دیسک باقی می‌مانند. این قابلیت، ابزار را برای دستیارهای کدنویسی محلی، ابزارهای تولید سند و جریان‌های کاری پیشرفته توسعه، به گزینه‌ای ایده‌آل تبدیل می‌کند.

این سازوکار با StateBackend تفاوت بنیادی دارد. در حالی که StateBackend فایل‌ها را بر اساس شناسه رشته (thread_id) ایزوله می‌کند، FilesystemBackend با دیسک به عنوان یک منبع مشترک برخورد می‌کند. هر رشته‌ای که به دایرکتوری ریشه دسترسی داشته باشد، می‌تواند همان فایل‌هایی را بخواند یا بنویسد که یک توسعه‌دهنده انسانی در یک پوشه محلی انجام می‌دهد.

همان‌طور که در تحلیل‌های پیشین ما درباره‌ی معماری حافظه در مدل‌های عامل-محور اشاره کردیم، گذار از حافظه موقت به دیسک فیزیکی، ریسک‌ها و پاداش‌های متفاوتی دارد. در همین راستا، رویکردهای مشابهی مانند تبدیل نشست‌های Claude Code به لایه‌ی حافظه‌ی دائمی نیز تلاش کرده‌اند تا تداوم داده‌ها را در محیط‌های محلی بهبود بخشند.

مقایسه StateBackend در برابر FilesystemBackend

برای درک تفاوت معماری، نحوه تعامل رشته‌ها با ذخیره‌سازی را بررسی کنید:

• StateBackend: رشته A فایل‌های موقت مخصوص به خود را دارد و رشته B فایل‌های موقت جداگانه‌ای دارد. ذخیره‌سازی در وضعیت LangGraph مدیریت می‌شود.
• FilesystemBackend: هر دو رشته A و B به یک پوشه واقعی و واحد در کامپیوتر شما اشاره می‌کنند. فایل‌ها، همان فایل‌های معمولی سیستم‌عامل در یک دایرکتوری پیکربندی‌شده هستند.

مکانیزم عملکرد

برای پیاده‌سازی این قابلیت، عامل با یک root_dir و یک پرچم ایمنی حیاتی به نام virtual_mode=True مقداردهی اولیه می‌شود. این تنظیم، مسیرهای مجازی (مانند /notes/todo.md) را به یک مسیر فیزیکی واقعی در ماشین مپ می‌کند.

به عنوان مثال، اگر root_dir روی ./agent_workspace تنظیم شده باشد، مسیر مجازی /notes/todo.md به صورت زیر مپ می‌شود:
your-project-folder/agent_workspace/notes/todo.md

مسیر کامل دقیقاً به سیستم‌عامل بستگی دارد. در ویندوز، این مسیر ممکن است به صورت C:\Users\Talha\deep-agents-demo\agent_workspace\notes\todo.md باشد. در macOS یا لینوکس، به شکل /home/talha/deep-agents-demo/agent_workspace/notes/todo.md ظاهر خواهد شد.

به نقل از راهنمای dev.to، قابلیت virtual_mode به عنوان یک حفاظ اصلی (Primary Guardrail) عمل می‌کند. این قابلیت تلاش‌های رایج برای «فرار از مسیر» (Path-escape) را مسدود می‌کند و مانع دسترسی عامل به مناطق حساس مانند ../../some-other-folder/file.txt یا ~/secret-file.txt می‌شود. با این حال، باید توجه داشت که این یک سندباکس (Sandbox) کامل نیست؛ بلکه یک محدودیت بر اساس مسیر است و مانند یک سندباکس دوردست (Remote Sandbox)، پردازش پایتون را ایزوله نمی‌کند. مستندات رسمی Deep Agents توصیه می‌کنند virtual_mode=True را حتماً در کنار یک دایرکتوری ریشه پیکربندی‌شده استفاده کنید.

استراتژی CompositeBackend

برای جریان‌های کاری حرفه‌ای، LangChain رویکرد ترکیبی یا CompositeBackend را پیشنهاد می‌دهد. این روش اجازه می‌دهد توسعه‌دهندگان عملیات‌های مختلف فایل را بر اساس پیشوند مسیر (Path prefix) به لایه‌های ذخیره‌سازی متفاوتی هدایت کنند. CompositeBackend عملیات فایل را با پیشوند مسیر روت می‌کند؛ یک مسیر منطبق، عملیات را به آن بک‌سند خاص می‌فرستد و مسیرهایی که با هیچ روتی منطبق نیستند، از بک‌سند پیش‌فرض استفاده می‌کنند.

• وضعیت زودگذر (Ephemeral State): آثار داخلی عامل، مانند خروجی‌های حجیم ابزارها، یادداشت‌های پژوهشی میانی، فایل‌های برنامه‌ریزی یا محتوای مرتبط با گفتگو، به StateBackend (پیش‌فرض) هدایت می‌شوند.
• دیسک بادوام (Durable Disk): تنها فایل‌هایی که صراحتاً به یک پیشوند خاص، مانند /workspace/ هدایت شده‌اند، از طریق FilesystemBackend روی دیسک واقعی نوشته می‌شوند.

تصور کنید یک عامل در حال پیش‌نویس یک پروژه است. او ممکن است ۱۰ فایل موقت برای طوفان فکری ایجاد کند (که در وضعیت زودگذر ذخیره می‌شوند)، اما در نهایت فقط فایل نهایی main.py را در پوشه پروژه شما بنویسد. اگر مسیری مانند /workspace/src/hello.py باشد، CompositeBackend آن را به FilesystemBackend در مسیر ./my_project/src/hello.py هدایت می‌کند. اما اگر مسیر /tmp/tool-output.txt باشد، به StateBackend هدایت می‌شود.

این استراتژی مانع از آن می‌شود که دایرکتوری محلی شما با فایل‌های «تخته‌سیاه» (Scratchpad) هوش مصنوعی شلوغ شود و تضمین می‌کند که تنها خروجی‌های صریح پروژه روی دیسک قرار گیرند. این امر منجر به ایجاد یک دایرکتوری پروژه تمیزتر شده و احتمال مخلوط شدن آثار داخلی عامل با فایل‌های اپلیکیشن شما را کاهش می‌دهد.

ریسک‌های امنیتی حیاتی

دادن دسترسی مستقیم به دیسک، بردارهای امنیتی قابل توجهی را ایجاد می‌کند. مستندات رسمی هشدار می‌دهند که عامل‌ها ممکن است به‌طور تصادفی اسرار دسترسی قابل دسترس مانند فایل‌های .env یا کلیدهای API را بخوانند، اگر این‌ها در پوشه ریشه ارائه شده قرار داشته باشند. همچنین به دلیل دائمی بودن تغییرات، هر اشتباه توسط هوش مصنوعی می‌تواند منجر به بازنویسی داده‌های واقعی شود.

این چالش‌های امنیتی یادآور اهمیت ایزولاسیون خروجی برای جلوگیری از سرقت اعتبارنامه‌ها است تا از افشای ناخواسته‌ی اطلاعات حساس در محیط‌های کدنویسی جلوگیری شود.

توسعه‌دهندگان به‌شدت ترغیب شده‌اند که از قرار دادن ریشه در درایو اصلی سخت‌افزار خود پرهیز کنند. از پیکربندی‌هایی مانند FilesystemBackend(root_dir="C:/", virtual_mode=True) در ویندوز یا root_dir="/" در لینوکس/macOS دوری کنید. در عوض، باید از پوشه‌های فضای کاری اختصاصی (Dedicated Workspace Folders) استفاده کنید.

علاوه بر این، LangChain صراحتاً توصیه می‌کند که از این بک‌سند در APIهای وب عمومی، اپلیکیشن‌های چند-مستاجری (Multi-tenant) یا سیستم‌هایی با ورودی‌های کاربر غیرقابل اعتماد استفاده نشود. زیرا thread_id یک مرز امنیتی برای سیستم فایل نیست و اگر کاربرانی یک دایرکتوری ریشه مشترک داشته باشند، احتمالاً می‌توانند به فایل‌های یکدیگر دسترسی پیدا کنند. برای سیستم‌های تولیدی (Production)، مستندات StateBackend، StoreBackend یا یک محیط اجرای سندباکس کامل را توصیه می‌کنند.

جزئیات فنی پیاده‌سازی

برای شروع، توسعه‌دهندگان باید بسته‌های زیر را نصب کنند:
pip install deepagents langchain langgraph python-dotenv

کاربران باید اعتبارنامه‌های ارائه‌دهنده مدل را نیز پیکربندی کنند. از آنجایی که در مثال از OpenRouter استفاده شده است، کلید API باید در یک فایل .env به صورت OPENROUTER_API_KEY=your_api_key_here قرار گیرد. تابع load_dotenv() برای بارگذاری این متغیرهای محیطی از فایل استفاده می‌شود. نکته حیاتی این است که فایل‌های .env حاوی کلیدهای واقعی هرگز نباید در گیت‌هاب کامیت شوند.

عامل معمولاً با یک مدل با ظرفیت بالا جفت می‌شود. در مثال دقیق، از مدل nvidia/nemotron-3-super-120b-a12b از طریق OpenRouter با محدودیت max_tokens برابر با ۴۰۹۶ استفاده شده است. این محدودیت برای کنترل مصرف توکن و هزینه‌های مرتبط با APIهای پولی کاربردی است. توجه داشته باشید که رفتار ذخیره‌سازی توسط پیکربندی بک‌سند تعیین می‌شود، نه توسط خود مدل.

برای پیش‌بینی‌پذیری بیشتر، توسعه‌دهندگان باید از مسیرهای مطلق از طریق ماژول pathlib پایتون استفاده کنند:

from pathlib import Path
workspace_dir = Path("./agent_workspace").resolve()
agent = create_deep_agent(
    model=model, 
    backend=FilesystemBackend(root_dir=workspace_dir, virtual_mode=True)
)

این کار تضمین می‌کند که workspace_dir به‌طور خودکار به یک مسیر کامل سیستم‌عامل تبدیل شود (مثلاً C:\Users\Talha\deep-agents-demo\agent_workspace) و از بروز خطا در صورت اجرای اسکریپت از دایرکتوری‌های مختلف جلوگیری می‌کند.

نمونه گردش کار عملیاتی

این قابلیت، عامل را از یک چت‌بات به یک همکار محلی از طریق توالی اقدامات واقعی تبدیل می‌کند:

• نوشتن: عامل از ابزار write_file برای ایجاد فایل /notes/todo.md با محتوای مشخص استفاده می‌کند: "# To-do\n- Buy groceries\n- Finish the project\n- Review pull requests". چون ریشه روی ./agent_workspace است، فایل واقعی در مسیر ./agent_workspace/notes/todo.md ایجاد می‌شود.
• تأیید: عامل دستور ls را فراخوانی می‌کند تا تأیید کند فایل روی دیسک وجود دارد. از نظر مفهومی، سیستم فایل به‌روزرسانی شده تا شامل دایرکتوری /notes/ و فایل todo.md باشد.
• خواندن: با استفاده از همان رشته (demo-thread-1)، عامل از read_file برای بازیابی و گزارش سه مورد لیست کارهای-به-دست (to-do) استفاده می‌کند. این فایل در دسترس است زیرا فیزیکی روی دیسک است، نه فقط در وضعیت موقت.
• دسترسی بین-رشته‌ای: یک فراخوانی دوم با استفاده از demo-thread-2 می‌تواند با موفقیت /notes/todo.md را بیابد و بخواند. این ثابت می‌کند که thread_id یک مرز امنیتی برای سیستم فایل نیست. اگر دو عامل از یک ریشه FilesystemBackend مشترک استفاده کنند، می‌توانند بسته به مجوزهای سیستم‌عامل، به فایل‌های یکدیگر دسترسی داشته باشند.

کاربران می‌توانند این اقدامات را شخصاً با دستورات سیستم‌عامل تأیید کنند:

• ویندوز: dir agent_workspace\notes\ و type agent_workspace\notes\todo.md
• پاورشل: Get-ChildItem .\agent_workspace\notes\ و Get-Content .\agent_workspace\notes\todo.md
• macOS/لینوکس: ls agent_workspace/notes/ و cat agent_workspace/notes/todo.md

ساختار پیشنهادی پروژه

برای آزمایش ایمن و تمیز نگه داشتن پروژه‌ها، چیدمان زیر پیشنهاد می‌شود:

• deepagents-filesystem-demo/
  • .env (خارج از فضای کاری عامل نگه داشته می‌شود تا از نشت اطلاعات جلوگیری شود)
  • filesystem_demo.py
  • agent_workspace/ (دسترسی مستقیم عامل برای آزمایش‌ها)
    • notes/todo.md
  • my_project/ (هدف برای مسیر /workspace/ در CompositeBackend)
    • src/hello.py

توسعه‌دهندگان همچنین باید فایل .gitignore خود را به‌روز کنند تا از کامیت شدن آثار تولید شده یا اسرار در گیت‌هاب جلوگیری کنند:

# Agent-generated workspace files
agent_workspace/
# Add this only if you do not want generated project files in Git
# my_project/
# Never commit environment secrets
.env

تحلیل مقایسه‌ای: مستقل در برابر ترکیبی

هنگام تصمیم‌گیری در مورد اینکه از کدام رویکرد استفاده شود، توسعه‌دهندگان باید پیچیدگی پیکربندی را در برابر تمیزی پروژه بسنجند:

Standalone FilesystemBackend (مستقل)

• دامنه: تمامی فایل‌ها در یک پوشه واقعی واحد روی دیسک نوشته می‌شوند.
• پایداری: هر فایلی که توسط عامل ایجاد شود، به‌طور پیش‌فرض دائمی است.
• بهترین برای: آزمایش‌های محلی سریع و در مقیاس کوچک که شلوغ شدن دایرکتوری در آن اهمیت ندارد.
• پیچیدگی: پیکربندی بسیار ساده است.

CompositeBackend (ترکیبی)

• دامنه: فایل‌ها بر اساس پیشوندهای مسیر در مکان‌های مختلف توزیع می‌شوند.
• پایداری: تنها فایل‌های هدایت شده خاص (مثلاً زیر مسیر /workspace/) روی دیسک باقی می‌مانند؛ سایرین زودگذر هستند.
• بهترین برای: جریان‌های کاری واقعی توسعه و پروژه‌های حرفه‌ای که در آن‌ها سورس‌کد باید از تخته‌سیاه‌های تولید شده توسط عامل جدا باشد.
• پیچیدگی: پیکربندی کمی پیشرفته‌تر است اما کنترل بسیار بیشتری روی محیط فراهم می‌کند.

جمع‌بندی: انتخاب بک‌سند مناسب

• Standalone FilesystemBackend: برای آزمایش‌های محلی کوچک بهترین است. تمام فایل‌ها به یک پوشه واقعی می‌روند. پیکربندی ساده است، اما دایرکتوری‌ها می‌توانند نامرتب شوند زیرا آثار موقت، زودگذر نیستند.
• CompositeBackend: برای جریان‌های کاری توسعه واقعی بهترین است. اجازه می‌دهد مسیرهای منتخب (مانند /workspace/) به دیسک واقعی متصل شوند در حالی که سایر فایل‌ها در StateBackend باقی می‌مانند. این رویکرد تمیزی پوشه پروژه و کنترل بیشتری را فراهم می‌کند، هرچند پیکربندی آن کمی پیشرفته‌تر است.

نکته نهایی: StateBackend برای فایل‌هایی است که موقت هستند و به یک رشته LangGraph متصل‌اند؛ FilesystemBackend برای فایل‌هایی است که واقعی، بادوام و از طریق سیستم‌عامل به اشتراک گذاشته شده‌اند.

گام بعدی شما

• اگر از عامل‌ها برای تولید کد استفاده می‌کنید، استراتژی CompositeBackend را پیاده کنید تا فایل‌های موقت مدل با سورس‌کد شما مخلوط نشوند.
• برای امنیت بیشتر، یک پوشه ایزوله (Dedicated Workspace) بسازید و هرگز اجازه دسترسی به ریشه درایو را به مدل ندهید.
• فایل .gitignore خود را به‌روز کنید تا پوشه agent_workspace در مخزن گیت شما آپلود نشود.

اما داستان سخت‌افزاری مدیریت این حجم از دسترسی‌های I/O حتی پیچیده‌تر است؛ در تحلیل بعدی به بهینه‌سازی دسترسی داده‌ها در سیستم‌های عامل-محور خواهیم پرداخت.