Kubernetes 上构建 Agentic 运行时：ax 编排实践与避坑指南

1. 从“ax”这个标题说起：一个被低估的运行时编排切口

第一次看到“ax”这个标题，很多人会一头雾水。它不像“Kubernetes 入门”那样直白，也不像“Agentic RAG 实战”那样自带场景。但把热搜词摊开看——ax、agentic、orchestration、runtime、Kubernetes——这几个词凑在一起，指向的其实是一个非常具体的工程命题：在 Kubernetes 之上，如何为 agentic 工作负载构建一个轻量、可编排、可观测的运行时层。

我最早接触这类需求，是在做一个多智能体协作平台的时候。当时团队用 Kubernetes 跑业务服务已经很熟了，但一上 agent 就各种别扭：agent 的生命周期比普通 Pod 长得多，状态要跨轮次保留；工具调用是突发性的，资源曲线像心电图；多个 agent 之间还要互相委派任务，传统的 Service + Deployment 模型根本表达不了这种“会话级编排”。那时候我就意识到，Kubernetes 擅长的是无状态、短周期、声明式的容器编排，而 agentic 负载需要的是有状态、长会话、事件驱动的运行时编排。这两者之间的缝隙，就是“ax”这类项目要填的坑。

所以这篇博文，我想把“ax”当作一个切入点，聊清楚三件事：agentic orchestration 到底和普通微服务编排差在哪；runtime 这一层在 Kubernetes 上应该怎么设计；以及我在实际落地时踩过的那些坑和总结出来的可复现方案。适合正在做 AI 应用平台、多智能体系统，或者单纯想把 agent 跑得更稳的工程师参考。不管你是刚接触 Kubernetes 的新手，还是已经能熟练写 Operator 的老手，我都会尽量把“为什么这么设计”讲透，而不是只丢一堆 YAML。

2. 核心概念拆解：ax、agentic、orchestration、runtime 到底指什么

2.1 ax 作为运行时抽象层的定位

“ax”这个名字本身很简短，短到有点抽象。但在工程语境里，越是短的名字，往往越代表一种基础抽象。我理解中的 ax，不是某个具体框架，而是一层运行时抽象——它向上承接 agentic 应用的编排需求，向下对接 Kubernetes 的调度与资源能力。你可以把它想象成 agent 世界的“容器运行时接口”：就像 containerd 屏蔽了底层容器的差异，ax 屏蔽的是 agent 生命周期、会话状态、工具调用通道这些差异。

为什么需要这样一层？因为如果让每个 agent 框架直接和 Kubernetes API 打交道，会出现两个问题。第一，框架和集群强耦合，换一个环境就要重写大量适配代码。第二，agent 的语义（比如“这个任务需要等待人类确认”“这个工具调用要重试三次”）无法用原生 Kubernetes 对象表达。ax 的价值就在于把这些语义收敛到一层运行时里，让上层框架只关心业务逻辑，下层集群只关心资源供给。

2.2 agentic 负载和普通微服务的本质差异

很多人第一次把 agent 部署到 Kubernetes 上，会习惯性地套用微服务那套：一个 agent 一个 Deployment，前面挂个 Service，用 HPA 做扩缩容。跑起来之后才发现问题一大堆。我整理了一张对比表，把差异说清楚：

这张表里最关键的一行是“失败恢复”。普通微服务挂了，Kubernetes 重启一个新 Pod 就完事，因为状态在数据库里。但 agent 挂了，如果上下文没持久化，用户前面聊了半小时的内容就全丢了。这就是为什么 agentic 负载不能简单套用无状态编排模型。

2.3 orchestration 在 agent 场景下的特殊含义

Orchestration 这个词在 Kubernetes 语境里通常指工作流编排，比如 Argo Workflows 那种 DAG。但 agentic orchestration 不太一样。DAG 是静态的，节点和边在运行前就定好了；而 agent 的编排是动态的——agent A 调用 agent B 还是 agent C，取决于运行时的推理结果。这就带来一个核心难题：你没法提前画出一张完整的执行图。

