Sandboxed Agents for Codebase Migration (19 minute read)

將巨大的單一 PR（合併請求） 丟給審查者不僅風險極高，也難以推進程式碼現代化。透過將 Agents SDK 控制程式保留在信任主機外，並讓 Agent 在隔離沙盒中每次執行單一範圍的編輯與測試任務，能有效降低遷移風險。

將大型遷移 PR 拆解為受控的 Agent 沙盒任務

程式碼現代化是一個永無止境的過程。大型程式碼庫會不斷累積過期的依賴套件、安全漏洞與合規壓力。面對這些遺留下來的模式，開發團隊若試圖建立一個包含所有修改的大型 PR，往往會讓程式碼審查變得極度困難，且在合併時面臨極高的破壞風險。

為了解決這個問題，這份教學展示了如何利用受控環境中的 Agent（代理） 來執行程式碼遷移。其核心理念是「一次處理一個限定範圍的任務」。系統會將一個龐大的現代化專案，拆分為多個如單一任務般大小的儲存庫區塊（Repo shards）。

在每個獨立的任務中，Agent 會被指派去檢查特定的儲存庫、編輯指定的檔案、執行必要的檢查，最後回傳一個 Patch（修補程式）。在本文的範例中，Agent 的任務是將兩個服務的 OpenAI 客戶端包裝器，從舊版的 Chat Completions 遷移到最新的 Responses API。每個服務都會在各自的沙盒中運行，並回傳獨立的 Patch，讓開發者可以分別開啟 PR 進行審查與持續整合測試。

將控制主機與執行層分離的 Sandbox 作為工具架構

這套架構的核心設計在於「沙盒作為一項工具」（Sandbox as a tool）。在傳統模式下，開發者可能會啟動一個寫程式的 Agent，並將其控制程式（Harness）、Agent 迴圈、工具與檔案系統全部放在沙盒內部運行。這雖然可行，但會將任務調度與工具整合推入與生成程式碼相同的環境中，增加安全隱患。

本篇教學採用了不同的分離模式：可信任的主機行程（Host process）擁有 Agents SDK 控制程式、工具、MCP 伺服器（模型上下文協議，提供外部資料源）、憑證、策略與稽核紀錄。相對地，執行環境（也就是沙盒）只會接收到當前任務所需的限定工作區，以及執行終端機指令和編輯檔案所需的最低權限。

這種職責分離意味著，Host 可以自由使用機密金鑰、各種外部工具與服務；而沙盒僅取得完成該項任務所需的必要檔案。當 Agent 需要操作檔案系統、執行終端機指令、跑測試或生成 Patch 時，Host 才會呼叫沙盒。完整的 Agent 堆疊始終安全地保留在 Host 這一側。

從基準測試到修補程式：Agent 沙盒的工作流程

系統的整體工作流程從應用程式接收到遷移請求開始，並將其拆分成多個任務區塊。對於每個任務，Host 端的 Agents SDK 會啟動一個 Agent 並建立一個全新的沙盒環境。Host 會將該任務的儲存庫與遷移指示（例如 MIGRATION.md）掛載到沙盒內部的工作區。

在 Agent 開始修改任何檔案之前，Host 端會先針對該儲存庫執行一次基準測試（Baseline tests）。這確保了程式碼在 Agent 介入前是完全正常運作的。接著，Agent 會運用其專屬的兩項沙盒功能：用於終端機操作的 Shell() 與用於檔案編輯的 ApplyPatch()，來檢查程式碼、修改檔案並重新執行編譯與測試。

當任務完成後，Host 會接收該任務產生的遷移報告與 Patch，同時寫入稽核日誌。最後，Host 會直接刪除這個用完即丟的沙盒，並繼續處理下一個任務。所有 API 金鑰等敏感資訊都被嚴格限制在 Host 環境中，絕對不會被掛載進入儲存庫或沙盒內。

無縫切換 Docker、E2B 與 Cloudflare 沙盒供應商

由於所有與供應商（Provider）相關的程式碼，都被獨立隔離在沙盒創建的步驟中，這賦予了這套架構極高的彈性。開發團隊可以在不修改 SandboxAgent、工具、檔案清單（Manifest）或提示詞的情況下，自由切換不同的底層沙盒環境。

舉例來說，在本地端開發階段，開發者可以透過本機的 Docker 來運行沙盒。當準備部署到雲端時，只要更改沙盒客戶端（Sandbox Client）的實例化設定，就能直接指向託管型的沙盒供應商，例如 E2B，或是由 Worker 驅動的 Cloudflare 沙盒。

這個設計模式始終如一：更改沙盒的客戶端即可，無需動到 Agent 核心邏輯。這讓基礎設施團隊能夠根據資安規範與效能需求，隨時抽換執行環境。此外，Host 甚至可以連接外部的 MCP 伺服器，讓 Agent 在沙盒內修改程式碼時，仍能參照官方最新的 API 開發指南。

生產環境佈署：隔離資料存取與輸出驗證的邊界

在將這套模式推向生產環境時，必須建立清晰的信任邊界。任務調度、執行環境、資料存取與回傳的輸出，都應該被嚴格區隔。每個遷移任務都應被視為一個獨立的審查單位，由開發者針對產生的 Patch 進行人工檢閱，而不是讓系統自動將變更套用到正式的程式碼庫中。

客戶資料的儲存與外部網路存取，必須強制透過 Host 來路由，絕對不能讓沙盒直接擁有這些廣泛的權限。這確保了即使沙盒內生成的程式碼含有異常行為，也無法竊取敏感資料或對內網發起未經授權的連線。

最後，Host 必須在向使用者展示 Patch 或將其應用於真實環境之前，對沙盒的回傳結果進行確定性驗證。這不僅僅是檢查測試是否通過，還包含驗證遷移合約、結構化結果以及稽核日誌是否符合預期，確保大規模的程式碼現代化過程安全無虞。

分離控制主機與沙盒環境，讓 Agent 專注產出修補程式，是降低大型程式碼遷移風險的最佳架構。