AX - 开源琅嬛阁
项目介绍
AX(Agent Executor)是 Google 开源的 Agent 编排运行时。你用 ax.io/v1alpha1 清单声明 Task、Workspace 和 Model,它在 Kubernetes 上把代理放进沙箱、接上工作区,并按集群规模调度;沙箱执行依赖 Agent Substrate。用过 Kubernetes 的话,ax 的手感接近 kubectl:apply、get、describe,再加上暂停、恢复和进入沙箱。官方写明项目仍在密集开发,稳定发布前很可能出现破坏性变更。概念与清单说明在仓库 docs/,产品站点为 agentexecutor.io。
核心特性
- 三种声明式原语:
Task在带 CPU 与内存限制的沙箱里跑代理;Workspace预先准备 Git 仓库、MCP 服务和技能包;Model把平台要调用的模型,以及 Kubernetes Secret 里的凭据,收成可复用的集群资源 - kubectl 形态的 CLI:
ax apply、get、describe、delete管理任务、工作区和模型;ax suspend/ax resume挂起并恢复,ax ssh进入正在运行的沙箱 - 可暂停的执行单元:Task 故意做得很小,可以隔离、挂起、丢弃。代理自己决定是一个任务做完,还是拆成一棵任务树;每个节点共用同一套沙箱和生命周期
- 工作区只声明一次:Git 仓库会克隆进工作区路径,MCP 与技能注册表在命令启动前由 runner 物化。多个 Task 可以绑定同一个 Workspace,默认挂载点是
/workspace - 跟随当前集群:
ax走活跃的 Kubernetes context,也可用--context指定;资源落在 atespace(默认default),用-a切换
对用户价值
代理会积累状态、必须隔离、会调用模型和工具,还可能在无人看管时循环烧钱。把这些都写进每个应用的启动脚本,环境会散、密钥会散,暂停后也很难从同一现场继续。AX 把沙箱、预热工作区、模型凭据、暂停恢复和进沙箱查看收成集群里的 YAML。平台团队可以用已经熟悉的 apply / describe 流程接入编码代理,轮换模型密钥时改一处 Model,而不是翻每一份任务定义。官方把目标写成单集群承载大规模任务(README 的说法是数百万级);这是设计目标,不是本条目核实过的压测数字。
与替代方案
- Agent Substrate 是 AX 底下的沙箱运行时。每个 Task 都调度成 Substrate 上的 actor,Control API 预期在
ate-system命名空间。先装 Substrate,再部署 AX。 - Kubernetes Job 面向跑完即结束的批处理。AX 额外提供 Workspace 预挂载、
suspend/resume,以及在spec.debug: true时用ax ssh查看现场。README 把代理负载和这类一次性 Job 分开写。 - LangGraph、CrewAI 一类框架编排的是进程里的图、对话和工具调用。AX 不描述代理如何拆任务,只提供可隔离、可暂停的 Task;应用层框架仍然可以放进你自己的 runner 镜像。
- E2B、Daytona 一类产品用 API 按次提供托管沙箱。AX 部署在自己的集群里,清单和密钥留在 Kubernetes。没有 Kubernetes 时,托管沙箱的路径更短。
- 边界:API 组是
v1alpha1。ax ssh依赖spec.debug: true,默认关闭。示例里的 runner 镜像摘要会随仓库更新,应使用克隆下来的examples/。
适应人群
- 已有 Kubernetes,希望把编码代理放进隔离沙箱,并用声明式清单批量调度的平台或基础设施工程师。
- 需要在集群里统一 Git 工作区、MCP 与模型凭据,避免密钥和启动脚本散落在每个代理仓库的团队。
- 希望用接近 kubectl 的命令暂停、恢复、SSH 进运行中代理,观察其行为的 Agent 平台开发者。
如何使用
前置条件
- 一个已经装好 Agent Substrate 的 Kubernetes 集群。Substrate 位于
ate-system,Control API 为api.ate-system.svc.cluster.local:443,AX 默认去这里找它。 - 已安装 Go 和
kubectl。 - 已安装 Podman 或 Docker,并登录到集群节点能够拉取的镜像仓库。
确认 Substrate 的 API Service 存在后再继续:
kubectl get svc api -n ate-system安装方式
CLI 用 Go 安装。二进制在 $(go env GOPATH)/bin,这个目录需要在 PATH 里:
go install github.com/google/ax/cmd/ax@latest镜像和部署清单来自本仓库。AX_IMAGE_REPO 换成你的仓库地址(README 举例为 gcr.io/my-project):
git clone https://github.com/google/ax.gitcd axexport AX_IMAGE_REPO=<your-registry>make imagesmake deploymake images 构建并推送 ax-server 与 ax-task-runner。make deploy 在 ax-system 命名空间部署 PostgreSQL 和 ax-server;没有写 spec.image 的 Task 会使用刚推送的 ax-task-runner。
首次运行
在仓库根目录跑 README 的最小 Task(不绑定 Workspace 或 Model):
ax apply -f examples/simple.yamlax get tasksax ssh simple-task -- ls -la /workspaceax suspend task simple-taskax resume task simple-taskax get tasks 的列包括 NAME、ATESPACE、PHASE、ACTOR、WORKER-IP、AGE。示例跑起来后 PHASE 为 Running。想看完整生命周期,可在仓库根目录执行 ./demo.sh:官方说明它会应用自定义 workspace、等待就绪、经 ax ssh 执行命令,然后挂起任务。
带工作区时,把 Git 仓库和 AGENTS.md 写进 Workspace,Task 用 spec.workspace.name 引用它,并设置 debug: true。完整片段见 README 开头的 task.yaml。资源默认在 atespace default;其他空间用 ax get tasks -a my-atespace。
验证是否成功
kubectl get svc api -n ate-system能看到 Substrate 的 API Service。make deploy之后,ax-system里有控制面负载。README 写明其中包含 PostgreSQL 和ax-server。ax get tasks列出simple-task,PHASE 为Running。ax ssh simple-task -- ls -la /workspace能在沙箱里执行并看到/workspace。ax describe task simple-task能打印阶段和 conditions。概念文档把Ready定义成「任务在跑,且WorkspaceReady为 True」。最小示例没有单独的 Workspace,这项条件以 describe 的实际输出为准。ax ctx显示当前 kube context,以及 ax 如何连到控制面。ax version用来核对 CLI 版本。
常见坑 / 注意事项
- 官方警告:稳定版之前可能有破坏性变更。
v1alpha1清单不要当成长期兼容的 API。 ax ssh需要spec.debug: true。examples/simple.yaml已经打开;自己写的 Task 漏了这项,SSH 不可用。- 集群里还没有可用的 Substrate 时,不要先跑
make deploy。AX 不会替你把沙箱层装上。 make images把镜像推到AX_IMAGE_REPO。集群节点拉不到这个仓库时,Task 会停在拉镜像。go install ...@latest跟随默认分支;控制面镜像来自你克隆并make deploy的那次提交。两边对不上时,先对照ax version和集群里的镜像。ax跟随当前 Kubernetes context。kubectx切到别的集群后,任务会发到那个集群的控制面。先看ax ctx,或用ax --context=<name>。- 模型密钥放在 Kubernetes Secret 里,由
Model引用。不要把凭据写进仓库 YAML。 - 示例镜像摘要会变。使用仓库里的
examples/simple.yaml,不要从旧文档抄 digest。