企业官网建设流程全解析

谷歌开源 AX：任务状态为什么不能放 Kubernetes CRD——用 Redis Streams 编排十亿级 agent 的架构拆解

一句话概括：AX 是谷歌开源的 agent 编排运行时。它值得看的地方不是"又一个 agent 框架"，而是它为了扛住海量短生命周期任务，主动放弃了 Kubernetes CRD 作为任务状态存储——理由写在官方设计文档里，很直白。

所有事实来自 Google 官方仓库github.com/google/ax、其DESIGN.md/docs/与官网agentexecutor.io，抓取时间 2026-09-25。文末列了全部来源。

一、先对齐时间线：它不是今天才出生的

先把"新"这个字说准，避免误判成熟度：

仓库当前状态（2026-09-25 抓取）：Apache-2.0，主语言Go，11,133 star、536 fork、41 个 open issue，最近一次 push 是当天 13:25 UTC。

真正让它值得写的是 9 月 20 日那次重构。commit message 原文写得很清楚：

AX is undergoing a significant redesign, moving away from a single CLI with an embedded Python harness toward a general-purpose orchestration layer for agentic tasks.

拆成三个二进制：ax-server暴露 gRPC API 接收 Task manifest，ax-controller作为水平扩展的 reconciler消费Redis Streams，ax-task-runner在沙箱化 worker 内执行任务。任务状态现在存在 Redis 而不是 Kubernetes CRD，这样系统能处理数百万个短生命周期任务而不压垮 etcd。

旧的 Python harness、ATE client、SQL 事件日志和 skill 示例全部删除。

翻成一句话：它原本是个带内嵌 Python harness 的 CLI，现在是一套通用编排层。这个转向本身就是本文的主题。

二、它的立论：agent 是一种新的工作负载

README 里那句话是整个项目的地基：

Agents are a new kind of workload. They are neither stateless microservices nor run-to-completion batch jobs.
（Agent 是一种新的工作负载。它既不是无状态微服务，也不是跑完即走的批处理作业。）

官网把这条论证展开得更完整：

Agent 型负载是有状态、突发、长时间运行的 actor：它高强度计算一分钟，然后等待模型响应、工具响应或人工审批。为无状态微服务或可预测批处理作业设计的传统编排器，在维持空闲沙箱运行这件事上会变得极其昂贵，同时又缺乏对亚秒级 suspend/resume 的原生支持。

这段话解释了两个设计选择的动机：

1. 为什么要有suspend/resume——agent 大部分时间在等，等待期间不该占着 CPU 和内存。
2. 为什么不能复用现成的编排器——Kubernetes 擅长"让 N 个副本一直活着"，而 agent 需要的是"活着、随时能冻住、随时能解冻、且解冻后内存和文件系统都还在"。

值得注意的是这句自我定位：AX 官方明说它不是 agent SDK，而是运行 agent 的系统。这和 LangChain 一类框架不在一个层面。

三、四个（或三个？）原语

这部分有个值得注意的细节：官方三处表述目前没对齐。

• 仓库 README 写的是 “three small primitives”：Task/Workspace/Model
• 官网首页写的是 “four small primitives”，多一个Gateway（网络策略）
• docs/concepts.md目前详述的是三个：Task/Workspace/Model

我按最新最全的官网口径列四个，并标注文档现状：

Model的定义值得单独说一句，官方原话是 “AModelis not a model.”——它不是模型，而是一份具名的模型配置。把它做成一种资源的意义在于：轮换密钥、钉住新模型版本、收紧某个参数，都变成一次ax apply，而不是去翻遍所有 task 定义。AX 自己的组件也读它，比如根据goal规划 workspace 的时候。

Workspace里最有意思的是goal字段。它允许你用一句自然语言描述"环境该长什么样"，首次启动时 runner 会把这句话交给一个 agent 去把环境装完：