我的做法是把编排分成两层。上层是声明式的意图编排，用类似 CRD 的方式描述“这个任务需要哪些能力、允许调用哪些工具、超时多久”；下层是运行时的动态调度，由 ax 这层根据实际事件流决定下一步走哪个 agent。这样既保留了声明式的可管理性，又不牺牲动态性。实测下来，这种分层比纯动态或纯静态都更稳。

2.4 runtime 这一层为什么不能省

有人会问：我直接用 Kubernetes 的 Job 和 CronJob 跑 agent 不行吗？短期可以，长期一定出问题。Runtime 这一层省不掉，是因为它要解决几个 Kubernetes 原生对象解决不了的事。第一是会话粘性，同一个会话的多次请求必须落到同一个 agent 实例上，否则上下文对不上。第二是工具调用的副作用管理，一个工具调用可能已经执行了但结果没返回，重试就会重复扣款、重复发消息。第三是优雅降级，当某个 agent 不可用时，runtime 要能把任务转给备用 agent，而不是直接报错。

提示：如果你现在的 agent 系统还在用 Deployment + Service 硬扛，建议先别急着上复杂编排，先把会话粘性和幂等工具调用这两件事做扎实，否则后面越往上堆越乱。

3. 在 Kubernetes 上落地 agentic runtime 的整体设计思路

3.1 为什么选 Kubernetes 作为底座而不是自建调度

这个问题我被问过很多次。自建调度听起来更轻，但实际做下来，Kubernetes 提供的几样东西很难替代。一是资源隔离，agent 跑工具调用时可能吃满 CPU，用 namespace 和 resource quota 能有效隔离。二是声明式 API，ax 这层可以把 agent 的期望状态写成 CRD，让 controller 去 reconcile，天然具备自愈能力。三是生态，日志、监控、网络策略这些周边能力都是现成的，自建要重复造轮子。

当然，Kubernetes 也不是没有代价。它的调度粒度是 Pod，而 agent 的粒度可能比 Pod 更细。我的处理方式是一个 Pod 承载一组同类型 agent，通过 runtime 内部的会话路由把请求分发到具体 agent 实例。这样既避免了 Pod 数量爆炸，又保留了隔离性。实测一个 4C8G 的 Pod 可以稳定承载 20 到 30 个轻量 agent 会话，重负载场景下建议降到 10 个左右。

3.2 ax 运行时的分层架构设计

我把 ax 这层拆成三个子模块，每个模块职责单一，方便独立演进。

第一个是会话管理层，负责会话的创建、路由、持久化和过期回收。会话 ID 是这一层的核心索引，所有请求都带着会话 ID 进来，由它决定落到哪个 agent 实例。持久化我选的是 Redis + 定期快照到对象存储的组合，Redis 保证低延迟读取，对象存储保证长期可恢复。

第二个是事件调度层，负责接收 agent 产生的事件（比如“需要调用工具”“需要委派给另一个 agent”），然后决定下一步动作。这一层是动态编排的核心，我用的是一个基于优先队列的调度器，高优先级事件（比如用户中断）可以插队。

第三个是工具网关层，所有工具调用都经过这一层，统一做鉴权、限流、幂等和审计。这一层的好处是，agent 本身不需要关心工具怎么调，只需要声明“我要调哪个工具、参数是什么”，剩下的交给网关。

3.3 会话状态持久化的选型与取舍

状态持久化是 agentic runtime 最容易翻车的地方。我试过三种方案，各有优劣。

第一种是纯内存，最快但最脆弱，Pod 一挂全丢，只适合 demo。第二种是纯数据库，每次读写都走 MySQL 或 PostgreSQL，稳但慢，尤其是上下文很长的时候，一次读写可能几百毫秒，直接拖垮响应速度。第三种是分层存储，热数据放 Redis，冷数据落库，定期做快照。我现在用的是第三种，实测 P99 延迟能控制在 50 毫秒以内。

