AX：用声明式工作空间编排隔离的智能体任务
AX 给 Kubernetes 团队声明式运行隔离智能体任务，区别是用 Workspace 和 Gateway 管理状态与出站网络。
GitHub google/ax 更新 2026-09-23 分支 main 星标 7.6K 分叉 355
Go Kubernetes Agent Substrate 智能体编排 gRPC

🧭 决策指南

为什么现在热： README 突出 Agent Substrate、Kubernetes 风格 CLI、沙箱隔离以及面向 billions agent workloads 的目标；同时仓库当日新增 2,305 颗星、总星数达到 7,604，且最新版本为 v0.3.0。材料能说明这些关注点与增长信号，但无法确认具体的单一传播原因。

适合，如果你

  • 你已有 Kubernetes 集群、镜像仓库和 Agent Substrate Control API，想运行隔离的 Task。
    README 的 Quick start 要求 Kubernetes、container registry 和 reachable Agent Substrate Control API。
  • 你需要把 Git 仓库、MCP 服务器或 skill 包预置到每个智能体的 Workspace。
    README 的 Why? 章节说明 Workspace 可预连接 Git repos、MCP servers 和 skill packages。
  • 你要暂停智能体并恢复其状态，或用 ax ssh 检查运行中的沙箱。
    README 的 Why? 和 CLI usage 章节列出 ax suspend、ax resume 与 ax ssh。

不适合，如果你

  • 你没有 Kubernetes 集群、ko、可拉取镜像的 registry 或 Agent Substrate Control API。
    README 的 Quick start 第 2 步将这些列为部署 control plane 的前置条件。
  • 你的项目要求稳定且不接受 API 或协议变化。
    README 顶部 WARNING 明确表示 stable release 前可能引入 major breaking changes。
  • 你只需要无状态微服务或 run-to-completion batch job，而不是带状态和隔离需求的 agent workload。
    README 的 Why? 章节将 agents 与 stateless microservices、run-to-completion batch jobs 区分开。

前置条件

  • Kubernetes 集群。
  • ko；README 给出的安装示例为 brew install ko。
  • 一个 Kubernetes 集群可拉取的 container registry。
  • 可访问的 Agent Substrate Control API；集群内默认地址为 api.ate-system.svc.cluster.local:443。
  • 部署命令会使用 Redis，并将 control plane 部署到 ax-system namespace。
  • CLI 安装需要 Go，README 命令为 go install github.com/google/ax/cmd/ax@latest。

第一步命令（README 原文）

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

要注意

  • ax ssh 进入任务要求 Task 设置 spec.debug: true。
    README 的 CLI usage 说明 interactive shell 需要 task 的 spec.debug: true。
  • ax apply 依赖 ax.io/v1alpha1 清单格式和 control plane 连接。
    README 说明资源使用 ax.io/v1alpha1 manifests，并通过 gRPC 与 control plane 通信。
  • 跨集群操作会跟随 kubectx 当前 context，--context 可显式指定目标集群。
    README 的 Works with kubectx 章节和 Global flags 章节分别说明 active context 与 --context。
  • Model 的提供商与模型配置示例显示为 google 和 gemini-3.8-flash。
    README CLI usage 的 ax get models 示例展示 provider 为 google、model 为 gemini-3.8-flash。

材料未说明

  • README 未说明支持的 Kubernetes 版本范围。
  • README 未给出 Agent Substrate 的部署步骤、版本要求或兼容矩阵。
  • README 未量化 billions of tasks per cluster 的吞吐、延迟或资源消耗。
  • README 未说明 Task 的 CPU/memory limits 如何配置及其默认值。
  • README 未说明 Gateway 主机允许列表的完整配置语法和默认安全行为。
  • README 未说明 Google Gemini 之外支持哪些 Model provider。
  • README 未说明 control plane 的认证、授权、TLS 和多租户隔离细节。
  • README 未说明 Redis 的高可用、持久化和故障恢复配置。
  • README 未说明 v0.3.0 与 ax.io/v1alpha1 的稳定性或升级迁移策略。

