AX

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

通过工作区和网关规范声明一个智能体任务。AX 会将其沙箱化、接好工作区、隔离其网络，并帮助大规模运行。

AX 是一个高吞吐、声明式的编排器，用于在集群中运行数十亿个自主智能体工作负载。它构建于 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: "确保 Go 工具链可用且由源码构建"
  debug: true   # 允许你 `ax ssh` 进入沙箱

然后 apply 它，看着它启动，并“越过智能体的肩膀”围观它工作：

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

为什么？

智能体是一种全新的工作负载类型。它们既不是无状态微服务，也不是一次性运行的批处理作业。它们会累积状态、需要严格隔离、需要调用模型 API 和工具服务器，而且如果无人看管，可能会在循环中不断烧钱。AX 提供四个小巧的原语，以声明式方式处理这一切：

你想要…	AX 提供
在隔离沙箱中运行不受信任的智能体代码，并限制 CPU/内存	`Task`
预先接好 Git 仓库、MCP 服务器和技能包，让每个智能体热启动	`Workspace`
将出站流量锁定为显式的主机白名单	`Gateway`
配置平台自身使用的 LLM，凭据来自 Kubernetes secret	`Model`
暂停空闲智能体，并从原处精确恢复	`ax suspend` / `ax resume`
Shell 进入运行中的智能体，看看它在做什么	`ax ssh`

一切都通过 ax.io/v1alpha1 清单表达，并用一条命令应用。

快速开始

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 命名空间中。

3. 运行你的第一个任务

ax apply -f examples/task.yaml       # 一个文件包含 Task + Workspace + Gateway + 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 执行命令，并挂起任务。

文档

指南	阅读目的…
概念	了解 `Task`、`Workspace`、`Gateway` 和 `Model` 各自的作用，以及任务如何经历各阶段与条件。
清单	编写你自己的 YAML，每种类型都附有带注释的示例。
沙箱	了解 runner 在启动时做什么，以及你的命令可以依赖什么：元数据服务器、来宾服务、环境。
Runner	理解控制平面与任务容器之间的契约，并构建你自己的 runner 镜像替换默认版本。
网络	从集群、你的笔记本或 gRPC 客户端通过 atenet 路由器访问运行中的任务。
架构	理解控制平面如何组织，以及 API 参考。
开发	构建、测试并发布对 AX 本身的修改。
路线图	查看核心规范、actor 架构、智能体环境与治理方面的规划里程碑。

CLI 用法

ax 通过 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                   # 完整 spec + 实时状态（YAML 格式）
ax describe task task123              # 人类可读的详细信息
ax watch task task123                 # 实时输出状态与条件转换
ax suspend task task123               # 对 actor 状态做检查点并暂停
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

# Gateway、workspace、model 遵循相同的模式
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

# 连接相关
ax ctx                                # 当前的 kube 上下文以及 ax 如何连接控制平面
ax tunnel list                        # 后台隧道（状态保存在 ~/.ax/tunnels）
ax tunnel stop
ax version

与 `kubectx` 配合使用

ax 会跟随你当前激活的 Kubernetes 上下文。切换集群后，ax 会在后台解析并建立通往该集群控制平面的隧道。

kubectx staging-cluster
ax get tasks

kubectx prod-cluster
ax get tasks

# 或者不切换上下文直接指定目标
ax --context=dev-cluster get tasks

全局标志

标志	描述	默认值
`-a`, `--atespace`	命令的 atespace 范围	`default`
`-n`, `--namespace`	AX 安装所在的 Kubernetes 命名空间	`ax-system`
`--context`	要定位的 Kubernetes 上下文	激活的 `kubectx` / `current-context`
`--server`	控制平面地址，绕过自动检测	由 kube 上下文推导，或 `$AX_SERVER`

许可证

Apache License 2.0。详情见 LICENSE。

AX