Google AX 完整教學 2026：用 Kubernetes 思維跑 AI Agent——Task／Workspace／Gateway／Model 四大原語，沙箱隔離、網路白名單與暫停續跑一次搞懂

AX 是 Google 開源的宣告式 AI Agent 執行層（GitHub 7,382 stars、Apache 2.0、Go 撰寫）。它把 agent 當成一種新的工作負載，用四個 YAML 原語——Task、Workspace、Gateway、Model——一次解決沙箱隔離、環境預熱、網路白名單與 LLM 憑證管理，並支援暫停／續跑。 如果你用過 Kubernetes，ax 的用法會讓你覺得非常熟悉。

AI Agent 不是微服務，也不是 batch job

過去兩年，多數團隊把 agent 硬塞進現有的執行模型裡，結果兩邊都不合身。

• 塞進 serverless function：agent 跑到一半逾時，狀態全丟。
• 塞進 K8s Job / CronJob：每次啟動都要重新 clone repo、裝依賴、等環境熱起來。
• 塞進 一般 container：沒有網路邊界，agent 拿著你的 API key 能連到任何地方。
• 自己寫 queue + worker：光是要做「暫停後從原點續跑」就得造一整層狀態管理。

Google 在 2026 年 3 月開源的 AX，就是把這些問題當成「agent 是一種新型工作負載」重新設計的產物。它的定位很明確——不是 agent framework、不是 SDK，而是把 agent 跑起來的執行層（orchestration runtime）。

專案 README 的第一句話就講清楚了它想做的事：

AX is a high-throughput, declarative orchestrator to run billions of autonomous agent workloads in a cluster.

「用宣告式的方式，在叢集裡跑數十億個自主 agent 工作負載。」

它同時也放在 GitHub Trending 的榜首位置：一天內湧入 +2,324 stars，是目前社群關注度最高的 agent 基礎設施專案之一。

四大原語：AX 的整套心智模型

AX 的設計非常克制——只有四個 kind，全部是 ax.io/v1alpha1。

為什麼 Workspace 是最有價值的那個

README 裡有一段話點出了痛點：

Getting an agent to the point where it can start working is tedious.

Agent 要能開始做事之前，得先有資料來源（repo clone 到正確的 revision）、能呼叫的工具（MCP servers）、該帶的技能（skills）。傳統做法是每個 task 都重做一遍，每個框架都重新發明一次。

Workspace 把這件事變成「宣告一次、綁定多次」。更關鍵的是它可以帶一個 goal 欄位——一段自然語言的環境描述。首次啟動時，runner 會把這個 goal 交給一個 bootstrap agent 去把環境準備好（例如裝 toolchain、裝依賴），task 自己的指令則在環境就緒後才開始跑。

Task 刻意做得很小

AX 文件裡這段值得抄下來：

• 一個 agent 的生命週期裡會規劃、委派、重試、fan-out。
• AX 不試圖去 model 這個形狀。
• 它只給你一個「很便宜就能建立、隔離、暫停、丟掉」的原語。
• 一個 task 可以是整個工作，也可以是 agent 拆解問題後長出來的一整棵 task 樹的根。

每個節點拿到一樣的沙箱、一樣的生命週期、一樣的工具鏈。

Gateway：把 agent 的網路權限關進籠子

spec:
  listeners:
    - name: grpc
      port: 8494
      protocol: gRPC
  egress:
    allowlist:
      hosts:
        - host: "*"      # 允許所有 443；正式環境務必收緊
          port: 443

把 host 從 * 改成明確的 LLM provider 與 Git host，就等於切斷了 agent 大部分外洩資料的路徑。這種「預設就要你填 allowlist」的設計，是 AX 跟大部分「跑起來再說」方案最大的差異。

架構：為什麼狀態放 Redis，不放 etcd

AX 的架構決策有一個很工程師的答案。如果把數百萬個短命 task 存成 Kubernetes CRD，會把 etcd 推過舒適圈——etcd 的儲存上限是「個位數 GB」等級，寫入速率會成為瓶頸，控制平面會開始降級。

所以 AX 把狀態放在 Redis，並用 Redis Streams 當成 API server 跟可水平擴充的 controller 池之間的工作佇列。

                      ax apply -f task.yaml
                                |
                                v
                            ax-server          <- 無狀態 gRPC API + /healthz
                                |
                     寫入 store、發布事件
                                v
                              Redis         <- Task Hash + Event Streams + PubSub
                                |
                      XREADGROUP（Streams）
                                v
                          ax-controller     <- 可水平擴充的 worker
                                |
                        gRPC (Control API)
                                v
                         Agent Substrate
                ┌───────────────────────────────┐
                │ - Atespace Provisioning       │
                │ - Actor Creation & Activation │
                │ - Worker Assignment           │
                │ - Egress Policy Filtering     │
                └───────────────────────────────┘