💡 深度解析

6
不适合 我需要在 staging 和 prod Kubernetes 集群之间切换，并把智能体任务纳入生产运维；但当前项目是 v0.3.0、API 为 v1alpha1，AX 是否适合直接作为稳定生产接口？
适合读者： 负责生产 Kubernetes 平台、要求 API 稳定并需要跨 staging 与 prod 集群切换的基础设施负责人

不适合直接作为稳定生产接口，主要原因是 README 明确警告核心概念、协议和规范仍会发生重大破坏性变化。

  • 项目警告写明 “We will likely to introduce major breaking changes prior to a stable release”，当前 API 示例也是 ax.io/v1alpha1。
  • 项目数据表明最新版本为 v0.3.0、仅有 5 个 release，说明仍处于早期演进阶段。
  • AX 确实支持按 Kubernetes context 访问不同集群，并展示了 staging、prod 和 --context=dev-cluster 的用法，因此跨集群体验具备基础。
  • 但 README 没有给出升级迁移策略、版本兼容矩阵、稳定性承诺或生产 SLA；若生产接口必须长期保持兼容，现阶段风险高于其运维便利性。
  • README 警告：“We are still actively refining our core concepts, protocols, and specifications”
  • README 警告：“We will likely to introduce major breaking changes prior to a stable release”
  • 项目数据：最新版本 v0.3.0，共 5 个 release
  • Works with kubectx：`kubectx staging-cluster`、`kubectx prod-cluster` 和 `ax --context=dev-cluster get tasks`
ax version
材料未说明：README 未说明 v1alpha1 到后续 API 版本的迁移工具、兼容窗口和废弃周期。；README 未说明控制平面高可用、跨区域容灾、审计、SLA 和企业级权限模型。
适合 我需要让编码智能体从 `https://github.com/golang/go.git` 的 `my-fix` 分支启动，并在沙箱中检查 `/workspace`；AX 能否把这些初始化步骤写进一次声明式提交？
适合读者： 维护 Go 源码修复任务、需要预热 Git 分支并通过 MCP 服务器提供工具的编码智能体工程师

适合，README 的示例正是 Git 工作区、任务目标和沙箱调试的组合。

  • Workspace 可以声明 Git 仓库和分支；示例使用 https://github.com/golang/go.git 与 my-fix，并把 Workspace 名称 golang 绑定到 Task。
  • Task 的 goal 可以描述“Ensure that Go tool chain is available and is built from source”，因此代码准备和任务意图可放在同一份多文档 YAML 中。
  • 设置 debug: true 后可以通过 ax ssh 进入沙箱，README 的原例使用 ax ssh test -- ls -al /workspace 检查工作区。
  • 但 README 没有承诺 Git 私有仓库凭据、分支冲突处理、提交固定策略或 MCP 初始化失败后的恢复语义。
  • README YAML 示例：Workspace 使用 `repo: https://github.com/golang/go.git` 和 `branch: "my-fix"`
  • README YAML 示例：Task 使用 `workspaces` 和 `goal`
  • README YAML 示例：`debug: true`；Quick start 使用 `ax ssh test -- ls -al /workspace`
  • Why? 表格：Workspace 可预配置 Git repos、MCP servers 和 skill packages
ax apply -f task.yaml
材料未说明：README 未说明私有 Git 仓库认证、凭据注入方式以及分支不存在时的失败行为。；README 未说明 Workspace 初始化失败是否会阻止 Task 启动，以及 MCP 服务状态如何反馈给 Task。
视情况 我需要让智能体运行不可信代码，同时只允许访问模型 API、Git 仓库和 MCP 服务；AX 能否直接提供我需要的沙箱和网络边界？
适合读者： 需要在 Kubernetes 中执行不可信代码、并要求模型 API、Git 和 MCP 服务采用显式出站主机白名单的企业平台工程师

