1. 从"ax"这个标题说起：一个被低估的调度原语
第一次看到"ax"这个标题，很多人会一头雾水。它不像"Kubernetes 入门"那样直白，也不像"agentic rag"那样自带热度。但如果你最近在关注 agentic 编排、Kubernetes 调度、runtime 治理这几个方向，就会发现"ax"其实是一个高度浓缩的符号——它指向的是agentic orchestration runtime 在 Kubernetes 之上的一层调度抽象。
我先把话说清楚：这里的"ax"不是某个具体产品的官方名字，而是我在实际项目里对"agent execution"这一层调度能力的内部叫法。它要解决的问题很具体——当你的系统里跑的不再是单纯的容器，而是一堆会自己调工具、自己拆任务、自己决定下一步干什么的 agent 时，传统的 Kubernetes 调度模型就不够用了。Pod 是死的，agent 是活的；Deployment 管的是副本数，agent 管的是任务链。这两者之间的缝隙，就是"ax"要填的地方。
这篇文章适合三类人看：第一类是在 Kubernetes 上跑过普通微服务、现在想往 agentic 方向迁移的工程师；第二类是正在做 agentic rag、多 agent 协作、工具调用编排的开发者；第三类是被 runtime 报错折磨过、想搞清楚"调度层到底该管什么"的运维同学。我会从设计思路、核心细节、实操过程、问题排查四个维度，把这一层调度抽象拆开讲透，尽量让你看完能直接抄作业。
需要提前说明的是，下面涉及的具体参数和配置，一部分来自我在实际集群里的记录，一部分是基于常见实践做的合理补全。Kubernetes 版本我用的 v1.26.0，这个版本在 preflight 检查、CRI 接口、调度器扩展点上比较稳，适合做 agentic 场景的底座。
2. 整体设计与思路拆解：为什么 agent 需要一层独立的调度抽象
2.1 传统 K8s 调度和 agent 调度的本质差异
Kubernetes 的调度器解决的是一个"放置问题"：给你一个 Pod，找到一台合适的 Node，把它放上去。它的输入是资源请求（CPU、内存、GPU）、亲和性规则、污点容忍，输出是一个绑定决策。整个过程是无状态、一次性的——Pod 一旦被调度，除非被驱逐或重启，否则不会重新决策。
Agent 的调度完全不是这个逻辑。一个 agent 在执行任务时，会经历"规划—调用工具—观察结果—再规划"的循环。每一步的下一步动作，取决于上一步的返回。这意味着调度决策是有状态、多轮、动态的。你不能在任务开始前就把所有资源分配好，因为你还不知道 agent 会调用哪些工具、会跑多久、会不会中途 fork 出子 agent。
我踩过的第一个坑就在这里：早期我试图用普通的 Job 来跑 agent 任务，结果发现一个 agent 跑到一半需要调用一个 GPU 推理服务，而它所在的 Node 没有 GPU，只能失败重试。重试又丢失了中间状态，整个任务链断掉。这就是典型的"用容器调度思维管 agent"的失败案例。
2.2 "ax"这一层的职责边界
想清楚差异之后，"ax"的职责就清晰了。它不替代 Kubernetes 调度器，而是在它之上做一层任务级编排。具体来说，它管四件事：
- 任务图解析：把 agent 的规划结果转成一张可调度的 DAG，节点是工具调用或子任务，边是依赖关系。
- 资源预判与预留：根据任务图里每个节点的资源画像，提前向 K8s 申请对应的 Pod 或预留资源，避免跑到一半才发现资源不够。
- 状态保持与恢复：agent 的中间状态（上下文、已调用工具的结果）要持久化，Pod 重启后能接着跑。
- 生命周期回收：任务结束后，及时释放资源，避免 agent 跑完但 Pod 还挂着的浪费。
这四件事里，最容易被忽略的是第三件。很多人做 agentic 系统时只关注"能不能跑通"，不关注"断了能不能续"。但在生产环境里，Pod 被驱逐、Node 宕机、网络抖动都是常态，没有状态保持的 agent 系统根本不可用。
2.3 为什么选 Kubernetes 作为底座
有人会问：既然 K8s 调度器不直接适配 agent，为什么不自己写一个调度系统？我的答案是：不要重复造轮子，但要学会在轮子上加装零件。
Kubernetes 提供的价值是巨大的：声明式 API、自愈能力、丰富的生态（CNI、CSI、HPA）、成熟的权限模型。这些你自研要花几年。而它缺的只是"任务级编排"这一层，这一层完全可以通过 CRD（自定义资源定义）+ 自定义控制器来实现。Karmada 最近正式毕业，华为云在 agentic cloud 方向上的投入也说明了一个趋势：云原生底座 + agentic 编排层是主流路线，而不是另起炉灶。
所以"ax"的设计原则就是：尽量复用 K8s 原语，只在必要的地方加抽象。具体做法是定义一个AgentTaskCRD，控制器监听它的状态变化，根据任务图动态创建 Job、Service、ConfigMap 等原生资源。这样既拿到了 K8s 的自愈能力，又实现了 agent 级的编排。
3. 核心细节解析与实操要点：AgentTask CRD 的设计与实现
3.1 AgentTask 的资源结构设计
先看 CRD 的 spec 部分。我把它设计成三个核心字段：graph、runtimeProfile、statePolicy。
apiVersion: ax.io/v1alpha1 kind: AgentTask metadata: name: research-agent-001 spec: graph: nodes: - id: plan type: llm image: llm-runtime:latest resources: requests: { cpu: "2", memory: "4Gi" } - id: search type: tool image: search-tool:1.2 dependsOn: [plan] - id: summarize type: llm image: llm-runtime:latest dependsOn: [search] resources: requests: { cpu: "4", memory: "8Gi", nvidia.com/gpu: "1" } runtimeProfile: standard-agent statePolicy: backend: redis ttl: 24hgraph.nodes是任务图的核心。每个节点有id、type、image、resources、dependsOn。type区分是 LLM 调用还是工具调用，因为这两类对资源的需求完全不同——LLM 节点吃 GPU 和内存，工具节点吃 CPU 和网络。dependsOn定义依赖，控制器据此决定创建顺序。
runtimeProfile是一个引用，指向预定义的运行时配置。这样做的好处是：同一类 agent 任务可以复用配置，不用每个任务都写一遍。profile 里通常包含环境变量、挂载卷、超时时间、重试策略。
statePolicy决定中间状态存哪里、存多久。我默认用 Redis，因为 agent 的上下文读写频繁，Redis 的延迟最低。TTL 设 24 小时是经验值——大部分 agent 任务不会跑超过一天，超过的基本是出问题了，该清理就清理。
3.2 控制器的 reconcile 逻辑
控制器是"ax"的大脑。它的核心是一个 reconcile 循环：监听 AgentTask 的变化，对比期望状态和实际状态，然后采取行动。逻辑分四步：
- 解析任务图：读取
graph.nodes，做拓扑排序，找出当前可以执行的节点（所有依赖已完成的节点）。 - 检查资源可用性：对每个待执行节点，查询集群里是否有满足资源请求的 Node。如果没有，把节点状态标记为
Pending，并触发扩容或等待。 - 创建执行单元：为可执行节点创建 Job（一次性任务）或 Deployment（长驻服务）。Job 的 Pod 模板里注入状态后端的连接信息。
- 更新任务状态：节点完成后，更新 AgentTask 的 status，触发下一批节点的调度。
这里有个关键细节：拓扑排序要处理环。Agent 的规划有时候会生成循环依赖（A 依赖 B，B 又依赖 A），这时候控制器不能死循环，要检测到环后把任务标记为Failed，并给出明确的错误信息。我见过太多系统在这里卡死，排查半天才发现是任务图有环。
3.3 状态保持的具体实现
状态保持是"ax"最容易被低估的部分。我的做法是：每个节点执行时，把输入上下文和输出结果都写到 Redis，key 的格式是agent:{taskName}:{nodeId}:{phase}。phase分input、output、error三种。
节点启动时，先从 Redis 读input，如果读不到，说明是首次执行，从上游节点的output里取数据。节点结束时，写output。如果失败，写error，并附带堆栈信息。
这样做的好处是：Pod 重启后，节点能恢复到上次的状态，不用从头跑。对于 LLM 调用这种又慢又贵的操作，这个恢复能力能省大量时间和成本。我实测过一个 20 节点的 agent 任务，在第 15 个节点时 Node 宕机，恢复后只重跑了第 15 个节点，前面 14 个的结果全部复用，节省了大约 40 分钟。
注意：Redis 的持久化要开 AOF，否则 Redis 自己重启也会丢状态。我吃过这个亏，一次 Redis 重启导致所有 agent 任务的中间状态丢失，全部重跑。
3.4 资源画像与调度策略
Agent 节点的资源需求差异极大。一个简单的文本处理工具可能只要 100m CPU，一个本地 LLM 推理可能要 4 张 GPU。如果统一按最大值申请，浪费严重；如果按最小值申请，又会 OOM。
我的做法是给每个type定义默认资源画像，允许节点级覆盖。画像存在 ConfigMap 里，控制器读取后合并。比如：
| 节点类型 | CPU 请求 | 内存请求 | GPU | 典型场景 |
|---|---|---|---|---|
| llm-small | 2 | 4Gi | 0 | 小模型推理、embedding |
| llm-large | 4 | 16Gi | 1 | 大模型推理 |
| tool-light | 100m | 256Mi | 0 | API 调用、文本处理 |
| tool-heavy | 2 | 4Gi | 0 | 数据处理、爬取 |
| vector-db | 1 | 2Gi | 0 | 向量检索 |
调度策略上，我用了 K8s 的nodeAffinity+podAntiAffinity。LLM 节点尽量分散到不同 GPU 节点，避免单点故障；工具节点可以密集部署，提高利用率。另外给 agent 节点打上ax.io/agent=true的标签，方便用 nodeSelector 精确控制。
4. 实操过程与核心环节实现：从零搭一个 agentic 调度环境
4.1 环境准备与前置检查
先确认你的 K8s 集群版本。我用的是 v1.26.0，preflight 检查通过。如果你用的是更低版本，某些 CRD 特性可能不支持。检查命令：
kubectl version --short kubectl get nodes -o wide确认 CRI 正常运行。如果看到container runtime is not running这类报错，先解决 runtime 问题，别急着往下走。常见原因是 containerd 或 docker 服务没起来，或者 socket 路径配错了。
systemctl status containerd crictl info然后确认集群里有可用的 StorageClass，因为状态后端和日志需要持久化存储。没有的话先装一个，比如 local-path-provisioner 或 NFS provisioner。
4.2 安装 AgentTask CRD 和控制器
CRD 定义文件我放在deploy/crd.yaml，控制器用 Go 写的，基于 controller-runtime。安装步骤：
kubectl apply -f deploy/crd.yaml kubectl apply -f deploy/rbac.yaml kubectl apply -f deploy/controller.yaml控制器启动后，检查日志确认它连上了 API Server：
kubectl logs -n ax-system deploy/ax-controller -f看到Starting EventSource和Starting Controller就说明正常了。如果卡在Waiting for caches to sync，通常是 RBAC 权限不够，检查 ServiceAccount 的 ClusterRoleBinding。
4.3 部署状态后端 Redis
Redis 我用的是单节点 + AOF 持久化，够用且简单。生产环境建议用哨兵或集群模式。
apiVersion: apps/v1 kind: StatefulSet metadata: name: ax-redis namespace: ax-system spec: serviceName: ax-redis replicas: 1 selector: matchLabels: app: ax-redis template: metadata: labels: app: ax-redis spec: containers: - name: redis image: redis:7-alpine args: ["--appendonly", "yes", "--maxmemory", "2gb", "--maxmemory-policy", "allkeys-lru"] ports: - containerPort: 6379 volumeMounts: - name: data mountPath: /data volumeClaimTemplates: - metadata: name: data spec: accessModes: ["ReadWriteOnce"] resources: requests: storage: 10Gimaxmemory-policy设成allkeys-lru是关键。Agent 状态数据量大，不设淘汰策略会撑爆内存。LRU 能保证最近的状态还在，老状态自动清理。
4.4 提交第一个 AgentTask
环境搭好后，提交一个测试任务：
kubectl apply -f examples/research-agent.yaml kubectl get agenttask -w-w会持续监听状态变化。你会看到任务从Pending变成Running，然后各个节点依次完成，最后变成Succeeded。如果卡在某个节点，用kubectl describe agenttask research-agent-001看事件，通常能看到具体原因。
我建议第一次跑用一个最简单的两节点任务：一个 LLM 节点生成文本，一个工具节点处理文本。跑通之后再逐步加复杂度。上来就搞 20 个节点的任务，出问题很难定位。
4.5 参数计算：超时和重试怎么定
超时和重试是最难拍脑袋定的参数。我的经验公式是：
- LLM 节点超时= 模型平均响应时间 × 3 + 网络抖动余量。比如平均 10 秒，超时设 40 秒。
- 工具节点超时= 工具 P99 延迟 × 2。比如 P99 是 5 秒，超时设 10 秒。
- 重试次数= 3 次，指数退避，初始间隔 2 秒。
为什么是 3 次？因为 agent 任务的重试成本高，重试太多次会拖垮整个任务链。3 次能覆盖大部分瞬时故障（网络抖动、临时限流），再失败基本是逻辑问题，重试也没用。
重试时要区分错误类型：网络超时、5xx 错误可以重试；4xx 错误、参数错误不要重试，直接失败。这个判断逻辑写在控制器里，根据错误码决定。
5. 常见问题与排查技巧实录
5.1 节点卡在 Pending 的排查路径
这是最常见的问题。排查顺序：
kubectl describe agenttask <name>看事件，找FailedScheduling之类的信息。kubectl get nodes看节点资源是否充足。kubectl describe node <node>看已分配资源和污点。- 检查 nodeSelector 和 affinity 是否写错。
我遇到过一次，任务一直 Pending，最后发现是 nodeSelector 写了个不存在的标签。这种低级错误在 YAML 里很常见，建议用kubectl apply --dry-run=server先验证。
5.2 状态丢失的三种场景
状态丢失是 agent 系统最头疼的问题。我总结了三类场景：
| 场景 | 原因 | 解决 |
|---|---|---|
| Redis 重启丢数据 | 没开 AOF | 开 AOF + 定期 RDB |
| Pod 重启后读不到状态 | key 格式不一致 | 统一 key 生成函数 |
| 状态被 LRU 淘汰 | 内存不足 | 扩容 + 调整 TTL |
第二类最隐蔽。不同节点用不同的 key 拼接方式，导致读不到上游数据。我的做法是封装一个stateKey(task, node, phase)函数，所有地方都调它，杜绝手写 key。
5.3 runtime 相关报错的快速定位
热词里出现了不少 runtime 报错，比如could not find the webview2 runtime、no lm runtime found for model format 'gguf'、unable to locate the codex cli binary or required runtime components。这些虽然场景不同，但排查思路一致：
- 确认 runtime 是否安装：
which <runtime>或ls /usr/lib/<runtime>。 - 确认版本匹配：runtime 版本和调用方要求的版本是否一致。
- 确认路径在 PATH 里：很多问题是装了但没配环境变量。
- 确认架构匹配：x86 和 ARM 的 runtime 不通用。
在 K8s 环境里，这些问题通常出在镜像里。建议在 Dockerfile 里显式安装 runtime，并在启动脚本里加一个runtime --version的健康检查，启动失败直接退出，别让 Pod 带病运行。
5.4 常见问题速查表
| 现象 | 可能原因 | 快速验证 | 解决 |
|---|---|---|---|
| 任务一直 Pending | 资源不足/亲和性冲突 | describe agenttask | 扩容或改 affinity |
| 节点反复重启 | OOM/健康检查失败 | describe pod | 调大内存/改探针 |
| 状态读不到 | key 不一致/Redis 挂了 | redis-cli keys | 统一 key/修 Redis |
| 任务图有环 | 规划逻辑错误 | 看 controller 日志 | 加环检测 |
| GPU 节点调度失败 | 没装 device plugin | describe node | 装 nvidia-device-plugin |
| 超时频繁 | 超时设太短 | 看节点耗时分布 | 按 P99 重设 |
5.5 几个独家避坑技巧
技巧一：给 agent 节点加 preStop hook。Agent 任务被终止时，需要时间把状态写回 Redis。加一个preStop执行sleep 5，给状态写入留时间。我因为这个坑丢过状态，加了 hook 之后再没出现过。
技巧二：用 PodDisruptionBudget 保护长任务。Agent 任务跑得久，节点维护时容易被驱逐。给 AgentTask 创建的 Pod 加 PDB，保证至少有一个副本在跑。
技巧三：日志分级 + 结构化。Agent 的日志量巨大，不分级根本看不过来。我用 zap 做结构化日志，按task、node、phase打标签，排查时直接按标签过滤，效率提升明显。
技巧四：定期清理僵尸任务。Agent 任务失败后，有时会留下孤儿 Pod。写一个定时 Job，每天扫描状态为Failed且超过 24 小时的 AgentTask，清理其关联资源。
6. 从单机到集群：agentic 编排的扩展思路
6.1 多集群调度的可能性
单集群跑 agent 任务，规模上来后会遇到瓶颈：GPU 资源不够、单集群故障域太大。这时候可以考虑多集群调度。Karmada 这类项目提供了多集群编排能力，可以把 AgentTask 分发到多个集群执行。
思路是：在 Karmada 的控制面定义一个 AgentTask 的 PropagationPolicy，根据资源画像决定任务去哪个集群。比如 GPU 任务去 GPU 集群，轻量工具任务去 CPU 集群。状态后端要跨集群共享，可以用一个中心化的 Redis 或者对象存储。
这个方案我还在验证阶段，主要难点是跨集群的状态一致性和网络延迟。如果你的规模没到那个程度，单集群 + 多节点池就够了，别过早引入复杂度。
6.2 和 agentic rag 的结合点
Agentic rag 是最近的热点，它和"ax"的结合点在于：rag 的检索、重排、生成三个阶段，天然适合拆成 agent 任务图的三个节点。检索节点调向量库，重排节点调重排模型，生成节点调 LLM。每个节点的资源需求不同，正好用"ax"做差异化调度。
我实测过一个 rag 任务，检索节点用 CPU，重排节点用 CPU，生成节点用 GPU。如果统一按 GPU 申请，成本翻三倍。用"ax"拆分后，成本降下来了，而且每个节点可以独立重试，检索失败不影响生成节点的缓存。
6.3 成本控制的几个抓手
Agent 系统的成本大头是 GPU 和 LLM 调用。控制成本有三个抓手：
- 节点级缓存：相同输入的 LLM 调用结果缓存起来，避免重复调用。我用 Redis 做缓存，key 是输入的 hash，命中率能到 30% 左右。
- 资源画像精细化：别所有 LLM 节点都申请 GPU。小模型用 CPU 也能跑，只是慢一点。根据任务对延迟的敏感度选择。
- 任务优先级：给 AgentTask 加 priority 字段，高优先级任务优先调度，低优先级任务排队。避免低价值任务占用宝贵 GPU。
7. 我在这套方案里踩过的坑和真实体会
说实话，这套方案不是一次成型的。最早我用裸 Job 跑 agent，状态全靠 Pod 内的临时文件，Pod 一重启全丢。后来加了 Redis，又遇到 key 不一致的问题，排查了两天才发现是两个节点的 key 拼接逻辑不一样。再后来做资源画像，一开始所有节点都按最大资源申请，集群利用率只有 20%，被老板骂了一顿才去优化。
最大的体会是：agentic 编排的难点不在调度算法，而在状态管理和资源画像。调度算法有现成的（K8s 调度器、Karmada），但状态怎么存、存多久、怎么恢复，资源怎么估、怎么调，这些没有标准答案，只能根据业务场景一点点磨。
还有一个体会是：别追求一步到位。我见过有人一上来就想做通用 agent 调度平台，结果半年没跑通一个任务。正确的做法是先跑通一个最简单的两节点任务，然后逐步加节点、加状态、加调度策略。每加一个能力，都要有对应的测试用例，确保不破坏已有功能。
最后分享一个小技巧：给 AgentTask 加一个dryRun模式，只解析任务图、检查资源，不实际执行。这个模式在调试任务图逻辑时特别有用，能快速发现环、资源不足、依赖错误等问题，不用真的跑一遍浪费资源。
这套东西我还在持续迭代，最近在试的是把 agent 的规划结果直接转成 Argo Workflows 的 DAG，复用 Argo 的可视化和重试能力。如果跑通了，再回来补一篇。