apiVersion:ax.io/v1alpha1kind:Taskmetadata:name:data-analysisspec:workspaces:-name:python-envgoal:"Set up a Python 3 development environment"

四、核心架构：为什么状态不放 CRD

这是全文最硬的部分。DESIGN.md开头直接给了理由：

把数百万个短生命周期任务存成 Kubernetes CRD 会把 etcd 推到它的舒适区之外（个位数 GB 的存储上限、写入速率瓶颈、控制面性能退化）。AX 把状态放在 Redis，并用 Redis Streams 作为 API server 与水平扩展的 controller 池之间的工作队列。

这是对 Kubernetes 能力边界一次相当坦率的承认：etcd 适合存"集群的期望状态"，不适合存"每分钟产生几十万条的作业记录"。CRD 不是用来当高吞吐作业队列的。

数据流是这样的：

ax apply -f task.yaml │ ▼ ax-server ← 无状态 gRPC API（:8080）+ /healthz │ 存状态 & 发布事件 │ ▼ Redis ← Task Hashes + Event Streams + PubSub │ XREADGROUP（Streams） │ ▼ ax-controller ← 水平扩展的 reconciler 池 │ gRPC（Control API） │ ▼ Agent Substrate ← atespace 供给 / actor 创建与激活 / worker 分配

四个二进制各司其职：

注意ax-server是无状态的，状态全在 Redis——所以 API 层可以直接水平扩。控制面 API 是 gRPC 服务ax.v1alpha1.AX，健康检查则是普通 HTTPGET /healthz返回 200。

一个有意思的细节：Task的WatchTask是服务端流式 RPC，会实时推送 status 与 condition 的迁移，而不是让你轮询。

五、沙箱内部：PID 1 是谁

docs/sandbox.md写得很具体，而且官网演示里有一段真实终端输出可以互相印证：

$ ax ssh test -- ps -o pid,cmd PID CMD 1 /usr/local/bin/ax-task-runner 12 go build ./...

每个任务容器都以ax-task-runner作为 PID 1 启动。它启动后做四件事：

1. 加载Task和所有绑定的Workspacespec
2. 在80 端口起一个 metadata / guest 管理守护进程
3. 首次运行时按绑定顺序准备每个 workspace：克隆 Git 仓库、设置 skill 路径；如果绑定带goal，就把这个 goal 交给一个 Antigravity agent 去完成环境安装。这个 agent 需要容器里有GEMINI_API_KEY，默认给 10 分钟，可用AX_BOOTSTRAP_TIMEOUT改。在包括 agent 运行在内的所有 workspace 完成之前，任务一直报 not-ready。
4. 把spec.command作为子进程拉起（工作目录是第一个 workspace），并把AX_METADATA_URL和spec.env注入环境变量，然后监督它

两个容易忽略的工程设计：

• runner 作为 PID 1 始终不退出，即使命令已经结束。所以命令跑完之后 metadata server 仍在应答，ax ssh仍然能进得去；
• 沙箱停止或挂起时，runner 给命令的进程组发SIGTERM，等 10 秒，然后才强杀。这比"直接 SIGKILL"给了 agent 收尾的机会。

Metadata server 同时说 HTTP/1.1 和h2c，端点如下：

spec.debug: true时，同一个端口还会通过 gRPC 提供 Agent Substrate 的 guest services（进程服务 + 文件系统服务，前者正是ax ssh的底座）。它们默认关闭，因为允许在沙箱内任意执行进程和读写文件——ax ssh会拒绝连接没有开启它们的任务。这个默认值是合理的：把"能进容器执行任意命令"变成一个必须显式打开的开关。

六、网络：Task 没有 Service，也没有 Ingress

这一条对习惯了 Kubernetes 的人会有点反直觉。docs/networking.md明确写：

Task 不会得到属于自己的 Kubernetes Service 或 Ingress。

所有发往 task 的请求都走 Agent Substrate 的atenet router（ate-system命名空间下的atenet-routerService）。路由器只读一个 header：

