Skip to content

armgit / ax

Public Imported from GitHub
0

Agent Executor (AX) is Google's open agentic orchestration runtime

Go
4.7 KB
Raw Blame

Writing manifests

All four kinds can live in one multi-document YAML file. See examples/task.yaml for a complete, working set.

metadata.name and metadata.atespace become Substrate resource names, so they must be lowercase RFC 1123 labels: at most 63 lowercase alphanumeric characters or -, starting and ending with an alphanumeric character. ax apply rejects anything else up front rather than letting the task fail later with ActorCreationFailed.

When metadata.atespace is omitted, ax apply -a team-a -f manifest.yaml uses team-a. Without -a or --atespace, the manifest's atespace is preserved, or defaults to default if omitted. If an explicit flag disagrees with metadata.atespace, that resource is rejected before it is submitted.

Task

apiVersion: ax.io/v1alpha1
kind: Task
metadata:
  name: task123
  atespace: default
spec:
  image: "ghcr.io/my-org/my-agent-image"
  command: ["python", "agent.py"]
  env:
    - name: ENVIRONMENT
      value: "production"

  resources:
    limits:
      cpu: "2"
      memory: "4Gi"

  workspace:
    name: default-workspace
    path: "/workspace"   # optional; this is the default
    goal: "Install dependencies and run the test suite"   # Antigravity prepares the workspace to this goal on first run

  debug: true   # serve guest services inside the sandbox so `ax ssh` works; off by default

Image references

Substrate requires spec.image to be pinned by digest, e.g. ghcr.io/my-org/my-agent-image@sha256:.... A tag-only reference such as my-agent:v1 is rejected when the task's ActorTemplate is created, because a tag can move and would silently invalidate the actor's snapshots. If that happens the task reports Ready=False with reason TemplateCreationFailed and the Substrate error as the message. Resolve a tag to its digest with docker buildx imagetools inspect <image:tag> or crane digest <image:tag>.

Binding a workspace

A task binds at most one Workspace through spec.workspace. The binding needs a name; without a path the workspace is mounted at /workspace. That path is the working directory of spec.command, and the task reports WorkspaceReady once the workspace is prepared. A task with no workspace gets an empty working directory at /workspace.

To work on content from several sources, put it all in one Workspace, for example by listing several repositories under spec.git or adding files through spec.files.

Sizing the sandbox

spec.resources.limits caps the CPU and memory of the task's sandbox. The controller copies the limits onto the Substrate ActorTemplate it provisions for the task, using Kubernetes quantity syntax (500m, 2, 4Gi). Only cpu and memory are supported, each quantity must be greater than zero, and the CPU limit must be below 1000 cores. ax apply rejects values outside these rules, and a task whose limits Substrate refuses is marked Failed with reason TemplateCreationFailed rather than run without them. A task without limits is sized by its worker's defaults.

Substrate sizes sandboxes by limits alone, so spec.resources.requests is not supported and ax apply rejects a manifest that sets it.

Workspace

apiVersion: ax.io/v1alpha1
kind: Workspace
metadata:
  name: default-workspace
  atespace: default
spec:
  git:
    - name: origin
      repo: "https://github.com/chalk/chalk.git"
      branch: "main"
  files:
    - path: "AGENTS.md"
      content: |
        # Project Guidelines
        - Run `go test ./...` before submitting changes.
        - Keep dependencies minimal.
  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"

Model

For Google models, store the API key and set provider: google.

kubectl create secret generic gemini-api-secret --from-literal=GEMINI_API_KEY="AIzaSy..."

Then reference it from the Model:

apiVersion: ax.io/v1alpha1
kind: Model
metadata:
  name: default-model
  atespace: default
spec:
  provider: google
  model: gemini-3.8-flash
  secretKey:
    name: gemini-api-secret
    key: GEMINI_API_KEY

For Anthropic models, store the key the same way and set provider: anthropic.

kubectl create secret generic anthropic-api-secret --from-literal=ANTHROPIC_API_KEY="sk-ant-..."
apiVersion: ax.io/v1alpha1
kind: Model
metadata:
  name: claude-model
  atespace: default
spec:
  provider: anthropic
  model: claude-opus-5
  secretKey:
    name: anthropic-api-secret
    key: ANTHROPIC_API_KEY
  parameters:
    maxTokens: 16000