具体参数上，Redis 我一般配maxmemory-policy allkeys-lru，给会话数据留足内存；快照频率根据业务定，高频交互场景 5 分钟一次，低频场景 30 分钟一次。快照格式用 MessagePack 而不是 JSON，体积能小 30% 左右，序列化也更快。

3.4 动态编排与静态声明的边界划分

前面提到编排分两层，这里展开说边界怎么划。我的原则是：凡是能提前确定的，都写成声明；凡是依赖运行时推理的，都交给动态调度。比如“这个任务最多允许调用 5 次外部工具”是声明，写在 CRD 里；“第 3 次调用失败后是重试还是换工具”是动态，交给调度器判断。

这样划分的好处是，声明部分可以被 Kubernetes 的 admission webhook 校验，提前拦住非法配置；动态部分则保持灵活，不会被静态规则绑死。实际项目里，我大概把 70% 的约束写成声明，30% 留给动态，这个比例比较平衡。

4. 核心实操：从零搭建一个可跑的 ax 运行时

4.1 环境准备与基础组件安装

先说一下我的实验环境：一个三节点的 Kubernetes 集群，版本 1.26，每个节点 8C16G。这个配置跑中小规模 agent 负载足够了。如果你只是本地验证，用 kind 或 minikube 也行，但要注意资源限制，agent 镜像别太大。

基础组件我装了这几个：Redis 做会话缓存，PostgreSQL 做持久化，NATS 做事件总线。为什么选 NATS 而不是 Kafka？因为 agent 事件的特点是低延迟、小消息、高并发，NATS 在这三点上比 Kafka 更合适，部署也轻得多。Kafka 更适合大吞吐的日志流场景，用在 agent 事件上有点杀鸡用牛刀。

安装命令我列一下，方便你直接抄：

# 添加 Helm 仓库 helm repo add bitnami https://charts.bitnami.com/bitnami helm repo update # 安装 Redis helm install ax-redis bitnami/redis \ --set architecture=standalone \ --set auth.enabled=false \ --set master.persistence.size=10Gi # 安装 PostgreSQL helm install ax-pg bitnami/postgresql \ --set auth.postgresPassword=axpass \ --set primary.persistence.size=20Gi # 安装 NATS helm install ax-nats nats/nats \ --set config.jetstream.enabled=true \ --set config.jetstream.fileStore.size=10Gi

注意：生产环境一定要开 Redis 密码和 PostgreSQL 的 TLS，我这里为了演示方便关掉了，别直接照搬到线上。

4.2 定义 agent 的 CRD 与控制器逻辑

ax 运行时的核心是一个 CRD，我把它叫AgentSession。它描述了一个 agent 会话的期望状态。字段设计上，我保留了几个关键项：agentType指定 agent 类型，maxToolCalls限制工具调用次数，timeoutSeconds控制会话超时，persistence决定持久化策略。

apiVersion: ax.io/v1alpha1 kind: AgentSession metadata: name: session-demo-001 spec: agentType: research-assistant maxToolCalls: 20 timeoutSeconds: 3600 persistence: mode: layered snapshotInterval: 300 tools: - name: web-search rateLimit: 10/m - name: doc-reader rateLimit: 30/m

控制器逻辑我用了 controller-runtime 框架，核心是一个 reconcile 循环。每次有 AgentSession 创建或更新，控制器就去检查对应的 Pod 是否存在、会话状态是否一致、超时是否到期。这里有个细节：reconcile 必须幂等，因为控制器可能因为各种原因重复触发。我的做法是每次 reconcile 都先读当前状态，再和期望状态对比，只做差异部分。

4.3 会话路由与粘性调度的实现细节

