मुख्य कंटेंट तक स्किप करें

AX (Agent Executor): Google's Open Agent Runtime, Explained for Builders (2026)

उन्नत
What you'll learn
  • Place AX correctly in Google's stack: Kubernetes, Agent Sandbox, Agent Substrate, AX, then your harness
  • Read the four AX resources (Task, Workspace, Gateway, Model) and know what each one buys you
  • Explain what really survives an AX suspend/resume, what does not, and what your runner image must do about it
  • Run a first Task end to end with ax apply, ax watch and ax ssh, and know the three debugging traps
  • Decide when a self-hosted runtime like AX beats Claude Managed Agents or the OpenAI Agents API, and when it does not

On the night of September 20, 2026, AX: Google's open agentic orchestrator went to the top of Hacker News with 507 points and 222 comments. Most of those comments were people asking what it is for. That is a fair question, because the project has been public since May 20, 2026 (v0.1.0) and has changed shape twice since, so most of the blog posts you will find describe a CLI that no longer exists.

Here is the short version. AX is not a model, not an agent framework and not a hosted service. It is a Kubernetes-style control plane, with a kubectl-shaped CLI, that takes a declared agent Task, gives it a sandbox, clones its repos, wires its MCP servers and skills, fences its network, and can freeze it to a snapshot and thaw it later on any free worker. It sits under whatever harness you already use, whether that is Claude Code, Google's ADK, LangChain, or a Python loop you wrote yourself.

The stack, bottom to top​

The Google announcements use four names that are easy to confuse. They are four layers, and AX is the top one.

LayerWhat it isStatus (Sep 2026)Numbers Google publishes
Kubernetes / GKEThe cluster——
Agent Sandbox (kubernetes-sigs/agent-sandbox)A Sandbox CRD: gVisor-isolated pods (Kata pluggable), warm pools, pod snapshotsGA on GKE since May 21, 2026300 sandbox allocations/s per cluster; sub-second start, 90% within 200 ms
Agent Substrate (agent-substrate/substrate)A minimal control plane that multiplexes many idle actors onto few warm workers by snapshotting RAM + files to object storageOpen source, early, "not an officially supported Google product"; managed flavour on GKE in evaluation~250 stateful actors on 8 pods; "10x higher density" than plain containers; sub-second activation
AX (google/ax)Declarative Tasks/Workspaces/Gateways/Models + CLI on top of Substratev0.3.0, ax.io/v1alpha1, Apache-2.0, 4.3k stars"billions of tasks per cluster" (marketing claim, not a benchmark)
Your harnessClaude Code, ADK, LangChain, A2A agents, your own loop——

Two things the table hides. First, Substrate is where the interesting engineering lives (the snapshot and teleport machinery); AX is the ergonomic layer. Second, Substrate lives in its own GitHub org, not under google/, which several HN commenters flagged as a signal about how official any of this is. Treat the whole thing as a serious but pre-1.0 open-source project from a Google team, not a product with an SLA.

The four primitives​