ate-target-actor: <atespace>/<task>

它的行为是：解析出这个 actor 跑在哪台 worker 上，如果它处于挂起状态就先唤醒，然后把请求代理过去。Host和:authority留给你自己的应用，只有这个 header 负责选目标。

从集群内访问：

curl-H"ate-target-actor: default/task123"\http://atenet-router.ate-system.svc.cluster.local/metadata/v1alpha1/ax/task

从本机访问，先端口转发再照常说：

kubectl-nate-system port-forward svc/atenet-router8001:80curl-H"ate-target-actor: default/task123"http://localhost:8001/readyz

gRPC 则把同一个 header 放进 outgoing metadata：

ctx=metadata.AppendToOutgoingContext(ctx,"ate-target-actor","default/task123")resp,err:=client.SomeMethod(ctx,req)

"路由器发现目标是挂起的就先唤醒再代理"这一点是整套设计的关键。它意味着一个被 checkpoint 到磁盘的 agent 仍然持有一个稳定的寻址标识，外部无需知道它当前是否在内存里。没有这个能力，suspend就只能省自己的钱、断自己的路。

七、底座：Agent Substrate 凭什么能扛

AX 自己不做沙箱，它跑在Agent Substrate（github.com/agent-substrate/substrate）上面。这个底座的官方指标相当激进：

它的核心思路一句话讲完：把一大组 actor 映射到一小撮就绪 worker 上，赌的是"agent 类应用大部分时间在发呆"。官方把这套能力叫 Actor Teleport——挂起时把易失内存和文件系统状态一起做全量快照，唤醒时在 worker 池里任意一台机器上恢复。

Substrate 自己并不排斥 Kubernetes。它用 K8s 做基础设施供给和 worker 生命周期管理（worker 就是 Pod），在 Pod 和 Pod 自动扩缩容之上再叠一层 agent 专用的调度，为的是更低延迟。这个分层是合理的：K8s 管"机器"，Substrate 管"actor"，AX 管"任务语义"。

顺带一提，Substrate 的生态里还有个 CNCF Sandbox 项目kagent也在用它跑沙箱化的有状态 agent 负载——说明这不是一个只服务自家产品的内部组件。

八、跑起来：前置条件 → 步骤 → 验证

8.1 前置条件（不满足会直接失败）

先确认 Substrate 起来了，再往下走：

kubectl get svc api-nate-system

8.2 三步跑通第一个任务

# 1) 装 CLI（会装到 $(go env GOPATH)/bin，确认它在 PATH 里）goinstallgithub.com/google/ax/cmd/ax@latest# 2) 部署控制面（自动部署 Redis，然后用 ko 构建并部署控制面镜像）makedeployAX_IMAGE_REPO=<你的仓库># 3) 跑第一个任务（一个文件里同时有 Task + Workspace + Model）ax apply-fexamples/task.yaml ax get tasks# NAME ATESPACE PHASE ACTOR WORKER-IP AGE# task123 default Running task123 10.20.3.67 1m

ax的 CLI 形状是刻意照着kubectl做的：apply/get/describe/watch/delete，外加几个 agent 特有的动词：

axwatchtask task123# 实时流式看 phase 与 condition 迁移axsshtask123 --ls-la/workspace# 进沙箱翻一翻axsuspendtask task123# 打检查点并暂停ax resume task task123# 从断点继续

ax还会跟随你当前的 Kubernetes context——切集群后它会自动在后台解析并隧道到那个集群的控制面：

kubectx staging-cluster&&ax get tasks kubectx prod-cluster&&ax get tasks ax--context=dev-cluster get tasks# 或者不改 context 直接指定

8.3 怎么验证"挂起真的保住了状态"

这一步别只看命令返回 0。官网演示给了一条可复现的验证路径——在挂起前写一个文件，恢复后读它：