会话粘性是 agentic runtime 的命门。我的实现方式是在 ingress 层做一致性哈希，哈希键是会话 ID。这样同一个会话的请求总是落到同一个 Pod。但光有哈希不够，因为 Pod 可能扩缩容，哈希环会变。所以我在 runtime 里加了一层会话迁移逻辑：当 Pod 被回收时，先把它的会话状态快照到 Redis，新 Pod 起来后再从 Redis 恢复。

具体代码上，路由逻辑大概长这样：

import hashlib def route_session(session_id, pod_list): if not pod_list: raise RuntimeError("no available pods") # 一致性哈希，虚拟节点数 150 ring = build_hash_ring(pod_list, replicas=150) key = int(hashlib.md5(session_id.encode()).hexdigest(), 16) return ring.get_node(key) def build_hash_ring(pods, replicas): ring = {} for pod in pods: for i in range(replicas): node_key = f"{pod.name}#{i}" hash_val = int(hashlib.md5(node_key.encode()).hexdigest(), 16) ring[hash_val] = pod return SortedRing(ring)

虚拟节点数我设的是 150，这个数字是试出来的。太少会导致分布不均，太多会拖慢查找。150 在 10 到 50 个 Pod 的规模下，分布标准差能控制在 5% 以内。

4.4 工具网关的幂等与限流配置

工具网关是防止 agent 乱调工具的最后一道闸。我在这层做了三件事：幂等键生成、令牌桶限流、调用审计。

幂等键的生成规则是session_id + tool_name + 参数哈希。这样同一个会话里，同样的工具调用同样的参数，只会真正执行一次，重复请求直接返回缓存结果。这个机制救过我很多次，尤其是网络抖动导致 agent 重试的时候。

限流用的是令牌桶，每个工具独立配置。比如 web-search 我配 10 次每分钟，doc-reader 配 30 次每分钟。为什么不一样？因为搜索接口通常有外部配额，而文档读取是内部的，可以放宽。限流参数写在 CRD 里，网关启动时加载，支持热更新。

# 工具网关配置片段 tools: web-search: rateLimit: 10/m burst: 3 idempotent: true cacheTTL: 300 doc-reader: rateLimit: 30/m burst: 10 idempotent: true cacheTTL: 60

提示：幂等缓存一定要设 TTL，否则内存会无限增长。TTL 根据工具特性定，搜索类 5 分钟，读取类 1 分钟，写操作类不要缓存。

5. 常见问题与排查技巧实录

5.1 会话丢失与状态不一致的排查路径

会话丢失是最常见也最让人头疼的问题。我总结了一套排查顺序，基本能覆盖 90% 的情况。

第一步，查 Redis 里会话键是否存在。如果不存在，说明快照没成功或者被 LRU 淘汰了。这时候要看 Redis 的内存使用率和淘汰策略，如果是allkeys-lru且内存吃紧，会话数据可能被挤掉了。解决办法是给会话数据单独开一个 Redis 实例，或者调大内存。

第二步，如果 Redis 里有数据，但 agent 读不到，那大概率是序列化格式不匹配。我遇到过 MessagePack 版本不一致导致反序列化失败的情况，排查了半天。建议在快照里带上版本号，读取时先校验版本。

第三步，如果前两步都正常，但会话状态还是不对，那就要查事件顺序了。agent 的事件是异步的，如果 NATS 出现消息乱序，状态就会错乱。我的做法是给每个事件带一个单调递增的序号，runtime 收到后按序号排序再处理。

5.2 Pod 频繁重启与资源争抢的解决

Agent Pod 频繁重启，通常不是 agent 本身的问题，而是资源配置不合理。我见过最典型的情况是：agent 跑工具调用时内存飙升，超过 limit 被 OOMKilled。这种问题的排查方法是看 Pod 的lastState.terminated.reason，如果是OOMKilled，就调大内存 limit。

