【2026 最新】Google AX 教學：Task、Workspace、Gateway 暫停續跑 Agent

Google AX 教學最容易卡住的地方，不是指令，而是你同時看見 Kubernetes、Task、Workspace、Gateway、Agent Substrate，卻不知道哪一層負責哪件事。先把它想成一間可停業再開門的工作室：Task 是這次工作，Workspace 是留下來的工作桌，Gateway 是對外通行證，底層 Substrate 則負責把整間工作室暫停、保存與重新喚醒。

這篇以 2026 年 9 月 20 日發布的 AX v0.3.0 為準，帶你看懂現行架構、部署第一個隔離 Task，並用一張「可重跑收據」驗收暫停續跑、工作區保存與出站限制。它是依官方文件與固定版本程式碼整理的操作流程，不會假裝成 AlphaLab 已完成的本機 Kubernetes 實測。

先說結論：Google AX 適合誰？

如果你只想在筆電跑一個短命腳本，單一 container 更省事；如果你需要硬體級隔離，但工作生命週期仍由自己管理，microVM 更直接；如果你要同時管理許多 Agent 的建立、網路、工作區、暫停與續跑，才是 AX 開始有價值的地方。

先記住一句話：Task 決定「跑什麼」；Workspace 保存「留下什麼」；Gateway 限制「能連哪裡」；Agent Substrate 決定「怎麼停、怎麼醒」。本文所有操作都在這句話上疊加，不必先成為 Kubernetes 專家。

Google AX 教學第一步：拆開四個角色

1. Task：一份可管理的執行宣告

Task 是最小執行單位，描述 image、command、環境變數、Workspace 綁定與 Gateway 參照。schema 也有 CPU／記憶體欄位，但 v0.3.0 不能只因 manifest 寫了數值，就推論底層已套用對應限制。它不是「Agent 大腦」，而是告訴 AX 要把哪個程式放進怎樣的沙盒。建立、暫停、續跑、刪除，操作的都是這個資源。

2. Workspace：Task 重開後仍能找回的桌面

Workspace 是環境配方，可宣告 Git repository、技能與 MCP 相關設定；Task 綁定後，每個沙盒會得到自己的 Workspace 路徑。v0.3.0 預設 runner 直接做的是 Git clone 與建立 skills path，不能把所有宣告都當成已物化。它不是多人共用磁碟，也不等於資料庫。現行 runner 明確保證的是 /workspace 在 suspend／resume 間保存，因此 checkpoint、進度 JSON、待辦清單都應寫進這裡。

3. Gateway：網路入口與出站規則

Gateway schema 可宣告 listeners 與 egress allowlist，但 v0.3.0 的 runtime 接線不能把兩者混為一談：出站規則會轉成 Substrate policy；入站請求則依 官方 networking 文件統一走 atenet-router 與 ate-target-actor header，目前程式未用 listeners 建立 Task 專屬 Service／Ingress。這一層不能只看 YAML；你還要確認 GatewayReady，並做允許、拒絕兩種連線探針。

4. Agent Substrate：AX 底下的執行底盤

AX 的 server、Redis 與 controller 負責保存宣告、排工作與協調狀態；真正建立 actor／sandbox、保存 Workspace、恢復執行的是 Agent Substrate。AX v0.3.0 目前固定要求 gvisor-default runtime；底層 Substrate 也能支援 microVM，但那不代表 AX 這條預設路徑會自動替你切換。

先確認前置環境：這不是三行指令的筆電工具

官方 quickstart 的前提包括 Go 1.27.1 以上、ko、kubectl 與有效 kube context、可用的 Kubernetes cluster、能 push 且能被 cluster 拉取的 registry authentication，以及可連線的 Agent Substrate Control API。若採 Google Cloud 的官方路徑，還要先完成 GKE Agent Substrate 安裝；目前文件把一般入口定位為 evaluation／non-production，production support 另採 allowlist。這條路徑要求 GKE Standard，不支援 Autopilot；版本需為 1.36 並啟用指定 beta APIs，或 1.37 以上，節點至少 c3-standard-4，而且安裝要從本機執行，不用 Cloud Shell。

