1. 从ax这个标题说起一个被低估的调度原语第一次看到ax这个标题很多人会以为是某个命令行工具的缩写或者某个内部项目的代号。但把热搜词摊开来看——ax、agentic、orchestration、kubernetes、workspace——这几个词凑在一起指向的其实是一个非常具体的技术命题在 Kubernetes 之上为 agentic 工作负载做一层调度与工作区编排。我先把结论摆在前面ax 在这里不是一个具体的开源项目名而更像是一类agent 调度层的统称。它要解决的问题是——当你的系统里不再只有无状态的 HTTP 服务而是一堆会思考、会调工具、会长时间运行、会互相委派的 agent 时Kubernetes 原生的 Deployment/Service 模型就不够用了。你需要一个中间层把agent 的生命周期翻译成Kubernetes 能听懂的调度指令。这篇文章适合三类人看一是正在把 LLM 应用往生产环境搬的后端工程师二是已经在用 Kubernetes、但发现 agent 工作负载总是跑着跑着就卡住的 SRE三是想搞清楚 agentic orchestration 到底和传统微服务编排差在哪里的技术负责人。我会从设计思路、核心机制、实操落地、排错经验四个层面把这个东西拆开讲透。先给一个生活化的类比。传统微服务像快餐店每个窗口只做一件事来一个订单处理一个处理完就空闲。Agent 更像一个项目组有人负责调研有人负责写代码有人负责验收中间还要开会同步进度一个任务可能跑几小时甚至几天。你不能用管理快餐店的方式去管理项目组——这就是 ax 这类调度层存在的根本理由。2. ax 调度层的整体设计与选型逻辑2.1 为什么原生 Kubernetes 编排 agent 会水土不服Kubernetes 的设计哲学是声明式 最终一致。你告诉它我要 3 个副本它就维持 3 个副本。这个模型对无状态服务极其优雅但 agent 工作负载有三个特性和它天然冲突。第一是长时运行与状态保持。一个 agent 可能在执行一个多步任务中间调用了外部 API、写了临时文件、维护了对话上下文。如果这时候 Pod 被驱逐或重启整个任务上下文就丢了。Kubernetes 默认的重启策略是Always它假设你的进程是无状态的、重启无所谓的——这对 agent 是灾难。第二是资源需求的动态性。Agent 在思考阶段可能几乎不占 CPU但在调用工具、跑代码解释器、做向量检索时资源需求会瞬间飙升。用固定的requests/limits去框它要么浪费要么 OOM。第三是协作与依赖关系。多个 agent 之间可能存在父 agent 派生子 agent的树状结构或者agent A 等 agent B 的结果的依赖关系。Kubernetes 的 Service 只解决网络可达性不解决谁等谁、谁先谁后的编排语义。我踩过的最典型的一个坑早期直接把 agent 塞进 Deployment结果一个跑 RAG 的 agent 因为检索超时被 liveness probe 判定为死掉Pod 重启上下文全丢用户看到的是回答到一半突然从头开始。这个问题的根因不是 probe 配置错了而是用无状态的心跳去探测有状态的任务模型本身就不匹配。2.2 ax 调度层的三层架构拆解基于上面这些痛点ax 这类调度层通常会拆成三层。我用一张表把每层的职责和对应到 Kubernetes 的映射讲清楚。层级职责对应 K8s 原语关键设计点接入层接收任务、鉴权、路由到合适的 agentIngress / Gateway API任务 ID 与 trace ID 绑定编排层决定任务由哪个 agent 执行、如何拆分、如何合并自定义 CRD Controller状态机驱动而非副本数驱动执行层真正跑 agent 进程、挂载 workspace、管理生命周期Pod / Job / 自定义 Runtimeworkspace 持久化与隔离这里最关键的是编排层用 CRD 而不是 Deployment。为什么因为 CRD 允许你把一个 agent 任务建模成一个有状态的对象它有明确的阶段Pending - Planning - Executing - WaitingForTool - Completed/Failed。Controller 监听这个对象的状态变化在WaitingForTool阶段可以主动挂起资源在Executing阶段再拉起。这就是所谓的状态机驱动和 Deployment 的副本数驱动是两种完全不同的心智模型。提示如果你现在还在用 Deployment 跑 agent先别急着推翻重来。可以先用 Job 替代 Deployment因为 Job 天然支持跑完即止和失败重试次数控制是向 CRD 过渡的最低成本方案。2.3 workspace 为什么是 ax 的核心概念热搜词里反复出现 workspace这不是偶然。Agent 和普通服务的最大区别之一就是它需要一个可读写、可持久、可隔离的工作区。这个 workspace 里可能有下载的数据文件、生成的中间代码、向量索引、对话历史、工具调用的缓存。在 Kubernetes 里实现 workspace 有三种主流方案我实测下来各有取舍emptyDir最简单Pod 内容器共享但 Pod 一删就没了。适合纯临时任务。PVCPersistentVolumeClaim持久化但 ReadWriteOnce 模式下没法多 Pod 共享ReadWriteMany 又依赖具体的存储插件NFS、CephFS 等运维成本高。对象存储挂载如 S3 CSI扩展性最好但延迟高不适合频繁小文件读写。我的经验是agent 的 workspace 应该分两层。热数据当前任务的临时文件放 emptyDir冷数据需要跨任务复用的索引、模型缓存放 PVC 或对象存储。这样既保证了性能又保证了持久性。热搜里那条 setting up workspace: loading packages...卡住 的报错十有八九就是 workspace 挂载了一个网络存储而加载依赖包时网络抖动导致卡死。3. agentic orchestration 的核心机制与实操要点3.1 agent 生命周期管理从 Pod 到 AgentRuntime要让 Kubernetes 真正理解agent你需要定义一个比 Pod 更上层的抽象。我把它叫做 AgentRuntime本质上是一个 CRD。它的 spec 大概长这样apiVersion: ax.io/v1alpha1 kind: AgentRuntime metadata: name: research-agent-001 spec: agentImage: registry.example.com/research-agent:v1.2 workspace: hot: type: emptyDir sizeLimit: 2Gi cold: type: pvc claimName: agent-cache-pvc lifecycle: maxIdleSeconds: 300 checkpointOnSuspend: true resumeStrategy: fromCheckpoint resources: planning: requests: { cpu: 100m, memory: 256Mi } executing: requests: { cpu: 2, memory: 4Gi } limits: { cpu: 4, memory: 8Gi }注意这里我把 resources 拆成了planning和executing两档。这是 ax 调度层一个很实用的设计agent 在不同阶段用不同的资源档位。Planning 阶段只是调 LLM 做推理资源需求低Executing 阶段可能要跑代码、做检索资源需求高。Controller 根据当前状态动态调整 Pod 的 resource或者干脆用两个不同的 Pod 模板切换。checkpointOnSuspend这个字段是我强烈建议加的。Agent 被挂起比如等待人工审批、等待外部回调时把当前上下文序列化到 cold workspace。恢复时从 checkpoint 读回来。这样即使 Pod 被回收任务也不会丢。热搜里 power dc theres no valid workspace data to simulate 这类报错本质就是恢复时找不到有效的 checkpoint 数据。3.2 调度策略为什么不能只用默认调度器Kubernetes 默认调度器考虑的是 CPU、内存、亲和性这些维度。但 agent 调度还需要考虑几个额外维度模型亲和性某个 agent 需要访问本地缓存的模型文件最好调度到已经缓存了该模型的节点。工具亲和性agent 要调用的工具服务比如代码沙箱、浏览器渲染服务在哪个节点agent 就应该尽量靠近。成本感知不同节点池的价格差异可能很大批处理类 agent 应该优先调度到廉价节点。实现方式有两种。轻量方案是用nodeAffinitytaints/tolerations打标签把节点按是否缓存了模型是否属于廉价池分类。重量方案是写一个自定义调度器Scheduler Extender 或 Scheduling Framework 插件在打分阶段加入这些维度。我个人的建议是先用标签方案等真的遇到调度瓶颈再上自定义调度器。因为自定义调度器的维护成本很高Kubernetes 版本升级时经常要跟着改。标签方案虽然粗糙但胜在稳定、可观测、好排查。3.3 多 agent 协作的编排模式Agentic orchestration 最有意思的部分是多个 agent 怎么协作。我总结下来有三种常见模式对应不同的 CRD 设计。第一种是编排式Orchestrator-Worker。一个主 agent 负责拆解任务派生出一堆子 agent 并行执行最后汇总。这种模式在 CRD 里体现为父子关系父 AgentRuntime 的 status 里维护一个子任务列表。Kubernetes 层面可以用 Job 的completions和parallelism来控制并发度。第二种是流水线式Pipeline。Agent A 的输出是 Agent B 的输入像工厂流水线。这种模式适合用 Argo Workflows 或 Tekton 这类工作流引擎来编排每个 agent 是一个 step。好处是可观测性强每一步的输入输出都有记录。第三种是协商式Peer-to-Peer。多个 agent 平等协作通过消息队列或共享 workspace 交换信息。这种模式最难做因为要处理死锁、活锁、消息丢失。我的经验是除非业务真的需要否则尽量用前两种协商式的调试成本高得离谱。注意无论用哪种模式都要给 agent 之间的调用设置超时和熔断。我见过一个案例agent A 等 agent Bagent B 等 agent Cagent C 又因为某个工具超时卡住结果整条链路全部挂起Kubernetes 层面看起来一切正常Pod 都是 Running但业务已经死了。这种假活状态是最难排查的。4. 在 Kubernetes 上落地 ax 的完整实操流程4.1 环境准备与版本选择热搜里出现了 using kubernetes version: v1.26.0 和 preflight running pre-flight checks说明很多人在用 kubeadm 部署集群。我给一个明确的版本建议如果要跑 agentic 工作负载Kubernetes 版本不要低于 1.26。原因是 1.26 引入了 Pod Scheduling ReadinessschedulingGates这个特性对 agent 特别有用——你可以让 Pod 先创建但不调度等 workspace 准备好、模型加载完再移除 gate 让它开始调度。集群规格上我建议至少三个节点一个控制面两个工作节点。工作节点配置看你的 agent 类型如果跑本地小模型内存至少 32G如果只是调外部 API16G 够用。存储方面如果要用 PVC 做 cold workspace提前规划好 StorageClass。安装完集群后第一件事是装这几个组件# 安装 CRD 框架用于定义 AgentRuntime kubectl apply -f https://example.com/ax-crd-framework.yaml # 安装自定义 controller helm install ax-controller ax/ax-controller \ --namespace ax-system \ --create-namespace \ --set replicaCount2 # 验证 kubectl get crd | grep ax.io kubectl -n ax-system get pods4.2 定义第一个 AgentRuntime 并跑起来环境好了之后写一个最小的 AgentRuntime。我建议从最简单的开始不要一上来就搞多 agent 协作。apiVersion: ax.io/v1alpha1 kind: AgentRuntime metadata: name: hello-agent namespace: default spec: agentImage: registry.example.com/hello-agent:v0.1 workspace: hot: type: emptyDir sizeLimit: 1Gi lifecycle: maxIdleSeconds: 120 checkpointOnSuspend: false resources: executing: requests: { cpu: 500m, memory: 512Mi } limits: { cpu: 1, memory: 1Gi } task: input: 帮我统计当前 workspace 下的文件数量 timeoutSeconds: 300应用之后观察 controller 的行为kubectl apply -f hello-agent.yaml kubectl get agentruntime hello-agent -w你会看到 status 从Pending变成Executing然后变成Completed。如果卡在Pending大概率是镜像拉不下来或者资源不足。如果卡在Executing超过 timeoutcontroller 会把它标记为Failed并触发重试。这里有个细节值得说timeout 不要设得太短。Agent 调 LLM 的延迟波动很大同一个任务可能 10 秒完成也可能 3 分钟。我一般设 300 秒起步复杂任务设 1800 秒。设太短会导致任务被误杀设太长会导致资源被僵尸任务占着。4.3 workspace 的挂载与隔离实操Workspace 的挂载是实操中最容易出问题的地方。我给出一个经过验证的配置模板spec: workspace: hot: type: emptyDir sizeLimit: 2Gi medium: Memory # 关键用内存盘读写快 cold: type: pvc claimName: agent-cache-pvc mountPath: /workspace/cache securityContext: runAsNonRoot: true runAsUser: 1000 fsGroup: 1000 readOnlyRootFilesystem: true几个要点解释一下。medium: Memory让 emptyDir 用 tmpfs读写速度比磁盘快一个数量级适合 agent 频繁读写临时文件的场景。但要注意它占的是内存sizeLimit一定要设否则可能把节点内存吃光。fsGroup是为了让挂载的 PVC 对非 root 用户可写这个坑我踩过——不设 fsGroupagent 进程以非 root 运行时会报 permission denied。readOnlyRootFilesystem: true是安全加固防止 agent 往容器文件系统里写东西所有写入都必须走 workspace。隔离方面如果多个 agent 共享一个节点建议用RuntimeClass配合 gVisor 或 Kata Containers 做沙箱。因为 agent 可能会执行 LLM 生成的代码这些代码是不可信的。普通容器共享内核隔离性不够。gVisor 会带来一定的性能损耗大概 10%-30%但安全性提升明显。4.4 可观测性怎么知道 agent 到底在干什么Agent 的可观测性和普通服务不一样。普通服务你看 QPS、延迟、错误率就够了。Agent 你还需要看当前在哪个阶段、调了哪些工具、LLM 的 token 消耗、上下文长度、有没有陷入循环。我的做法是三层埋点。第一层是 Kubernetes 层面用kubectl describe agentruntime看状态流转。第二层是 agent 进程内部用 OpenTelemetry 打 trace每个工具调用是一个 span。第三层是业务层面把 agent 的决策过程比如我决定调用搜索工具作为结构化日志输出。# agent 内部的埋点示例 from opentelemetry import trace tracer trace.get_tracer(ax.agent) def call_tool(tool_name, params): with tracer.start_as_current_span(ftool.{tool_name}) as span: span.set_attribute(tool.params, str(params)) result do_call(tool_name, params) span.set_attribute(tool.result_size, len(str(result))) return result这样出问题时你可以顺着 trace 看到底是哪一步慢、哪一步错。热搜里 failed to start claudes workspace request error: net::err_connection_timed 这类错误如果有完整的 trace一眼就能看出是网络问题还是配置问题。5. 常见问题与排查技巧实录5.1 workspace 相关报错速查Workspace 是报错重灾区我把常见的几个整理成表。报错信息根因解决方向setting up workspace: loading packages...卡住网络存储挂载慢或依赖源不可达检查 PVC 后端存储健康度换用本地盘或加超时no valid workspace data to simulatecheckpoint 缺失或路径不对检查 cold workspace 挂载路径与 checkpoint 写入路径是否一致permission denied on /workspacefsGroup 未设置或 UID 不匹配设置 fsGroup确认容器内进程 UIDworkspace sizeLimit exceededemptyDir 写满调大 sizeLimit 或清理临时文件5.2 agent 卡死与假活排查Agent 卡死是最头疼的问题因为 Kubernetes 层面看起来一切正常。我的排查顺序是这样的。第一步看 agent 的当前阶段。kubectl get agentruntime name -o yaml看 status.phase。如果是Executing但很久没变说明 agent 进程可能卡在某个工具调用上。第二步进 Pod 看进程状态。kubectl exec -it pod -- ps aux看 agent 主进程在干什么。如果是D状态不可中断睡眠大概率是 IO 卡住。如果是S状态可能在等网络。第三步看网络连接。kubectl exec -it pod -- netstat -anp看有没有大量SYN_SENT或CLOSE_WAIT。前者说明连不上外部服务后者说明连接没正确关闭。第四步看日志的最后几行。Agent 卡死前通常会打最后一条日志那条日志就是线索。提示给 agent 加一个心跳机制。Agent 每隔 30 秒往一个文件或 etcd 写一次心跳controller 检测到心跳超时就主动重启。这比 liveness probe 更可靠因为它是业务层面的不受网络抖动影响。5.3 资源与成本优化的几个实操心得跑了一段时间后你会发现 agent 的资源利用率其实很低。Planning 阶段 CPU 几乎为 0Executing 阶段才起来。如果一直按 Executing 的规格占着资源浪费很大。我的优化手段有三个。一是用 VPAVertical Pod Autoscaler的 Off 模式让它推荐资源规格但不自动改你根据推荐值手动调。二是用 KEDA 做事件驱动伸缩没有任务时把 agent 副本缩到 0有任务再拉起来。三是把冷 workspace 放到对象存储用的时候再拉下来省 PVC 成本。还有一个容易被忽略的点LLM 的 token 成本。Agent 跑久了上下文会越来越长token 消耗指数级增长。我的做法是定期做上下文压缩把历史对话总结成摘要只保留最近几轮原文。这个逻辑要写在 agent 内部Kubernetes 层面管不了。5.4 版本升级与兼容性坑Kubernetes 版本升级时CRD 的兼容性要特别注意。apiextensions.k8s.io/v1beta1在 1.22 就被移除了如果你的 CRD 还是这个版本升级会直接失败。另外自定义 controller 用的 client-go 版本要和集群版本匹配否则会出现 API 调用失败。我建议的升级流程是先在测试集群升级跑一遍完整的 agent 任务确认没问题再上生产。生产升级时用滚动方式先升一个节点观察 24 小时再升下一个。Agent 任务对中断敏感宁可慢一点也不要一次性全升。6. 我对 ax 这类调度层的一些个人判断写到这里我想分享几个不那么技术但很重要的观察。第一agentic orchestration 目前还没有事实标准。Kubernetes 生态里Karmada 这类多集群调度项目在往 agentic cloud 方向走但具体怎么和 agent 生命周期结合各家做法都不一样。这意味着现在投入学习收益是长期的但短期内可能要忍受 API 不稳定、文档不全的痛苦。第二workspace 的设计决定了 agent 系统的上限。我见过太多项目agent 逻辑写得很漂亮但 workspace 设计得一塌糊涂结果任务一复杂就各种状态丢失、数据不一致。我的建议是在写第一行 agent 代码之前先把 workspace 的读写路径、持久化策略、隔离级别想清楚。第三不要过度依赖 Kubernetes 的原生能力。Kubernetes 是给无状态服务设计的agent 是有状态的。硬套原生模型最后会写出一堆 workaround。该写 CRD 就写 CRD该写 controller 就写 controller这层抽象是值得的。最后分享一个小技巧如果你在 Windows 上开发想本地跑 agent 的 workspace 做调试可能会遇到 requires the virtual machine platform on windows 这类提示。这不是 Kubernetes 的问题是本地容器运行时需要开启虚拟化平台支持。在启用或关闭 Windows 功能里勾选虚拟机平台和适用于 Linux 的 Windows 子系统重启即可。这个坑我在本地调试时踩过折腾了半天才发现是系统功能没开。Agent 调度这件事本质上是在让机器自主干活和让运维能管住机器之间找平衡。ax 这类调度层就是那个平衡点。它不完美但方向是对的。
Kubernetes 上 Agentic 工作负载调度：ax 调度层与 workspace 编排实践
1. 从ax这个标题说起一个被低估的调度原语第一次看到ax这个标题很多人会以为是某个命令行工具的缩写或者某个内部项目的代号。但把热搜词摊开来看——ax、agentic、orchestration、kubernetes、workspace——这几个词凑在一起指向的其实是一个非常具体的技术命题在 Kubernetes 之上为 agentic 工作负载做一层调度与工作区编排。我先把结论摆在前面ax 在这里不是一个具体的开源项目名而更像是一类agent 调度层的统称。它要解决的问题是——当你的系统里不再只有无状态的 HTTP 服务而是一堆会思考、会调工具、会长时间运行、会互相委派的 agent 时Kubernetes 原生的 Deployment/Service 模型就不够用了。你需要一个中间层把agent 的生命周期翻译成Kubernetes 能听懂的调度指令。这篇文章适合三类人看一是正在把 LLM 应用往生产环境搬的后端工程师二是已经在用 Kubernetes、但发现 agent 工作负载总是跑着跑着就卡住的 SRE三是想搞清楚 agentic orchestration 到底和传统微服务编排差在哪里的技术负责人。我会从设计思路、核心机制、实操落地、排错经验四个层面把这个东西拆开讲透。先给一个生活化的类比。传统微服务像快餐店每个窗口只做一件事来一个订单处理一个处理完就空闲。Agent 更像一个项目组有人负责调研有人负责写代码有人负责验收中间还要开会同步进度一个任务可能跑几小时甚至几天。你不能用管理快餐店的方式去管理项目组——这就是 ax 这类调度层存在的根本理由。2. ax 调度层的整体设计与选型逻辑2.1 为什么原生 Kubernetes 编排 agent 会水土不服Kubernetes 的设计哲学是声明式 最终一致。你告诉它我要 3 个副本它就维持 3 个副本。这个模型对无状态服务极其优雅但 agent 工作负载有三个特性和它天然冲突。第一是长时运行与状态保持。一个 agent 可能在执行一个多步任务中间调用了外部 API、写了临时文件、维护了对话上下文。如果这时候 Pod 被驱逐或重启整个任务上下文就丢了。Kubernetes 默认的重启策略是Always它假设你的进程是无状态的、重启无所谓的——这对 agent 是灾难。第二是资源需求的动态性。Agent 在思考阶段可能几乎不占 CPU但在调用工具、跑代码解释器、做向量检索时资源需求会瞬间飙升。用固定的requests/limits去框它要么浪费要么 OOM。第三是协作与依赖关系。多个 agent 之间可能存在父 agent 派生子 agent的树状结构或者agent A 等 agent B 的结果的依赖关系。Kubernetes 的 Service 只解决网络可达性不解决谁等谁、谁先谁后的编排语义。我踩过的最典型的一个坑早期直接把 agent 塞进 Deployment结果一个跑 RAG 的 agent 因为检索超时被 liveness probe 判定为死掉Pod 重启上下文全丢用户看到的是回答到一半突然从头开始。这个问题的根因不是 probe 配置错了而是用无状态的心跳去探测有状态的任务模型本身就不匹配。2.2 ax 调度层的三层架构拆解基于上面这些痛点ax 这类调度层通常会拆成三层。我用一张表把每层的职责和对应到 Kubernetes 的映射讲清楚。层级职责对应 K8s 原语关键设计点接入层接收任务、鉴权、路由到合适的 agentIngress / Gateway API任务 ID 与 trace ID 绑定编排层决定任务由哪个 agent 执行、如何拆分、如何合并自定义 CRD Controller状态机驱动而非副本数驱动执行层真正跑 agent 进程、挂载 workspace、管理生命周期Pod / Job / 自定义 Runtimeworkspace 持久化与隔离这里最关键的是编排层用 CRD 而不是 Deployment。为什么因为 CRD 允许你把一个 agent 任务建模成一个有状态的对象它有明确的阶段Pending - Planning - Executing - WaitingForTool - Completed/Failed。Controller 监听这个对象的状态变化在WaitingForTool阶段可以主动挂起资源在Executing阶段再拉起。这就是所谓的状态机驱动和 Deployment 的副本数驱动是两种完全不同的心智模型。提示如果你现在还在用 Deployment 跑 agent先别急着推翻重来。可以先用 Job 替代 Deployment因为 Job 天然支持跑完即止和失败重试次数控制是向 CRD 过渡的最低成本方案。2.3 workspace 为什么是 ax 的核心概念热搜词里反复出现 workspace这不是偶然。Agent 和普通服务的最大区别之一就是它需要一个可读写、可持久、可隔离的工作区。这个 workspace 里可能有下载的数据文件、生成的中间代码、向量索引、对话历史、工具调用的缓存。在 Kubernetes 里实现 workspace 有三种主流方案我实测下来各有取舍emptyDir最简单Pod 内容器共享但 Pod 一删就没了。适合纯临时任务。PVCPersistentVolumeClaim持久化但 ReadWriteOnce 模式下没法多 Pod 共享ReadWriteMany 又依赖具体的存储插件NFS、CephFS 等运维成本高。对象存储挂载如 S3 CSI扩展性最好但延迟高不适合频繁小文件读写。我的经验是agent 的 workspace 应该分两层。热数据当前任务的临时文件放 emptyDir冷数据需要跨任务复用的索引、模型缓存放 PVC 或对象存储。这样既保证了性能又保证了持久性。热搜里那条 setting up workspace: loading packages...卡住 的报错十有八九就是 workspace 挂载了一个网络存储而加载依赖包时网络抖动导致卡死。3. agentic orchestration 的核心机制与实操要点3.1 agent 生命周期管理从 Pod 到 AgentRuntime要让 Kubernetes 真正理解agent你需要定义一个比 Pod 更上层的抽象。我把它叫做 AgentRuntime本质上是一个 CRD。它的 spec 大概长这样apiVersion: ax.io/v1alpha1 kind: AgentRuntime metadata: name: research-agent-001 spec: agentImage: registry.example.com/research-agent:v1.2 workspace: hot: type: emptyDir sizeLimit: 2Gi cold: type: pvc claimName: agent-cache-pvc lifecycle: maxIdleSeconds: 300 checkpointOnSuspend: true resumeStrategy: fromCheckpoint resources: planning: requests: { cpu: 100m, memory: 256Mi } executing: requests: { cpu: 2, memory: 4Gi } limits: { cpu: 4, memory: 8Gi }注意这里我把 resources 拆成了planning和executing两档。这是 ax 调度层一个很实用的设计agent 在不同阶段用不同的资源档位。Planning 阶段只是调 LLM 做推理资源需求低Executing 阶段可能要跑代码、做检索资源需求高。Controller 根据当前状态动态调整 Pod 的 resource或者干脆用两个不同的 Pod 模板切换。checkpointOnSuspend这个字段是我强烈建议加的。Agent 被挂起比如等待人工审批、等待外部回调时把当前上下文序列化到 cold workspace。恢复时从 checkpoint 读回来。这样即使 Pod 被回收任务也不会丢。热搜里 power dc theres no valid workspace data to simulate 这类报错本质就是恢复时找不到有效的 checkpoint 数据。3.2 调度策略为什么不能只用默认调度器Kubernetes 默认调度器考虑的是 CPU、内存、亲和性这些维度。但 agent 调度还需要考虑几个额外维度模型亲和性某个 agent 需要访问本地缓存的模型文件最好调度到已经缓存了该模型的节点。工具亲和性agent 要调用的工具服务比如代码沙箱、浏览器渲染服务在哪个节点agent 就应该尽量靠近。成本感知不同节点池的价格差异可能很大批处理类 agent 应该优先调度到廉价节点。实现方式有两种。轻量方案是用nodeAffinitytaints/tolerations打标签把节点按是否缓存了模型是否属于廉价池分类。重量方案是写一个自定义调度器Scheduler Extender 或 Scheduling Framework 插件在打分阶段加入这些维度。我个人的建议是先用标签方案等真的遇到调度瓶颈再上自定义调度器。因为自定义调度器的维护成本很高Kubernetes 版本升级时经常要跟着改。标签方案虽然粗糙但胜在稳定、可观测、好排查。3.3 多 agent 协作的编排模式Agentic orchestration 最有意思的部分是多个 agent 怎么协作。我总结下来有三种常见模式对应不同的 CRD 设计。第一种是编排式Orchestrator-Worker。一个主 agent 负责拆解任务派生出一堆子 agent 并行执行最后汇总。这种模式在 CRD 里体现为父子关系父 AgentRuntime 的 status 里维护一个子任务列表。Kubernetes 层面可以用 Job 的completions和parallelism来控制并发度。第二种是流水线式Pipeline。Agent A 的输出是 Agent B 的输入像工厂流水线。这种模式适合用 Argo Workflows 或 Tekton 这类工作流引擎来编排每个 agent 是一个 step。好处是可观测性强每一步的输入输出都有记录。第三种是协商式Peer-to-Peer。多个 agent 平等协作通过消息队列或共享 workspace 交换信息。这种模式最难做因为要处理死锁、活锁、消息丢失。我的经验是除非业务真的需要否则尽量用前两种协商式的调试成本高得离谱。注意无论用哪种模式都要给 agent 之间的调用设置超时和熔断。我见过一个案例agent A 等 agent Bagent B 等 agent Cagent C 又因为某个工具超时卡住结果整条链路全部挂起Kubernetes 层面看起来一切正常Pod 都是 Running但业务已经死了。这种假活状态是最难排查的。4. 在 Kubernetes 上落地 ax 的完整实操流程4.1 环境准备与版本选择热搜里出现了 using kubernetes version: v1.26.0 和 preflight running pre-flight checks说明很多人在用 kubeadm 部署集群。我给一个明确的版本建议如果要跑 agentic 工作负载Kubernetes 版本不要低于 1.26。原因是 1.26 引入了 Pod Scheduling ReadinessschedulingGates这个特性对 agent 特别有用——你可以让 Pod 先创建但不调度等 workspace 准备好、模型加载完再移除 gate 让它开始调度。集群规格上我建议至少三个节点一个控制面两个工作节点。工作节点配置看你的 agent 类型如果跑本地小模型内存至少 32G如果只是调外部 API16G 够用。存储方面如果要用 PVC 做 cold workspace提前规划好 StorageClass。安装完集群后第一件事是装这几个组件# 安装 CRD 框架用于定义 AgentRuntime kubectl apply -f https://example.com/ax-crd-framework.yaml # 安装自定义 controller helm install ax-controller ax/ax-controller \ --namespace ax-system \ --create-namespace \ --set replicaCount2 # 验证 kubectl get crd | grep ax.io kubectl -n ax-system get pods4.2 定义第一个 AgentRuntime 并跑起来环境好了之后写一个最小的 AgentRuntime。我建议从最简单的开始不要一上来就搞多 agent 协作。apiVersion: ax.io/v1alpha1 kind: AgentRuntime metadata: name: hello-agent namespace: default spec: agentImage: registry.example.com/hello-agent:v0.1 workspace: hot: type: emptyDir sizeLimit: 1Gi lifecycle: maxIdleSeconds: 120 checkpointOnSuspend: false resources: executing: requests: { cpu: 500m, memory: 512Mi } limits: { cpu: 1, memory: 1Gi } task: input: 帮我统计当前 workspace 下的文件数量 timeoutSeconds: 300应用之后观察 controller 的行为kubectl apply -f hello-agent.yaml kubectl get agentruntime hello-agent -w你会看到 status 从Pending变成Executing然后变成Completed。如果卡在Pending大概率是镜像拉不下来或者资源不足。如果卡在Executing超过 timeoutcontroller 会把它标记为Failed并触发重试。这里有个细节值得说timeout 不要设得太短。Agent 调 LLM 的延迟波动很大同一个任务可能 10 秒完成也可能 3 分钟。我一般设 300 秒起步复杂任务设 1800 秒。设太短会导致任务被误杀设太长会导致资源被僵尸任务占着。4.3 workspace 的挂载与隔离实操Workspace 的挂载是实操中最容易出问题的地方。我给出一个经过验证的配置模板spec: workspace: hot: type: emptyDir sizeLimit: 2Gi medium: Memory # 关键用内存盘读写快 cold: type: pvc claimName: agent-cache-pvc mountPath: /workspace/cache securityContext: runAsNonRoot: true runAsUser: 1000 fsGroup: 1000 readOnlyRootFilesystem: true几个要点解释一下。medium: Memory让 emptyDir 用 tmpfs读写速度比磁盘快一个数量级适合 agent 频繁读写临时文件的场景。但要注意它占的是内存sizeLimit一定要设否则可能把节点内存吃光。fsGroup是为了让挂载的 PVC 对非 root 用户可写这个坑我踩过——不设 fsGroupagent 进程以非 root 运行时会报 permission denied。readOnlyRootFilesystem: true是安全加固防止 agent 往容器文件系统里写东西所有写入都必须走 workspace。隔离方面如果多个 agent 共享一个节点建议用RuntimeClass配合 gVisor 或 Kata Containers 做沙箱。因为 agent 可能会执行 LLM 生成的代码这些代码是不可信的。普通容器共享内核隔离性不够。gVisor 会带来一定的性能损耗大概 10%-30%但安全性提升明显。4.4 可观测性怎么知道 agent 到底在干什么Agent 的可观测性和普通服务不一样。普通服务你看 QPS、延迟、错误率就够了。Agent 你还需要看当前在哪个阶段、调了哪些工具、LLM 的 token 消耗、上下文长度、有没有陷入循环。我的做法是三层埋点。第一层是 Kubernetes 层面用kubectl describe agentruntime看状态流转。第二层是 agent 进程内部用 OpenTelemetry 打 trace每个工具调用是一个 span。第三层是业务层面把 agent 的决策过程比如我决定调用搜索工具作为结构化日志输出。# agent 内部的埋点示例 from opentelemetry import trace tracer trace.get_tracer(ax.agent) def call_tool(tool_name, params): with tracer.start_as_current_span(ftool.{tool_name}) as span: span.set_attribute(tool.params, str(params)) result do_call(tool_name, params) span.set_attribute(tool.result_size, len(str(result))) return result这样出问题时你可以顺着 trace 看到底是哪一步慢、哪一步错。热搜里 failed to start claudes workspace request error: net::err_connection_timed 这类错误如果有完整的 trace一眼就能看出是网络问题还是配置问题。5. 常见问题与排查技巧实录5.1 workspace 相关报错速查Workspace 是报错重灾区我把常见的几个整理成表。报错信息根因解决方向setting up workspace: loading packages...卡住网络存储挂载慢或依赖源不可达检查 PVC 后端存储健康度换用本地盘或加超时no valid workspace data to simulatecheckpoint 缺失或路径不对检查 cold workspace 挂载路径与 checkpoint 写入路径是否一致permission denied on /workspacefsGroup 未设置或 UID 不匹配设置 fsGroup确认容器内进程 UIDworkspace sizeLimit exceededemptyDir 写满调大 sizeLimit 或清理临时文件5.2 agent 卡死与假活排查Agent 卡死是最头疼的问题因为 Kubernetes 层面看起来一切正常。我的排查顺序是这样的。第一步看 agent 的当前阶段。kubectl get agentruntime name -o yaml看 status.phase。如果是Executing但很久没变说明 agent 进程可能卡在某个工具调用上。第二步进 Pod 看进程状态。kubectl exec -it pod -- ps aux看 agent 主进程在干什么。如果是D状态不可中断睡眠大概率是 IO 卡住。如果是S状态可能在等网络。第三步看网络连接。kubectl exec -it pod -- netstat -anp看有没有大量SYN_SENT或CLOSE_WAIT。前者说明连不上外部服务后者说明连接没正确关闭。第四步看日志的最后几行。Agent 卡死前通常会打最后一条日志那条日志就是线索。提示给 agent 加一个心跳机制。Agent 每隔 30 秒往一个文件或 etcd 写一次心跳controller 检测到心跳超时就主动重启。这比 liveness probe 更可靠因为它是业务层面的不受网络抖动影响。5.3 资源与成本优化的几个实操心得跑了一段时间后你会发现 agent 的资源利用率其实很低。Planning 阶段 CPU 几乎为 0Executing 阶段才起来。如果一直按 Executing 的规格占着资源浪费很大。我的优化手段有三个。一是用 VPAVertical Pod Autoscaler的 Off 模式让它推荐资源规格但不自动改你根据推荐值手动调。二是用 KEDA 做事件驱动伸缩没有任务时把 agent 副本缩到 0有任务再拉起来。三是把冷 workspace 放到对象存储用的时候再拉下来省 PVC 成本。还有一个容易被忽略的点LLM 的 token 成本。Agent 跑久了上下文会越来越长token 消耗指数级增长。我的做法是定期做上下文压缩把历史对话总结成摘要只保留最近几轮原文。这个逻辑要写在 agent 内部Kubernetes 层面管不了。5.4 版本升级与兼容性坑Kubernetes 版本升级时CRD 的兼容性要特别注意。apiextensions.k8s.io/v1beta1在 1.22 就被移除了如果你的 CRD 还是这个版本升级会直接失败。另外自定义 controller 用的 client-go 版本要和集群版本匹配否则会出现 API 调用失败。我建议的升级流程是先在测试集群升级跑一遍完整的 agent 任务确认没问题再上生产。生产升级时用滚动方式先升一个节点观察 24 小时再升下一个。Agent 任务对中断敏感宁可慢一点也不要一次性全升。6. 我对 ax 这类调度层的一些个人判断写到这里我想分享几个不那么技术但很重要的观察。第一agentic orchestration 目前还没有事实标准。Kubernetes 生态里Karmada 这类多集群调度项目在往 agentic cloud 方向走但具体怎么和 agent 生命周期结合各家做法都不一样。这意味着现在投入学习收益是长期的但短期内可能要忍受 API 不稳定、文档不全的痛苦。第二workspace 的设计决定了 agent 系统的上限。我见过太多项目agent 逻辑写得很漂亮但 workspace 设计得一塌糊涂结果任务一复杂就各种状态丢失、数据不一致。我的建议是在写第一行 agent 代码之前先把 workspace 的读写路径、持久化策略、隔离级别想清楚。第三不要过度依赖 Kubernetes 的原生能力。Kubernetes 是给无状态服务设计的agent 是有状态的。硬套原生模型最后会写出一堆 workaround。该写 CRD 就写 CRD该写 controller 就写 controller这层抽象是值得的。最后分享一个小技巧如果你在 Windows 上开发想本地跑 agent 的 workspace 做调试可能会遇到 requires the virtual machine platform on windows 这类提示。这不是 Kubernetes 的问题是本地容器运行时需要开启虚拟化平台支持。在启用或关闭 Windows 功能里勾选虚拟机平台和适用于 Linux 的 Windows 子系统重启即可。这个坑我在本地调试时踩过折腾了半天才发现是系统功能没开。Agent 调度这件事本质上是在让机器自主干活和让运维能管住机器之间找平衡。ax 这类调度层就是那个平衡点。它不完美但方向是对的。
