1. 从“ax”这个标题说起一个被低估的运行时编排切口第一次看到“ax”这个标题很多人会一头雾水。它不像“Kubernetes 集群搭建”那样直白也不像“Agentic RAG 实战”那样自带场景。但把热搜词摊开看——ax、agentic、orchestration、runtime、Kubernetes——这几个词拼在一起指向的其实是一个非常具体的技术切口面向智能体Agent工作负载的运行时编排层。我把它理解成“Agent eXecution”的缩写也就是智能体执行层。为什么这么拆因为 agentic 这个词现在被用得很泛但真正落地的时候绕不开三个硬问题第一智能体的任务不是一次函数调用而是一串有状态、有分支、可能失败重试的流程第二这些流程需要跑在某个 runtime 上而 runtime 的资源调度、隔离、生命周期管理天然属于 Kubernetes 的地盘第三orchestration 不是简单的“串起来”而是要处理并发、超时、回滚、可观测性。所以“ax”这个项目本质上是在回答一个问题当你的业务从“调 API”变成“跑 Agent”之后底层的运行时该怎么设计它适合谁看如果你正在把 LLM 能力往生产环境搬或者你已经在 Kubernetes 上跑了一些推理服务但发现 Agent 的编排逻辑散落在业务代码里、难以复用和观测那这个方向就值得你花时间。哪怕你只是刚接触 Kubernetes想找一个有真实业务背景的练手项目从“ax”这个切口进去也比单纯背 kubectl 命令有意思得多。我接下来会从设计思路、核心细节、实操落地、问题排查四个层面把这个项目拆开讲。所有内容基于我对 agentic orchestration 和 Kubernetes runtime 的常见实践理解来补全不保证和某个具体仓库完全一致但逻辑上能自洽你照着搭一个最小可用版本是没问题的。2. 整体设计与思路拆解为什么是 Runtime Orchestration 的组合2.1 为什么不能把 Agent 逻辑写在业务代码里我见过太多项目一开始就是把 Agent 的循环写在 Flask 或者 FastAPI 的 handler 里调一次模型判断一下要不要调工具再调一次模型最后返回。短流程没问题一旦流程变长问题就全出来了。比如你有一个“查订单→判断是否退款→生成回复→记录工单”的 Agent中间任何一步失败你都得在业务代码里写 try-catch然后手动决定是重试还是回滚。更麻烦的是当你有十个这样的 Agent每个都这么写代码重复率极高而且没法统一做限流、超时和日志。“ax”这个项目的设计思路就是把这部分逻辑从业务代码里抽出来下沉到一层 runtime 里。业务代码只负责定义“这个 Agent 有哪些步骤、每个步骤的输入输出是什么”至于怎么调度、怎么重试、怎么记录状态交给 runtime 层。这跟当年把 Web 应用从“裸写 socket”变成“跑在 Tomcat 上”是一个道理。你不需要自己管理线程池和连接容器帮你做了。2.2 为什么选 Kubernetes 作为底座有人会问为什么非得是 Kubernetes我用 Docker Compose 或者直接跑在虚机上不行吗短期可以但 Agent 工作负载有几个特点让 Kubernetes 的优势变得很明显。第一Agent 的调用量波动大可能白天闲晚上忙Kubernetes 的 HPA 能根据队列长度或者 CPU 自动扩缩容。第二Agent 的每个步骤可能依赖不同的镜像或环境Kubernetes 的 Pod 隔离和镜像管理天然适配。第三你需要可观测性Kubernetes 生态里的 Prometheus、Grafana、OpenTelemetry 都是现成的。更重要的是Kubernetes 的 CRD自定义资源定义机制让你可以把“Agent 任务”定义成一种资源就像 Deployment 或者 Job 一样。你可以写一个 AgentTask 的 YAML提交给集群然后由 controller 去 reconcile。这种声明式的思路比在代码里写命令式的调度逻辑要清晰得多。热搜词里出现了“karmada正式毕业”和“agentic cloud”其实也侧面说明多集群的 Agent 编排正在成为社区关注的方向。Karmada 解决的是跨集群调度而“ax”这类项目解决的是单集群内的 Agent 运行时两者是互补的。2.3 核心架构分层我把“ax”的架构分成四层从下往上说。最底层是Kubernetes 基础设施层负责节点、网络、存储这些。往上是Runtime 层这一层包含容器运行时比如 containerd 或者 CRI-O、以及可能的 WebAssembly 运行时或者轻量级沙箱用来执行 Agent 的每个步骤。再往上是Orchestration 层也就是“ax”的核心它包含任务队列、状态机、重试策略、超时控制。最上面是Agent 定义层用户在这里用 YAML 或者 SDK 描述 Agent 的步骤和依赖。这个分层的好处是每一层可以独立演进。比如你想换一个更快的容器运行时不影响上面的编排逻辑你想加一个新的重试策略也不用动底层的 Kubernetes 配置。我在实际搭类似系统的时候最深的体会就是边界清晰比功能丰富更重要。一开始就想做大而全最后往往是一团乱麻。2.4 和 Agentic RAG 的关系热搜词里有个“agentic rag”这其实是“ax”的一个典型应用场景。传统 RAG 是“检索→拼接→生成”一次完成。Agentic RAG 则是“检索→判断够不够→不够再检索→可能调别的工具→再生成”是一个多轮循环。这个循环如果写在业务代码里就是一堆 while 循环和 if-else。但如果放到“ax”的 runtime 里你就可以把“检索”定义成一个步骤“判断”定义成另一个步骤然后用编排层去控制循环和退出条件。这样你的 RAG 逻辑就是可配置、可观测、可复用的。3. 核心细节解析与实操要点从 CRD 到状态机3.1 定义 AgentTask 这个 CRD要让 Kubernetes 认识你的 Agent 任务第一步是定义一个 CRD。我一般会把它叫做 AgentTaskapiVersion 用自己的组名比如 ax.io/v1alpha1。spec 里至少包含这几个字段agentRef指向一个 Agent 定义、input任务的输入参数、timeoutSeconds超时时间、retryPolicy重试策略。status 里则记录 phasePending/Running/Succeeded/Failed、currentStep当前执行到哪一步、startTime、completionTime。这里有个细节要注意不要把整个 Agent 的步骤定义都塞进 AgentTask 的 spec 里。AgentTask 应该是一个“实例”而 Agent 的“模板”应该单独定义一个 Agent CRD。这样你才能复用同一个 Agent 模板创建多个任务实例。这跟 Deployment 和 Pod 的关系是一样的。我见过有人把步骤直接写在任务里结果每次改流程都要改任务定义非常痛苦。3.2 状态机的设计为什么不用简单的线性流程Agent 的执行流程往往不是线性的。比如一个客服 Agent可能先查订单如果订单存在就判断是否退款如果不存在就转人工。这是一个树状结构不是一条直线。所以“ax”的编排层需要一个状态机而不是一个简单的步骤列表。我通常会用“步骤 转移条件”来描述。每个步骤有名字、有执行器executor、有输出。转移条件则是一个表达式根据上一步的输出决定下一步走哪个分支。实现状态机有两种常见做法。一种是用代码写死比如用 Python 的 transitions 库或者自己写一个 switch-case。另一种是用声明式的方式把状态和转移定义成 YAML然后由一个通用的引擎去解释执行。我倾向于后者因为这样可以让非开发人员也能看懂流程而且方便做可视化。但声明式的代价是表达能力有限遇到特别复杂的逻辑还是得写代码。折中方案是简单分支用声明式复杂逻辑封装成自定义 executor。3.3 Runtime 的选择容器还是 WebAssemblyAgent 的每个步骤最终都要在某个 runtime 里执行。最常见的是容器因为生态成熟什么语言都能跑。但容器有个问题启动慢通常要几百毫秒到几秒。如果你的 Agent 有很多短步骤容器启动的开销就不可忽略了。这时候可以考虑 WebAssembly比如用 WasmEdge 或者 Wasmtime启动时间可以做到毫秒级。但 Wasm 的生态还在发展中不是所有库都能用。我的建议是先用容器把流程跑通等遇到性能瓶颈再考虑 Wasm。不要一开始就追求极致性能那样会陷入无穷无尽的兼容性问题。热搜词里有个“codemeter runtime下载”和“webview2 runtime”这些其实都是 runtime 依赖问题的体现。在 Kubernetes 里你可以通过 initContainer 来预装依赖或者把依赖打包进镜像避免运行时才发现缺东西。3.4 超时与重试的策略Agent 的步骤可能因为网络问题、模型限流、工具不可用而失败。重试是必须的但不能无脑重试。我一般会区分两类错误可重试错误比如 429 限流、503 服务不可用和不可重试错误比如 400 参数错误、401 鉴权失败。可重试错误用指数退避初始间隔 1 秒最大间隔 30 秒最多重试 3 次。不可重试错误直接失败记录日志。超时也要分层设置。单个步骤的超时比如调模型 30 秒调工具 10 秒。整个任务的超时比如 5 分钟。如果任务超时要能优雅地取消正在执行的步骤释放资源。Kubernetes 的 context 机制可以帮你做这件事但需要你在 executor 里定期检查 context 是否被取消。我踩过的坑是忘记在 executor 里检查 context导致任务已经超时了但步骤还在跑白白消耗资源。4. 实操过程与核心环节实现搭一个最小可用的 ax4.1 环境准备与依赖检查假设你已经有一个 Kubernetes 集群版本 1.26 以上。先确认几个东西kubectl 能正常连集群容器运行时是 running 状态。热搜词里有个报错“container runtime is not running”这个在自建集群里很常见通常是 containerd 或者 Docker 没启动。用systemctl status containerd检查一下如果是 inactive就systemctl start containerd并设置开机自启。然后确认你有权限创建 CRD 和 Controller。如果是托管集群可能需要 cluster-admin 权限。我一般会先跑一个简单的 Job 测试一下确保集群能正常调度 Pod。命令是kubectl run test --imagebusybox --restartNever -- echo hello然后kubectl logs test看输出。这一步能排除掉大部分环境问题。4.2 编写 Agent 和 AgentTask 的 CRD先写 Agent 的 CRD。apiVersion 是 apiextensions.k8s.io/v1kind 是 CustomResourceDefinition。名字用 agents.ax.io。spec 里定义 group 为 ax.ioversions 里写 v1alpha1scope 用 Namespaced。schema 用 openAPIV3Schema至少定义 spec.steps 是一个数组每个 step 有 name、image、command、timeoutSeconds 这些字段。然后写 AgentTask 的 CRD。名字用 agenttasks.ax.io。schema 里 spec 包含 agentRef、input、timeoutSeconds。status 包含 phase、currentStep、message。写完用kubectl apply -f提交。提交后用kubectl get crd | grep ax确认创建成功。这里有个容易忽略的点CRD 的 schema 校验要写清楚。如果你不写 required 字段用户提交一个缺字段的 YAML 也能通过但 controller 处理时会报错。我一般会把 agentRef 和 input 设为 required并且给 input 一个 type: object 的定义允许任意键值对。4.3 Controller 的核心逻辑Controller 用 client-go 或者 kubebuilder 来写。核心是一个 reconcile 循环监听 AgentTask 的创建和更新事件然后根据 status.phase 决定做什么。如果是 Pending就读取对应的 Agent 定义初始化状态机把 phase 改成 Running。如果是 Running就检查当前步骤是否完成完成了就推进到下一步没完成就等待。如果所有步骤都完成phase 改成 Succeeded。如果某一步失败且重试次数用尽phase 改成 Failed。写 reconcile 的时候要注意幂等性。因为 controller 可能会重复处理同一个事件你的逻辑必须能处理“已经 Running 的任务再次进入 reconcile”这种情况。我通常会在 status 里记录一个 observedGeneration只有当 spec 的 generation 变化时才重新初始化。另外不要在主循环里做阻塞操作比如等待一个 Pod 跑完。应该用 informer 监听 Pod 的状态变化或者用 workqueue 的 rate limiter 来控制重试频率。4.4 步骤执行器的实现每个步骤的执行器本质上是一个函数输入是上一步的输出和任务的 input输出是这一步的结果。在 Kubernetes 里最简单的实现方式是为每个步骤创建一个 JobJob 的 Pod 里跑一个容器容器执行具体的命令。Controller 监听 Job 的完成状态把 Job 的日志或者输出文件作为步骤的输出。但这种方式有个问题步骤之间的数据传递不方便。Job 的输出在 Pod 里Controller 要拿到它要么挂载共享存储要么让 Pod 把输出写到某个地方。我一般会用 ConfigMap 或者 PVC 来传递中间结果。如果数据量小用 ConfigMap 就够了如果数据量大比如图片或者向量就用 PVC。另一个方案是用一个常驻的 executor 服务Controller 通过 gRPC 调用它这样数据传递更直接但 executor 服务本身需要高可用。4.5 一个完整的 YAML 示例下面是一个 Agent 定义的例子描述一个“查订单并生成回复”的流程。第一个步骤是查订单第二个步骤是判断是否需要退款第三个步骤是生成回复。步骤之间用 next 字段指定下一步如果 next 为空就结束。apiVersion: ax.io/v1alpha1 kind: Agent metadata: name: order-assistant spec: steps: - name: query-order image: my-registry/order-query:latest command: [/app/query] timeoutSeconds: 30 next: check-refund - name: check-refund image: my-registry/refund-check:latest command: [/app/check] timeoutSeconds: 15 next: generate-reply - name: generate-reply image: my-registry/reply-gen:latest command: [/app/generate] timeoutSeconds: 60对应的 AgentTask 就简单多了只需要引用这个 Agent 并传入 input。apiVersion: ax.io/v1alpha1 kind: AgentTask metadata: name: task-001 spec: agentRef: order-assistant input: orderId: 12345 userId: u-001 timeoutSeconds: 300提交之后用kubectl get agenttask task-001 -o yaml看 status应该能看到 phase 从 Pending 变成 Running然后 currentStep 依次变化。5. 常见问题与排查技巧实录5.1 任务一直卡在 Pending这是最常见的问题。原因通常有三个controller 没跑起来、CRD 没注册成功、或者 RBAC 权限不够。排查顺序是先kubectl get pods -n ax-system看 controller 的 Pod 是否 Running。如果没 Running看日志通常是镜像拉取失败或者配置错误。如果 Running 但任务还是 Pending看 controller 日志里有没有“forbidden”字样有的话就是 RBAC 问题需要给 controller 的 ServiceAccount 绑定 cluster-admin 或者自定义的 Role。还有一个隐蔽的原因AgentTask 的 namespace 和 Agent 的 namespace 不一致。如果你的 controller 只监听某个 namespace而任务提交到了另一个 namespace就会一直 Pending。我建议一开始就让 controller 监听所有 namespace等稳定了再考虑限制范围。5.2 步骤执行失败但没重试检查 retryPolicy 是否配置正确。如果你用的是自定义的 controller确认重试逻辑是在 reconcile 里实现的而不是在 executor 里。我见过有人在 executor 里写重试结果 executor 本身挂了重试逻辑根本没执行。正确的做法是executor 只负责执行一次失败就返回错误由 controller 决定是否重试。这样即使 executor 崩溃controller 也能重新调度。另外区分错误类型很重要。如果你的 executor 把所有错误都当成可重试那参数错误也会被重试浪费资源。我一般会在 executor 的返回值里带一个 errorType 字段controller 根据这个字段决定是否重试。5.3 中间结果丢失如果步骤之间用 ConfigMap 传递数据要注意 ConfigMap 的大小限制默认是 1MB。超过这个大小会创建失败。如果数据量大改用 PVC。但 PVC 的问题是任务结束后需要清理否则会残留一堆无用的 PVC。我通常会在 AgentTask 的 status 里记录用到的 PVC 名字任务完成后由 controller 删除。另一个坑是ConfigMap 的更新不是原子的。如果你在步骤 A 里写 ConfigMap步骤 B 里读可能会读到旧版本。解决办法是用 resourceVersion 做乐观锁或者干脆用 PVC 加文件锁。5.4 常见问题速查表问题现象可能原因排查命令解决方式任务卡 Pendingcontroller 未运行kubectl get pods -n ax-system检查 controller 日志修复镜像或配置任务卡 PendingRBAC 权限不足kubectl logs -n ax-system controller-pod绑定合适的 Role 或 ClusterRole步骤失败不重试retryPolicy 未生效kubectl get agenttask name -o yaml检查 controller 重试逻辑确认错误类型中间结果丢失ConfigMap 超限kubectl describe configmap name改用 PVC 或减小数据量任务超时未取消executor 未检查 context查看 executor 日志在 executor 里定期检查 context.Done()容器运行时未运行containerd 未启动systemctl status containerd启动 containerd 并设置开机自启5.5 几个我踩过的坑第一个坑是忘记设置 activeDeadlineSeconds。Kubernetes 的 Job 有一个 activeDeadlineSeconds 字段如果不设置Job 可能永远跑下去。我在 AgentTask 的 controller 里会根据 spec.timeoutSeconds 给每个步骤的 Job 设置 activeDeadlineSeconds确保超时后 Job 会被终止。第二个坑是日志收集不完整。Agent 的步骤可能产生大量日志如果只靠kubectl logsPod 删除后就看不到了。我建议在 controller 里把每个步骤的日志收集起来存到对象存储或者日志系统里。最简单的做法是在 Pod 里加一个 sidecar把日志转发到 stdout然后由集群的日志采集器统一收集。第三个坑是并发控制。如果同一个 Agent 被多个任务同时调用可能会争抢资源。我一般会在 Agent 定义里加一个 concurrencyPolicy 字段支持 Allow、Forbid、Replace 三种策略。Forbid 表示如果前一个任务还没完成新任务就排队等待。Replace 表示新任务替换旧任务。这个在 Kubernetes 的 CronJob 里也有类似设计可以直接借鉴。6. 扩展方向从单集群到多集群的 Agent 编排6.1 为什么需要考虑多集群单集群跑一段时间后你会遇到几个问题。第一资源不够了需要加节点但单集群的节点数有上限。第二不同地域的用户需要就近执行减少延迟。第三不同环境开发、测试、生产需要隔离。这时候就需要多集群编排。热搜词里“karmada正式毕业”和“华为云携手社区共建agentic cloud坚实底座”说的就是这个方向。Karmada 提供的是多集群的调度和分发能力而“ax”这类 runtime 项目需要和 Karmada 集成才能把 AgentTask 分发到不同的集群。6.2 多集群下的状态同步多集群最大的挑战是状态同步。一个 AgentTask 在主集群创建但实际执行在成员集群。主集群的 controller 需要知道成员集群里任务的进度。常见的做法是成员集群的 controller 把状态上报到主集群主集群的 controller 聚合状态。这中间需要处理网络分区、时钟漂移、重复上报等问题。我建议用 Kubernetes 的 Lease 机制来做 leader election确保同一时间只有一个 controller 在处理状态同步。另一个方案是用消息队列比如 Kafka 或者 NATS把状态变更事件发到队列里主集群消费队列更新状态。这种方式解耦更彻底但引入了额外的运维复杂度。如果团队规模不大我建议先用 Lease 方案简单可靠。6.3 和 Agentic Cloud 的关系“Agentic Cloud”这个概念我理解是把 Agent 的运行时、编排、工具链都做成云服务。用户只需要定义 Agent 的逻辑底层的调度、扩缩容、可观测性都由云平台提供。这跟当年的“Serverless”很像只不过 Serverless 抽象的是函数Agentic Cloud 抽象的是 Agent。要实现这个目标需要几个关键组件统一的 Agent 定义标准、跨集群的调度器、细粒度的资源计量、以及完善的安全隔离。目前社区还在早期但方向是清晰的。6.4 一个务实的演进路线如果你现在是从零开始我建议的路线是第一阶段单集群跑通 AgentTask 的创建、执行、状态更新。第二阶段加入重试、超时、并发控制。第三阶段接入可观测性把指标和日志接到 Prometheus 和 Grafana。第四阶段考虑多集群先用 Karmada 做简单的分发再逐步完善状态同步。不要跳过前三个阶段直接做多集群那样会同时面对太多变量排查问题会非常痛苦。7. 一些实操心得和后续可以做的事我在搭类似系统的过程中最大的体会是Runtime 的稳定性比功能丰富度重要得多。一个能稳定跑 1000 个任务的简单 runtime比一个功能花哨但经常崩溃的复杂 runtime 有价值。所以一开始不要追求支持所有类型的 Agent先把一种类型做透。比如先支持“线性步骤 条件分支”的 Agent等稳定了再支持循环和并行。另一个心得是可观测性要提前做不要等出问题了再加。我在 controller 里从一开始就暴露了 Prometheus 指标包括任务总数、成功数、失败数、平均执行时间、各步骤的执行时间。这些指标在排查问题时非常有用。比如你发现某个步骤的执行时间突然变长就能快速定位到是模型限流还是工具变慢。后续可以扩展的方向有几个。一是支持 Agent 的版本管理让同一个 Agent 的不同版本可以灰度发布。二是支持 Agent 之间的调用也就是一个 Agent 的步骤可以触发另一个 Agent。三是支持更细粒度的资源配额比如限制某个 Agent 每天最多调用多少次模型。这些都是在生产环境里会真实遇到的需求。最后分享一个小技巧在 AgentTask 的 status 里加一个lastTransitionTime字段记录每次 phase 变化的时间。这样你就能算出任务在每个阶段停留了多久对优化流程很有帮助。这个字段在 Kubernetes 的原生资源里很常见但自己写 CRD 的时候容易忘。加上它排查问题时能省不少事。
