ax

AX

[!WARNING] 我们仍在积极完善核心概念、协议与规范。在稳定版本发布之前，很可能会引入重大的破坏性变更。

用工作区（workspace）和网关（gateway）规范声明一个 agent 任务。AX 为其提供沙箱、装配工作区、隔离网络，并帮助你在规模化场景下运行它。

AX 是一个高吞吐、声明式的编排器，用于在集群中运行数十亿个自主 agent 工作负载。它构建在 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

然后应用它，观察它启动，并从 agent 的背后审视它：

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

为什么需要它？

Agent 是一种全新的工作负载。它既不是无状态的微服务，也不是运行到结束的批处理作业。它会累积状态、需要严格隔离、会调用模型 API 和工具服务器，如果没有人在盯着，还可能在一个循环中不断烧钱。AX 提供四个小巧的原语，以声明式的方式处理这一切：

你想要……	AX 提供……
在带有 CPU/内存限制的隔离沙箱中运行不可信的 agent 代码	Task
预先接好 Git 仓库、MCP 服务器和 skill 包，让每个 agent 都热启动	Workspace
将出站流量限制到显式的主机允许列表	Gateway
配置平台自身使用哪个 LLM，并从 Kubernetes secret 中读取凭据	Model
暂停空闲的 agent，并在它停下的地方精确恢复	ax suspend / ax resume
Shell 进入正在运行的 agent，查看它在做什么	ax ssh

一切都以 ax.io/v1alpha1 manifest 的形式表达，并通过一条命令应用。

快速开始

1. 安装 CLI

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

这会把 ax 二进制文件放到 $(go env GOPATH)/bin。请确保该目录在你的 PATH 中。

2. 部署控制平面

你需要一个 Kubernetes 集群、ko（brew install ko）、一个你的集群可以拉取的容器镜像仓库，以及一个可达的 Agent Substrate Control API（集群内默认：api.ate-system.svc.cluster.local:443）。

make deploy AX_IMAGE_REPO=<your-registry>

这会先部署 Redis，然后使用 ko 构建并部署控制平面镜像。所有内容都会落入 ax-system namespace。

3. 运行你的第一个任务

ax apply -f examples/task.yaml       # Task + Workspace + Gateway + Model in one file
ax get tasks
# NAME      ATESPACE   PHASE     ACTOR           WORKER-IP    AGE
# task123   default    Running   task123         10.20.3.67   1m

ax watch task task123                # stream phase and condition changes live
ax ssh task123 -- ls -la /workspace  # poke around inside the sandbox
ax suspend task task123              # checkpoint and pause
ax resume task task123               # pick up where it left off

想看到完整的生命周期端到端演示？运行 ./demo.sh。它会应用一个自定义工作区、等待就绪、通过 ax ssh 执行命令，并挂起任务。

文档

指南	阅读它来……
核心概念	了解 Task、Workspace、Gateway 和 Model 各自做什么，以及任务如何在阶段（phase）和条件（condition）之间流转。
Manifest	编写你自己的 YAML，每种 kind 都附有带注释的示例。
沙箱	了解 runner 在启动时做什么，以及你的命令可以依赖什么：metadata server、guest services、环境变量。
Runner	理解控制平面与任务容器之间的契约，并构建你自己的 runner 镜像来替换默认镜像。
网络	从集群、你的笔记本电脑或 gRPC 客户端，通过 atenet router 访问正在运行的任务。
架构	理解控制平面如何组合在一起，另有 API 参考。
开发	构建、测试并发布对 AX 本身的修改。

CLI 用法

ax 通过 gRPC 与控制平面通信。它刻意做成 kubectl 的形态：apply、get、describe、watch、delete，外加一些 agent 专属的动词。

日常命令

# Apply anything (multi-document YAML, file or stdin)
ax apply -f examples/task.yaml

# Tasks
ax get tasks                          # list
ax get tasks -a my-atespace           # list in another atespace
ax get task task123                   # full spec + live status as YAML
ax describe task task123              # human-readable detail
ax watch task task123                 # stream status and condition transitions
ax suspend task task123               # checkpoint actor state and pause
ax resume task task123                # resume a suspended task
ax delete task task123

# Shell into the running sandbox
ax ssh task123                        # interactive shell (task needs spec.debug: true)
ax ssh task123 -- ls -la /workspace   # one-off command
ax ssh task123 -- python3 main.py

# Gateways, workspaces, models follow the same pattern
ax get gateways
# NAME              ATESPACE   LISTENERS             EGRESS-HOSTS
# default-gateway   default    8494/gRPC,8080/HTTP   *
ax describe gateway default-gateway
ax delete gateway default-gateway

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

# Connection plumbing
ax ctx                                # active kube context and how ax is reaching the control plane
ax tunnel list                        # background tunnels (state lives in ~/.ax/tunnels)
ax tunnel stop
ax version

与 kubectx 协同工作

ax 会跟随你当前活跃的 Kubernetes context。切换集群后，ax 会在后台解析并隧道连接到该集群的控制平面。

kubectx staging-cluster
ax get tasks

kubectx prod-cluster
ax get tasks

# Or target a context without switching
ax --context=dev-cluster get tasks

全局标志

标志	描述	默认值
-a, --atespace	该命令的 Atespace 作用域	default
-n, --namespace	安装 AX 的 Kubernetes namespace	ax-system
--context	要指定的 Kubernetes context	当前活跃的 kubectx / current-context
--server	控制平面地址，绕过自动检测	由 kube context 推导，或 $AX_SERVER

许可证

Apache License 2.0。详见 LICENSE。