axsshtest--touchnotes.txt# 挂起前落一个文件axsuspendtasktestax resume tasktestaxsshtest--lsnotes.txt# 期望输出：notes.txt

官方演示的实际输出就是notes.txt。这说明恢复回来的不只是进程，而是文件系统状态。要验证内存状态，官方提供了 Counter Demo：一个有状态 Go HTTP server，反复 suspend/resume 后计数不回零。

8.4 在任务里读自己的配置

容器内不需要任何 SDK 就能自省配置。下面这段轮询/readyz直到 workspace 就绪，用的全是标准库：

importosimporttimeimporturllib.errorimporturllib.request BASE=os.environ["AX_METADATA_URL"].rstrip("/")defwait_ready(timeout=600.0,interval=2.0):"""轮询 /readyz，直到 workspace 初始化完成（503 -> 200）。"""deadline=time.monotonic()+timeoutwhiletime.monotonic()<deadline:try:withurllib.request.urlopen(f"{BASE}/readyz",timeout=5)asresp:ifresp.status==200:returnTrueexcepturllib.error.HTTPErrorasexc:ifexc.code!=503:raisetime.sleep(interval)returnFalseif__name__=="__main__":print("workspace ready:",wait_ready())

九、五个容易踩的坑

关于任务状态机，官方建议只等我Ready这一个 condition：

挂起会把Ready置为 False、reason 为TaskSuspended；恢复再置回。

十、现状与风险（必须说清楚）

官方自己在 README 顶部挂了警告：

我们仍在积极调整核心概念、协议与规范。在稳定版发布之前，很可能会引入重大破坏性变更。

加上底座 Substrate 也标着 pre-1.0、明确不保证向后兼容，所以：

• 不适合现在押上生产。它的价值目前在于读它的设计，而不是把它当基础设施。
• 它不是托管服务。要自建 K8s 集群、自己装 Substrate、自己维护 Redis 和镜像仓库——"零运维"不在承诺里。
• Redis 是控制面的有状态依赖。这是换取 etcd 之外高吞吐的代价，也意味着备份和可用性要自己设计。
• "十亿级"是设计目标而非实测数据。官方措辞是 “allowing you to scale to billions of concurrent agent sessions per cluster”，我找到的公开演示规模是 250 actor / 8 pod。两者不矛盾，但不要混为一谈。

十一、路线图里最值得盯的四件事

官方路线图（docs/roadmap.md）里有几项一旦落地会明显改变能力边界：

1. Task 之间可以分叉——把一个运行中或已挂起的 Task（含检查点内存与 workspace 文件系统状态）分叉成多个并行任务，用来并发探索投机执行路径。这是 suspend/resume 的自然延伸，也是"有状态"真正变成优势的地方。
2. 空闲检测与自动挂起——持续监控 actor 活动（进程执行、I/O、网络流量、活跃 gRPC/SSH 会话），自动对空闲任务触发检查点，回收 worker 的 CPU 与内存来提高密度。
3. 给每个 Task 发 SPIFFE 身份——签发 X.509-SVID，让任务、MCP server 与内部服务之间走零信任 mTLS。
4. runner 层自动采集 OTel 指标、分布式 trace 与结构化 agent 轨迹（prompt、模型响应、工具调用、进程执行、生命周期迁移），且不需要用户容器做任何埋点。

第 4 条对做 agent 评测和强化学习的人价值最大：轨迹采集从"每个框架各写一遍"变成运行时自带。

十二、一句话总结

AX 最有信息量的地方不是它提供了Task/Workspace/Gateway/Model这几个声明式原语——那是自然的设计选择。最有信息量的是它为了这些原语，选择不把状态放进 Kubernetes CRD，并在设计文档里直说了 etcd 的存储上限与写入瓶颈。一家把 Kubernetes 做成行业标准的公司，在自己的新编排器上给 etcd 划了一条边界，这条边界比任何功能列表都更值得记住。

参考来源

标签：开源, Kubernetes, AI Agent, Go, 云原生