1. 从“ax”这个标题说起一个被低估的运行时编排命题第一次看到“ax”这个标题很多人会一头雾水——两个字母既不像产品名也不像技术栈缩写。但把热搜词摊开来看线索就清楚了agentic、orchestration、runtime、Kubernetes这几个词反复出现再加上“karmada正式毕业”“agentic cloud坚实底座”这类行业动态基本可以判断“ax”指向的是一个面向智能体Agent场景的运行时编排层而不是某个具体的开源项目名。换句话说它更像是一类问题的代号当你的系统里跑的不再是单纯的容器而是一堆会自己决策、自己调工具、自己调其他 Agent 的“活体进程”时底层的调度、隔离、生命周期管理该怎么做。我过去两年在几个内部平台里折腾过类似的东西从最早的“把 LLM 调用塞进 CronJob”这种土办法到后来用 Kubernetes 的 CRD 去描述 Agent 的拓扑关系踩过的坑足够写一本小册子。所以这篇东西不打算复述任何官方文档而是把我理解的“ax 这一类运行时编排系统”拆开来讲它到底解决什么问题、核心抽象是什么、在 Kubernetes 上落地时哪些地方最容易翻车、以及我实测下来比较稳的一套做法。适合谁看如果你已经在用 Kubernetes 跑服务现在想把 Agent 工作流也搬上去或者你正在设计一个多 Agent 协作平台那这篇内容应该能帮你省掉至少两轮返工。如果你只是听说过 agentic 这个词也没关系我会从最基础的概念开始铺垫尽量用生活化的类比把运行时编排这件事讲透。2. 核心概念拆解Agentic Runtime 到底在编排什么2.1 从“容器编排”到“智能体编排”的范式迁移Kubernetes 解决的核心问题是我有一堆无状态的容器怎么让它们在几百台机器上合理分布、故障自愈、滚动升级。它的基本假设是——进程是哑的行为是确定的。你给它一个镜像它跑起来就是那套逻辑不会今天调这个 API、明天自己决定换个数据库。Agent 完全打破了这个假设。一个 Agent 的运行过程是接收输入 → 推理 → 决定调用哪个工具 → 拿到结果 → 再推理 → 可能再调另一个 Agent → 最终输出。这个过程里下一步做什么是运行时才决定的而且同一个输入两次跑出来的路径可能完全不同。这就带来几个容器编排从来没遇到过的问题生命周期不确定一个 Agent 任务可能 200ms 结束也可能因为要等一个人工审批卡在那里 3 天。资源画像漂移推理阶段吃 GPU调工具阶段几乎不吃等审批阶段纯占内存。依赖是动态的Agent A 今天调 B明天可能因为 prompt 变了去调 C拓扑关系不是静态声明的。状态必须可恢复跑到一半挂了不能从头再来得从上一个“决策点”续上。所以“ax”这类系统要做的不是把 Agent 当成容器来调度而是在容器编排之上再抽象一层“决策点编排”。我习惯把它类比成Kubernetes 管的是“谁在哪里跑”Agentic Runtime 管的是“谁在什么时候决定让谁跑”。2.2 四个核心抽象Task、Agent、Tool、Session不管具体实现叫什么名字我见过的所有 Agentic Runtime 都绕不开这四个概念。理解它们之间的关系比记任何 API 都重要。Task是最外层的单位代表“用户想要完成的一件事”。它是有明确终态的——成功、失败、取消。一个 Task 可以理解成一个有向无环图DAG但和传统工作流不同的是这个图的边是运行时才确定的。Agent是执行单元每个 Agent 有自己的系统提示、可用工具集、模型配置。它接收一个输入产出一个输出中间可能产生若干次工具调用。Agent 本身是无状态的状态存在 Session 里。Tool是 Agent 能调用的外部能力可以是一个 HTTP 接口、一段代码、甚至另一个 Agent。Tool 的关键属性是幂等性和超时——这两个属性没定义好整个编排就会变成一团乱麻。Session是状态的载体。它记录了这个 Task 到目前为止的所有决策、工具调用结果、中间产物。Session 必须能持久化而且最好能支持“回放到某个决策点”。把这四个东西的关系画清楚其实就一句话Task 驱动 AgentAgent 通过 Tool 产生副作用所有过程记录在 Session 里。Runtime 的职责就是保证这四者之间的调度、隔离和恢复。2.3 为什么是 Kubernetes而不是自己写调度器有人会问Agent 编排这么特殊为什么不自己写一套调度系统我的答案是你最终还是要回到 Kubernetes因为你要的隔离、网络、存储、可观测性它都已经有了。自己写调度器听起来很酷但你要面对的是怎么限制一个 Agent 的内存不让它把宿主机吃爆怎么给不同 Agent 分配不同的网络策略怎么把日志和指标统一收集这些问题 Kubernetes 用 namespace、cgroup、CNI、CRI 已经解决了十年。你要做的不是重造这些轮子而是在 Kubernetes 的抽象之上加一层 Agent 语义。具体做法通常是用 CRD 定义 Agent 和 Task用 Operator 监听这些 CRD 的变化然后转换成 Pod、Job、ConfigMap 这些原生资源。这样你既拿到了 Kubernetes 的稳定性又保留了 Agent 层的灵活性。Karmada 这类多集群项目毕业其实也是这个思路的延伸——当你的 Agent 要跨集群调度时底层的多集群编排能力直接复用。3. 在 Kubernetes 上落地 Agentic Runtime 的关键设计3.1 用 CRD 描述 Agent 拓扑从静态 YAML 到动态图最直觉的做法是给每个 Agent 写一个 Deployment然后用 Service 互相调用。我早期就是这么干的结果很快撞墙Agent 之间的调用关系是动态的你没法在 YAML 里写死“A 调用 B”。而且每次改 prompt 都要重新打镜像、滚动升级迭代速度根本跟不上。后来我改成用 CRD 来描述。核心是三个资源apiVersion: ax.example.com/v1 kind: Agent metadata: name: researcher spec: model: gpt-4o systemPrompt: 你是一个研究助手... tools: - name: web_search endpoint: http://tool-search:8080 - name: summarize endpoint: http://tool-summarize:8080 maxSteps: 20 timeoutSeconds: 300apiVersion: ax.example.com/v1 kind: Task metadata: name: task-001 spec: entryAgent: researcher input: 帮我调研一下 Kubernetes 上跑 Agent 的最佳实践 sessionTTL: 86400Operator 监听到 Task 创建后会做几件事为这个 Task 创建一个 Session 记录存在 etcd 或外部数据库启动 entryAgent 对应的 Pod注入 Session ID 作为环境变量。Agent Pod 启动后从环境变量拿到 Session ID从挂载的 ConfigMap 拿到自己的配置然后开始跑。这里有个关键设计Agent Pod 不是常驻的。一个 Task 开始时创建Task 结束后销毁。这样做的理由是 Agent 的资源画像太不稳定常驻会浪费大量资源。但代价是冷启动延迟——如果 Agent 镜像很大每次启动要等几十秒。我的做法是把基础镜像做薄把模型调用做成 sidecar 或者外部服务Agent Pod 本身只跑编排逻辑。3.2 决策点的持久化Session 到底该怎么存Session 存储是整套系统里最容易做错的地方。我见过有人直接把 Session 存在 Agent Pod 的内存里Pod 一挂全丢也见过有人每步都写数据库结果写放大把数据库打爆。我的经验是Session 要分层存。热数据最近几步的决策记录放 Redis冷数据完整历史放对象存储或宽表。每次 Agent 做出一个决策调用工具、切换 Agent、输出结果就往 Redis 写一条记录同时异步刷到冷存储。这样恢复的时候先从 Redis 读最近状态如果 Redis 没有再从冷存储重建。记录的结构大概是这样{ sessionId: sess-abc123, taskId: task-001, step: 7, agent: researcher, action: tool_call, tool: web_search, input: {query: kubernetes agent orchestration}, output: {results: [...]}, timestamp: 2026-09-22T09:40:00Z, status: completed }这里有个坑工具调用的幂等性。如果 Agent 调了一个有副作用的工具比如发邮件、下单然后 Pod 挂了恢复后它可能会重试。所以每个工具调用必须带一个幂等键工具侧要能识别重复请求。我在实际项目里是强制要求所有 Tool 接口都接受idempotency-keyheader没有这个 header 的请求直接拒绝。3.3 资源隔离与配额别让一个 Agent 拖垮整个集群Agent 的资源消耗有个特点突发性极强。推理的时候可能要吃满 GPU等结果的时候几乎不占资源。如果按峰值分配浪费巨大如果按均值分配峰值来了就 OOM。我的做法是给 Agent Pod 设置requests 按均值、limits 按峰值同时用 Kubernetes 的 ResourceQuota 限制单个 namespace 的总量。更重要的是给每个 Task 设置一个总预算——比如最多消耗 10 个 CPU 小时、5GB 内存小时。Operator 在调度时会检查这个预算超了就拒绝启动新 Agent。另一个容易被忽略的是网络隔离。Agent 会调用各种外部工具如果不加限制一个被 prompt 注入攻击的 Agent 可能去调它不该调的工具。我的做法是用 NetworkPolicy 限制 Agent Pod 的出站流量只允许访问白名单里的工具服务。这个白名单从 Agent 的 CRD 里读动态生成 NetworkPolicy。4. 实操从零搭一个最小可用的 Agentic Runtime4.1 环境准备与依赖检查假设你已经有一个能用的 Kubernetes 集群v1.26 以上并且 kubectl 配置好了。先确认几个前提条件kubectl version --short kubectl get nodes kubectl get sc # 确认有默认 StorageClass然后检查集群里有没有装 cert-managerOperator 的 webhook 需要证书和 prometheus-operator可观测性。如果没有用 helm 装一下helm repo add jetstack https://charts.jetstack.io helm install cert-manager jetstack/cert-manager \ --namespace cert-manager --create-namespace \ --set installCRDstrue这里有个实测经验cert-manager 的版本要和 Kubernetes 版本匹配。我在 v1.26 集群上装过 cert-manager v1.16webhook 一直起不来日志里报unable to locate the codex cli binary or required runtime components这种看起来完全不相关的错误最后发现是 cert-manager 的 API 版本和集群不兼容。降到 v1.14 就正常了。所以装之前先查一下兼容性矩阵别盲目用 latest。4.2 定义 CRD 与 Operator 骨架CRD 的定义我前面已经给了 Agent 和 Task 两个。Operator 用 kubebuilder 生成骨架kubebuilder init --domain example.com --repo github.com/example/ax-operator kubebuilder create api --group ax --version v1 --kind Agent kubebuilder create api --group ax --version v1 --kind Task make manifests make installReconcile 逻辑的核心是监听 Task 的创建事件创建对应的 Session 记录然后启动 entryAgent 的 Pod。Pod 的模板大概是这样apiVersion: v1 kind: Pod metadata: name: agent-{{taskId}}-{{step}} labels: ax/task-id: {{taskId}} ax/agent: {{agentName}} spec: restartPolicy: Never containers: - name: agent image: registry.example.com/ax-agent-runtime:latest env: - name: SESSION_ID value: {{sessionId}} - name: AGENT_CONFIG valueFrom: configMapKeyRef: name: agent-{{agentName}}-config key: config.yaml resources: requests: cpu: 500m memory: 512Mi limits: cpu: 2 memory: 2Gi注意restartPolicy: Never——Agent Pod 挂了就是挂了由 Operator 决定是重建还是标记 Task 失败。不要让 Kubernetes 自动重启否则会丢失决策上下文。4.3 Agent Runtime 容器的实现要点Agent Runtime 容器是整个系统的心脏。它要做的事读配置、连 Session 存储、跑推理循环、调工具、写决策记录。我用 Python 写过一个最小实现核心循环大概 200 行import os, json, redis, requests session_id os.environ[SESSION_ID] r redis.Redis(hostredis, port6379) def load_config(): with open(/etc/agent/config.yaml) as f: return yaml.safe_load(f) def get_history(): return [json.loads(x) for x in r.lrange(fsession:{session_id}, 0, -1)] def call_tool(tool, input_data): idem_key f{session_id}-{len(get_history())} resp requests.post( tool[endpoint], jsoninput_data, headers{idempotency-key: idem_key}, timeout30 ) return resp.json() def record(step): r.rpush(fsession:{session_id}, json.dumps(step)) r.expire(fsession:{session_id}, 86400) def main(): config load_config() history get_history() # 这里接你的推理逻辑产出 next_action next_action decide(config, history) if next_action[type] tool_call: result call_tool(next_action[tool], next_action[input]) record({step: len(history), action: tool_call, result: result}) elif next_action[type] finish: record({step: len(history), action: finish, output: next_action[output]})这段代码里最关键的是idempotency-key的生成方式——我用session_id 当前步数作为键保证同一步的重试不会产生重复副作用。这个设计我踩过坑最早用 UUID结果重试时生成了新键工具侧以为是新请求重复执行了两次。4.4 部署与验证跑通第一个 Task把 Operator 和 Runtime 镜像都推上去之后创建一个测试 Taskkubectl apply -f - EOF apiVersion: ax.example.com/v1 kind: Task metadata: name: test-task spec: entryAgent: echo input: hello ax sessionTTL: 3600 EOF然后观察kubectl get tasks kubectl get pods -l ax/task-idtest-task kubectl logs -l ax/task-idtest-task如果一切正常你会看到 Pod 启动、跑完、退出Task 状态变成 Succeeded。如果卡住先看 Operator 日志再看 Pod 事件。我遇到最多的问题是 RBAC 权限不够——Operator 需要创建 Pod、ConfigMap、NetworkPolicy 的权限这些在 kubebuilder 生成的 role.yaml 里默认没有要手动加。5. 常见问题与排查技巧实录5.1 容器运行时相关的报错怎么定位热搜词里有一条[error cri]: container runtime is not running这个错误在 Agent 场景下特别常见因为 Agent Pod 生命周期短、创建频繁很容易触发容器运行时的限流或状态异常。排查顺序是先看节点状态kubectl describe node node确认Container Runtime那一栏是不是 Ready。如果是 containerd登到节点上看systemctl status containerd以及crictl ps能不能列出容器。如果 containerd 正常但 kubelet 报这个错大概率是 kubelet 和 containerd 的 socket 配置不一致检查/var/lib/kubelet/kubeadm-flags.env里的--container-runtime-endpoint。我实测下来Agent 场景下最稳妥的做法是给 Agent Pod 单独划一个节点池这个节点池的容器运行时配置调优过比如调大max-concurrent-downloads、缩短image-pull-progress-deadline避免和普通业务互相影响。5.2 WebView2 Runtime 缺失这类“环境依赖”问题热搜里还有could not find the webview2 runtime和you can install the product microsoft visual c 2022 x86 minimum runtime这些看起来和 Agent 编排无关但实际项目中经常遇到——因为很多 Agent 要调用的工具是 Windows 桌面应用或者依赖特定运行时的二进制。我的处理原则是所有工具依赖必须在镜像里固化不允许运行时动态安装。具体做法是在 Dockerfile 里显式声明所有依赖并且加一个启动时的自检脚本FROM mcr.microsoft.com/windows/servercore:ltsc2022 # 安装 VC runtime ADD https://example.com/vc_redist.x64.exe /tmp/ RUN /tmp/vc_redist.x64.exe /quiet /norestart # 自检 COPY check_runtime.ps1 /check_runtime.ps1 RUN powershell -File /check_runtime.ps1自检脚本里检查关键 DLL 是否存在、版本是否匹配不匹配就直接让构建失败。这样问题在 CI 阶段就暴露了不会等到线上跑 Task 的时候才发现。5.3 模型格式不兼容no lm runtime found for model format gguf这个报错说明你的推理引擎不认识 GGUF 格式。Agent 场景下模型来源很杂有的用 GGUF有的用 safetensors有的直接调 API。我的建议是在 Runtime 层做一层模型适配不要让 Agent 直接面对模型格式。具体做法是定义一个 Model 接口Agent 只认这个接口底层用哪个引擎、什么格式由适配层决定class ModelAdapter: def generate(self, prompt, **kwargs): raise NotImplementedError class GGUFAdapter(ModelAdapter): def __init__(self, model_path): from llama_cpp import Llama self.llm Llama(model_pathmodel_path) def generate(self, prompt, **kwargs): return self.llm(prompt, **kwargs) class APIAdapter(ModelAdapter): def __init__(self, endpoint, api_key): self.endpoint endpoint self.api_key api_key def generate(self, prompt, **kwargs): resp requests.post(self.endpoint, json{prompt: prompt, **kwargs}, headers{Authorization: fBearer {self.api_key}}) return resp.json()[text]这样换模型只需要换 AdapterAgent 的逻辑完全不用动。这个设计我在三个项目里复用每次换模型都是半天搞定。5.4 常见问题速查表现象可能原因排查动作解决方式Task 一直 Pending资源配额不足或调度失败kubectl describe task看 Events调大 ResourceQuota 或加节点Agent Pod 反复重启restartPolicy 配置错误kubectl get pod -o yaml看 restartPolicy改成 Never由 Operator 控制工具调用超时工具服务响应慢或网络策略拦截在 Pod 里 curl 工具地址调大 timeout检查 NetworkPolicySession 丢失Redis 没持久化或 TTL 太短redis-cli ttl session:xxx开启 AOF调大 TTL决策重复执行幂等键生成逻辑有误看工具侧日志是否有重复请求用 sessionstep 生成幂等键Operator 无响应webhook 证书过期kubectl logs -n ax-system deploy/ax-controller-manager重启 cert-manager 或手动续签6. 多集群与规模化当 Agent 数量超过单集群承载6.1 Karmada 这类多集群编排的接入点单集群跑几十个 Agent 没问题上百个就开始吃力上千个基本要炸。这时候就得上多集群。Karmada 毕业之后多集群编排的成熟度已经足够支撑生产它的核心价值是把 Agent 的调度决策从单集群扩展到集群联邦。接入方式不复杂把 Agent 和 Task 的 CRD 注册到 Karmada 控制面然后定义 PropagationPolicy决定哪些 Task 调度到哪些成员集群。比如按地域调度apiVersion: policy.karmada.io/v1alpha1 kind: PropagationPolicy metadata: name: task-propagation spec: resourceSelectors: - apiVersion: ax.example.com/v1 kind: Task placement: clusterAffinity: clusterNames: - cluster-beijing - cluster-shanghai spreadConstraints: - spreadByField: cluster maxGroups: 2这样 Task 会被均匀分散到两个集群避免单集群过载。但要注意Session 存储必须跨集群共享否则 Agent 在 A 集群启动、漂移到 B 集群后读不到历史。我的做法是把 Redis 换成跨集群的 Redis Cluster或者直接用对象存储做 Session 后端。6.2 规模化后的成本控制Agent 跑多了成本会失控。我见过一个团队一个月烧掉几十万最后发现是某个 Agent 陷入了死循环一直在调工具。控制成本的核心手段是预算 熔断每个 Task 设置最大步数maxSteps超过就强制终止。每个 Agent 设置最大工具调用次数超过就降级。整个 namespace 设置 ResourceQuota防止单个团队吃光集群。接入成本监控按 Task 维度统计资源消耗异常时告警。这些手段里最大步数是最有效的。我实测下来90% 的失控都是因为 Agent 陷入了“调工具→结果不满意→再调”的循环。设一个 20 步的上限基本能拦住绝大多数问题。7. 我踩过的几个印象深刻的坑第一个坑是把 Agent 当无状态服务来设计。早期我觉得 Agent 每次都是新 Pod天然无状态结果发现 Agent 的“记忆”全在 Session 里Session 丢了整个 Task 就废了。后来我把 Session 的可靠性提到和数据库一个级别做了主从 定期备份才敢上生产。第二个坑是工具的超时设置。我一开始给所有工具设了 30 秒超时结果有个工具是调人工审批的30 秒根本不够Task 全卡死。后来改成按工具类型分别设超时计算类 10 秒查询类 30 秒人工类 24 小时。这个分类看起来简单但没踩过坑的人真的想不到。第三个坑是日志量爆炸。Agent 每一步决策都打日志一个 Task 跑 20 步就是 20 条一天一万个 Task 就是 20 万条。日志系统直接被打爆。后来我改成结构化日志 采样关键决策点全量记录中间过程按 10% 采样。这样既保留了排查能力又把日志量降了一个数量级。最后一个坑是版本兼容。Agent 的 prompt 和工具接口是强耦合的改了 prompt 没改工具或者改了工具没改 prompt都会导致 Task 失败。我的做法是给 Agent 配置加版本号prompt 和工具集必须版本匹配不匹配直接拒绝启动。这个约束看起来死板但省掉了无数“为什么昨天还好今天就不行”的排查时间。这套东西我前后迭代了大概一年半从最早的脚本拼凑到现在相对稳定的 Operator Runtime 架构中间推翻重来过两次。如果你现在刚开始做我的建议是先把单集群跑通把 Session 和幂等这两个基础打牢再考虑多集群和规模化。很多团队一上来就追求“云原生”“多集群”结果基础没打好后面全是补丁。
Kubernetes 上的 Agentic Runtime 编排：从 CRD 到多集群的工程实践
1. 从“ax”这个标题说起一个被低估的运行时编排命题第一次看到“ax”这个标题很多人会一头雾水——两个字母既不像产品名也不像技术栈缩写。但把热搜词摊开来看线索就清楚了agentic、orchestration、runtime、Kubernetes这几个词反复出现再加上“karmada正式毕业”“agentic cloud坚实底座”这类行业动态基本可以判断“ax”指向的是一个面向智能体Agent场景的运行时编排层而不是某个具体的开源项目名。换句话说它更像是一类问题的代号当你的系统里跑的不再是单纯的容器而是一堆会自己决策、自己调工具、自己调其他 Agent 的“活体进程”时底层的调度、隔离、生命周期管理该怎么做。我过去两年在几个内部平台里折腾过类似的东西从最早的“把 LLM 调用塞进 CronJob”这种土办法到后来用 Kubernetes 的 CRD 去描述 Agent 的拓扑关系踩过的坑足够写一本小册子。所以这篇东西不打算复述任何官方文档而是把我理解的“ax 这一类运行时编排系统”拆开来讲它到底解决什么问题、核心抽象是什么、在 Kubernetes 上落地时哪些地方最容易翻车、以及我实测下来比较稳的一套做法。适合谁看如果你已经在用 Kubernetes 跑服务现在想把 Agent 工作流也搬上去或者你正在设计一个多 Agent 协作平台那这篇内容应该能帮你省掉至少两轮返工。如果你只是听说过 agentic 这个词也没关系我会从最基础的概念开始铺垫尽量用生活化的类比把运行时编排这件事讲透。2. 核心概念拆解Agentic Runtime 到底在编排什么2.1 从“容器编排”到“智能体编排”的范式迁移Kubernetes 解决的核心问题是我有一堆无状态的容器怎么让它们在几百台机器上合理分布、故障自愈、滚动升级。它的基本假设是——进程是哑的行为是确定的。你给它一个镜像它跑起来就是那套逻辑不会今天调这个 API、明天自己决定换个数据库。Agent 完全打破了这个假设。一个 Agent 的运行过程是接收输入 → 推理 → 决定调用哪个工具 → 拿到结果 → 再推理 → 可能再调另一个 Agent → 最终输出。这个过程里下一步做什么是运行时才决定的而且同一个输入两次跑出来的路径可能完全不同。这就带来几个容器编排从来没遇到过的问题生命周期不确定一个 Agent 任务可能 200ms 结束也可能因为要等一个人工审批卡在那里 3 天。资源画像漂移推理阶段吃 GPU调工具阶段几乎不吃等审批阶段纯占内存。依赖是动态的Agent A 今天调 B明天可能因为 prompt 变了去调 C拓扑关系不是静态声明的。状态必须可恢复跑到一半挂了不能从头再来得从上一个“决策点”续上。所以“ax”这类系统要做的不是把 Agent 当成容器来调度而是在容器编排之上再抽象一层“决策点编排”。我习惯把它类比成Kubernetes 管的是“谁在哪里跑”Agentic Runtime 管的是“谁在什么时候决定让谁跑”。2.2 四个核心抽象Task、Agent、Tool、Session不管具体实现叫什么名字我见过的所有 Agentic Runtime 都绕不开这四个概念。理解它们之间的关系比记任何 API 都重要。Task是最外层的单位代表“用户想要完成的一件事”。它是有明确终态的——成功、失败、取消。一个 Task 可以理解成一个有向无环图DAG但和传统工作流不同的是这个图的边是运行时才确定的。Agent是执行单元每个 Agent 有自己的系统提示、可用工具集、模型配置。它接收一个输入产出一个输出中间可能产生若干次工具调用。Agent 本身是无状态的状态存在 Session 里。Tool是 Agent 能调用的外部能力可以是一个 HTTP 接口、一段代码、甚至另一个 Agent。Tool 的关键属性是幂等性和超时——这两个属性没定义好整个编排就会变成一团乱麻。Session是状态的载体。它记录了这个 Task 到目前为止的所有决策、工具调用结果、中间产物。Session 必须能持久化而且最好能支持“回放到某个决策点”。把这四个东西的关系画清楚其实就一句话Task 驱动 AgentAgent 通过 Tool 产生副作用所有过程记录在 Session 里。Runtime 的职责就是保证这四者之间的调度、隔离和恢复。2.3 为什么是 Kubernetes而不是自己写调度器有人会问Agent 编排这么特殊为什么不自己写一套调度系统我的答案是你最终还是要回到 Kubernetes因为你要的隔离、网络、存储、可观测性它都已经有了。自己写调度器听起来很酷但你要面对的是怎么限制一个 Agent 的内存不让它把宿主机吃爆怎么给不同 Agent 分配不同的网络策略怎么把日志和指标统一收集这些问题 Kubernetes 用 namespace、cgroup、CNI、CRI 已经解决了十年。你要做的不是重造这些轮子而是在 Kubernetes 的抽象之上加一层 Agent 语义。具体做法通常是用 CRD 定义 Agent 和 Task用 Operator 监听这些 CRD 的变化然后转换成 Pod、Job、ConfigMap 这些原生资源。这样你既拿到了 Kubernetes 的稳定性又保留了 Agent 层的灵活性。Karmada 这类多集群项目毕业其实也是这个思路的延伸——当你的 Agent 要跨集群调度时底层的多集群编排能力直接复用。3. 在 Kubernetes 上落地 Agentic Runtime 的关键设计3.1 用 CRD 描述 Agent 拓扑从静态 YAML 到动态图最直觉的做法是给每个 Agent 写一个 Deployment然后用 Service 互相调用。我早期就是这么干的结果很快撞墙Agent 之间的调用关系是动态的你没法在 YAML 里写死“A 调用 B”。而且每次改 prompt 都要重新打镜像、滚动升级迭代速度根本跟不上。后来我改成用 CRD 来描述。核心是三个资源apiVersion: ax.example.com/v1 kind: Agent metadata: name: researcher spec: model: gpt-4o systemPrompt: 你是一个研究助手... tools: - name: web_search endpoint: http://tool-search:8080 - name: summarize endpoint: http://tool-summarize:8080 maxSteps: 20 timeoutSeconds: 300apiVersion: ax.example.com/v1 kind: Task metadata: name: task-001 spec: entryAgent: researcher input: 帮我调研一下 Kubernetes 上跑 Agent 的最佳实践 sessionTTL: 86400Operator 监听到 Task 创建后会做几件事为这个 Task 创建一个 Session 记录存在 etcd 或外部数据库启动 entryAgent 对应的 Pod注入 Session ID 作为环境变量。Agent Pod 启动后从环境变量拿到 Session ID从挂载的 ConfigMap 拿到自己的配置然后开始跑。这里有个关键设计Agent Pod 不是常驻的。一个 Task 开始时创建Task 结束后销毁。这样做的理由是 Agent 的资源画像太不稳定常驻会浪费大量资源。但代价是冷启动延迟——如果 Agent 镜像很大每次启动要等几十秒。我的做法是把基础镜像做薄把模型调用做成 sidecar 或者外部服务Agent Pod 本身只跑编排逻辑。3.2 决策点的持久化Session 到底该怎么存Session 存储是整套系统里最容易做错的地方。我见过有人直接把 Session 存在 Agent Pod 的内存里Pod 一挂全丢也见过有人每步都写数据库结果写放大把数据库打爆。我的经验是Session 要分层存。热数据最近几步的决策记录放 Redis冷数据完整历史放对象存储或宽表。每次 Agent 做出一个决策调用工具、切换 Agent、输出结果就往 Redis 写一条记录同时异步刷到冷存储。这样恢复的时候先从 Redis 读最近状态如果 Redis 没有再从冷存储重建。记录的结构大概是这样{ sessionId: sess-abc123, taskId: task-001, step: 7, agent: researcher, action: tool_call, tool: web_search, input: {query: kubernetes agent orchestration}, output: {results: [...]}, timestamp: 2026-09-22T09:40:00Z, status: completed }这里有个坑工具调用的幂等性。如果 Agent 调了一个有副作用的工具比如发邮件、下单然后 Pod 挂了恢复后它可能会重试。所以每个工具调用必须带一个幂等键工具侧要能识别重复请求。我在实际项目里是强制要求所有 Tool 接口都接受idempotency-keyheader没有这个 header 的请求直接拒绝。3.3 资源隔离与配额别让一个 Agent 拖垮整个集群Agent 的资源消耗有个特点突发性极强。推理的时候可能要吃满 GPU等结果的时候几乎不占资源。如果按峰值分配浪费巨大如果按均值分配峰值来了就 OOM。我的做法是给 Agent Pod 设置requests 按均值、limits 按峰值同时用 Kubernetes 的 ResourceQuota 限制单个 namespace 的总量。更重要的是给每个 Task 设置一个总预算——比如最多消耗 10 个 CPU 小时、5GB 内存小时。Operator 在调度时会检查这个预算超了就拒绝启动新 Agent。另一个容易被忽略的是网络隔离。Agent 会调用各种外部工具如果不加限制一个被 prompt 注入攻击的 Agent 可能去调它不该调的工具。我的做法是用 NetworkPolicy 限制 Agent Pod 的出站流量只允许访问白名单里的工具服务。这个白名单从 Agent 的 CRD 里读动态生成 NetworkPolicy。4. 实操从零搭一个最小可用的 Agentic Runtime4.1 环境准备与依赖检查假设你已经有一个能用的 Kubernetes 集群v1.26 以上并且 kubectl 配置好了。先确认几个前提条件kubectl version --short kubectl get nodes kubectl get sc # 确认有默认 StorageClass然后检查集群里有没有装 cert-managerOperator 的 webhook 需要证书和 prometheus-operator可观测性。如果没有用 helm 装一下helm repo add jetstack https://charts.jetstack.io helm install cert-manager jetstack/cert-manager \ --namespace cert-manager --create-namespace \ --set installCRDstrue这里有个实测经验cert-manager 的版本要和 Kubernetes 版本匹配。我在 v1.26 集群上装过 cert-manager v1.16webhook 一直起不来日志里报unable to locate the codex cli binary or required runtime components这种看起来完全不相关的错误最后发现是 cert-manager 的 API 版本和集群不兼容。降到 v1.14 就正常了。所以装之前先查一下兼容性矩阵别盲目用 latest。4.2 定义 CRD 与 Operator 骨架CRD 的定义我前面已经给了 Agent 和 Task 两个。Operator 用 kubebuilder 生成骨架kubebuilder init --domain example.com --repo github.com/example/ax-operator kubebuilder create api --group ax --version v1 --kind Agent kubebuilder create api --group ax --version v1 --kind Task make manifests make installReconcile 逻辑的核心是监听 Task 的创建事件创建对应的 Session 记录然后启动 entryAgent 的 Pod。Pod 的模板大概是这样apiVersion: v1 kind: Pod metadata: name: agent-{{taskId}}-{{step}} labels: ax/task-id: {{taskId}} ax/agent: {{agentName}} spec: restartPolicy: Never containers: - name: agent image: registry.example.com/ax-agent-runtime:latest env: - name: SESSION_ID value: {{sessionId}} - name: AGENT_CONFIG valueFrom: configMapKeyRef: name: agent-{{agentName}}-config key: config.yaml resources: requests: cpu: 500m memory: 512Mi limits: cpu: 2 memory: 2Gi注意restartPolicy: Never——Agent Pod 挂了就是挂了由 Operator 决定是重建还是标记 Task 失败。不要让 Kubernetes 自动重启否则会丢失决策上下文。4.3 Agent Runtime 容器的实现要点Agent Runtime 容器是整个系统的心脏。它要做的事读配置、连 Session 存储、跑推理循环、调工具、写决策记录。我用 Python 写过一个最小实现核心循环大概 200 行import os, json, redis, requests session_id os.environ[SESSION_ID] r redis.Redis(hostredis, port6379) def load_config(): with open(/etc/agent/config.yaml) as f: return yaml.safe_load(f) def get_history(): return [json.loads(x) for x in r.lrange(fsession:{session_id}, 0, -1)] def call_tool(tool, input_data): idem_key f{session_id}-{len(get_history())} resp requests.post( tool[endpoint], jsoninput_data, headers{idempotency-key: idem_key}, timeout30 ) return resp.json() def record(step): r.rpush(fsession:{session_id}, json.dumps(step)) r.expire(fsession:{session_id}, 86400) def main(): config load_config() history get_history() # 这里接你的推理逻辑产出 next_action next_action decide(config, history) if next_action[type] tool_call: result call_tool(next_action[tool], next_action[input]) record({step: len(history), action: tool_call, result: result}) elif next_action[type] finish: record({step: len(history), action: finish, output: next_action[output]})这段代码里最关键的是idempotency-key的生成方式——我用session_id 当前步数作为键保证同一步的重试不会产生重复副作用。这个设计我踩过坑最早用 UUID结果重试时生成了新键工具侧以为是新请求重复执行了两次。4.4 部署与验证跑通第一个 Task把 Operator 和 Runtime 镜像都推上去之后创建一个测试 Taskkubectl apply -f - EOF apiVersion: ax.example.com/v1 kind: Task metadata: name: test-task spec: entryAgent: echo input: hello ax sessionTTL: 3600 EOF然后观察kubectl get tasks kubectl get pods -l ax/task-idtest-task kubectl logs -l ax/task-idtest-task如果一切正常你会看到 Pod 启动、跑完、退出Task 状态变成 Succeeded。如果卡住先看 Operator 日志再看 Pod 事件。我遇到最多的问题是 RBAC 权限不够——Operator 需要创建 Pod、ConfigMap、NetworkPolicy 的权限这些在 kubebuilder 生成的 role.yaml 里默认没有要手动加。5. 常见问题与排查技巧实录5.1 容器运行时相关的报错怎么定位热搜词里有一条[error cri]: container runtime is not running这个错误在 Agent 场景下特别常见因为 Agent Pod 生命周期短、创建频繁很容易触发容器运行时的限流或状态异常。排查顺序是先看节点状态kubectl describe node node确认Container Runtime那一栏是不是 Ready。如果是 containerd登到节点上看systemctl status containerd以及crictl ps能不能列出容器。如果 containerd 正常但 kubelet 报这个错大概率是 kubelet 和 containerd 的 socket 配置不一致检查/var/lib/kubelet/kubeadm-flags.env里的--container-runtime-endpoint。我实测下来Agent 场景下最稳妥的做法是给 Agent Pod 单独划一个节点池这个节点池的容器运行时配置调优过比如调大max-concurrent-downloads、缩短image-pull-progress-deadline避免和普通业务互相影响。5.2 WebView2 Runtime 缺失这类“环境依赖”问题热搜里还有could not find the webview2 runtime和you can install the product microsoft visual c 2022 x86 minimum runtime这些看起来和 Agent 编排无关但实际项目中经常遇到——因为很多 Agent 要调用的工具是 Windows 桌面应用或者依赖特定运行时的二进制。我的处理原则是所有工具依赖必须在镜像里固化不允许运行时动态安装。具体做法是在 Dockerfile 里显式声明所有依赖并且加一个启动时的自检脚本FROM mcr.microsoft.com/windows/servercore:ltsc2022 # 安装 VC runtime ADD https://example.com/vc_redist.x64.exe /tmp/ RUN /tmp/vc_redist.x64.exe /quiet /norestart # 自检 COPY check_runtime.ps1 /check_runtime.ps1 RUN powershell -File /check_runtime.ps1自检脚本里检查关键 DLL 是否存在、版本是否匹配不匹配就直接让构建失败。这样问题在 CI 阶段就暴露了不会等到线上跑 Task 的时候才发现。5.3 模型格式不兼容no lm runtime found for model format gguf这个报错说明你的推理引擎不认识 GGUF 格式。Agent 场景下模型来源很杂有的用 GGUF有的用 safetensors有的直接调 API。我的建议是在 Runtime 层做一层模型适配不要让 Agent 直接面对模型格式。具体做法是定义一个 Model 接口Agent 只认这个接口底层用哪个引擎、什么格式由适配层决定class ModelAdapter: def generate(self, prompt, **kwargs): raise NotImplementedError class GGUFAdapter(ModelAdapter): def __init__(self, model_path): from llama_cpp import Llama self.llm Llama(model_pathmodel_path) def generate(self, prompt, **kwargs): return self.llm(prompt, **kwargs) class APIAdapter(ModelAdapter): def __init__(self, endpoint, api_key): self.endpoint endpoint self.api_key api_key def generate(self, prompt, **kwargs): resp requests.post(self.endpoint, json{prompt: prompt, **kwargs}, headers{Authorization: fBearer {self.api_key}}) return resp.json()[text]这样换模型只需要换 AdapterAgent 的逻辑完全不用动。这个设计我在三个项目里复用每次换模型都是半天搞定。5.4 常见问题速查表现象可能原因排查动作解决方式Task 一直 Pending资源配额不足或调度失败kubectl describe task看 Events调大 ResourceQuota 或加节点Agent Pod 反复重启restartPolicy 配置错误kubectl get pod -o yaml看 restartPolicy改成 Never由 Operator 控制工具调用超时工具服务响应慢或网络策略拦截在 Pod 里 curl 工具地址调大 timeout检查 NetworkPolicySession 丢失Redis 没持久化或 TTL 太短redis-cli ttl session:xxx开启 AOF调大 TTL决策重复执行幂等键生成逻辑有误看工具侧日志是否有重复请求用 sessionstep 生成幂等键Operator 无响应webhook 证书过期kubectl logs -n ax-system deploy/ax-controller-manager重启 cert-manager 或手动续签6. 多集群与规模化当 Agent 数量超过单集群承载6.1 Karmada 这类多集群编排的接入点单集群跑几十个 Agent 没问题上百个就开始吃力上千个基本要炸。这时候就得上多集群。Karmada 毕业之后多集群编排的成熟度已经足够支撑生产它的核心价值是把 Agent 的调度决策从单集群扩展到集群联邦。接入方式不复杂把 Agent 和 Task 的 CRD 注册到 Karmada 控制面然后定义 PropagationPolicy决定哪些 Task 调度到哪些成员集群。比如按地域调度apiVersion: policy.karmada.io/v1alpha1 kind: PropagationPolicy metadata: name: task-propagation spec: resourceSelectors: - apiVersion: ax.example.com/v1 kind: Task placement: clusterAffinity: clusterNames: - cluster-beijing - cluster-shanghai spreadConstraints: - spreadByField: cluster maxGroups: 2这样 Task 会被均匀分散到两个集群避免单集群过载。但要注意Session 存储必须跨集群共享否则 Agent 在 A 集群启动、漂移到 B 集群后读不到历史。我的做法是把 Redis 换成跨集群的 Redis Cluster或者直接用对象存储做 Session 后端。6.2 规模化后的成本控制Agent 跑多了成本会失控。我见过一个团队一个月烧掉几十万最后发现是某个 Agent 陷入了死循环一直在调工具。控制成本的核心手段是预算 熔断每个 Task 设置最大步数maxSteps超过就强制终止。每个 Agent 设置最大工具调用次数超过就降级。整个 namespace 设置 ResourceQuota防止单个团队吃光集群。接入成本监控按 Task 维度统计资源消耗异常时告警。这些手段里最大步数是最有效的。我实测下来90% 的失控都是因为 Agent 陷入了“调工具→结果不满意→再调”的循环。设一个 20 步的上限基本能拦住绝大多数问题。7. 我踩过的几个印象深刻的坑第一个坑是把 Agent 当无状态服务来设计。早期我觉得 Agent 每次都是新 Pod天然无状态结果发现 Agent 的“记忆”全在 Session 里Session 丢了整个 Task 就废了。后来我把 Session 的可靠性提到和数据库一个级别做了主从 定期备份才敢上生产。第二个坑是工具的超时设置。我一开始给所有工具设了 30 秒超时结果有个工具是调人工审批的30 秒根本不够Task 全卡死。后来改成按工具类型分别设超时计算类 10 秒查询类 30 秒人工类 24 小时。这个分类看起来简单但没踩过坑的人真的想不到。第三个坑是日志量爆炸。Agent 每一步决策都打日志一个 Task 跑 20 步就是 20 条一天一万个 Task 就是 20 万条。日志系统直接被打爆。后来我改成结构化日志 采样关键决策点全量记录中间过程按 10% 采样。这样既保留了排查能力又把日志量降了一个数量级。最后一个坑是版本兼容。Agent 的 prompt 和工具接口是强耦合的改了 prompt 没改工具或者改了工具没改 prompt都会导致 Task 失败。我的做法是给 Agent 配置加版本号prompt 和工具集必须版本匹配不匹配直接拒绝启动。这个约束看起来死板但省掉了无数“为什么昨天还好今天就不行”的排查时间。这套东西我前后迭代了大概一年半从最早的脚本拼凑到现在相对稳定的 Operator Runtime 架构中间推翻重来过两次。如果你现在刚开始做我的建议是先把单集群跑通把 Session 和幂等这两个基础打牢再考虑多集群和规模化。很多团队一上来就追求“云原生”“多集群”结果基础没打好后面全是补丁。
