返回洞察
工程實踐#engineering#AI Agent#architecture#SDK#context management

由生成網頁到交付業務：設計 Agent 的工作環境

探討如何將既有業務系統與創意資源重塑為 AI Agent 的工作環境。透過領域組合、任務視圖、批次寫入協定與多維度反饋機制，在有限上下文預算內引導 Agent 達成跨領域商業目標。

發佈 2026年10月28日Reading time: 5 分鐘Foundax
由生成網頁到交付業務：設計 Agent 的工作環境

假設商戶提出這樣的要求：

「我想喺英國推呢款新托盤，做個限時 85 折首發，網頁設計要乾淨俐落。」

對工程師而言，這個需求揭示了兩個平行的世界：嚴謹的商業邏輯（計算折扣、核對物流、扣減庫存）與開放的創意設計（版面佈局、文案、視覺組合）。

最初期的 Agent 整合嘗試往往採取兩種極端：一是讓模型僅負責生成前端靜態程式碼，這會導致業務邏輯斷裂；二是將龐大的底層資料庫與全量 API 規格直接暴露給模型，這會迅速耗盡模型的上下文預算 (context budget)，並引發大量的幻覺與重試。Agent 真正需要的是一個經過設計的「工作環境」——它既能將現有業務能力轉換為明確的契約，又能為視覺創意保留自由度，並提供精準的失敗反饋。

領域探索與狀態寫入：約束與容錯

為了解決上下文膨脹的問題，平台不提供靜態的 API 傾印，而是透過 createBusinessClient(baseUrl) 初始化 SDK，並由 client.catalog() 暴露領域清單、用途與依賴關係。Agent 依據任務目標，針對性地發起讀取，例如呼叫 client.read("shippingPolicies")。每次領域讀取的回傳結構皆為 {revision, shopId, rows}，不挾帶多餘的實體欄位，這讓 Agent 能夠清晰追蹤當前觀察到的業務狀態版本。

在構建這個英國首發活動時，Agent 需要建立新的促銷與活動記錄。平台提供了 client.apply(plan) 協定，透過傳入明確的領域與數值進行狀態變更：

const { revision } = await client.read("products");

const plan = {
  expectedRevision: revision,
  operations: [
    {
      domain: "promotions", 
      value: { 
        id: "opening-offer", 
        percent: 15, 
        productIds: ["tray"] 
      }
    },
    {
      domain: "campaigns", 
      value: { 
        id: "quiet-mornings", 
        title: "UK launch", 
        country: "GB", 
        productIds: ["tray"], 
        shippingPolicyId: "ie-standard", 
        promotionId: "opening-offer" 
      }
    }
  ]
};

await client.apply(plan);

這個設計在約束與容錯之間取得了平衡。如果 value 內的 productIds 參照了不存在的商品，這類商品或促銷參照錯誤會直接導致整個批次被拒絕。然而，對於尚未齊全的活動 (Campaign) 草稿，系統允許成功儲存。這並非表示資料合法，而是將「狀態寫入」與「業務就緒檢查」解耦，為後續的修復行動保留空間。

任務視圖與領域組合：減少重複實作

如果我們要求 Agent 在生成的頁面程式碼中，自行透過 API 獲取商品資料、比對折扣並核對退貨條款，不僅會產生極端脆弱的代碼，更浪費了寶貴的執行預算。

因此，平台在宿主端 (Host) 實作了 campaignView 這個任務導向的讀取模型，將商品、促銷、物流、退貨與媒體資源進行領域組合。前端頁面程式碼或外部 Agent 只需呼叫 client.campaign(id) 即可獲取聚合後的視圖。這改變了生成頁面程式碼的職責：它現在只需專注於視覺佈局與互動體驗，無需重構任何業務計算。

這種責任劃分在訂單環節更為嚴格。下單操作 client.order(input) 接收的完整頂層結構為 {expectedRevision, campaignId, country, items}，其中 items 包含 productId 與 quantity。宿主系統作為絕對權威，會重新計算總價、核對庫存與目的地。儲存的訂單會永久保留成交時的金額與條款，其生命週期與隨時可能更新的 SDK 視圖完全獨立。商戶提供的未知商業事實（如運費定價）必須由外部輸入，模型無法也無權憑空捏造。

