AI Agent

《Google AX 怎么用？开源 AI Agent 编排运行时安装与开发教程》

Q: Google AX 安装后怎么确认第一个任务真正运行了？

先确认控制面已部署且 CLI 能连接集群，再应用官方示例任务。用 `ax get tasks` 查看任务记录，用 `ax watch task ` 跟踪阶段和条件；等工作区准备完成后，再按需启用调试并用 `ax ssh` 检查命令和目录。任务阶段能显示运行，不代表你的网络和权限策略已验收。

Q: Google AX 的工作区会在任务恢复后重新初始化吗？

官方 runner 将工作区目录放在可持久化的 `/workspace` 卷中，暂停后恢复时会重新启动容器，但保留目录内容。因此自定义 runner 应按每个工作区路径记录初始化标记，避免恢复时重复克隆仓库或覆盖 Agent 状态；同时仍要自行定义任务删除后的清理和数据保留规则。

Q: 自定义 Agent 接入 Google AX 时必须实现什么？

你可以先沿用默认 runner 镜像，只替换任务命令；需要控制生命周期时，可在 Go 程序中调用 `runner.Run`。完全自定义 runner 则要读取任务和工作区定义、准备工作区、启动命令、提供健康与就绪接口，并处理终止信号。上线前还要验证你的日志系统能捕获 Agent 子进程输出和退出状态。

发布于 2026.09.25

Kvmjet · 约 15 分钟阅读

《Google AX 怎么用？开源 AI Agent 编排运行时安装与开发教程》

数据点：官方 runner 契约规定，容器在 80 端口提供健康与就绪接口；工作区准备完成前，/readyz 返回 503，就绪后返回 200。runner 文档

最快解法：先照官方 Quickstart 跑通单个任务和工作区生命周期，再验证沙箱、网络边界与观测接口；这些检查通过后才进入小规模并发试点。Google AX 负责组织任务和执行运行时，不替代底层模型，也不是拿来即用的业务 Agent。

谁该看：构建 Agent 任务执行器的 Go 开发者，可从这里确认 runner 接口和任务流程。
谁该看：负责隔离执行环境的 SRE、平台工程师，以及需要评估远程开发环境的技术负责人。

最后更新于 2026 年 9 月 25 日；信息核对自官方仓库 README、Quickstart 示例及 runner、workspace 相关文档。这些文档仍提示核心概念和协议可能调整，仓库示例也不等于每种部署形态都已经过生产验证。

Google AX 安装部署前，先分清运行时边界

AX 把任务声明为 Task，把仓库、工具与技能等准备工作放入 Workspace，并用 Gateway 描述任务的网络入口与出站范围。它运行在 Agent Substrate 提供的隔离执行基础上；任务内实际执行的 Agent 命令仍由你指定，模型配置也有单独的 Model 资源。换句话说，编排运行时、Agent 程序和模型是三件事，不要把 AX 当作模型本身或现成的业务 Agent。官方概念说明

这条分界影响你怎么采购和部署：

✅ 适合 AX 的问题：多个 Agent 任务需要声明式创建、隔离工作区、限制网络出口，并观察生命周期。
⚠️ 不是 AX 自动替你完成的事：选择适合业务的模型、保证自定义 Agent 逻辑正确、定义生产日志保留和组织级凭证策略。
❌ 不能从示例直接推导的结论：某种集群规模、性能指标或生产可用性。官方 README 提到集群运行目标，但仓库同时明确说明核心协议仍在迭代；这不应被写成你部署后的容量承诺。

以一个 Go 团队为例：你希望 Agent 在独立目录中拉取代码、运行测试，并且只能访问代码托管服务与模型 API。AX 能把任务、工作区和 Gateway 纳入同一套声明；你仍需为目标集群准备执行底座、镜像仓库、可接受的出站规则，以及能检索 Agent 命令输出的日志方案。

第一步：先准备 CLI 和控制面依赖

官方 Quickstart 提供的 CLI 安装入口是 Go 工具链：

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

安装后确认 $(go env GOPATH)/bin 在 PATH 中，再从仓库开始部署：

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

这里的关键不是只把 ax 命令装到笔记本，而是把控制面部署到可运行任务的环境。官方列出的 Quickstart 前置条件包括 Kubernetes 集群、ko、集群可拉取的容器镜像仓库，以及可访问的 Agent Substrate Control API；文档也给出用 brew install ko 安装 ko 的方式。当前 Quickstart 没有在该步骤中声明最低 Go 版本，因此不要根据旧文章自行补一个版本门槛。官方仓库 Quickstart 与部署说明