對應的四個執行檔：

控制平面提供 ax.v1alpha1.AX gRPC 服務，健康檢查是純 HTTP：GET /healthz 回 200。

底層：Agent Substrate 才是真正扛壓的那層

AX 本身不負責隔離，它把這件事交給 Agent Substrate（同樣是開源專案，也在今日 GitHub Trending 上）。Substrate 的定位是「secure-by-default 的 agent 執行 runtime」，官方數據相當有企圖心：

Substrate 的關鍵能力是「Actor Teleport」——把有狀態的 actor 連同記憶體與檔案系統狀態一起快照、暫停、之後在任何可用 worker 上以不到一秒的時間復活。這正是 ax suspend / ax resume 能成立的底層原因。

它也強調框架無關：因為是在 kernel 層管理標準 OCI container，官方文件明確列出可承載 ADK、LangChain、Claude Code、Codex、Antigravity，以及把 MCP server 本身當成 actor 跑。目前採用者包括 CNCF Sandbox 專案 kagent。

實戰：從零到第一個任務

步驟 1：安裝 CLI

go install github.com/google/ax/cmd/ax@latest

執行檔會落在 $(go env GOPATH)/bin，記得加進 PATH。

步驟 2：部署控制平面

前置需求：一個 Kubernetes 叢集、ko（brew install ko）、一個叢集拉得到的 container registry，以及可連線的 Agent Substrate Control API（叢集內預設 api.ate-system.svc.cluster.local:443）。

make deploy AX_IMAGE_REPO=<your-registry>

這會依序部署 Redis，再用 ko 建置並部署控制平面映像，全部落在 ax-system namespace。

步驟 3：寫一份完整的 task.yaml

AX 的漂亮之處是四種 kind 可以放在同一個多文件 YAML 裡：

apiVersion: ax.io/v1alpha1
kind: Workspace
metadata:
  name: golang
spec:
  git:
    - repo: https://github.com/golang/go.git
      branch: "my-fix"
---
apiVersion: ax.io/v1alpha1
kind: Gateway
metadata:
  name: default-gateway
spec:
  egress:
    allowlist:
      hosts:
        - host: "api.anthropic.com"
          port: 443
        - host: "github.com"
          port: 443
---
apiVersion: ax.io/v1alpha1
kind: Model
metadata:
  name: claude-model
spec:
  provider: anthropic
  model: claude-opus-5-5
  secretKey:
    name: anthropic-api-secret
    key: ANTHROPIC_API_KEY
  parameters:
    maxTokens: 16000
---
apiVersion: ax.io/v1alpha1
kind: Task
metadata:
  name: test
spec:
  image: "ghcr.io/my-org/my-agent-image"
  command: ["python", "agent.py"]
  resources:
    requests:
      cpu: "500m"
      memory: "1Gi"
    limits:
      cpu: "2"
      memory: "4Gi"
  workspaces:
    - name: golang
      path: "/workspace"
      goal: "Ensure the Go toolchain is available and built from source"
  gateway:
    name: default-gateway
  debug: true   # 開啟 guest services，讓 ax ssh 進得去

API key 走 Kubernetes secret，不要寫進 manifest：

kubectl create secret generic anthropic-api-secret \
  --from-literal=ANTHROPIC_API_KEY="sk-ant-..."

步驟 4：跑起來、看它做事

ax apply -f task.yaml
ax get tasks
# NAME      ATESPACE   PHASE     ACTOR      WORKER-IP     AGE
# test      default    Running   test       10.20.3.67    1m

ax watch task test                # 即時串流 phase 與 condition 變化
ax ssh test -- ls -al /workspace  # 進沙箱看 agent 在做什麼
ax suspend task test              # checkpoint 後暫停
ax resume task test               # 從原點續跑

CLI 速查表

ax 刻意做成 kubectl 的形狀：

它跟著 kube context 走，也能跟 kubectx 無縫搭配：

kubectx staging-cluster && ax get tasks
kubectx prod-cluster    && ax get tasks
ax --context=dev-cluster get tasks   # 不切換 context 直接指定

全域旗標有 -a/--atespace（資源作用域，預設 default）、-n/--namespace（預設 ax-system）、--context、--server。

沙箱裡面長什麼樣子

每個 task container 都以 ax-task-runner 當 PID 1。開機流程是：