多維度反饋與修復迴圈

單純的寫入成功不代表業務能夠上線。不同的失敗類型必須驅動 Agent 採取不同的修復行動。

在上述的 plan 範例中，Agent 將目標國家為 GB 的活動關聯到了名為 ie-standard 的既有物流政策。這在資料結構上是完全合法的（ID 存在），草稿也會被成功儲存。但當 Agent 嘗試呼叫 client.check("quiet-mornings") 時，系統會回傳：

{
  "revision": 43,
  "issues": [
    {
      "code": "shipping_coverage",
      "message": "Select a shipping policy covering GB."
    }
  ]
}

在此狀態下，client.campaign(id) 視圖與訂單操作都會被系統阻擋。這種 shippingcoverage 錯誤要求 Agent 發起業務關係修復（尋找或建立適用於 GB 的物流政策），這與語法錯誤觸發的程式碼修復截然不同。通過一項檢查並不能豁免其他維度的驗證要求。

英國活動誤用愛爾蘭配送政策時的就緒檢查、視圖阻擋與參照修復

創意資源：模板說明與實際像素

業務邏輯雖然嚴謹，但商戶同樣重視「設計要乾淨俐落」。

模板說明 (Template instructions) 在這裡扮演了關鍵角色。它不僅提供 HTML/CSS 骨架，更向 Agent 傳達了購物旅程的意圖與適配方向。然而，有些設計決策無法單靠文字或資料庫驗證來解決。例如，系統中存在一個合成茶杯的圖片，其手柄向右延伸；而新推出的「托盤 (tray)」則是俯視圖且比例更寬。

如果 Agent 只是盲目替換模板標籤或套用固定的圖片裁切比例，茶杯的手柄很可能會被切斷，或者與托盤在視覺上產生嚴重的重疊。媒體的中繼資料可以縮小資產的選擇範圍，但要判斷排版佈局與裁切是否合理，最終仍必須依賴對實際像素 (actual pixels) 的觀察。當截圖顯示手柄被裁切時，這類反饋驅動的是排版或資產選擇的修復。平台必須保留普通程式碼的創意自由，而非僅提供預先設限的配置項。

上下文生命週期管理

在實際的互動過程中，商戶隨時可能變更需求。當原始碼被修改、狀態被更新後，舊有的 API 讀取收據與先前的網頁截圖就會立刻失效。如果將上下文視為一個不斷附加的日誌 (append-only log)，模型很快就會被過期的狀態混淆。

這要求架構必須將上下文視為一個動態的生命週期。當前的目標與約束、已確認的業務事實、尚未解決的錯誤 (unresolved gaps)、原始碼版本以及最新相關的觀察結果，必須與可復原的原始歷史紀錄區隔開來。每當輸入發生變更時，必須重新執行檢查與截圖，而非重複使用舊有截圖。在評估這類系統時，除了關注延遲、輪數與上下文大小，更要綜合評估其在業務、互動與視覺品質上的實際交付表現。

開放性與教學參考實作

為了具體展現這些架構決策，我們發布了 agent-native-business-environments (MIT, Node 22+) 作為公開的參考實作。它包含單一店鋪的 Node 宿主環境、JSON 持久化機制、開放的 SDK、HTML/CSS/JS 頁面以及模板指南。

該專案不是一個具備模型迴圈或生產級支付堆疊的完整 Agent 框架；其上下文生命週期管理目前也僅以設計文件和虛擬碼呈現。但它清晰地展示了可執行的架構邊界。專案中包含一個使用合成資料的確定性腳本範例（無模型呼叫），精準重現了上述 GB/IE 物流不匹配的儲存、阻擋與修復過程。工程師可以透過 npm run demo 親自觀察這個反饋迴圈，並透過根目錄的 TASK.md / TASK.zh-CN.md 作為入口，利用這些共享的契約與文件，嘗試接入自帶瀏覽器與視覺工具的外部 Agent。

延伸閱讀

本專欄的其他文章