1. 从“ax”这个标题说起一个被低估的调度原语第一次看到“ax”这个标题很多人会以为是某个命令行工具的缩写或者某个内部项目的代号。但把热搜词摊开来看——ax、agentic、orchestrator、kubernetes、workspace——这几个词凑在一起指向的其实是一个非常具体的技术命题在 Kubernetes 之上为 agentic 工作负载构建一套轻量级的调度与编排层。ax 在这里我更愿意把它理解成 “agent executor” 或者 “agent exchange” 的缩写它不是一个现成的开源项目名而是一类架构模式的代称。为什么这个命题现在值得聊因为过去两年agentic 应用从 demo 走向生产最大的瓶颈已经不是模型能力而是运行时环境。一个 agent 要干活它需要 workspace工作空间来存放中间文件、需要 orchestrator编排器来协调多个子任务、需要调度器来决定哪个节点跑哪个 agent、需要隔离机制来防止一个 agent 把另一个 agent 的上下文污染掉。这些东西Kubernetes 原生能力能覆盖一部分但覆盖得不够顺手。ax 要解决的就是这“不够顺手”的部分。这篇文章适合三类人看第一类是在做 agentic 应用落地、已经被 workspace 管理和调度问题折磨过的工程师第二类是想把现有 Kubernetes 集群改造成 agent 运行底座的平台团队第三类是对 agentic orchestration 这个概念感兴趣、想搞清楚它和传统微服务编排到底差在哪里的技术负责人。我会从设计思路、核心细节、实操过程、问题排查四个维度展开尽量把每个决策背后的“为什么”讲清楚而不是只丢一堆 YAML 出来。需要提前说明的是ax 不是一个有官方文档的标准项目它更像是一种架构实践。下面涉及的具体实现一部分来自我在实际项目中的取舍一部分来自社区里常见的做法我会明确标注哪些是“我试过可行的”哪些是“理论上应该这样但需要你根据环境调整”。2. 整体设计与思路拆解为什么是 Kubernetes Agentic Orchestrator2.1 为什么不在裸机上直接跑 agent很多人第一反应是agent 不就是个进程吗我写个 Python 脚本用 supervisor 管起来不就行了这个方案在单机、单 agent、低频调用的场景下确实够用。但一旦进入 agentic 场景问题就来了。agentic 的核心特征是多步推理 工具调用 状态保持一个任务可能拆成十几个子步骤每个子步骤可能调用不同的工具、访问不同的数据源、产生不同的中间产物。这些中间产物需要有个地方存这就是 workspace 概念的由来。裸机方案的问题在于第一资源隔离靠进程级别一个 agent 跑飞了把内存吃满其他 agent 跟着遭殃第二workspace 管理靠本地目录多机部署时目录同步是个噩梦第三扩缩容靠手动流量高峰时加机器、低谷时减机器运维成本高第四故障恢复靠重启脚本agent 跑到一半挂了中间状态全丢。Kubernetes 恰好在这四个维度上都有成熟方案Pod 级别的资源隔离、PVC 或 emptyDir 的 workspace 挂载、HPA 或 KEDA 的弹性伸缩、以及基于 controller 的故障自愈。但 Kubernetes 原生调度器是给无状态微服务设计的它不理解 agent 的“任务亲和性”。比如一个 agent 需要访问某个特定的向量数据库分片或者需要 GPU 资源来跑本地推理或者需要和另一个 agent 共享 workspace。这些需求原生调度器要么不支持要么需要写很复杂的 affinity 规则。这就是为什么需要一个 agentic orchestrator 层它站在 Kubernetes 之上把 agent 的语义需求翻译成 Kubernetes 能理解的调度原语。2.2 ax 的核心抽象Agent、Workspace、Task 三元组ax 的设计里最核心的三个概念是 Agent、Workspace、Task。Agent 是执行单元它封装了一个具体的 agentic 能力比如“代码生成 agent”、“数据检索 agent”、“报告撰写 agent”。Workspace 是状态载体它可以是 emptyDir临时、PVC持久、或者 ConfigMap只读配置。Task 是调度单元它描述了一次具体的执行请求用哪个 Agent、挂哪个 Workspace、跑在什么资源约束下、优先级多高、超时多久。这三个概念的关系是一个 Task 绑定一个 Agent 和一个 Workspaceorchestrator 负责把 Task 调度到合适的节点上Kubernetes 负责实际拉起 Pod。为什么这样设计因为 agentic 场景下同一个 Agent 可能被多个 Task 复用同一个 Workspace 可能被多个 Agent 共享。如果把 Agent 和 Workspace 硬编码在一起复用性就很差。拆成三元组之后你可以灵活组合Agent A 加 Workspace X 跑一个任务Agent B 加 Workspace X 跑另一个任务两者共享中间数据但互不干扰执行。这里有个关键决策Workspace 的生命周期管理。我试过两种方案。方案一是 Workspace 随 Task 创建、随 Task 销毁优点是干净缺点是如果 Task 需要重试中间状态就丢了。方案二是 Workspace 独立于 Task 存在Task 只是“借用”它优点是重试友好缺点是垃圾回收需要额外逻辑。最终我选了方案二但加了一个 TTL 机制Workspace 创建时打上 TTL 标签orchestrator 定期扫描超过 TTL 且没有活跃 Task 引用的 Workspace 自动回收。这个 TTL 默认设 24 小时可以通过注解覆盖。2.3 调度策略的取舍Bin Packing 还是 Spread调度策略上ax 面临一个经典选择是把 agent 尽量塞到少数节点上Bin Packing还是尽量分散到多个节点上Spread。Bin Packing 的优点是资源利用率高缺点是单点故障影响面大。Spread 的优点是隔离性好缺点是资源碎片化。我的选择是混合策略对于无状态的、短生命周期的 agent比如单次问答用 Bin Packing因为它们挂了重启成本低对于有状态的、长生命周期的 agent比如持续运行的监控 agent用 Spread因为它们挂了恢复成本高。这个策略通过给 Task 打上ax.io/lifecycle标签来实现orchestrator 根据标签选择不同的调度 profile。具体实现上Bin Packing 用podAffinity加preferredDuringSchedulingIgnoredDuringExecutionSpread 用podAntiAffinity加同样的 preferred 规则。为什么不用 required因为 required 太刚性节点资源不足时会导致 Pod 一直 Pending。preferred 允许调度器在条件不满足时降级保证可用性优先。3. 核心细节解析与实操要点Workspace 挂载与 Agent 生命周期3.1 Workspace 的三种挂载模式及选择依据Workspace 在 ax 里有三种挂载模式对应不同的使用场景。第一种是emptyDir挂载到 Pod 的/workspace目录生命周期和 Pod 绑定。适合纯计算型 agent比如代码解释器中间产物不需要持久化。第二种是persistentVolumeClaim挂载到同一个路径生命周期独立于 Pod。适合需要跨 Task 共享数据的 agent比如一个 agent 生成数据集另一个 agent 消费数据集。第三种是configMap或secret只读挂载适合存放 agent 的配置文件、提示词模板、API 凭证。选择依据很简单问自己三个问题。第一这个 workspace 里的数据Pod 重启后还需要吗需要就用 PVC不需要就用 emptyDir。第二这个 workspace 里的数据需要被其他 Pod 读取吗需要就用 PVC 加ReadWriteMany访问模式不需要就用ReadWriteOnce。第三这个 workspace 里的数据是静态配置还是动态生成静态就用 ConfigMap动态就用 PVC。这里有个坑ReadWriteMany不是所有存储类都支持。我踩过的坑是在某个云厂商的默认存储类上创建了ReadWriteMany的 PVC结果 Pod 一直卡在 ContainerCreating事件里报FailedMount。排查后发现是存储类不支持多节点读写。解决方案是换用支持 NFS 或 CephFS 的存储类或者改用对象存储加 initContainer 同步。如果你的环境没有共享存储一个退而求其次的方案是每个 Pod 用独立的 emptyDir通过一个 sidecar 容器做定期同步但一致性会弱一些。3.2 Agent 容器的启动流程与 initContainer 的作用一个 ax agent 的 Pod 里通常有三个容器initContainer、主 agent 容器、sidecar 容器。initContainer 负责准备工作空间比如从对象存储拉取初始数据、解压数据集、设置目录权限。主 agent 容器跑实际的 agentic 逻辑。sidecar 容器负责日志收集、指标暴露、或者 workspace 同步。为什么要把准备工作放在 initContainer 而不是主容器里因为 initContainer 和主容器的生命周期是分离的initContainer 跑完就退出不占用主容器的资源配额。而且 initContainer 可以按顺序执行多个每个负责一个独立的准备步骤失败时更容易定位问题。我见过有人把所有准备工作塞进主容器的 entrypoint 脚本里结果脚本一长调试起来非常痛苦而且主容器的资源配额被准备工作占了一部分agent 实际能用的资源就少了。initContainer 的一个常见用途是等待依赖就绪。比如 agent 需要访问一个向量数据库但数据库可能还没启动。可以在 initContainer 里跑一个循环用nc -z或curl探测数据库端口直到通了再退出。这样主容器启动时依赖一定是就绪的。注意要设置合理的超时否则 initContainer 会一直卡住Pod 永远起不来。我一般设 300 秒超时超过就失败让 orchestrator 决定是重试还是告警。3.3 资源配额与 QoS 等级的设置经验Agent 的资源需求差异很大。一个简单的检索 agent 可能只需要 100m CPU、128Mi 内存一个跑本地推理的 agent 可能需要 4 核 CPU、16Gi 内存、甚至一张 GPU。ax 的做法是让 Task 描述里显式声明资源需求orchestrator 负责校验和调度。这里的关键是QoS 等级的选择。Kubernetes 有三种 QoSGuaranteed、Burstable、BestEffort。Guaranteed 要求 requests 等于 limits适合对延迟敏感的 agent。Burstable 允许 requests 小于 limits适合有突发流量的 agent。BestEffort 不设 requests 和 limits适合完全不在乎性能的后台任务。我的经验是生产环境的 agent 一律用 Guaranteed 或 Burstable不用 BestEffort。因为 BestEffort 的 Pod 在节点资源紧张时最先被驱逐agent 跑到一半被驱逐中间状态丢失用户体验很差。如果实在不确定资源需求先用 Burstable设一个保守的 requests 和一个宽松的 limits跑一段时间后看监控数据再调整。调整的时候注意limits 不是越高越好设太高会导致节点超卖多个 agent 同时跑时互相争抢反而更慢。GPU 资源的声明要特别小心。Kubernetes 里 GPU 是扩展资源写法是nvidia.com/gpu: 1。注意 GPU 不支持超卖一个 GPU 只能分配给一个 Pod。如果你的 agent 只是偶尔用 GPU可以考虑用 MIGMulti-Instance GPU或者时间片共享但这需要节点层面的配置不是所有环境都支持。4. 实操过程与核心环节实现从零搭建一个 ax 调度层4.1 环境准备与前置检查在开始之前你需要一个可用的 Kubernetes 集群版本建议 1.26 及以上。为什么是 1.26因为 1.26 引入了PodSchedulingReadiness特性允许 Pod 在准备好之前不参与调度这对 agent 场景很有用——agent 可能需要先加载模型权重再接受任务。另外 1.26 的kubectl对--subresource的支持更完善调试起来方便。前置检查清单如下。第一确认集群有可用的存储类kubectl get storageclass能看到至少一个非 default 的存储类。第二确认节点有足够的资源kubectl describe nodes看 Allocatable 和 Allocated 的差值。第三确认你有 cluster-admin 权限因为要创建 CRD 和 ClusterRole。第四确认网络插件支持 NetworkPolicy因为 agent 之间可能需要网络隔离。如果是在 Windows 上做开发注意一个常见问题某些 agent 运行时需要虚拟化平台支持。如果你在 Windows 上跑 Docker Desktop需要在 BIOS 里开启虚拟化并在 Docker Desktop 设置里启用 WSL2 后端。这个坑我踩过报错信息通常是requires the virtual machine platform on windows解决方案是在“启用或关闭 Windows 功能”里勾选“虚拟机平台”和“适用于 Linux 的 Windows 子系统”然后重启。4.2 定义 Agent 和 Task 的 CRDax 的核心是两组 CRDAgent 和 Task。Agent 描述一个可复用的执行单元Task 描述一次具体的执行请求。下面是我实际使用的 CRD 定义做了简化去掉了部分生产环境才需要的字段。apiVersion: apiextensions.k8s.io/v1 kind: CustomResourceDefinition metadata: name: agents.ax.io spec: group: ax.io versions: - name: v1alpha1 served: true storage: true schema: openAPIV3Schema: type: object properties: spec: type: object properties: image: type: string command: type: array items: type: string workspaceMode: type: string enum: [emptyDir, pvc, configMap] defaultResources: type: object properties: cpu: type: string memory: type: string scope: Namespaced names: plural: agents singular: agent kind: Agent shortNames: - agTask 的 CRD 类似但多了agentRef、workspaceRef、priority、timeoutSeconds这些字段。为什么用 CRD 而不是 ConfigMap因为 CRD 有 schema 校验写错了字段名会直接报错而 ConfigMap 不会。而且 CRD 可以被 RBAC 精细控制比如只允许某个 ServiceAccount 创建 Task不允许修改 Agent。创建完 CRD 后用kubectl get crd | grep ax.io确认。如果看到agents.ax.io和tasks.ax.io说明创建成功。接下来要写一个 controller 来监听这些资源。controller 可以用 client-go 写也可以用 kubebuilder 生成骨架。我推荐 kubebuilder因为它帮你处理了 informer、workqueue、leader election 这些样板代码你只需要关注 reconcile 逻辑。4.3 Orchestrator 的 Reconcile 逻辑与调度决策Orchestrator 的核心是一个 reconcile 循环监听 Task 的创建事件读取 Task 的 spec找到对应的 Agent生成一个 Pod 的 spec提交给 Kubernetes API Server。这个过程中有几个关键决策点。第一个决策点是节点选择。Orchestrator 需要根据 Task 的资源需求、Workspace 的访问模式、Agent 的亲和性规则计算出一个候选节点列表。我的做法是先用 Kubernetes 的NodeAffinity做粗筛再用自定义的评分函数做细排。评分函数考虑三个因子节点剩余资源、节点上已有 agent 的数量、节点到存储的网络延迟。权重分别是 0.5、0.3、0.2。这个权重不是拍脑袋定的是跑了一周的 benchmark 后调出来的。如果你的场景对网络延迟特别敏感可以把第三个因子的权重调高。第二个决策点是并发控制。同一个 Agent 可能同时被多个 Task 引用如果无限制地创建 Pod节点资源很快会被打满。我的做法是给每个 Agent 设一个maxConcurrency字段orchestrator 在 reconcile 时检查当前活跃的 Pod 数量超过阈值就把 Task 放进一个等待队列等有 Pod 退出后再调度。等待队列用 Kubernetes 的workqueue实现支持优先级排序。第三个决策点是超时与重试。Task 的 spec 里有timeoutSeconds和maxRetries。orchestrator 在创建 Pod 时会设置一个activeDeadlineSeconds等于 Task 的超时时间。Pod 超时后会被 Kubernetes 自动终止orchestrator 监听到终止事件检查重试次数如果没超过上限就重新创建 Pod超过就标记 Task 为 Failed。注意activeDeadlineSeconds是从 Pod 启动开始算的不包括调度等待时间。如果你希望包括调度时间需要在 orchestrator 层面自己计时。4.4 一个完整的 Task 执行示例下面是一个完整的 Task YAML展示了如何引用一个 Agent、挂载一个 PVC Workspace、设置资源约束和超时。apiVersion: ax.io/v1alpha1 kind: Task metadata: name: code-review-task-001 namespace: agentic labels: ax.io/lifecycle: short ax.io/priority: high spec: agentRef: name: code-review-agent workspaceRef: name: shared-repo-pvc mountPath: /workspace/repo resources: requests: cpu: 2 memory: 4Gi limits: cpu: 4 memory: 8Gi timeoutSeconds: 1800 maxRetries: 2 env: - name: REVIEW_DEPTH value: deep - name: OUTPUT_FORMAT value: markdown提交这个 Task 后orchestrator 会在几秒内创建一个 Pod。你可以用kubectl get tasks -n agentic看 Task 状态用kubectl get pods -n agentic -l ax.io/taskcode-review-task-001看 Pod 状态。Pod 的日志里会输出 agent 的执行过程。如果一切正常Task 状态会从 Pending 变成 Running最后变成 Succeeded。这里有个细节workspaceRef里的shared-repo-pvc必须提前创建好并且和 Task 在同一个 namespace。如果 PVC 不存在orchestrator 会报错Task 卡在 Pending。我建议在创建 Task 之前先用kubectl get pvc -n agentic确认 PVC 存在且状态是 Bound。5. 常见问题与排查技巧实录5.1 Workspace 挂载失败从事件里找线索Workspace 挂载失败是最常见的问题表现是 Pod 卡在 ContainerCreatingkubectl describe pod的 Events 里会有FailedMount或FailedAttachVolume。排查思路分三步。第一步确认 PVC 状态kubectl get pvc -n namespace如果是 Pending说明存储类没有正确配置或者没有可用的 PV。第二步确认访问模式kubectl get pvc -o yaml看accessModes如果是ReadWriteMany但存储类不支持就会挂载失败。第三步确认节点和存储的网络连通性如果是 NFS 或 CephFS检查节点的防火墙规则和路由表。我遇到过一个比较隐蔽的问题PVC 状态是 Bound访问模式也对但 Pod 就是挂不上。排查后发现是存储类的volumeBindingMode设成了WaitForFirstConsumer而 Pod 的调度被一个不满足的 nodeAffinity 卡住了导致 PV 一直没有绑定到具体节点。解决方案是放宽 nodeAffinity或者把volumeBindingMode改成Immediate。但Immediate有它自己的问题可能导致 PV 绑定到一个没有 Pod 的节点上造成资源浪费。所以更推荐的做法是保留WaitForFirstConsumer但确保 nodeAffinity 不会把 Pod 卡死。5.2 Agent 启动卡住从 initContainer 日志入手Agent 启动卡住表现是 Pod 状态是 Running但主容器一直没有输出或者 initContainer 一直不退出。排查思路是先用kubectl logs pod -c init-container-name看 initContainer 的日志。如果日志停在某一步不动说明那一步卡住了。常见原因有三个等待依赖超时、下载数据太慢、权限不足。等待依赖超时是最常见的。比如 initContainer 在等一个数据库但数据库地址配错了或者网络策略不允许访问。解决方案是检查环境变量和 NetworkPolicy。下载数据太慢通常是对象存储的带宽问题可以考虑用 CDN 或者预先把数据打包进镜像。权限不足通常是 PVC 的fsGroup没设对导致容器里的非 root 用户无法写入。解决方案是在 Pod 的 securityContext 里设置fsGroup值等于容器里运行用户的 GID。还有一个坑是setting up workspace: loading packages...卡住。这个报错通常出现在 agent 启动时加载依赖包的阶段。原因可能是包管理器在等待网络或者包源不可达。解决方案是检查容器的网络策略确认允许访问包源或者预先在镜像里把依赖装好避免运行时下载。5.3 调度失败Pending Pod 的排查路径Task 创建后Pod 一直 Pendingkubectl describe pod的 Events 里会有FailedScheduling。排查路径如下。第一看 Events 里的具体原因常见的有Insufficient cpu、Insufficient memory、node(s) had taint、node(s) didnt match node selector。第二根据原因调整。如果是资源不足要么降低 requests要么加节点。如果是 taint要么去掉 taint要么给 Pod 加 toleration。如果是 node selector 不匹配检查标签是否正确。我遇到过一个比较特殊的情况节点资源明明够但 Pod 就是调度不上去。排查后发现是节点的Allocatable和Capacity有差异Capacity是物理资源Allocatable是扣除了系统预留之后的资源。如果 requests 设得比Allocatable大就会调度失败。解决方案是用kubectl describe node看Allocatable的实际值而不是看Capacity。5.4 常见问题速查表问题现象可能原因排查命令解决方案Pod 卡在 ContainerCreatingPVC 挂载失败kubectl describe pod检查 PVC 状态和访问模式initContainer 不退出依赖未就绪或超时kubectl logs -c init检查依赖地址和网络策略Pod 一直 Pending资源不足或亲和性不匹配kubectl describe pod调整 requests 或节点标签Agent 启动后无输出主容器 entrypoint 错误kubectl logs检查 command 和 argsTask 超时未终止activeDeadlineSeconds 未设kubectl get task -o yaml补设超时字段Workspace 数据丢失emptyDir 随 Pod 销毁kubectl get pod -o yaml改用 PVC 挂载多个 Agent 互相干扰缺少网络隔离kubectl get networkpolicy添加 NetworkPolicyGPU 资源无法分配驱动或插件未装kubectl describe node安装 GPU operator5.5 几个我踩过的坑和对应的技巧第一个坑是Task 的 namespace 和 Agent 的 namespace 不一致。ax 的设计里Agent 是 namespace 级别的资源Task 只能引用同 namespace 的 Agent。我一开始没注意把 Agent 建在defaultTask 建在agentic结果 orchestrator 一直报agent not found。解决方案是要么把 Agent 和 Task 放同一个 namespace要么把 Agent 改成 Cluster 级别的资源。我选了前者因为 namespace 隔离更清晰。第二个坑是PVC 的容量规划。Agent 产生的中间数据可能比预期大很多PVC 满了之后写入失败agent 报错退出。解决方案是给 PVC 设一个合理的容量并在 orchestrator 里加一个监控当 PVC 使用率超过 80% 时告警。另外可以给 Workspace 加一个清理策略Task 成功后自动删除临时文件只保留最终产物。第三个坑是日志太多导致节点磁盘满。Agent 的日志如果直接写到 stdout会被 Kubernetes 的日志驱动收集到节点磁盘上。如果 agent 输出很频繁节点磁盘很快会满。解决方案是给容器的日志设一个大小限制在 Pod 的 spec 里加logging配置或者用 sidecar 把日志转发到远端存储。我一般用 Fluent Bit 做 sidecar配置简单资源占用也小。第四个坑是Agent 之间的时钟不同步。如果多个 agent 协作时间戳不一致会导致排序错乱。解决方案是确保所有节点都开启了 NTP 同步或者在 agent 层面统一用 UTC 时间。这个坑比较隐蔽因为单机测试时不会出现只有多节点部署时才暴露。6. 从 ax 出发Agentic Orchestration 的边界与延伸ax 这套东西跑通之后我最大的体会是agentic orchestration 的难点不在调度算法而在状态管理。传统微服务的调度是无状态的请求来了就处理处理完就结束。Agent 不一样它有一个持续演进的 workspace这个 workspace 里可能有半成品的数据、未完成的推理链、待确认的中间结果。调度器不仅要决定“在哪里跑”还要决定“状态怎么迁移”、“失败怎么恢复”、“并发怎么隔离”。这三个问题Kubernetes 原生能力只能解决一部分剩下的需要 orchestrator 层来补。如果你想把 ax 的思路用到自己的项目里我的建议是从小处着手。先不要搞复杂的 CRD 和 controller用一个简单的 Job 加一个 PVC 就能跑起来。等遇到瓶颈了再逐步引入 orchestrator。比如当你发现需要动态调整资源配额时引入一个简单的 admission webhook当你发现需要跨 Task 共享 workspace 时引入一个 workspace 管理器当你发现需要优先级调度时引入一个自定义调度器。每一步都解决一个具体问题而不是一开始就设计一个大而全的架构。另外agentic 场景下的可观测性和传统微服务很不一样。传统微服务看 QPS、延迟、错误率就够了agent 还需要看推理步数、工具调用次数、workspace 大小变化、中间结果的语义一致性。这些指标目前没有标准方案需要自己埋点。我一般会在 agent 的代码里加一个轻量的 metrics 库把关键事件打成 Prometheus 指标然后用 Grafana 做面板。这个投入是值得的因为 agent 的行为很难预测没有可观测性就等于盲人摸象。最后分享一个我在实际使用中的小技巧给每个 Task 的 Pod 加一个ax.io/task-id标签值就是 Task 的名字。这样排查问题时可以用kubectl get pods -l ax.io/task-idtask-name快速找到对应的 Pod不用在几十个 Pod 里翻。这个标签还可以用来做日志聚合Fluent Bit 可以根据标签把日志路由到不同的索引里。成本很低但排查效率提升很明显。