视情况，AX 提供了声明式沙箱和出站白名单原语，但完整安全保证取决于 Agent Substrate 及其配置。

  • Task 用于在隔离沙箱中运行不可信智能体代码，并支持 CPU、内存限制。
  • Gateway 用显式 host allowlist 锁定出站流量，适合表达模型 API、Git 或 MCP 的必要访问边界。
  • AX 明确运行在 Agent Substrate 之上；README 没有把 AX 自身描述为能够独立防御内核漏洞、沙箱逃逸或高权限恶意代码的安全边界。
  • 示例中的 Gateway 输出为 EGRESS-HOSTS *，说明通配符会放宽出口控制；同时，模型凭据通过 Kubernetes Secret 配置，但应用层工具权限、数据脱敏和身份认证不由这些原语自动解决。
  • Why? 表格：`Task` 提供 “Run untrusted agent code in an isolated sandbox with CPU/memory limits”
  • Why? 表格：`Gateway` 提供 “Lock outbound traffic down to an explicit host allowlist”
  • README 开头：“It runs on top of Agent Substrate for sandboxed execution”
  • CLI usage：Gateway 示例显示 `EGRESS-HOSTS *`；Model 使用 Kubernetes secret
make deploy AX_IMAGE_REPO=<your-registry>
材料未说明：README 未说明 Agent Substrate 的隔离机制、逃逸防护、节点权限模型和安全审计结果。；README 未说明 Gateway 是否支持按任务、用户或工具进行更细粒度的身份授权。
适合 我想在 Kubernetes 中声明 Google 的 `gemini-3.8-flash`，凭据放在 Secret 里，并通过 Gateway 限制模型请求出口；AX 是否覆盖这条配置链路？
适合读者： 需要让平台通过 Kubernetes Secret 使用 Google 的 `gemini-3.8-flash`，并把模型出口限制在允许主机范围内的 AI 基础设施工程师

适合，AX 的 Model 和 Gateway 原语覆盖了声明模型配置、Secret 凭据和网络出口这条链路。

  • README 将 Model 定义为平台使用的 LLM 配置，并明确说明凭据来自 Kubernetes Secret。
  • ax describe model 的示例显示 provider 为 google、model 为 gemini-3.8-flash，与该配置约束直接对应。
  • Gateway 用显式主机允许列表控制出站访问，因此可以把模型服务地址纳入任务的网络边界，而不必把出口策略写进智能体代码。
  • 这些能力只说明配置和边界表达方式；README 没有说明具体 Secret 字段、Google API 端点清单、密钥轮换、请求审计或模型不可用时的重试策略。
  • Why? 表格：Model “Configure which LLM the platform itself uses, with credentials from a Kubernetes secret”
  • CLI usage：`default-model default google gemini-3.8-flash`
  • Why? 表格：Gateway “Lock outbound traffic down to an explicit host allowlist”
  • 项目数据：项目主语言为 Go；最新 release 为 v0.3.0
ax apply -f examples/task.yaml
材料未说明：README 未列出 Model 清单中 provider、model 和 Secret 引用的完整字段格式。；README 未说明 Google 模型端点、凭据轮换和多模型故障切换的配置方式。
适合 我想用 Go 构建自定义 runner image，替换 AX 默认的任务执行器；README 是否提供了足够的扩展入口来接入，而不是只能使用内置 runner？
适合读者： 希望用自定义容器替换默认执行器、并需要明确控制平面与任务容器契约的 Go 平台开发者

