Filesystem 工具：用檔案管理 Context，不讓 Token 爆炸

Context window 的問題，用 AI 做複雜任務的人幾乎都遇過：任務進行到一半，context 裡已經塞了一大堆工具回傳的資料、中間結果、對話紀錄，然後模型開始「失憶」——前面說過的事不記得了，或者乾脆給你一個 context too long 的錯誤。

解法有幾種，但最直接的是：把不需要一直待在 context 裡的東西，暫時放到別的地方。

Deep Agents 的 Virtual Filesystem 就是那個「別的地方」。

代理人的虛擬 Filesystem

Deep Agents 給代理人內建了四個 filesystem 工具：

• ls：列出目錄下有哪些檔案
• read_file：讀取指定檔案的內容
• write_file：把內容寫入新檔案
• edit_file：修改現有檔案的部分內容

這些工具的設計跟你在終端機裡操作檔案是一樣的邏輯，只是執行環境是代理人的虛擬空間——具體用哪種後端儲存，由你設定（下一篇會說，預設是 in-memory）。

為什麼要有 Filesystem

直接來一個類比：想像一個分析師要處理一份 50 頁的技術報告。

沒有 Filesystem 的做法：把整份報告丟進 context，然後在 context 裡做分析。問題是，當報告內容 + 分析過程 + 後續對話全部堆在一起，context 很快就擠爆，而且你無法「只看報告的第三章，其他先放旁邊」。

有 Filesystem 的做法：把報告寫進 report.md，每次只 read_file 需要的那個段落，分析結果寫進 analysis.md，最後再讀取 analysis.md 產生最終報告。Context 裡只有「當下這一步真正需要的東西」。

這就是 Filesystem 工具的核心價值——讓代理人可以做 選擇性讀取，不需要把所有東西一直裝在 context 裡。

實際示範

來看一個研究任務的範例：

from deepagents import create_deep_agent
 
def fetch_article(url: str) -> str:
    """抓取網頁文章的內容。"""
    return f"文章內容：{url} 的詳細內容，包含大量技術細節..."
 
agent = create_deep_agent(
    tools=[fetch_article],
    system_prompt="""你是一個研究助理。
    
    處理大量資訊時，善用 filesystem 工具：
    - 用 write_file 把抓到的原始資料存起來
    - 用 read_file 按需要讀取，不要一次把所有東西載入 context
    - 分析結果也存成檔案，最後再整合
    """,
)
 
result = agent.invoke({
    "messages": [
        {"role": "user", "content": "幫我研究這三篇文章的共同主題：url1, url2, url3。整理成一份摘要報告。"}
    ]
})

代理人可能的執行流程會是這樣：

1. fetch_article("url1") → write_file("article1.md", 內容)
2. fetch_article("url2") → write_file("article2.md", 內容)
3. fetch_article("url3") → write_file("article3.md", 內容)
4. read_file("article1.md") → 分析主題 → write_file("analysis1.md", 結果)
5. 同樣處理 article2 和 article3
6. read_file("analysis1.md"), read_file("analysis2.md"), read_file("analysis3.md") → 整合 → 最終報告

每一步 context 裡只有當前步驟需要的資料，而不是三篇文章全部同時塞著。

edit_file：修改而不是覆蓋

有一個工具特別值得說一下：edit_file。

和 write_file（整個覆蓋）不同，edit_file 可以只修改檔案的特定部分——類似程式碼的 diff 操作。這在代理人需要逐步建構一份文件時很有用：

• 先寫好文件的骨架
• 每個步驟完成後，用 edit_file 更新對應的段落
• 不需要每次都重寫整份文件

這讓代理人在長時間的任務裡，可以維護一個「持續更新的工作文件」，而不是在 context 裡靠記憶維持狀態。

Filesystem 工具和外部工具的分工

值得釐清的一點是：Filesystem 工具是代理人自己的工作空間，不是你的應用程式儲存資料的地方。

簡單說：你的工具負責「跟外面世界溝通」，Filesystem 工具負責「代理人自己整理中間過程」。

什麼任務最需要 Filesystem

特別有價值的場景：

• 需要處理多份長文件（報告、程式碼、論文）
• 任務有多個階段，每個階段都會產生輸出給下一階段用
• 需要代理人反覆修改某份文件直到滿足條件
• 同時追蹤多個資訊來源

可以不用的場景：

• 簡單的問答或單步工具呼叫
• 輸入資料量小，放在 context 完全沒問題
• 不需要中間儲存的短任務

一句話說清楚

Filesystem 工具讓代理人從「只有腦子沒有桌子」，變成「有桌子可以把東西攤開、分類、逐步處理」的工作方式。

但這個虛擬桌子的「底層實作」是可以換的——測試時用記憶體、正式環境用磁碟或雲端儲存。下一篇來聊這個選擇。

上一篇：任務規劃與 write_todos：讓代理人先想清楚再做事 下一篇：可插拔後端：In-Memory、Disk、LangGraph Store、Sandbox 怎麼選