AX: оркестратор агентных задач для Kubernetes

[!WARNING] AX и многие его функции находятся в активной разработке. Мы продолжаем уточнять базовые концепции, протоколы и спецификации, и до выхода стабильного релиза возможны значительные ломающие изменения.

Опишите агентную задачу с рабочими пространствами и спецификациями модели. AX изолирует её в песочнице, подключает рабочее пространство и помогает запускать задачи в масштабе.

AX — высокопроизводительный декларативный оркестратор (orchestrator) для запуска миллиардов автономных агентных нагрузок в кластере. Он работает поверх Agent Substrate для изолированного выполнения задач и рассчитан на обработку миллиардов задач на кластер. Если вы работали с Kubernetes, ax покажется вам знакомым.

# task.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: Task
metadata:
  name: test
spec:
  workspaces:
    - name: golang
      goal: "Ensure that Go tool chain is available and is built from source"
  debug: true   # lets you `ax ssh` into the sandbox

Затем примените конфигурацию, следите за запуском и наблюдайте за работой агента:

ax apply -f task.yaml
ax watch task test
ax ssh test -- ls -al /workspace

Зачем это нужно?

Агенты — это новый тип нагрузки. Они не являются ни stateless-микросервисами, ни пакетными заданиями типа «выполнил и завершился». Они накапливают состояние, требуют строгой изоляции, обращаются к API моделей и серверам инструментов и могут бесконечно сжигать деньги, если за ними никто не следит. AX предоставляет три небольших примитива, которые декларативно решают все эти задачи:

Что вам нужно Что предлагает AX

Что вам нужно	Что предлагает AX
Запустить ненадёжный агентный код в изолированной песочнице с ограничениями по CPU и памяти	`Task`
Заранее подключить Git-репозитории, MCP-серверы и пакеты навыков, чтобы каждый агент стартовал подготовленным	`Workspace`
Настроить, какую LLM использует платформа, с учётными данными из Kubernetes Secret	`Model`
Приостановить простаивающий агент и продолжить с того же места	`ax suspend` / `ax resume`
Зайти в работающий агент через shell и посмотреть, что он делает	`ax ssh`

Запустить ненадёжный агентный код в изолированной песочнице с ограничениями по CPU и памяти

Task

Заранее подключить Git-репозитории, MCP-серверы и пакеты навыков, чтобы каждый агент стартовал подготовленным

Workspace

Настроить, какую LLM использует платформа, с учётными данными из Kubernetes Secret

Model

Приостановить простаивающий агент и продолжить с того же места

ax suspend / ax resume

Зайти в работающий агент через shell и посмотреть, что он делает

ax ssh

Всё выражается в виде манифестов ax.io/v1alpha1 и применяется одной командой.

Быстрый старт

Предварительные требования

AX планирует каждую задачу как изолированного актора на Agent Substrate, поэтому Substrate должен быть запущен в вашем кластере до развёртывания AX. Вам потребуются:

Кластер Kubernetes с установленным Agent Substrate (см. ниже)
Go и kubectl
ko (brew install ko) и реестр контейнеров, из которого кластер может загружать образы

Чтобы установить Agent Substrate, следуйте инструкциям в README Substrate. Substrate разворачивается в пространстве имён ate-system и открывает Control API по адресу api.ate-system.svc.cluster.local:443 — именно там AX ожидает его найти. Перед тем как продолжить, убедитесь, что он запущен:

kubectl get svc api -n ate-system

1. Установите CLI

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

Бинарный файл ax появится в $(go env GOPATH)/bin. Убедитесь, что этот каталог добавлен в переменную PATH.

2. Разверните control plane

Когда все предварительные требования выполнены — в первую очередь убедитесь, что Control API Agent Substrate доступен — разверните control plane AX:

make deploy AX_IMAGE_REPO=<your-registry>

Это развернёт Redis, а затем соберёт и задеплоит образы control plane с помощью ko. Всё окажется в пространстве имён ax-system.

3. Запустите первую задачу

ax apply -f examples/task.yaml       # Task + Workspace + Model в одном файле
ax get tasks
# NAME      ATESPACE   PHASE     ACTOR           WORKER-IP    AGE
# task123   default    Running   task123         10.20.3.67   1m

ax watch task task123                # потоковый вывод изменений фазы и условий
ax ssh task123 -- ls -la /workspace  # исследуем содержимое песочницы
ax suspend task task123              # создать чекпоинт и приостановить
ax resume task task123               # продолжить с того места, где остановились

Хотите увидеть полный жизненный цикл? Запустите ./demo.sh. Скрипт применяет кастомное рабочее пространство, ждёт готовности, выполняет команды через ax ssh и приостанавливает задачу.

