Passa al contenuto principale

AX (Agent Executor): il runtime open per agenti di Google, spiegato per chi costruisce (set 2026)

Avanzato
What you'll learn
  • Collocare AX correttamente nello stack di Google: Kubernetes, Agent Sandbox, Agent Substrate, AX, poi il tuo harness
  • Leggere le quattro risorse AX (Task, Workspace, Gateway, Model) e sapere cosa ti dà ciascuna
  • Spiegare cosa sopravvive davvero a un suspend/resume di AX, cosa no, e cosa deve fare la tua immagine runner al riguardo
  • Eseguire un primo Task end to end con ax apply, ax watch e ax ssh, e conoscere le tre trappole di debugging
  • Decidere quando un runtime self-hosted come AX batte Claude Managed Agents o la OpenAI Agents API, e quando no

La notte del 20 settembre 2026, AX: l'orchestratore agentico open di Google è salito in cima a Hacker News con 507 punti e 222 commenti. La maggior parte di quei commenti erano persone che chiedevano a cosa serve. È una domanda legittima, perché il progetto è pubblico dal 20 maggio 2026 (v0.1.0) e da allora ha cambiato forma due volte, quindi la maggior parte dei blog post che troverai descrive una CLI che non esiste più.

Ecco la versione breve. AX non è un modello, non è un framework per agenti e non è un servizio hosted. È un control plane in stile Kubernetes, con una CLI a forma di kubectl, che prende un Task di agente dichiarato, gli assegna una sandbox, clona i suoi repo, collega i suoi server MCP e le sue skill, recinta la sua rete, e può congelarlo in uno snapshot per scongelarlo più tardi su qualsiasi worker libero. Sta sotto qualunque harness tu usi già, che sia Claude Code, l'ADK di Google, LangChain o un loop Python scritto da te.

Lo stack, dal basso verso l'alto​

Gli annunci di Google usano quattro nomi facili da confondere. Sono quattro layer, e AX è quello in cima.

LayerCos'èStato (set 2026)Numeri pubblicati da Google
Kubernetes / GKEIl cluster——
Agent Sandbox (kubernetes-sigs/agent-sandbox)Una CRD Sandbox: pod isolati con gVisor (Kata pluggable), warm pool, snapshot dei podGA su GKE dal 21 maggio 2026300 allocazioni di sandbox/s per cluster; avvio sotto il secondo, 90% entro 200 ms
Agent Substrate (agent-substrate/substrate)Un control plane minimale che multiplexa molti actor inattivi su pochi worker caldi facendo snapshot di RAM + file verso l'object storageOpen source, embrionale, "non un prodotto Google ufficialmente supportato"; versione managed su GKE in valutazione~250 actor stateful su 8 pod; "densità 10x" rispetto ai container semplici; attivazione sotto il secondo
AX (google/ax)Task/Workspace/Gateway/Model dichiarativi + CLI sopra Substratev0.3.0, ax.io/v1alpha1, Apache-2.0, 4,3k stelle"miliardi di task per cluster" (claim di marketing, non un benchmark)
Il tuo harnessClaude Code, ADK, LangChain, agenti A2A, il tuo loop——

Due cose che la tabella nasconde. Primo, Substrate è dove vive l'ingegneria interessante (la macchina di snapshot e teleport); AX è il layer ergonomico. Secondo, Substrate vive in una org GitHub tutta sua, non sotto google/, cosa che diversi commentatori su HN hanno segnalato come un indizio su quanto tutto questo sia ufficiale. Tratta l'insieme come un progetto open source serio ma pre-1.0 di un team Google, non come un prodotto con uno SLA.

Le quattro primitive​

