業務 Agent 程式碼執行架構：從工具呼叫到受控寫入

將 AI Agent 落地到現有商業軟件中，是許多工程團隊正在面對的挑戰。Foundax 作為一個擁有商品、規格、庫存、多語言內容、促銷與交易系統的完整平台，而不僅僅是頁面生成器，在整合 Agent 的過程中經歷了架構上的反覆探索。

最初，我們試圖透過封裝業務 API 讓 Agent 使用（傳統的 Tool Calling）。但我們很快發現，當面對真實的、複合的網店營運需求時，純粹的 API 工具組合會讓模型與系統的互動變得極度笨重。本文將重演這段架構演進，探討為什麼我們最終選擇引入沙箱（Sandbox），讓業務 Agent 像編寫程式碼的 Coding Agent 一樣工作，以及背後關於資料快照、執行授權與受控寫入的技術機制。

工具粒度的陷阱：從「模擬後台操作」到「陷入無限迴圈」

在真實的商業場景中，商家的需求往往是具體且帶有複雜條件的。例如一個典型的營運任務：

「幫我準備週末的清倉活動；找出可售庫存超過 20 件的商品，排除已經參加其他優惠的商品，幫它們補齊缺失的英文介紹，最後生成一份折扣建議先讓我審閱。」

在早期的設計中，我們嘗試為模型提供不同粒度的工具：

粗粒度工具（整項任務封裝）：例如提供一個 prepareweekendsale 工具。這對模型來說很容易呼叫，但致命傷是缺乏彈性。只要業務條件微調（例如增加「排除特定類別」），工具的參數與邏輯分支就會無限膨脹。
細粒度工具（CRUD 級別）：我們讓模型像人類操作後台一樣，依次呼叫 listproducts、checkinventory、updatetranslation。但這種設計將關係型資料庫的 Join 邏輯推給了 LLM。模型必須自己維護龐大的中間集合，在多輪對話中傳遞 ID，手動關聯商品、規格、翻譯與促銷狀態。
中間粒度工具：雖然能優化常見的查詢組合，但永遠無法窮舉所有長尾需求。且當工具目錄變大時，還需要額外的檢索與召回機制。

最根本的問題在於經濟性與穩定性。複雜任務的多輪協調會大量消耗模型的推理能力、Token 上下文、執行時間以及 API 預算。模型在「判斷業務邏輯」與「處理大量確定性資料過濾」之間疲於奔命。邊界清晰的任務固然適合直接使用工具，但在處理不可預測的業務組合時，我們需要一種更高效的方式。

關於這種架構整合的宏觀設計，可進一步參考將 Coding Agent 接入真實商業系統：Foundax 架構實踐。

轉換視角：用程式碼編排業務

與其讓 Agent 透過 API 介面去「點擊」虛擬按鈕，不如讓它發揮最擅長的事情：閱讀 Schema 並編寫程式碼。這並非淘汰 Tool Calling，模型依然需要透過工具來讀取檔案、執行命令、提交結果，但它的工作模式發生了本質上的改變。

我們引入了包含 Shell 和檔案系統的 Sandbox，將營運需求轉化為數據處理腳本。模型擅長讀程式碼和寫程式；那些確定性的 join、filter 與批次計算交由 Python 或 Node.js 腳本在本地執行，而 LLM 則專注於探索、修正、驗證以及非確定性的業務判斷（例如「這段商品描述的語氣是否合適」）。這並非承諾能完全消除多輪對話或固定 API 呼叫次數，其核心目的是減少模型在不同工具間不必要的資料搬運與逐輪協調成本，至於完整任務的實際開銷與效益，仍需針對具體業務場景進行實測評估。

業務 Schema 與語義授權

要讓模型寫出正確的腳本，我們必須提供清晰的業務視圖（Business Schema）。這不僅僅是資料庫結構的 Dump，而是帶有業務語義的授權數據字典。我們必須向模型解釋：

每一行的具體含義、主鍵與外鍵的關聯。
金額與數量的單位、取值範圍。
商業邏輯的歸屬：例如「價格」與「庫存」歸屬於具體的商品規格（Variant），而「多語言介紹」歸屬於商品與語言的交叉組合（Product × Language）。
業務公式的定義：例如「可售庫存」在我們的系統中定義為「現有庫存減去已預留庫存」（注意：這僅為本次授權視圖的範例，不能泛化為所有商業系統的標準庫存公式）。

沙箱執行與目錄掛載架構

引入腳本執行後，安全與權限隔離成為首要任務。在我們的架構中，宿主（Host）與沙箱（Sandbox）的職責有嚴格的邊界：

宿主：負責用戶身份驗證、授權、準備模型允許讀取的數據快照、排程命令，並在最後取回產物。
沙箱：嚴格限制檔案存取、網路連線與運算資源。沙箱內不持有生產資料庫的直連憑證，也沒有完整的應用程式權限。Agent 在沙箱中生成的腳本，只能輸出「操作建議」，無法直接更改線上數據。