Документация

Раздел Для чего читать

Раздел	Для чего читать
Concepts	Узнать, что делают `Task`, `Workspace` и `Model`, и как задача проходит через фазы и условия.
Manifests	Писать собственные YAML-файлы, используя аннотированный пример каждого вида.
Sandbox	Узнать, что делает runner при запуске и на что может рассчитывать ваша команда: сервер метаданных, гостевые сервисы, переменные окружения.
Runners	Понять контракт между control plane и контейнером задачи, а также создать собственный образ runner взамен стандартного.
Networking	Обращаться к работающей задаче через маршрутизатор atenet из кластера, с ноутбука или из gRPC-клиента.
Architecture	Понять, как устроен control plane, и ознакомиться с справочником API.
Development	Собирать, тестировать и выкатывать изменения в сам AX.
Roadmap	Смотреть запланированные этапы: базовые спецификации, архитектура акторов, агентные среды и управление.

Concepts

Узнать, что делают Task, Workspace и Model, и как задача проходит через фазы и условия.

Manifests

Писать собственные YAML-файлы, используя аннотированный пример каждого вида.

Sandbox

Узнать, что делает runner при запуске и на что может рассчитывать ваша команда: сервер метаданных, гостевые сервисы, переменные окружения.

Runners

Понять контракт между control plane и контейнером задачи, а также создать собственный образ runner взамен стандартного.

Networking

Обращаться к работающей задаче через маршрутизатор atenet из кластера, с ноутбука или из gRPC-клиента.

Architecture

Понять, как устроен control plane, и ознакомиться с справочником API.

Development

Собирать, тестировать и выкатывать изменения в сам AX.

Roadmap

Смотреть запланированные этапы: базовые спецификации, архитектура акторов, агентные среды и управление.

Использование CLI

ax взаимодействует с control plane по gRPC. По своей форме он намеренно похож на kubectl: apply, get, describe, watch, delete плюс несколько специфичных для агентов команд.

Повседневные команды

# Применить что угодно (многодокументный YAML, файл или stdin)
ax apply -f examples/task.yaml

# Задачи
ax get tasks                          # список
ax get tasks -a my-atespace           # список в другом atespace
ax get task task123                   # полная спецификация + текущий статус в виде YAML
ax describe task task123              # читаемое описание
ax watch task task123                 # потоковый вывод статуса и переходов условий
ax suspend task task123               # создать чекпоинт состояния актора и приостановить
ax resume task task123                # возобновить приостановленную задачу
ax delete task task123

# Войти в работающую песочницу через shell
ax ssh task123                        # интерактивный shell (задача должна иметь spec.debug: true)
ax ssh task123 -- ls -la /workspace   # разовая команда
ax ssh task123 -- python3 main.py

# Рабочие пространства и модели — по той же схеме

ax get workspaces
# NAME                ATESPACE   GIT-REPOS   MCP-SERVERS
# default-workspace   default    1           1
ax describe workspace default-workspace
ax delete workspace default-workspace

ax get models
# NAME            ATESPACE   PROVIDER   MODEL
# default-model   default    google     gemini-3.8-flash
ax describe model default-model
ax delete model default-model

# Подключение
ax ctx                                # активный контекст kube и способ, которым ax достигает control plane
ax tunnel list                        # фоновые туннели (состояние хранится в ~/.ax/tunnels)
ax tunnel stop
ax version

Работа с `kubectx`

ax следует за вашим активным контекстом Kubernetes. Переключите кластер — и ax в фоне найдёт и настроит туннель до control plane этого кластера.

kubectx staging-cluster
ax get tasks

kubectx prod-cluster
ax get tasks

# Или указать контекст, не переключаясь
ax --context=dev-cluster get tasks

Глобальные флаги

Флаг Описание По умолчанию

Флаг	Описание	По умолчанию
`-a`, `--atespace`	Область видимости atespace для команды	`default`
`-n`, `--namespace`	Пространство имён Kubernetes, где установлен AX	`ax-system`
`--context`	Целевой контекст Kubernetes	активный `kubectx` / `current-context`
`--server`	Адрес control plane в обход автоопределения	берётся из контекста kube или из `$AX_SERVER`

-a, --atespace

Область видимости atespace для команды

default

-n, --namespace

Пространство имён Kubernetes, где установлен AX

ax-system

--context

Целевой контекст Kubernetes

активный kubectx / current-context

--server

Адрес control plane в обход автоопределения

берётся из контекста kube или из $AX_SERVER

Лицензия

Apache License 2.0. Подробнее — в файле LICENSE.