你的 code agent 產生程式、跑測試，第二輪修正到一半遇到 deploy；服務重啟後，是從頭再付一次模型費，還是接著最後成功的步驟？如果這個問題會影響使用者結果或成本，就需要 durable workflow。若任務只是一次模型呼叫加一個快速 tool，普通 API route 反而更簡單。
Vercel 在 2026 年 6 月 17 日更新的官方實作指南，用 Workflow、Sandbox、AI Gateway 做一個 code evaluator：模型先生成程式與測試，Sandbox 執行，測試失敗就把 error context 帶回下一輪。這個範例的價值不在「自動寫 code」，而在三個責任被分開，失敗時能知道該從哪一層處理。
先判斷：你真的需要 durable workflow 嗎？
| 任務特徵 | 建議 | 原因 |
|---|---|---|
| 一兩次模型呼叫，幾十秒內完成，失敗可整次重跑 | 一般 API route / background function | 架構較簡單，沒有額外 checkpoint 心智負擔 |
| 多步模型與工具呼叫，重啟後不能全部重跑 | Vercel Workflow | 可保存完成的 step，從最後 checkpoint 繼續 |
| 要等待人工批准、webhook 或長時間事件 | Durable workflow | 流程可 suspend／resume，不必讓 request 一直掛著 |
| 需要執行模型生成的 shell、程式與測試 | Workflow + Sandbox | orchestration 與不可信執行環境要分離 |
| 只要切換模型、追 usage 與 failover | AI Gateway | 不必為模型路由硬加 Workflow 或 Sandbox |
Durable 不等於「跑得久」而已。真正判斷點是：程序消失後，任務進度是否必須保存；某一步重試時，已完成結果是否要沿用；流程能否安全地暫停等待外部事件。只想避免 HTTP timeout 時，先檢查平台的 background execution 能力，別直接把所有 function 改成 workflow。
三個元件各自管什麼？
Workflow 管流程狀態。使用 "use workflow" 標示 orchestrator，以 "use step" 切出可保存、重試與觀測的工作。官方說，process crash 或 redeploy 後，流程會從最後完成的 step 重播，不必把前面模型呼叫全部再跑一次。
Sandbox 管執行副作用。Vercel Sandbox 是 ephemeral Linux microVM，具有自己的 filesystem、network 與 resource limits。模型生成的程式、套件安裝、shell command、test output 應留在這裡，不直接碰 application server。需要 Docker 與完整測試依賴時，可接著看 Vercel Sandbox Docker 指南。
AI Gateway 管模型入口。它提供單一 API、模型切換、usage、spend tracking 與 observability。模型 provider allowlist、fallback 與資料政策仍要由團隊決定，可搭配 AI Gateway 治理指南檢查。
這三層可以單獨使用。只執行不可信程式時可只用 Sandbox；只要模型路由可只用 Gateway；只有工作真的要跨失敗保存進度，才加入 Workflow。
最小實作怎麼開始？
官方範例使用 Next.js、Workflow SDK、Vercel Sandbox、AI SDK 與 AI Gateway。建立專案後安裝依賴：
npx create-next-app@latest ai-code-evaluator --typescript --tailwind --app
cd ai-code-evaluator
npm install workflow @vercel/sandbox ai @ai-sdk/gateway
vercel link
vercel env pull部署在 Vercel 時，AI Gateway 與 Sandbox 可透過 OIDC token 驗證；本機開發用 vercel env pull 取得環境。官方說本機 OIDC token 每 12 小時過期，失效時要重新 pull。不要把 token 或 Gateway key 提交到 repository。
接著用 withWorkflow() 包住 Next config，否則 "use workflow"、"use step" 只會是沒有作用的字串：
import { withWorkflow } from "workflow/next";
import type { NextConfig } from "next";
const nextConfig: NextConfig = {};
export default withWorkflow(nextConfig);第一版 workflow 保持三個 step 就好：generateCode()、generateTests()、executeInSandbox()。Sandbox 回傳 exit code、stdout、stderr 與測試結果；失敗時只把必要 error context 傳到下一輪。不要一開始加入部署、開 PR、寫資料庫與通知，否則很難分辨重試錯在模型、測試還是外部副作用。
Retry 最難處理的是重複副作用
Vercel 官方範例最多嘗試三輪，這只是教學選擇。產品應根據每輪模型費、Sandbox 時間、錯誤是否可修與使用者等待上限，設定自己的 retry budget。語法錯誤或單元測試失敗可能值得再試；權限不足、依賴不存在、需求互相矛盾時，重跑三次只會重複花錢。
更重要的是 idempotency。Workflow 重播 step 時，純計算可以安全重做，外部副作用不一定。建立部署、寄 email、扣款、建立 issue、合併 PR 或寫 production database 前，必須使用 idempotency key、唯一 operation ID、狀態檢查與去重；高風險步驟還要 suspend 等人工批准。
step 邊界也不要切得太碎。每一行一個 step 會讓流程難讀、資料傳輸增加；整個 agent 一個 step 又失去 checkpoint 價值。比較實用的切法，是每個 step 都有清楚輸入、可序列化輸出、可判斷成功與否，而且重試策略一致。
Sandbox 有隔離，仍然要限制網路與 secrets
MicroVM 能隔離 host，不代表模型生成的程式可以拿到全部環境變數與 unrestricted network。先決定 sandbox 是否需要出網、可連哪些 domain、能讀哪些 secret、可寫多少檔案、CPU／memory／time limit，以及 output 最大尺寸。測試 code agent 時，預設不給 production credential。
agent 可能從 repository、issue、套件文件或網路讀到 prompt injection。這些內容不該直接改變 Sandbox 權限，也不該讓 workflow 跳過批准。把「模型看到的文字」視為不可信輸入，把 secrets 與部署權限留在獨立 step，並只在符合政策時注入。
上線前至少保留 prompt／model、每個 step 的輸入輸出摘要、Sandbox command、exit code、重試原因、模型 usage、人工批准與最終 diff。workflow 顯示 success 只代表流程完成；工程團隊還要能追查測試、變更與副作用。完整交付可參考 AI coding agent 從 issue 到 PR的 review gate。
一週試跑怎麼驗證？
先選一個沒有 production secrets 的小型 repository，只接受「產生單一函式與單元測試」任務。第一天確認三個 step 與 Dashboard observability；第二天故意讓測試失敗，看 error context 是否只進下一輪；第三天在 step 中途 redeploy，確認已完成模型呼叫沒有重跑。
接著測 timeout、無法安裝依賴、Sandbox 無網路、模型回傳 code fence 與超過 retry budget。最後才加一個人工批准點，例如測試通過後等待人確認是否建立 PR。若團隊無法回答「哪一步可重試、哪一步不可重複、失敗後誰處理」，先不要接正式 repo。
常見問題
Vercel Workflow 和一般 background job 有什麼差別？
一般 background job 可以延後執行，但未必保存每個完成 step。Durable Workflow 會 checkpoint，程序重啟後能從已完成步驟繼續，也能 suspend 等待人或外部事件。
有 Vercel Sandbox 就能安全執行任何 AI 程式嗎？
不能。Sandbox 隔離 host，但仍要限制 network、secrets、資源、timeout、檔案與輸出。模型生成程式也可能濫用可用權限，production credential 預設不應注入。
官方範例為什麼重試三次？
三次是範例的 maxIterations，方便展示測試失敗後的 self-healing loop。實際上限要依模型成本、錯誤類型、Sandbox 時間與使用者 SLA 設定。
Workflow retry 會不會重複寄信、扣款或部署？
可能。Durability 不會自動替外部 API 去重。這類 step 要使用 idempotency key、operation ID、狀態檢查與人工批准，並在重試前先確認操作是否已完成。
一定要同時使用 Workflow、Sandbox、AI Gateway 嗎？
不用。只需隔離 code execution 可單用 Sandbox；只需模型路由與 usage 可用 Gateway；只有任務要跨失敗保存進度、等待事件或逐步重試時，才需要 Workflow。