為此，我們設計了分離的邏輯掛載點（Mount Points），這是一套公開的參考設計：

/repo：唯讀的原始碼與業務說明文件。
/data：按用戶、租戶、資源與權限嚴格準備的業務資料快照。
/work：Agent 在會話期間編寫的腳本、日誌與中間運算結果。
/outputs：最終輸出的建議清單與交付物。

內部執行器效能優化

為了讓這套機制足夠流暢，我們對內部執行器的排程進行了專項優化：

會話啟動耗時從約 2.1s 縮短至 1.0–1.4s。
首個工具鏈命令耗時從約 0.87s 縮短至 0.10–0.15s。

(註：此數據僅為內部針對執行器準備與調度環節的測量，不代表端到端的任務完成時間或 Token 節省比例。具體的資源開銷仍需依賴完整鏈路的觀測。)

快照機制與受控寫入（Controlled Writes）

在 Agent 分析資料與編寫腳本的同時，真實世界的網店仍在運作——顧客可能正在下單佔用庫存，營運人員可能正在修改價格。如果直接基於過時的資料進行寫入，將引發嚴重的資料災難。

資料快照與一致性水位

不可變的原始碼快照可以依據構建與存取範圍進行複用；但業務資料的快照必須嚴格綁定使用者的授權範圍（包含租戶、資源與權限）。我們透過 Version Watermark（版本水位線）結合業務域的依賴關係來決定資料的刷新範圍。

這裡存在一個具體的競態條件風險：如果系統在匯出舊資料快照的期間發生了業務寫入，卻給這份快照標上了最新的水位線，系統就會將過期的資料誤認為最新狀態。因此，資料本身與其水位線必須嚴格屬於同一個一致性截面（Consistency Cross-section）匯出。

在執行設計上，單一命令所依賴的資料快照版本是固定的；只有在命令切換時，系統才會為沙箱掛載包含新水位線的完整資料版本，同時保留 /work 目錄下的腳本以便接續執行。必須強調，這套快照生命週期是架構設計中需要實現的一致性責任（目前的開源範例尚未包含完整的快照快取或自動刷新實作），並且這僅用於 Agent 的計算與決策階段——當最終建議交由業務服務寫入時，依然必須對當前的生產狀態進行嚴格校驗。

三階段寫入：計算、確認、執行

Agent 的工作成果絕不是一次性調用就直接修改生產資料。我們將寫入過程拆分為三個階段：

計算完成： Agent 將具體物件與欄位的修改建議輸出至 /outputs。
用戶確認：商家或營運人員檢閱這些建議。
業務寫入：由宿主的業務服務（Business Services）實際執行寫入。

在「業務寫入」階段，系統會重新檢查權限、欄位約束以及記錄版本（Record Version）。一旦發現衝突（例如 Agent 建議折扣的商品，其庫存在這段期間內已被清空），系統會拒絕寫入。衝突發生時必須重新讀取當前狀態並進行計算，絕不能僅僅替換版本號強行寫入。

此外，即使 Agent 將所有的修改建議輸出在同一個檔案中，這也不代表它們是一個原子事務（Atomic Transaction）。跨域的事務、部分成功與重試策略，均由具體的業務服務負責定義；例如，涉及收費與退款的通知，必須走各自獨立且明確授權的通道。

結語

讓業務 Agent 像 Coding Agent 一樣工作，本質上是為了在「不可預測的業務組合」與「系統執行效率」之間找到平衡。業界對此已有許多探索，例如 OpenHands 提供了通用的 Agent SDK 來處理底層的執行循環與會話管理，Anthropic 關於使用 MCP 執行程式碼的研究探討了模型如何透過程式碼進行組合運算，以及 Cloudflare Code Mode 以程式碼組合工具呼叫的實踐。在這些成熟的通用執行架構之上，我們的核心挑戰與貢獻，在於如何將既有的商業系統資料契約、快照生命週期，以及受控寫入機制，安全且高效地整合進 Agent 的工作流中。

若您對其他領域的 Agent 整合應用感興趣，例如前端程式碼與 UI 領域的結合，可以參考如何讓 AI 生成的前端程式碼支援可視化編輯。

完整的架構設計與合成數據的可運行盤點範例，已於 Foundax Agent Business Workspace (GitHub) 開源（採用 MIT 授權）。該範例示範了讀取、計算、建議，以及作用域、欄位、庫存約束與記錄版本的校驗流程（註：範例不含完整的生產級沙箱、快照快取或自動刷新實作）。我們非常歡迎與其他維護複雜商業系統的工程團隊交流具體問題，您可以透過 GitHub Issues、Discussions 或 contact@novariseintl.com 與我們聯繫。

我們為什麼讓業務 Agent 像 Coding Agent 一樣工作

工具粒度的陷阱：從「模擬後台操作」到「陷入無限迴圈」