Tutto in AX è una risorsa YAML dentro un atespace (l'unità di tenancy di Substrate; default se non specifichi altro). Le applichi con ax apply -f esattamente come faresti con kubectl.

Task: l'unità di esecuzione isolata​

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

Un Task è deliberatamente piccolo. Il documento sui concetti descrive agenti che creano molti Task nel corso della loro vita, invece di vivere dentro un unico processo lungo. Tre campi contano più di quanto sembri:

  • workspaces[].goal è una descrizione in linguaggio naturale dell'ambiente di cui il Task ha bisogno. Il setup "generativo" di AX prova a completare il workspace partendo da quella frase (installare una toolchain, scaricare le dipendenze). È l'unico punto in cui un modello è nel loop prima che il tuo agente parta.
  • debug: true è l'unico modo per entrare nella sandbox con ax ssh. Senza, i guest service non vengono esposti e la CLI rifiuta di connettersi.
  • gateway è opzionale nello schema, ma se lo ometti ti stai affidando a qualunque sia la policy di egress di default del substrate. Dichiarane uno.

Workspace: git + MCP + skill, materializzati prima che l'agente parta​

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"

Questa è la risorsa che rende AX qualcosa di più di "Job Kubernetes con una sandbox". Un Workspace pre-clona i repository, risolve i server MCP (per endpoint esplicito o per query a un registry) e deposita i pacchetti di skill in un path. Nota il path di default delle skill: /.agents/skills è la stessa convenzione di directory che lo standard SKILL.md cross-agent usa per Codex, Cursor e Gemini CLI, quindi un Workspace può passare le stesse skill a qualunque harness giri dentro il Task.

Gateway: listener in ingresso, allowlist in uscita​

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

Il manifest di riferimento arriva con host: "*" sulla 443, che è una policy allow-everything. Cambiala. Le allowlist di egress sono il singolo controllo più efficace contro i pattern di esfiltrazione descritti nelle nostre pagine su prompt injection e cosa carica il tuo agente, e AX ti dà un posto dichiarativo dove metterle. I listener sono il modo in cui un Task espone una porta (per un endpoint A2A, un dev server, una UI di debug); ax tunnel li inoltra sul tuo laptop.

Model: provider + ID del modello + un Secret Kubernetes​

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

La documentazione di riferimento mostra i provider google e anthropic. La credenziale è un riferimento a un Secret Kubernetes, quindi il manifest non contiene mai la chiave e la chiave viene ruotata dove già ruoti i secret. AX non è solo-Gemini; la documentazione del runner però segnala che GEMINI_API_KEY viene iniettata automaticamente quando l'atespace ha credenziali Gemini, che è l'unico punto in cui il modello di casa Google ha una scorciatoia.

Cosa succede davvero dentro un Task​

Questa è la parte che nessun post di lancio copre, ed è dove perderai un pomeriggio se la salti. Da docs/runner.md:

  1. L'entrypoint è fisso. Qualunque spec.image tu fornisca, il controller avvia il container con /usr/local/bin/ax-task-runner come PID 1. La tua immagine deve contenere un eseguibile a quel path (un symlink va bene). L'immagine base pubblicata è gcr.io/ax-substrate/ate-images/ax-task-runner, ed estenderla è la strada normale.
  2. Il tuo comando arriva via environment, non via argv. Il runner riceve AX_TASK_YAML (l'intero Task, status incluso) e AX_WORKSPACES_YAML (ogni Workspace collegato, come YAML multi-documento), estrae spec.command dal Task e lo avvia come processo figlio con il primo workspace come working directory. Espone anche AX_METADATA_URL, un piccolo server HTTP locale di metadati.
  3. Il bootstrap ha un orologio da 10 minuti. La materializzazione del Workspace (clone, risoluzione MCP, installazione delle skill, lo step generativo del goal) deve completarsi entro AX_BOOTSTRAP_TIMEOUT, default 10 minuti. I monorepo grandi su un worker freddo possono sforarlo.
  4. Il control plane non legge il tuo exit code. Il runner logga lo stato di uscita del comando ma resta su come PID 1, che il tuo agente sia ancora in esecuzione o no. Quindi un Task in fase Running non significa che il tuo agente sia vivo. Scrivi un tuo segnale di completamento (un file nel workspace, un messaggio sulla tua coda, una cancellazione del Task dall'interno) e osserva quello.
  5. Lo shutdown è SIGTERM, 10 secondi, SIGKILL. Il runner inoltra SIGTERM al process group del comando e attende un periodo di grazia limitato. Scrivi lo stato su disco per tempo.

Suspend e resume: cosa sopravvive​

Suspend/resume è la funzionalità che giustifica l'intero stack. Gli agenti passano la maggior parte del loro tempo reale ad aspettare un modello, un tool o un umano, e la scommessa di Substrate è che un agente inattivo dovrebbe costare storage, non un pod caldo.

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

Cosa dicono i doc che sopravvive, e cosa no:

Sopravvive a un suspend/resumeNon sopravvive
Il volume /workspace (file, clone, artefatti di build)L'albero dei processi: il tuo agente riparte dal suo entrypoint
Lo snapshot di memoria dell'actor a livello Substrate (RAM + file, nel layer Substrate)Le connessioni di rete aperte (doc GKE: gli agenti devono gestire la riconnessione)
Spec e status del TaskQualsiasi cosa scritta fuori dal volume del workspace

Il doc del runner è esplicito sulla conseguenza: dopo il resume, il runner vede gli stessi file ma un albero di processi nuovo, quindi deve tenere traccia del fatto che il setup del workspace sia già stato eseguito (i marker file sono il meccanismo suggerito), altrimenti ri-clonerà ogni repo. Se il tuo agente tiene il suo piano o la sua conversazione solo in memoria di processo, un resume li perde; tieni la trascrizione su disco nel workspace. È la stessa lezione della nostra pagina sugli harness per agenti long-running, imposta dall'infrastruttura.

Guided walkthrough1 of 6
  1. go install github.com/google/ax/cmd/ax@latest. AX segue il contesto kubeconfig attivo (kubectx funziona) e usa come default il namespace ax-system e l'atespace default. Per un laptop, gli script hack/ del repo Agent Substrate tirano su un cluster kind con il substrate installato; il control plane di AX si deploya poi con make deploy AX_IMAGE_REPO=<your registry>, che richiede ko e un registry su cui puoi fare push.

Fai preparare a Claude i manifest per un agente che già esegui

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).

Dove si colloca AX rispetto ai loop di agenti hosted​

La domanda più votata nel thread HN era "qual è il vantaggio rispetto alla OpenAI Agents API?". La risposta onesta è che sono layer diversi.

AX + Agent SubstrateClaude Managed AgentsOpenAI Agents APIIl runtime a isolate di Cloudflare
Chi esegue il loopTu (qualsiasi harness nel container)Anthropic (l'harness è il loro)OpenAI (l'harness Codex)Tu, su Workers/Durable Objects
Dove giraIl tuo cluster Kubernetes, qualsiasi cloud o on-premL'infrastruttura di AnthropicQuella di OpenAI, o una sandbox self-hostedL'edge di Cloudflare
IsolamentoSandbox gVisor / Cloud Hypervisor per TaskAmbiente gestito da AnthropicSandbox hosted o self-hostedIsolate V8, container on demand
Scelta del modelloQualsiasi provider tu metta in una risorsa ModelClaudeModelli OpenAIQualsiasi (via API)
Modello di costo a riposoSnapshot su storage, resume on demandFatturazione per sessioneFatturazione per sessioneGli isolate vanno in ibernazione
Cosa possiediCluster, upgrade, secret, policy di egressUna chiave APIUna chiave APIUn account Workers

Scegli AX quando hai bisogno di sovranità dei dati, vuoi eseguire i modelli di più di un vendor dietro un'unica policy, gestisci già Kubernetes, o vuoi agenti che possano dormire per giorni senza pagare compute. Scegli un loop hosted quando vuoi un harness funzionante oggi e non vuoi possedere un cluster. Molti team faranno entrambe le cose: un loop hosted per le sessioni interattive, infrastruttura in stile AX per flotte di Task in background.

Trappole e le critiche che vale la pena ascoltare​

  • La documentazione di giugno descrive un tool diverso. La preview di maggio esponeva una CLI centrata sulle conversazioni (ax exec --conversation … --resume, ax fork per il branching delle traiettorie, un protocollo AgentService con bridge ADK e A2A). Il riferimento dei comandi nel README di settembre è centrato sulle risorse: apply, get, describe, watch, suspend, resume, delete, ssh, tunnel, ctx. Se un tutorial mostra ax fork, è di prima del redesign. Le cinque capacità di punta del blog di maggio (esecuzione durevole, isolamento, consistenza di sessione single-writer, recupero delle connessioni, branching delle traiettorie) restano gli obiettivi dichiarati; quanto della storia del branching sopravviva nel modello a risorse non è documentato al momento in cui scriviamo.
  • v1alpha1 fa sul serio. Il README avverte di breaking change importanti prima di una release stabile. Fissa la versione della CLI e il digest dell'immagine runner, e rileggi docs/manifests.md a ogni upgrade.
  • Kubernetes non è opzionale. La lamentela più ripetuta nel thread. Il quickstart di Substrate gira su kind, quindi puoi provarlo su un laptop, ma produzione significa un cluster vero. Se non gestisci già Kubernetes, AX non è il motivo per iniziare.
  • Il GKE Agent Substrate managed ha requisiti stringenti. GKE 1.37+ (1.36 con flag beta), Workload Identity, API beta abilitate alla creazione del cluster, tipi di macchina uniformi per ActorTemplate (niente E2), un bucket Cloud Storage per gli snapshot, isolamento gVisor o Cloud Hypervisor, e nessun passthrough GPU. L'uso in produzione è dietro un programma GA privato su allowlist.
  • I default di egress negli esempi sono permissivi. host: "*" sulla 443 permette a un agente di raggiungere qualsiasi endpoint HTTPS. È l'opposto di ciò che vuoi per un Task che legge repo non fidati. Segui le stesse regole di mettere in sicurezza agenti locali e ibridi.
  • Due progetti, due org, un disclaimer. AX è sotto google/; Substrate è sotto agent-substrate/ e dichiara di non essere un prodotto Google ufficialmente supportato. Nessuno dei due è ammesso al programma di vulnerability reward OSS di Google. Metti in conto di leggere il sorgente quando qualcosa si rompe.
Vocabolario AX
Premi Invio o Spazio per girare la carta. Usa le frecce sinistra e destra per spostarti tra le carte.Termine mostrato.
1 / 8

Mettiti alla prova

0/6
  1. Fornisci spec.image con il tuo ENTRYPOINT. Cosa esegue AX come PID 1?
  2. Il tuo agente esce con status 1. Cosa mostra ax get task?
  3. Dopo ax resume, il tuo agente ri-clona ogni repository. Perché?
  4. ax ssh rifiuta di connettersi al tuo Task. Causa più probabile?
  5. Quale layer implementa davvero lo snapshot degli agenti inattivi su storage e il loro ripristino su un worker caldo?
  6. Un tutorial di giugno 2026 ti dice di eseguire ax fork per fare branching di una traiettoria. Cosa devi aspettarti?

Fonti e approfondimenti​

Prossimi passi​