Everything in AX is a YAML resource in an atespace (Substrate's tenancy unit; default unless you say otherwise). You ax apply -f them exactly as you would with kubectl.

Task: the unit of isolated execution​

apiVersion: ax.io/v1alpha1
kind: Task
metadata:
  name: fix-flaky-test
spec:
  image: "ghcr.io/my-org/my-agent-image"
  command: ["my-agent", "--goal", "fix the flaky test"]
  env:
    - name: ENVIRONMENT
      value: "staging"
  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

A Task is deliberately small. The concepts doc describes agents creating many Tasks over their lifetime rather than living inside one long process. Three fields matter more than they look:

  • workspaces[].goal is a plain-English description of the environment the Task needs. AX's "generative" setup tries to complete the workspace from that sentence (install a toolchain, fetch dependencies). It is the one place where a model is in the loop before your agent starts.
  • debug: true is the only way to get ax ssh into the sandbox. Without it the guest services are not exposed and the CLI refuses to connect.
  • gateway is optional in the schema, but if you leave it out you are relying on whatever the substrate's default egress policy is. Declare one.

Workspace: git + MCP + skills, materialised before the agent starts​

apiVersion: ax.io/v1alpha1
kind: Workspace
metadata:
  name: golang
spec:
  git:
    - name: origin
      repo: "https://github.com/golang/go.git"
      branch: "my-fix"
  mcp:
    registries:
      - provider: google
        query: "mcp.tags:build"
    servers:
      - name: git-tools
        endpoint: "http://git-mcp.default.svc.cluster.local:8080"
  skills:
    registries:
      - provider: google
        query: "skills.tags:nodejs"
    path: "/.agents/skills"

This is the resource that makes AX more than "Kubernetes Jobs with a sandbox". A Workspace pre-clones repositories, resolves MCP servers (by explicit endpoint or by a registry query), and drops skill packages into a path. Note the default skills path: /.agents/skills is the same directory convention the cross-agent SKILL.md standard uses for Codex, Cursor and Gemini CLI, so a Workspace can hand the same skills to whichever harness runs inside the Task.

Gateway: listeners in, allowlist out​

apiVersion: ax.io/v1alpha1
kind: Gateway
metadata:
  name: default-gateway
spec:
  listeners:
    - name: http
      port: 8080
      protocol: HTTP
  egress:
    allowlist:
      hosts:
        - host: "api.anthropic.com"
          port: 443

The reference manifest ships with host: "*" on 443, which is an allow-everything policy. Change it. Egress allowlists are the single most effective control against the exfiltration patterns in our prompt-injection and what your agent uploads pages, and AX gives you a declarative place to put them. Listeners are how a Task exposes a port (for an A2A endpoint, a dev server, a debug UI); ax tunnel forwards them to your laptop.

Model: provider + model ID + a Kubernetes secret​

apiVersion: ax.io/v1alpha1
kind: Model
metadata:
  name: claude-model
spec:
  provider: anthropic
  model: claude-opus-5
  secretKey:
    name: anthropic-api-secret
    key: ANTHROPIC_API_KEY
  parameters:
    maxTokens: 16000
    temperature: 0.9

The reference docs show google and anthropic providers. The credential is a reference to a Kubernetes Secret, so the manifest never contains the key and the key is rotated where you already rotate secrets. AX is not Gemini-only; the runner docs do mention that GEMINI_API_KEY is injected automatically when the atespace has Gemini credentials, which is the one place Google's own model gets a shortcut.

What actually happens inside a Task​

This is the part no launch post covers, and it is where you will lose an afternoon if you skip it. From docs/runner.md:

  1. The entrypoint is fixed. Whatever spec.image you supply, the controller starts the container with /usr/local/bin/ax-task-runner as PID 1. Your image must contain an executable at that path (a symlink is fine). The published base image is gcr.io/ax-substrate/ate-images/ax-task-runner, and extending it is the normal route.
  2. Your command arrives via environment, not argv. The runner receives AX_TASK_YAML (the whole Task, including status) and AX_WORKSPACES_YAML (every bound Workspace as multi-document YAML), parses spec.command out of the Task, and starts it as a child process with the first workspace as the working directory. It also exposes AX_METADATA_URL, a small local HTTP metadata server.
  3. Bootstrap has a 10-minute clock. Workspace materialisation (clones, MCP resolution, skill install, the generative goal step) must finish within AX_BOOTSTRAP_TIMEOUT, default 10 minutes. Large monorepos on a cold worker can blow through it.
  4. The control plane does not read your exit code. The runner logs the command's exit status but stays up as PID 1 whether or not your agent is still running. So a Task in phase Running does not mean your agent is alive. Write your own completion signal (a file in the workspace, a message to your own queue, a Task deletion from inside) and watch that.
  5. Shutdown is SIGTERM, 10 seconds, SIGKILL. The runner forwards SIGTERM to the command's process group and waits a bounded grace period. Flush state early.

Suspend and resume: what survives​

Suspend/resume is the feature that justifies the whole stack. Agents spend most of their wall-clock waiting on a model, a tool, or a human, and Substrate's bet is that an idle agent should cost storage, not a warm pod.

ax suspend task fix-flaky-test   # Ready=False, snapshot taken
ax resume  task fix-flaky-test   # restored on any free worker

What the docs say survives, and what does not:

Survives a suspend/resumeDoes not survive
The /workspace volume (files, clones, build artefacts)The process tree: your agent restarts from its entrypoint
Substrate-level actor memory snapshot (RAM + files, at the Substrate layer)Open network connections (GKE docs: agents must handle reconnection)
Task spec and statusAnything written outside the workspace volume

The runner doc is explicit about the consequence: after resume, the runner sees the same files but a new process tree, so it must track whether workspace setup already ran (marker files are the suggested mechanism) or it will re-clone every repo. If your agent keeps its plan or its conversation only in process memory, a resume loses it; keep the transcript on disk in the workspace. This is the same lesson as our long-running agent harnesses page, enforced by the infrastructure.

Guided walkthrough1 of 6
  1. go install github.com/google/ax/cmd/ax@latest. AX follows your active kubeconfig context (kubectx works) and defaults to namespace ax-system and atespace default. For a laptop, the Agent Substrate repo's hack/ scripts stand up a kind cluster with the substrate installed; AX's control plane is then deployed with make deploy AX_IMAGE_REPO=<your registry>, which needs ko and a registry you can push to.

Have Claude draft the manifests for an agent you already run

I run an agent as a container image ghcr.io/acme/triage-agent:1.4. Its entrypoint is "triage --repo REPO_PATH --model MODEL_ID". It needs: the repo github.com/acme/backend on branch main, an MCP server for Linear reachable at http://linear-mcp.tools.svc.cluster.local:8080, outbound access only to api.anthropic.com:443 and github.com:443, and the Anthropic key from the Kubernetes Secret "anthropic-api-secret" (key ANTHROPIC_API_KEY).

Write the four google/ax v1alpha1 manifests (Model, Gateway, Workspace, Task) for this, following docs/manifests.md in the repo. Then write a Dockerfile that extends the published ax-task-runner base image and installs my agent WITHOUT changing the entrypoint. Finally, list what I must change in the agent so that (a) it treats the first workspace as its working directory, (b) it survives a suspend/resume by keeping its plan and transcript on disk under /workspace and using a marker file to skip re-setup, and (c) it signals completion in a way the AX control plane can't (it ignores exit codes).

Where AX sits next to the hosted agent loops​

The most-upvoted question in the HN thread was "what is the benefit over the OpenAI Agents API?" The honest answer is that they are different layers.

AX + Agent SubstrateClaude Managed AgentsOpenAI Agents APICloudflare's isolate runtime
Who runs the loopYou (any harness in the container)Anthropic (the harness is theirs)OpenAI (the Codex harness)You, on Workers/Durable Objects
Where it runsYour Kubernetes cluster, any cloud or on-premAnthropic's infrastructureOpenAI's, or a self-hosted sandboxCloudflare's edge
IsolationgVisor / Cloud Hypervisor sandbox per TaskAnthropic-managed environmentHosted or self-hosted sandboxV8 isolate, container on demand
Model choiceAny provider you put in a Model resourceClaudeOpenAI modelsAny (via API)
Idle cost modelSnapshot to storage, resume on demandSession-based billingSession-based billingIsolates hibernate
You ownCluster, upgrades, secrets, egress policyAn API keyAn API keyA Workers account

Pick AX when you need data sovereignty, want to run more than one vendor's model behind one policy, already operate Kubernetes, or want agents that can sleep for days without paying for compute. Pick a hosted loop when you want a working harness today and do not want to own a cluster. Many teams will do both: a hosted loop for interactive sessions, AX-style infrastructure for fleets of background Tasks.

Gotchas and the pushback worth listening to​

  • The June-era docs describe a different tool. The May preview exposed a conversation-centric CLI (ax exec --conversation … --resume, ax fork for trajectory branching, an AgentService protocol with ADK and A2A bridges). The September README's command reference is resource-centric: apply, get, describe, watch, suspend, resume, delete, ssh, tunnel, ctx. If a tutorial shows ax fork, it is from before the redesign. The five headline capabilities from the May blog (durable execution, isolation, single-writer session consistency, connection recovery, trajectory branching) are still the stated goals; how much of the branching story survives in the resource model is not documented as of this writing.
  • v1alpha1 means it. The README warns of major breaking changes before a stable release. Pin the CLI version and the runner image digest, and re-read docs/manifests.md on every upgrade.
  • Kubernetes is not optional. The most-repeated complaint in the thread. The Substrate quickstart runs on kind, so you can try it on a laptop, but production means a real cluster. If you do not already run Kubernetes, AX is not the reason to start.
  • Managed GKE Agent Substrate has hard requirements. GKE 1.37+ (1.36 with beta flags), Workload Identity, beta APIs enabled at cluster creation, uniform machine types per ActorTemplate (no E2), a Cloud Storage bucket for snapshots, gVisor or Cloud Hypervisor isolation, and no GPU passthrough. Production use is behind an allowlisted private GA program.
  • Egress defaults are permissive in the examples. host: "*" on 443 lets an agent reach any HTTPS endpoint. That is the opposite of what you want for a Task that reads untrusted repos. Follow the same rules as securing local and hybrid agents.
  • Two projects, two orgs, one disclaimer. AX is under google/; Substrate is under agent-substrate/ and states it is not an officially supported Google product. Neither is eligible for Google's OSS vulnerability rewards program. Budget for reading source when something breaks.
AX vocabulary
कार्ड पलटने के लिए Enter या Space दबाएँ। कार्ड बदलने के लिए बाएँ और दाएँ तीर कुंजियों का उपयोग करें।शब्द दिखाया गया।
1 / 8

Check yourself

0/6
  1. You supply spec.image with your own ENTRYPOINT. What does AX run as PID 1?
  2. Your agent exits with status 1. What does ax get task show?
  3. After ax resume, your agent re-clones every repository. Why?
  4. ax ssh refuses to connect to your Task. Most likely cause?
  5. Which layer actually implements snapshotting idle agents to storage and restoring them on a warm worker?
  6. A tutorial from June 2026 tells you to run ax fork to branch a trajectory. What should you expect?

Sources & further reading​

Next​