跳转到内容

AX - 开源琅嬛阁

google/ax

Agent Executor (AX) is Google's open agentic orchestration runtime

24
85
14,394
769
github.com · google/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 存在后再继续:

Terminal window
kubectl get svc api -n ate-system

安装方式

CLI 用 Go 安装。二进制在 $(go env GOPATH)/bin,这个目录需要在 PATH 里:

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

镜像和部署清单来自本仓库。AX_IMAGE_REPO 换成你的仓库地址(README 举例为 gcr.io/my-project):

Terminal window
git clone https://github.com/google/ax.git
cd ax
export AX_IMAGE_REPO=<your-registry>
make images
make deploy

make images 构建并推送 ax-server 与 ax-task-runner。make deploy 在 ax-system 命名空间部署 PostgreSQL 和 ax-server;没有写 spec.image 的 Task 会使用刚推送的 ax-task-runner。

首次运行

在仓库根目录跑 README 的最小 Task(不绑定 Workspace 或 Model):

Terminal window
ax apply -f examples/simple.yaml
ax get tasks
ax ssh simple-task -- ls -la /workspace
ax suspend task simple-task
ax resume task simple-task

ax 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。