• 適合繼續：你已有 Kubernetes／registry，並想研究大量 Agent 的生命週期與隔離控制。
• 先補底層：你還不熟 image、Pod、Service 或 registry；先看 Docker sandbox 與 microVM 教學，會少掉一半名詞焦慮。
• 只想做一個 Agent：先用 AI Agent Harness 心智模型整理 loop、工具與狀態，再判斷是否值得加 AX。

AX 的 README 直接標示概念、協定與 API 仍在快速變動，並預告 stable 前可能出現重大 breaking changes。因此下面把版本固定在 v0.3.0，而不是使用會漂移的 @latest。

go install github.com/google/ax/cmd/ax@v0.3.0
export PATH="$(go env GOPATH)/bin:$PATH"

git clone --branch v0.3.0 --depth=1 https://github.com/google/ax.git
cd ax
make deploy AX_IMAGE_REPO=<your-registry>

<your-registry> 必須是 cluster 節點能拉取的 repository。部署完成後，先檢查 ax-server、controller 與 Redis 的 Pod，再處理 Task；若控制面都沒 Ready，後面任何 Agent 錯誤都只是連鎖反應。也要執行 kubectl get ds -n ate-system -l app=atelet -L ate.dev/substrate-version，保存安裝的 Substrate version label 與 component image digest；只鎖 AX tag，仍不能完整重現整條 runtime。

先停在這裡做 snapshot storage preflight。v0.3.0 的 ActorTemplate builder在沒收到 AX_SNAPSHOTS_BUCKET 時會落到專案內硬編碼的測試 bucket，而 checked-in controller Deployment 沒有設定這個變數。GKE installer 建出的 bucket 也不會自動寫入 AX Deployment。套用第一個 Task 前，必須把 controller 的 AX_SNAPSHOTS_BUCKET 指到本專案 Substrate worker 可讀寫的 snapshot location，重啟 controller，再檢查產生的 ActorTemplate storageLocation；沒有通過就停止，不要期待 suspend／resume 自動成功。

kubectl -n ax-system set env deployment/ax-controller \
  AX_SNAPSHOTS_BUCKET=gs://<your-substrate-snapshot-bucket>/ax/
kubectl -n ax-system rollout status deployment/ax-controller

上面 bucket 名稱必須換成你安裝時建立並完成 IAM 的實際位置，不可照抄 placeholder。若改用自訂 spec.image，它也不是任意 OCI image：依 runner contract，image 內必須有可執行的 /usr/local/bin/ax-task-runner；官方範例的 digest 已包含它。

第一次部署時，不要用同一個 Task 逐步加 image、env 或 Workspace。v0.3.0 更新 Task spec 後，既有同名 actor 可能繼續使用舊 template；Workspace 也有 maiden-run marker，不能當 live rollout。要分階段實驗，就每階段使用新 Task name。要改正式 Task 且保留資料，先把 /workspace 的 checkpoint／artifact 匯出到明確的外部儲存並驗證；delete 會 teardown actor，新 Task 不會繼承舊 Workspace。完成匯出後，才 delete、確認 NotFound，再用新 name 建立。每一步都保存 manifest、ax describe 與探針輸出，才能知道故障出在哪一層。

跑起第一個 Task：先照官方範例，再縮緊權限

v0.3.0 repository 已附完整範例，但 examples/task.yaml 的文件順序是 Task、Workspace、Gateway、Model，而 CLI 會逐份送出。Task 的事件可能在依賴建立前就被 controller 消費；Workspace／Gateway 的更新本身不會重排相依 Task。請先把官方檔案的三個區塊分成 workspace.yaml、gateway.yaml、task.yaml，依賴先、Task 最後；這個不帶 goal 的最小流程不需要 Model：

ax apply -f workspace.yaml
ax get workspace default-workspace

ax apply -f gateway.yaml
ax get gateway default-gateway

ax apply -f task.yaml
ax get tasks
ax watch task task123
ax describe task task123

