程式撰寫 Agent 不該困在聊天框裡

程式碼 Agent 需要的不只是聊天介面——它需要完整的開發環境。新的「Deep Agents IDE」指南展示如何 End to End 地構建一個真正的 IDE 風格 Agent UI，包含沙盒檔案系統、動態檔案樹、Diff 面板、終端機和聊天功能。

沙盒策略與生命週期管理

不同的應用場景需要不同的沙盒作用域策略：

• Thread-scoped（推薦）：每個 LangGraph 對話執行緒擁有獨立沙盒，檔案變更互相隔離，沙盒狀態在頁面重新載入後保留，清理機制明確
• Agent-scoped：同一 Assistant 下的所有執行緒共用單一沙盒，適用於需要跨對話保持專案狀態的場景
• User-scoped：每位使用者擁有單一沙盒，需要自定義身份驗證
• Session-scoped：由前端產生 Session ID，無需 LangGraph 執行緒，適合演示和原型設計，但不會在瀏覽器 Session 間持久化

Agent 與沙盒後端整合

Deep Agent 自動從沙盒獲得檔案系統工具（read_file、write_file、edit_file、ls、glob、grep）和 execute 工具，無需手動設定。使用後端工廠模式實現 Thread-scoped 沙盒時，工廠函數接收 BackendRuntime 物件，從中讀取執行緒 ID，並在執行期間解析對應的沙盒。沙盒 ID 存放在執行緒元資料中作為單一真實來源，避免應用層快取。

前端檔案瀏覽 API

通過 Hono API 伺服器暴露沙盒檔案系統，在 langgraph.json 的 http.app 欄位註冊。API 端點包含執行緒 ID 作為路徑參數，確保前端始終存取正確沙盒的檔案。兩個核心端點：GET /api/sandbox/:threadId/tree 取得檔案樹，GET /api/sandbox/:threadId/file 讀取單一檔案內容。

實時檔案同步機制

IDE 體驗的關鍵在於邊 Agent 工作邊更新檔案，而非等待完成。監聽資訊流中來自 write_file、edit_file、execute 等檔案變更工具的 ToolMessage，當這些工具呼叫完成時，立即重新整理對應檔案。execute 工具完成後應重新整理所有檔案，因為殼層命令可能修改任意檔案。

檔案變更偵測與 Diff 顯示

在每次 Agent 執行前拍攝檔案內容快照，執行後比對快照以識別變更檔案。使用框架特定的 Diff 程式庫（React 用 @pierre/diffs、Vue 用 @git-diff-view/vue）渲染統一 Diff 格式。使用者點擊變更檔案時預設顯示 Diff 檢視。

UI 架構

三面板佈局：檔案樹（固定 208px，左側）、程式碼/Diff 檢視器（彈性寬度，中央）、聊天面板（固定 320px，右側）。檔案樹使用 VS Code 風格圖示標記，被修改的檔案顯示琥珀色指示點。變更檔案摘要顯示所有修改檔案及其新增/刪除行數統計。

實踐最佳做法

• 生產環境使用 Thread-scoped 沙盒，沙盒 ID 存放在執行緒元資料
• Agent 後端工廠與 API 伺服器共享同一 getOrCreateSandboxForThread 函數，保證沙盒解析方式一致
• 在 sessionStorage 持久化執行緒 ID，使頁面重新載入後重新連接同一執行緒和沙盒
• 每個相關工具呼叫（非僅執行完成時）都同步檔案
• 變更檔案預設顯示 Diff 檢視
• 唯讀操作（如 read_file）只顯示簡短摘要，重點突出變更工具的完整輸出
• 以實際工作專案初始化沙盒，而非空沙盒
• 檔案樹過濾 node_modules 目錄