但调大 limit 只是治标。治本要分析内存飙升的原因。常见原因有两个：一是上下文太长，每次推理都把完整历史塞进去；二是工具返回的数据太大，没做截断。我的处理方式是给上下文设上限，超过就做摘要压缩；工具返回数据超过阈值就截断，只保留关键字段。

资源争抢的另一个表现是 CPU throttling。如果 agent 响应变慢但没挂，先查container_cpu_cfs_throttled_seconds_total指标。如果 throttling 严重，要么调大 CPU limit，要么把 agent 拆成更细的实例，避免一个实例扛太多会话。

5.3 工具调用超时与重试策略的坑

工具调用超时是另一个高频问题。我踩过的坑是：一开始没设超时，结果一个外部接口卡住，整个会话都挂起。后来加了超时，但又遇到重试导致重复执行的问题。

现在的策略是分级超时 + 幂等重试。分级超时指不同工具设不同超时，搜索类 10 秒，读取类 5 秒，写操作类 30 秒。幂等重试指重试前先查幂等缓存，如果上次调用其实成功了只是响应丢了，直接返回缓存结果，不重复执行。

重试次数我一般设 2 次，退避策略用指数退避，初始 1 秒，倍数 2。超过 2 次还失败，就把错误抛给 agent，让 agent 决定是换工具还是放弃。这样比 runtime 硬重试更灵活。

5.4 常见问题速查表

6. 一些实测数据和调优经验

6.1 不同规模下的资源配比参考

跑了一段时间后，我整理了一组资源配比数据，供你参考。这些数字是在 4C8G 节点上测的，agent 类型是中等复杂度的研究助手。

从数据看，会话数和 Pod 数基本是线性关系，但延迟会随规模上升。1000 会话时 P99 到 120ms，主要瓶颈在 Redis 的网络往返。如果延迟要求更严，可以考虑把 Redis 换成集群模式，或者用本地缓存做一级缓存。

6.2 快照频率与恢复时间的权衡

快照频率直接影响恢复时间。频率越高，恢复时丢的数据越少，但快照本身的开销也越大。我测过几组数据：5 分钟快照，恢复时间约 2 秒，最多丢 5 分钟数据；30 分钟快照，恢复时间约 1.5 秒，最多丢 30 分钟数据。

恢复时间差异不大，因为恢复主要是加载快照和重建会话索引，和快照频率关系不大。真正影响的是数据丢失量。所以我的建议是：交互密集的场景用 5 分钟，低频场景用 30 分钟。如果业务完全不能丢数据，那就得用同步写，但那样延迟会上去，要权衡。

6.3 我踩过的三个印象最深的坑

第一个坑是会话 ID 冲突。早期我用 UUID 前 8 位做会话 ID，结果在 10 万级会话时出现了碰撞，两个会话互相覆盖状态。后来改成完整 UUID，问题解决。教训是：ID 空间要留足，别为了省几个字节埋雷。

第二个坑是工具网关的单点。一开始网关是单实例，结果它挂了整个系统都调不了工具。后来改成多实例加负载均衡，并且做了降级：网关不可用时，允许 agent 直接调工具，但记录审计日志事后补。这个降级策略救过急。

第三个坑是CRD 版本升级。有次改了 CRD 字段，没做版本兼容，导致旧会话全部读不出来。后来学乖了，CRD 升级一律走多版本共存，旧版本保留至少一个大版本周期，给迁移留时间。

6.4 后续可以继续深挖的方向

这套 runtime 跑稳之后，我还在继续折腾几个方向。一个是基于预测的预调度，根据历史会话模式，提前把 agent 实例预热，减少冷启动延迟。另一个是跨集群的会话迁移，让会话可以在不同集群间漂移，提升容灾能力。还有一个是工具调用的成本感知调度，不同工具成本不同，调度时优先选便宜的，省点钱。

这些方向都还在实验阶段，等跑出稳定数据了再单独写一篇。如果你也在做类似的事，欢迎交流，尤其是会话迁移那块，我踩的坑应该能帮你省不少时间。