如果 Workspace 或 Gateway 查不到，就不要送 Task。這個順序避開 v0.3.0 的 dependency race；它也避免 missing Workspace 被略過、Task 先以空目錄啟動，或 missing Gateway 先落到 wildcard。若要替已存在的 Task 更新 Gateway policy，先 apply Gateway、確認新值存在，再重新 apply Task 觸發 reconcile，最後重跑正反探針。image、env、Workspace 變更則不要依賴同名 Task update；v0.3.0 已有 stale actor 重現，應改用新 Task。

不要把 watch 顯示 Running 當成完成。v0.3.0 的 watch 在 phase 到 Running 時就會離開；官方 demo 另外等的是 Ready=True。使用完整 Task 範例時，仍要用 describe 檢查 WorkspaceReady、GatewayReady 與 Ready，但它們只是必要狀態，不是工作成功的充分證據：v0.3.0 的已回報案例顯示 Git clone 失敗仍可能得到 WorkspaceReady。後面還要補檔案、應用輸出與網路探針。

範例把 debug: true 打開，才能使用 ax ssh。這個選項會啟用沙盒內的任意程序與檔案操作服務；平常預設為 false。驗收完成後，把不需要互動除錯的工作改回 false，不要讓測試便利性默默變成長期權限。

Google AX 暫停續跑：保存的是檔案，不是 RAM

這是整篇最重要的界線。依照 v0.3.0 runner 合約，ax suspend 會終止目前 command process group；resume 後是新的 container、全新的 process tree，再從保存的 /workspace 啟動。換句話說，存在記憶體的迴圈計數會消失，寫進 Workspace 的 checkpoint 才會回來。

用這組命令製作最小「續跑收據」：

ax ssh task123 -- sh -lc \
  'printf "step=1\n" > /workspace/ax-receipt.txt'

ax suspend task task123
ax describe task task123   # 等到 phase: Suspended

ax resume task task123
ax describe task task123   # 等到 Ready=True

ax ssh task123 -- cat /workspace/ax-receipt.txt

最後一行若仍輸出 step=1，你證明的是「Workspace 有還原」；它沒有證明 Python／Node process 從原 instruction pointer 接著跑。真正要做長任務時，把工作切成可重入步驟，每一步完成後原子寫入 checkpoint，啟動時先讀 checkpoint 再決定下一步。這和 事件紀錄與可恢復 Agent 教學的核心觀念相同：重啟不是例外，而是正常路徑。

三個最低限度 smoke tests：路由、出站、Workspace

1. 身分：先驗證你連到哪個 Task

AX 會讓 Task 與同名 actor 對應，路由識別是 <atespace>/<task>，例如 default/task123。請為 Task A 與 Task B 各寫不同 canary 檔案，再透過相同入口讀取；A 只能讀到 A 的內容，B 只能讀到 B 的內容。這能抓出本次測試裡明顯的路由串線，不能單獨證明 gVisor、snapshot 或 worker reuse 的完整安全邊界。

atespace 是資源 scope，不要自行把它推論成完整的終端使用者授權系統。v0.3.0 的 AX application layer 未配置 TLS 或 authentication interceptor，CLI 使用 insecure transport。預設 Service 雖是 ClusterIP，Kubernetes port-forward 與 RBAC 只是外層邊界；不要把 AX server 直接暴露到公網。若你需要更成熟的 runtime control 清單，可搭配 Agent Runtime Controls 驗收表逐項檢查。

2. 出站：一個允許、一個拒絕，還要看 condition

官方範例的 Gateway 使用 host: "*"。練習時先在 gateway.yaml 改成真的需要的 host，例如 github.com；依序更新 Gateway、確認內容，再重新 apply Task 讓 policy reconciliation 發生：

ax apply -f gateway.yaml
ax get gateway default-gateway
ax apply -f task.yaml
ax describe task task123

ax ssh task123 -- curl -I --max-time 10 https://github.com
ax ssh task123 -- curl -I --max-time 10 https://example.com