适合，README 明确把 Runner 契约作为可替换执行层的扩展点。

  • Runners 文档的目标是理解 control plane 与 task container 之间的 contract，并构建自己的 runner image 来替换默认实现。
  • AX 控制平面和 CLI 主要用 Go 实现，项目数据也显示 Go 是绝大多数代码的主语言，因此 Go 开发者的语言环境与项目一致。
  • Sandbox 文档说明了 runner 启动时的行为、metadata server、guest services 和环境依赖，可作为自定义镜像设计的接口背景。
  • 但 README 摘要没有列出启动协议、健康状态、退出码、信号处理、状态持久化和凭据注入字段；因此它确认了扩展方向，却不足以独立完成兼容实现。
  • Documentation：Runners “build your own runner image to replace the default”
  • Documentation：Sandbox 说明 metadata server、guest services、environment
  • CLI usage：`ax` 通过 gRPC 与 control plane 通信
  • 项目数据：Go 代码 299270 bytes，占主要代码量
go install github.com/google/ax/cmd/ax@latest
材料未说明：README 未提供 Runner contract 的完整消息格式、生命周期事件和版本兼容规则。；README 未说明自定义 runner image 的构建、注册、选择和回滚字段。
视情况 我已经有 Kubernetes 集群，并希望用类似 kubectl 的方式批量创建、观察、暂停和恢复数十亿个智能体任务；AX 是否适合成为这层编排入口？
适合读者： 已经运行 Kubernetes 集群、计划在单个集群批量调度数十亿个自主智能体任务的 AI 平台工程师

视情况，AX 的资源模型和操作方式很匹配，但实际规模能力不能只由 README 的目标声明确认。

  • AX 将 Task、Workspace、Gateway 和 Model 表达为 ax.io/v1alpha1 多文档清单，并提供 apply、watch、suspend、resume 等命令，适合纳入声明式平台工作流。
  • README 明确把项目定位为高吞吐编排器，目标是在集群中运行 billions of autonomous agent workloads，并建立在 Kubernetes 和 Agent Substrate 之上。
  • 多集群操作复用 Kubernetes context，可通过 kubectx staging-cluster、kubectx prod-cluster 后继续使用 AX。
  • 但 README 没有给出控制平面吞吐、Redis 容量、调度公平性、故障恢复或数十亿任务的基准数据，因此不能据此承诺目标规模下的 SLA。
  • Why?: “AX gives you four small primitives that handle all of that declaratively”
  • README 原句：“a high-throughput, declarative orchestrator to run billions of autonomous agent workloads in a cluster”
  • Works with kubectx：切换 `staging-cluster` 和 `prod-cluster` 的示例
  • 项目数据：Go 为主语言；最新版本 v0.3.0，共 5 个 release
ax apply -f examples/task.yaml
材料未说明：README 未说明控制平面和 Redis 在目标任务规模下的吞吐、容量及高可用配置。；README 未说明跨集群批量提交、租户配额、限流和调度公平性的实现。

✨ 核心亮点

  • Task、Workspace、Gateway、Model 四种声明式原语
  • 支持 ax suspend 与 ax resume 检查点恢复
  • 基于 Agent Substrate 承载大规模沙箱任务
  • README 明确提示稳定版前可能有重大破坏性变更

🔧 工程化

  • 用 ax.io/v1alpha1 YAML 声明 Task、Workspace、Gateway 和 Model
  • ax ssh 可进入 debug 沙箱查看 /workspace 内容
  • ax watch 实时查看任务阶段与条件变化
  • Gateway 用主机允许列表限制智能体出站网络

⚠️ 风险

  • README 警告稳定版前可能引入重大破坏性变更
  • 部署依赖 Kubernetes、ko、镜像仓库和 Agent Substrate API
  • 模型凭据依赖 Kubernetes Secret，配置细节未在材料中展开
  • README 声称支持 billions 任务，但未提供性能测量数据

👥 适合谁？

  • 需要在 Kubernetes 集群运行隔离智能体工作负载的团队
  • 希望用 Go 或 YAML 管理 Task 生命周期的开发者
  • 需要 Git、MCP 服务器和 skill 包预置的智能体平台