1. 載入 Task 與所有綁定的 Workspace spec。
2. 在 port 80 啟動 metadata 與 guest management daemon。
3. 首次啟動時依綁定順序準備每個 workspace：clone git repo、設定 skills 路徑；若有 goal，交給 bootstrap agent 完成環境設定。這一步需要容器內有 GEMINI_API_KEY，預設給 10 分鐘（可用 AX_BOOTSTRAP_TIMEOUT 調整）。
4. 以第一個 workspace 為工作目錄，啟動 spec.command 並持續監督。

runner 即使指令結束也會留在 PID 1，所以 metadata server 持續回應、ax ssh 還進得去。停止或暫停沙箱時，runner 會對指令的 process group 送 SIGTERM、等 10 秒，然後強制 kill。

Agent 可以完全不用 SDK 就自我檢查，只要打這些端點（同一 port 同時支援 HTTP/1.1 與 h2c）：

# 從 task 內部：
curl -s "$AX_METADATA_URL/metadata/v1alpha1/ax/task"

Task 的生命週期用 phase（Running、Suspended、Failed、Terminating）加 condition 描述，其中 Ready 是你最該 wait 的那一個（WorkspaceReady 為 True 且 task 正在跑）。掛 Ready 而不是靠 sleep，是寫 agent pipeline 的第一條紀律。

跟其他方案怎麼選

一句話總結差異：smolvm 解決「這一段程式碼能不能安全跑」，AX 解決「一萬個 agent 同時跑、中途斷掉怎麼辦」。 兩者不是替代關係，很多架構會同時用到。

限制與風險（務必先讀）

AX 與 Agent Substrate 都還在早期階段，官方文件把話講得很白：

• AX 自己的警告：「我們仍在積極調整核心概念、協定與規格，穩定版之前很可能會有重大 breaking changes。」
• API 是 v1alpha1，任何欄位都可能改。
• Substrate 明確標示「尚未準備好用於生產環境」，且「不是 Google 官方支援的產品」，也不在 Google 開源漏洞獎勵計畫範圍內。
• 必需 Kubernetes，加上 ko、registry 與一個可連線的 Substrate 控制平面——這是自架門檻，不是 docker run 等級的體驗。
• bootstrap agent 需要 GEMINI_API_KEY，而且預設只給 10 分鐘；環境複雜時容易卡在 WorkspaceReady 不成立。
• ax ssh 需要 spec.debug: true，而開啟後沙箱內就允許任意行程執行與檔案讀寫——正式環境請記得關掉。
• 成本會失控。README 自己說 agent「can burn money in a loop if nobody is watching」；務必把 Model.parameters、effort、resources limits 設好，並監控 token 用量。

什麼時候該用 AX

• 你要跑 fan-out 型工作：一個任務會拆出十個、百個子任務，每個都需要同樣的環境。
• 你需要 中斷續跑：agent 跑 6 小時，中間機器重啟不能把進度歸零。
• 你在做 agent 平台而不是單一 agent：需要集中管理憑證、統一網路政策、統一可觀測性。
• 你在跑 RL／評測環境：需要大量暫時性、可丟棄、有狀態的沙箱。

反過來說，如果只是「本機跑一支 agent 腳本」，ax 的部署成本完全不划算——那時候 smolvm 或直接 Docker 就好。

延伸閱讀

• smolvm 完整教學：用硬體隔離 VM 安全執行不受信任的 Python／JavaScript 程式碼 — 單機版的沙箱解答，跟 AX 是互補而非競爭的兩層。
• Render Workflows 完整解析：Durable AI Workflow 讓 AI Agent 永不超時 — 不想自架 K8s 時，託管式的持久化工作流長什麼樣。
• Docker 完整教學 2026 — AX 的 Task 就是 OCI container，先把 Docker 的基本盤打好。
• Herdr 教學：一個終端機管理整群 AI Agent — 開發者本機端的多 agent 管理，跟 AX 的叢集端正好是一組對照。
• Roundtable：多 Agent 任務工作區 — 多 agent 協作的另一種架構路線。
• Tailscale 完整教學 2026 — 自架叢集要對外時的安全連線基礎。

原始來源

• GitHub：google/ax（README、docs/concepts.md、docs/manifests.md、docs/sandbox.md、DESIGN.md）
• GitHub：agent-substrate/substrate
• Google Cloud 官方部落格：Agent Executor（AX 前身）公告
• GitHub Trending（2026-09-22 快照：單日 +2,324 stars）

本文所有規格、指令與 YAML 皆取自官方 repository 文件；AX 目前為 v1alpha1、Substrate 為早期開發階段，實際部署前請以官方最新文件為準，並留意 breaking changes。