google ax

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

用工作区和网关规范声明一个智能体任务。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: "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

为什么？

智能体是一种新型工作负载。它们既不是无状态微服务，也不是运行至完成的批处理任务。它们会累积状态，需要严格隔离，调用模型 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=

这会部署 Redis，然后使用 ko 构建并部署控制平面镜像。所有内容都落在 ax-system 命名空间中。

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 运行命令，并暂停任务。

文档

| 指南 | 阅读以了解…… | |---|---| | Concepts | 了解 Task、Workspace、Gateway 和 Model 各自的作用，以及任务如何在阶段和条件之间流转。 | | Manifests | 编写你自己的 YAML，附带每种类型的注释示例。 | | Sandbox | 了解运行器在启动时做什么，以及你的命令可以依赖什么：元数据服务器、客户机服务、环境。 | | Runners | 理解控制平面与任务容器之间的契约，并构建你自己的运行器镜像来替换默认镜像。 | | Networking | 从集群、你的笔记本电脑或 gRPC 客户端通过 atenet 路由器访问运行中的任务。 | | Architecture | 了解控制平面如何组合在一起，以及 API 参考。 | | Development | 构建、测试和发布对 AX 本身的更改。 | | Roadmap | 查看核心规范、Actor 架构、智能体环境和治理方面的计划里程碑。 |

CLI 用法

ax 通过 gRPC 与控制平面通信。它刻意模仿 kubectl 的风格：apply、get、describe、watch、delete，外加一些智能体特有的动词。

日常命令

# 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 上下文。切换集群后，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 作用域 | |