這不是保證第一個會成功，而是驗收門檻：只有允許目標成功、拒絕目標失敗，而且 GatewayReady=True，才能算這組 policy 通過。若兩個都成功，規則太寬；若兩個都失敗，也不能說隔離成功，因為 v0.3.0 的 hostname allowlist 重現報告顯示 allowlisted TLS host 也可能被擋。此時應判定版本能力未通過，不要把「全部斷線」包裝成安全。

還有兩個 source-level 陷阱：v0.3.0 reconciliation 程式碼在 Task 沒寫 Gateway，或參照的 Gateway 查不到而被 worker 當成 nil 時，都會產生 wildcard egress；套用 policy 失敗時，也可能把 GatewayReady=False 寫入狀態後繼續讓 Task 走向 Running。所以 phase、condition 與正反探針必須一起看。

另一個容易誤判的點是：manifest 的 HostRule 雖有 port 欄位，但 v0.3.0 的 egress 轉譯程式只使用 host／CIDR，沒有把 port 帶進底層 policy。因此現在應把它當成 host allowlist 驗收，不能對讀者承諾已完成 port-level 封鎖。這是固定版本程式碼的觀察，不代表未來版本仍會如此。

3. Workspace：用兩個 Task 做交叉污染測試

建立兩個只改 metadata.name 的 Task，各自在 /workspace 寫入不同 nonce。分別 suspend／resume 後重讀：每個 nonce 都要存在，而且不能在另一個 Task 出現。這一組測試可驗收檔案保存並抓出明顯交叉污染，比只看 dashboard 的綠燈更有意義；它仍不是完整隔離證明。

取消、失敗與收據：別只留下「看起來有跑」

v0.3.0 的 CLI／API 提供 suspend、resume 與 delete，未定義名為 cancel 的 Task 操作。已匯出必要資料、確定要刪除 AX Task／actor 時，使用 ax delete task task123；server 採兩階段刪除，先把資源設為 Terminating，完成底層 teardown 後再刪掉記錄。CLI 最多等待五分鐘看到 NotFound；若 reconcile 失敗而卡在 Terminating，先查 controller log，再重送 delete 讓事件重新入列。若只是稍後繼續，才使用 suspend。

還有一個反直覺行為：Task 的 command 結束後，runner 仍保持 PID 1 存活，以便 metadata 與 SSH 服務繼續工作；預設 AX 控制面也拿不到 child process 的 exit code。因此 phase 仍是 Running，不等於你的工作成功。最簡單的做法是用 wrapper command 在自然結束時把 $? 與結果摘要寫進 /workspace；需要更完整事件處理時，再自訂 runner 的 OnCommandExit。你的收據至少要包含：

command:
  - sh
  - -lc
  - 'python agent.py; rc=$?; printf "%s\n" "$rc" > /workspace/exit-code; exit "$rc"'

1. 輸入版本：AX tag、image digest、manifest 的 Git commit。
2. 狀態證據：Task phase 與三個 conditions。
3. 工作證據：應用程式自己的 exit status、checkpoint 與輸出 hash。
4. 邊界證據：allowed／denied egress，以及 A／B Workspace nonce。
5. 清理證據：delete 後 ax get tasks 不再出現該 Task。

這種「控制面狀態不等於工作完成」的區別，也是 實作 AI Agent Harness時一定要自己保存 run state 與 evaluator 結果的原因。

AX、單一 container、microVM 怎麼選？

• 選單一 container：一個團隊、少量短任務、失敗就重跑，而且你願意自己管理狀態與網路規則。
• 選 microVM：你優先要更強的工作負載隔離，Task 編排、保存與路由仍由現有平台負責。
• 選 AX：你已有 Kubernetes 與 Substrate，並需要資源宣告、批量生命週期、Workspace 保存、Gateway 與 actor routing 形成同一個控制面。

AX 不會取代 Agent 本身的 reasoning loop、工具權限設計或品質評估。它處理的是「執行環境怎麼被宣告與調度」。要補齊上層，可以接著讀 AI Evals 入門，把成功條件從「程序有啟動」提升成「答案真的符合任務」。

v0.3.0 現在最該知道的四個邊界

