What is Google AX?The assignment desk for your agent’s workspace.

Chapter 01

Why do you need AX if Substrate already runs agents?

You have a room where software can run. What should it run? Which repository should be there? How will you see whether the room is ready? Those are different questions from finding somewhere to execute a process.

In the Agent Substrate article, we used a shared office to explain actors, workers, and saved environments. Keep that building in your mind. Now add an assignment desk near the entrance. Someone needs to turn a request into an organized piece of work.

AX is Google’s open agent orchestration runtime. In its current form, you describe tasks and their workspaces. AX coordinates that declared setup and runs each task as a sandboxed actor on Agent Substrate. [1]

“Orchestration” simply means coordinating the pieces needed to run the work. “Declarative” means describing the setup you want in a document, rather than personally performing every setup step. You’ll see that document as YAML, a readable format for configuration. [1]

Our assignment is deliberately small: check whether a project’s README includes installation instructions, then write a short report. The check itself can be ordinary code. Later you could replace that check with an agent that reads the project and suggests better instructions. Start with a result you can inspect.

The office coordinator can arrange a desk and hand over the assignment. That doesn’t make the coordinator the person who reads the document. Likewise, AX coordinates execution; your command or agent supplies the behavior. [3]

Chapter 02

What exactly do you hand to the assignment desk?

A request like “check the docs” leaves several questions unanswered. Which project? What should run? Does this work need a language model? AX separates those decisions into named resources: Task, Workspace, and Model. [2]

A Task describes one unit of execution. Its spec can name a container image, a command, environment variables, and workspace bindings. A container image is the packaged software environment. The command is the program you want that environment to start. [2]

A Workspace describes the material to prepare for a task. For example, it can name a Git repository to clone and files to write. You can reuse that definition across tasks. Reusing the definition doesn’t mean every task edits one shared live folder; setup is materialized inside each sandbox. [2]

A Model describes model-provider settings and a reference to credentials stored in a Kubernetes secret. AX’s own components can use it, including workspace planning. It isn’t the agent’s reasoning program, and a simple command-only task doesn’t need a Model resource. [2]

Think of three office documents: the work order, the desk preparation checklist, and the model service settings card. For our README check, the work order starts a checker. The workspace supplies the project. If the checker is deterministic code, there’s no reason to add a model just to make the example sound more advanced.

Chapter 03

Where does the actual work happen?

You submit a description. How does that become a program changing files? Follow the handoff, rather than imagining one giant agent doing everything.

The AX control plane is the service that manages AX resources and coordinates task execution. The CLI, the ax command you use in a terminal, talks to that service. AX then uses Substrate’s API to manage the task’s actor. [1]

Inside the sandbox, a runner prepares the environment and starts your task command. AX supplies a default runner called ax-task-runner. It stays available to supervise the command and expose the task’s management endpoints. [3]

Here’s the office version. The coordinator receives your form. The building provides a room. The runner is the person who opens the room, lays out the project, and starts the requested activity. Your checker or agent is the activity happening at the desk.

That separation helps you ask a better troubleshooting question. If the repository never appeared, look at preparation. If the checker reports a missing heading, inspect the project. If the sandbox never starts, inspect the execution path. Don’t treat every failure as “the AI got confused.”

You can build a custom runner, but it must honor AX’s runner contract. An arbitrary image with an arbitrary entrypoint isn’t enough: AX expects the runner executable at /usr/local/bin/ax-task-runner. I’d keep the default runner for the first experiment and change one thing at a time. [3]

Chapter 04

Can we follow one small assignment all the way through?

Imagine the task is on your desk now: “Does this project explain how to install it?” We’ll use a plain checker first, so you can understand the machinery without also debugging model behavior.

First, define the project material in a Workspace. It could clone the repository and include a checker script. Then bind that Workspace from a Task and set the task command to run the checker. The runner prepares the bound workspaces before starting the command; the first workspace becomes its working directory. [2]

Next, apply the resources and resume the task. At the source revision used here, creating a Task leaves it Suspended; applying its YAML alone doesn’t start execution. The upstream demonstration explicitly resumes it. We’ll include that step in the hands-on section. [7]

Then the runner prepares the room. Our checker reads the README, looks for an installation section, and writes report.txt under /workspace. Those names describe our teaching example, not files AX invents for you.

Want a concrete work order? This complete teaching manifest supplies a tiny README and a Python checker as Workspace files. Its Task binds that workspace at /workspace and runs python3 check_readme.py. There’s no model call or setup goal in this example.

kind: Task
metadata:
  name: readme-check
spec:
  workspaces:
    - name: readme-review
      path: /workspace
  command: ["python3", "check_readme.py"]
  debug: true

The excerpt shows the mapping; use the complete download when applying it. With AX and Substrate installed, save that file as readme-check.yaml, then run:

ax apply -f readme-check.yaml
ax resume task readme-check
ax watch task readme-check
# After the checker writes its report, inspect it:
ax ssh readme-check -- cat /workspace/report.txt

The watch command streams status; press Ctrl+C when you’ve finished watching. Wait for the checker to write its report before reading it. If the file isn’t there yet, the command may still be running. The checker looks for a Markdown heading containing “install.” The supplied README lacks one, so its report says Installation heading: MISSING. That narrow rule is easy to inspect; it doesn’t judge whether installation instructions are actually useful. A later reasoning agent could do that deeper review.

Finally, inspect the report. Does it point to a real installation section? Does it explain what is missing? You decide what counts as a useful answer. The runtime getting a program into a room is one achievement; the program meeting your requirement is another.