部署命令会安装 Redis，并使用 ko 构建、部署控制面组件到 ax-system 命名空间。部署前先确认镜像仓库访问权限和 Substrate API 连通性；如果 CLI 已安装但后端依赖缺失，命令存在并不代表任务运行时已经就绪。

注意：AX 示例任务可能引用模型凭证、Gateway 或工作区设置。逐项检查示例清单所需资源，并通过集群的 Secret 机制注入凭证；不要把 API Key 写进提交到仓库的 YAML。官方示例清单

第二步：跑通 Google AX Quickstart 的任务生命周期

控制面部署后，先运行官方示例，而不是立刻把自定义 Agent 和生产权限一起引进来：

ax apply -f examples/task.yaml
ax get tasks
ax watch task task123

示例文件把 Task、Workspace、Gateway 和 Model 放在多文档 YAML 中。任务提交后，用 ax get tasks 确认记录，再用 ax watch 查看阶段和条件变化；不要只看任务名已经创建，就认定工作区和网络策略均已生效。官方生命周期说明中，WorkspaceReady 表示绑定的工作区都完成准备，GatewayReady 表示网络策略已经应用，而 Ready 才是运行且工作区就绪的条件。

工作区的流程可以这样理解：Workspace 描述仓库、MCP 服务或技能等环境内容；任务通过 spec.workspaces 绑定它；runner 按绑定路径准备工作区；spec.command 在第一个工作区中启动。没有设置路径的工作区会落在 /workspace/<name>，而第一个绑定工作区是任务命令的工作目录。官方清单字段说明

若任务需要交互排障，官方示例可用 debug: true 启用 ax ssh，例如：

ax ssh task123 -- ls -la /workspace
ax suspend task task123
ax resume task task123

恢复后，容器进程树会重新启动，但持久化工作区可继续使用。首次试跑请检查目录确实包含预期代码，再暂停、恢复并确认 Agent 状态没有因重复初始化而丢失。实际显示的任务名称、阶段和执行结果会随清单与环境变化，不应把文档中的示例输出当作固定结果。

第三步：自定义 Agent 从 runner 契约接入

最省改动的做法通常是沿用默认 runner，只替换或扩展 Agent 命令及镜像依赖。需要在 Go 侧加入初始化、回调或退出处理时，官方入口是导入 github.com/google/ax/runner 并调用 runner.Run；自己实现 runner，则要遵守控制面与任务容器之间的契约。

控制面通过 AX_TASK_YAML 传入 Task，通过 AX_WORKSPACES_YAML 传入绑定工作区定义；runner 准备工作区、启动 spec.command，并提供供 AX 观察任务的接口。官方契约列出的关键接口包括：

/healthz：runner 存活后返回健康状态。
/readyz：所有工作区准备好之前保持未就绪；这决定控制面何时设置 WorkspaceReady。
/metadata/v1alpha1/ax/task 与 /metadata/v1alpha1/ax/workspaces：提供任务和工作区的 YAML 元数据。

这里有个容易漏掉的运维边界：官方说明 runner 应在 Agent 命令退出后继续运行，以保留元数据服务和调试能力；控制面当前不会从容器读取命令退出码。因此，自定义 runner 应自行记录 Agent 退出状态、标准输出和错误输出，必要时把结果送入团队现有日志或任务回调。否则任务表面仍可观察，真正的 Agent 失败却不一定能从控制面状态直接看出来。

第四步：隔离、网络与观测逐项验收

AX 有声明网络边界的 Gateway，但“定义了白名单”与“你的目标环境确实拒绝了其他流量”不是同一件事。官方清单示例包含允许任意主机通过 443 端口的写法，并提醒生产环境应收紧；上线前请改成实际依赖的主机和端口，并从任务中测试未允许的目标是否不可达。官方网络配置说明

文件访问也要做真实检查。工作区挂载路径说明代码放在哪里，但不要据此假定 Agent 进程只能看到这个目录；应在实际任务容器里核实挂载、凭证文件和其他可读路径，再决定是否能执行不可信代码。AX 文档说明任务在沙箱中运行，但具体资源请求、限制和基础设施配置仍需核对你的 Task 清单与执行环境。

debug: true 不是无害的观测开关。官方 runner 文档说明，启用后会提供沙箱内的进程执行和文件访问能力，ax ssh 也只连接明确选择启用调试的任务。默认保持关闭；只有排障期间启用，并把操作权限、任务生命周期和关闭条件写进运维流程。官方沙箱说明