1. 新版不是五月份的舊架構。v0.3.0 發布前的核心重構 commit已改用 Task／Workspace／Gateway、Redis Streams、controller 與 runner；舊文章談到的 Python harness、SQL event log 與 trajectory branching，不應直接套到 v0.3.0。
2. 預設 Redis manifest 不是生產級持久層。repository 內的 deploy/redis.yaml 沒配置 PVC 或 password；正式環境要另外處理耐久性、備援與存取控制。
3. 宣告存在不等於完整接線。v0.3.0 的 TaskSpec 沒有 modelRef；帶 goal 的 Workspace 路徑由 controller 查找固定名稱的 gemini-api-secret/GEMINI_API_KEY。預設 runner 的直接實作會 Git clone、建立 skills path，但未解析 skills registry，也未物化 MCP config。Task.spec.env 是可由 API 讀回的 literal value，不能拿來放 credential。不要因 examples 裡有 Model、MCP 或 skills 宣告，就把它當成 Task 已接線。
4. 這仍是早期專案。AX 使用 ax.io/v1alpha1，README 明說 stable 前可能大幅變動；底層 Agent Substrate 也標示 early development。鎖 tag、鎖 image digest、保存收據，才有可重現性。

Google AX 教學常見問題

Google AX 是 Google Cloud 的代管服務嗎？

不是本文所操作的形態。AX v0.3.0 是 Apache-2.0 授權的開源控制面，需要你部署；官方 GKE 路徑則提供底層 Agent Substrate 的安裝與環境整合。

我能在 Docker Desktop 直接跑 AX 嗎？

官方 quickstart 的目標環境是 Kubernetes 加可連線的 Agent Substrate，不是單一 docker run。本機 cluster 是否可行，仍取決於你能否完整提供 Substrate、registry 與網路前提。

suspend 會保留程式記憶體嗎？

不會。現行 runner 合約是保存 /workspace，resume 時建立新 container 與 process tree。需要續跑的狀態要先寫入檔案。

Workspace 是多個 Agent 共用的磁碟嗎？

不是。每個 Task 有自己的 durable /workspace；v0.3.0 預設 runner 直接完成的是 Git clone 與建立 skills path，MCP／skills registry 並未物化。若要跨 Agent 共享資料，仍應設計明確的外部儲存與授權。

Gateway 寫了 allowlist 就一定封住其他網站嗎？

不能只靠 YAML 判定。請同時確認 GatewayReady=True，並執行允許／拒絕探針；v0.3.0 的 port 欄位目前不能當成已生效的 port-level policy，而且已有人重現 hostname allowlist 連允許的 TLS host 也阻擋。允許與拒絕若沒有各自得到正確結果，就判定這版 Gateway 沒通過。

Task 顯示 Running 就代表 Agent 成功嗎？

不代表。要看 WorkspaceReady、GatewayReady、Ready，再檢查應用自己的輸出、exit status 與 evaluator；runner 存活和工作成功是兩件事。

要停止工作該用 suspend 還是 delete？

稍後還要從 Workspace 續跑就用 suspend；已匯出必要資料、要刪除 AX Task／actor 時才用 delete。v0.3.0 沒有另一個名為 cancel 的 Task 指令。

現在適合直接上 production 嗎？

更適合先做有版本鎖定、可回收、可觀測的 evaluation。若要進正式流量，至少要另補控制面認證、Redis 耐久與備援、network fail-closed、secret 管理、工作成功判定與升級回滾。

七個重點一次帶走

1. AX 是 Agent 執行控制面，不是替你思考的模型或 harness。
2. Task 管執行，Workspace 管可保存檔案，Gateway 管網路，Substrate 管沙盒生命週期。
3. Running 不等於 Ready，更不等於應用工作成功。
4. suspend／resume 保存 /workspace，不保存 RAM 或原 process tree。
5. 出站驗收要同時看 GatewayReady、允許探針與拒絕探針。
6. 停止後還要續跑用 suspend；已匯出必要資料、要刪除 Task／actor 時才用 delete。
7. v0.3.0 仍是 v1alpha1 早期設計；固定 AX tag、Substrate version／image digest、snapshot location 與驗收收據，比追 @latest 可靠。