If you replace the checker with a reasoning agent, keep the same assignment small. Ask for a proposed report or patch that you can review. Add the agent program and its required configuration explicitly. Writing “improve these docs” into a workspace setup field doesn’t supply that program.

Chapter 05

Does a workspace “goal” tell the agent what job to do?

This is the field I’d slow down at. It sounds like the place to write your entire assignment. In the current AX model, the goal on a workspace binding describes the environment you need prepared. [2]

The official example asks for a Go toolchain to be available and built from source. That is desk preparation: make the tools ready. The default runner can hand a binding goal to an Antigravity agent during first-boot setup. Your task’s spec.command is the separate program started afterward. [4]

For the README example, “make Python and the project available” would be a setup requirement. “Read the README and write a report” is the checker’s assignment. You can often avoid model-based preparation entirely by packaging known tools in the image and preparing the files directly.

One caution belongs here. At this revision, workspace setup can log a goal-bootstrap error and continue. A ready environment therefore doesn’t prove that every requested setup goal was achieved. Inspect the files and tools your command actually needs. [10]

You’ll also see fields for tool and skill integrations in Workspace definitions. Don’t read a declaration as proof of a finished integration. For this first task, stay with the repository and files you can inspect directly. Add another dependency only when you have a check that shows it works.

Chapter 06

What survives when you pause the task?

You’ve read the report and want to come back later. Do you need the room occupied the whole time? AX exposes suspend and resume commands that use Substrate’s lifecycle support. [1]

Here’s the detail that connects this article to Substrate’s Full and Data snapshots: the current AX runner uses a durable directory at /workspace. Suspend and resume preserve that volume, then start a fresh container with a new process tree. AX’s actor template requests volume snapshot fidelity. [3]

So imagine placing the project folder and report in storage, then opening them at a desk later. The files can survive. A value held only in a running program’s memory isn’t a saved project file. Don’t design this AX example around an exact frozen instruction resuming in memory. [8]

If the agent needs conversation history, progress, or a cursor into a larger job, design it to write that state to durable storage and load it when it starts. Prefer small checkpoints you can examine. For our assignment, saving the report under the durable workspace is a simple starting point.

A restart also raises an ordinary application question: what happens if the command repeats? Writing the same local report may be fine. Sending the same email twice may not be. Keep external actions out of your first exercise, and add explicit protection against repeated effects when you introduce them.

Chapter 07

How can you try the lifecycle without adding an AI model?

Want to see the handoffs before building the documentation checker? Use the minimal example shipped in Google’s repository. It gives you an inspectable sandbox without needing a model resource. [6]

This is a cluster exercise. The official prerequisites are Kubernetes with Agent Substrate already installed, Go, kubectl, ko, and a container registry the cluster can pull from. The AX quickstart explains control-plane deployment. Use a development cluster and review those prerequisites before applying anything. [1]

From an AX repository checkout with the CLI and control plane installed, the upstream example supplies the task. Add the explicit resume shown in the demonstration, then inspect the sandbox.

ax apply -f examples/simple.yaml
ax resume task simple-task
ax describe task simple-task
ax ssh simple-task -- ls -la /workspace
ax suspend task simple-task
ax resume task simple-task
ax ssh simple-task -- ls -la /workspace

Wait for the task to become ready before using ax ssh. The minimal example enables debug: true, which exposes guest services for process execution and file access inside the sandbox. That opt-in is required for ax ssh; keep it deliberate. [4]

An empty workspace listing is a useful first result. It tells you where you are, without mixing in a model answer. To extend the exercise, write a small file under /workspace, suspend, resume, and read it again. Then try the documentation checker. That sequence makes each new failure easier to locate.

Before creating another task, decide what you want to learn from it. For the checker, save its input revision and report together. You should be able to show someone the exact document it read and the output it produced, rather than pointing only at a green status.

Chapter 08

How will you know the assignment actually succeeded?

You see Ready. Can you tell your teammate the documentation check passed? No. In AX, readiness is about the running task and prepared workspaces. It isn’t an assessment of the report. [2]

The default runner stays alive after the command exits. It logs the command’s exit status, but the control plane doesn’t currently read that exit status back from the container. A running task can therefore outlive a checker that has finished or failed. [3]

For this assignment, define success as a report you can open, with a clear finding tied to the README it inspected. If a checker exits with an error, surface that error in your application’s own result handling. If an agent proposes changes, review the patch and run the relevant checks before accepting them.

I’d recommend AX as a learning experiment when you specifically want to understand declared task environments on Substrate. Begin with one small task, durable output, and an explicit review. The project warns that its concepts and protocols are still changing, so pin the revision for an experiment you want to reproduce. [1]

You should now be able to explain the whole assignment without a diagram: AX takes the work order, Substrate provides the sandboxed room, the runner prepares it, your program does the check, and you inspect the result. When the task pauses, preserve what the next process will need in the workspace.

Keep these words

A small glossary

Task

A named unit of execution: image, command, environment and workspace bindings.

Workspace

A reusable description of the project material and environment to prepare.

Model

Model-provider configuration, including a reference to credentials.

Control plane

The service coordinating task resources and execution.

Runner

The program inside the sandbox that prepares workspaces and supervises the command.

Durable workspace

Files saved under /workspace that survive this runner’s suspend and resume.

Ready

The task is running and its workspace preparation is reported ready; inspect application results separately.

Check your understanding

Can you explain the handoffs?