AX: декларативный оркестратор агентных задач от Google

AX — декларативный оркестратор от Google для запуска агентных задач в масштабе. Проект построен поверх Agent Substrate и рассчитан на миллиарды задач в одном кластере. Если вы работали с Kubernetes, интерфейс AX покажется знакомым: YAML-манифесты, declarative подход, привычные команды apply, get, watch.

Агенты — это новый тип нагрузки. Они не stateless-микросервисы и не пакетные задания. Они накапливают состояние, требуют строгой изоляции, обращаются к API моделей и серверам инструментов и могут бесконечно потреблять ресурсы без контроля. Если агент залип в цикле и жжёт токены — некому его остановить. AX решает эти проблемы четырьмя базовыми примитивами, выраженными как манифесты ax.io/v1alpha1.

Примитивы

Дополнительно: ax suspend / ax resume для паузы и возобновления агентов, ax ssh для подключения к запущенному агенту.

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

Установка CLI

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

Бинарник попадёт в $(go env GOPATH)/bin. Убедитесь, что директория добавлена в PATH.

Развёртывание control plane

Для работы необходим Kubernetes-кластер, утилита ko (brew install ko), container registry и доступный Agent Substrate Control API (по умолчанию: api.ate-system.svc.cluster.local:443).

make deploy AX_IMAGE_REPO=<your-registry>

Команда развёртывает Redis, затем собирает и деплоит образы control plane через ko. Всё попадает в namespace ax-system.

Первый запуск

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

ax apply -f task.yaml
ax get tasks
ax watch task test
ax ssh test -- ls -al /workspace
ax suspend task test
ax resume task test

Флаг debug: true позволяет подключиться к песочнице через ax ssh.

CLI

Интерфейс CLI построен по аналогии с kubectl: apply, get, describe, watch, delete и специфичные для агентов команды.

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

ax apply -f examples/task.yaml       # мультидокументный YAML
ax get tasks                          # список задач
ax get tasks -a my-atespace           # фильтр по atespace
ax get task task123                   # полный spec + статус
ax describe task task123              # подробное описание
ax watch task task123                 # стриминг статуса
ax suspend task task123               # чекпоинт и пауза
ax resume task task123                # возобновление
ax delete task task123

ax ssh task task123                   # интерактивная shell
ax ssh task task123 -- python3 main.py

Gateways, workspaces и models работают по тому же принципу: ax get gateways, ax describe workspace, ax delete model.

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

AX автоматически следует активному контексту kubectx — переключение кластера меняет и target control plane. Это удобно при работе с несколькими окружениями: staging, production, dev.

Пример multi-document манифеста

Один YAML-файл может содержать все четыре ресурса сразу — Task, Workspace, Gateway и Model. Это удобно для воспроизводимых конфигураций, которые можно версионировать в Git и применять одной командой ax apply.

Архитектура

AX работает как control plane для агентных задач. Задачи выполняются в изолированных песочницах поверх Agent Substrate. Сетевой трафик ограничивается через Gateway, ресурсы — через Task-спецификацию. Вся конфигурация — декларативные YAML-манифесты.

Жизненный цикл задачи проходит через фазы (phases) и условия (conditions). Control plane отслеживает состояние каждой задачи, управляет распределением по воркерам и обеспечивает чекпоинтирование. Если задача завершилась неудачно или зависла — AX предоставляет инструменты для диагностики через ax describe и ax ssh.

Проект активно развивается — стабильного релиза пока нет, API может меняться. Репозиторий содержит 625 коммитов и задокументированную архитектуру.

Документация в репозитории охватывает ключевые аспекты:

• Concepts — модель Task, Workspace, Gateway, Model, жизненный цикл задач
• Manifests — написание YAML-манифестов
• Sandbox — что доступно внутри песочницы: metadata server, guest services, переменные окружения
• Runners — контракт между control plane и контейнером задачи, собственные runner images
• Networking — маршрутизация трафика к задачам через atenet router
• Architecture — обзор control plane и API reference

Лицензия

Apache License 2.0.

Для кого этот проект

AX подходит командам, которые запускают множество агентных задач параллельно и нуждаются в изоляции, контроле ресурсов и возможности наблюдать за агентами в реальном времени. Если вы строите пайплайны, где десятки или сотни агентов работают с кодом, данными или API — AX даёт инфраструктурный уровень для управления ими.

Для одиночных coding agent проектов AX может оказаться избыточным — проще использовать CLI-инструменты напрямую. Но при масштабировании до промышленного использования агентов декларативный подход с изоляцией и networking становится необходимым.