在进入下一阶段前，用这份验收清单做一次可复现检查：

[ ] 用干净的测试任务确认 WorkspaceReady 和 GatewayReady 条件符合预期。
[ ] 核对任务实际能读写的目录；确认其他敏感路径和凭证没有意外暴露。
[ ] 用 Gateway 白名单限制出站流量，并从任务内验证允许与拒绝的目标。
[ ] 默认关闭 debug；需要 SSH 排障时记录启用人、用途和关闭动作。
[ ] 检查 /healthz、/readyz 和元数据接口，再确认 Agent 输出及退出状态进入可检索日志。
[ ] 执行暂停、恢复和删除测试；明确工作区何时保留、何时清理，以及日志保留策略。

第五步：通过单任务验收后再扩大试点

单任务验证成功后，先复制相同镜像和清单跑并发试点，不要一步跳到“生产规模”。重点观察每个任务是否拿到独立工作区、并发时依赖准备是否可重复、任务失败后是否能识别退出原因，以及删除任务后工作区和敏感数据是否按预期处理。工作区恢复机制尤其值得验证：默认 runner 会避免恢复时重复准备工作区；自定义 runner 也应记录初始化完成状态，以免再次克隆覆盖已有 Agent 工作。

按风险决定下一步：

✅ 若任务边界、出站规则、失败日志和清理流程都能复现，再扩大并发范围，并逐步添加资源限制与告警。
⚠️ 若任务能运行但退出状态不可追溯，先补 runner 回调或日志收集，再测试并发。
❌ 若只能依赖长期打开的 ax ssh 才知道任务在做什么，暂缓上线；先补齐非交互式观测与失败恢复。

目前没有可核验的 Kvmjet AX 部署配置、节点地域或任务实测记录，因此不提供远程环境任务性能或成本结论。若你的团队还在选开发与试点环境，可以先看基础设施说明和帮助中心，将开发工作站与 AX 实际运行的 Kubernetes、Linux 任务容器区分开来。

常见问题

Google AX 安装后怎么确认第一个任务真正运行了？

先确认控制面已部署且 CLI 能连接集群，再应用官方示例任务。用 ax get tasks 查看任务记录，用 ax watch task <任务名> 跟踪阶段和条件；等工作区准备完成后，再按需启用调试并用 ax ssh 检查命令和目录。任务阶段能显示运行，不代表你的网络和权限策略已验收。

Google AX 的工作区会在任务恢复后重新初始化吗？

官方 runner 将工作区目录放在可持久化的 /workspace 卷中，暂停后恢复时会重新启动容器，但保留目录内容。因此自定义 runner 应按每个工作区路径记录初始化标记，避免恢复时重复克隆仓库或覆盖 Agent 状态；同时仍要自行定义任务删除后的清理和数据保留规则。

自定义 Agent 接入 Google AX 时必须实现什么？

你可以先沿用默认 runner 镜像，只替换任务命令；需要控制生命周期时，可在 Go 程序中调用 runner.Run。完全自定义 runner 则要读取任务和工作区定义、准备工作区、启动命令、提供健康与就绪接口，并处理终止信号。上线前还要验证你的日志系统能捕获 Agent 子进程输出和退出状态。

Google AX 上线前要如何检查沙箱和网络策略？

分别核对任务容器可读写的路径、资源限制、Gateway 出站主机与端口白名单，以及凭证进入任务的方式。默认关闭调试入口；只有排障确有需要时才临时启用 debug，因为 ax ssh 提供沙箱内任意进程执行和文件访问能力。再测试拒绝访问的目标确实不可达，并确认失败能在任务状态或日志中定位。

为 AX 试点选开发环境：先分清工作站和任务沙箱

继续共用一台个人开发机，容易把 Agent 试验依赖、凭证和临时文件混在日常开发环境里；临时 SSH 到一台普通云主机，也可能缺少持续可用的工作区和熟悉的开发工具。但这并不意味着 Mac 能代替 AX 的 Kubernetes 控制面或 Linux 任务容器。若你需要一台独立、持续可访问的远程 Mac 来编写 Go runner、维护清单和连接测试集群，短期租用 Kvmjet 的远程 Mac 开发环境可以把开发工作站与本地设备分开；真正的 AX 执行与沙箱边界，仍应由你部署和验收的运行环境负责。