1. 从“ax”这个标题说起一个被低估的调度关键词第一次看到“ax”这个标题很多人会以为是某个库的缩写或者干脆是打错了。但把热词铺开一看——ax调度、agent、kubernetes、workspace、gateway——这几个词凑在一起指向其实非常明确这是一套围绕Agent 工作负载在 Kubernetes 上的调度与网关接入的实践方案。ax 在这里我更倾向于把它理解成一个代号代表“agent execution”这条链路也就是智能体从被创建、被调度、被分配到工作空间到最终通过网关对外提供服务的完整闭环。为什么这个方向值得单独拿出来讲因为过去一年里Agent 类应用的部署形态发生了明显变化。早期大家跑一个 Agent基本就是本地起个进程配个 API Key能对话就行。但现在不一样了Agent 开始有记忆、有工具调用、有沙箱工作空间、有多实例并发甚至一个 Agent 背后挂着好几个子 Agent 协同。这种负载放到单机上跑资源隔离做不好一个 Agent 把内存吃满其他全挂放到 Kubernetes 上跑又会遇到调度策略、工作空间持久化、网关路由、502 报错排查这一堆问题。热词里那些“502 bad gateway”“workspace requires the virtual machine platform”“setting up workspace loading packages 卡住”全都是真实踩坑现场。这篇内容适合三类人看一是正在把 Agent 从本地脚本往集群上迁的开发者二是负责 Agent 平台基础设施、需要设计调度和网关方案的工程师三是刚接触 Kubernetes想搞明白 Agent 场景下调度到底特殊在哪的入门者。我会尽量把每个决策背后的“为什么”讲清楚参数怎么算、配置怎么写、报错怎么查都给出可以直接抄的路径。不堆概念讲人话。2. 整体设计思路为什么 Agent 负载不能照搬普通微服务那套2.1 Agent 负载的三个特殊之处普通微服务是无状态的请求来了处理完就走副本随便扩缩容调度器想放哪放哪。Agent 完全不是这个逻辑。第一个特殊点是有状态的工作空间。一个 Agent 在运行过程中会产生会话上下文、临时文件、工具调用的中间产物这些东西往往需要挂载到一个持久化的 workspace 里。热词里“claudes workspace requires the virtual machine platform on windows”就是典型的 workspace 依赖问题——工作空间不是简单挂个空目录就行它对运行环境有要求。第二个特殊点是执行时长不可预测。普通接口几百毫秒返回Agent 一次任务可能跑几分钟甚至几十分钟中间还要调外部工具、等模型响应。这就导致调度时不能简单按 CPU 请求量来装箱否则一个长任务把节点占死其他 Pod 排队。第三个特殊点是网关链路更长。Agent 对外通常不是直接暴露端口而是经过一层 gateway 做鉴权、限流、协议转换。热词里“springcloud gateway”“vercel ai gateway”“gateway配置路由转发固定链接地址”都指向这个环节。链路一长502 这类错误就特别容易出现而且排查起来要一层层剥。2.2 调度方案选型为什么是 Kubernetes 而不是别的有人会问Agent 调度用 Docker Compose 或者 Nomad 不行吗小规模确实行但一旦涉及多租户、多 Agent 类型、动态扩缩容Kubernetes 的优势就出来了。它的 Device Plugin 机制可以把特殊资源比如 GPU、特定加速卡抽象成可调度资源热词里“kubernetes device plugin”就是这个点。Agent 如果要用到推理加速硬件通过 Device Plugin 注册后调度器就能像分配 CPU 一样分配这些设备。另一个关键是 Kubernetes 的Workspace 抽象能力。通过 PersistentVolumeClaim 加 StorageClass可以给每个 Agent 实例分配独立的工作空间互不干扰。再配合 Namespace 做租户隔离一个团队一个命名空间资源配额和网络策略都能单独控制。这套组合拳是 Compose 给不了的。至于 ax 调度这个说法我理解它强调的是“agent execution 调度”核心是在标准调度器之上加一层面向 Agent 的调度策略。标准 Kubernetes 调度看的是资源请求和节点亲和性而 Agent 调度还要看工作空间就绪状态、网关注册状态、依赖的模型服务是否可用。这层逻辑通常通过自定义调度器扩展或者 Admission Webhook 来实现。2.3 网关在整个链路里的位置Gateway 不是可有可无的装饰。Agent 对外提供服务时网关承担四件事路由把请求转发到正确的 Agent 实例、鉴权校验调用方身份、限流防止单个 Agent 被打爆、协议适配把外部 HTTP 请求转成 Agent 内部能理解的格式。热词里“gateway nc adapter 下载”“gateway配置路由转发固定链接地址”说明很多人在做路由固定化这件事也就是让某个 Agent 始终对应某个固定入口而不是每次调度后地址都变。这里有个设计取舍是让网关做服务发现动态路由还是给每个 Agent 分配固定地址动态路由灵活但调试麻烦固定地址稳定但扩缩容时要额外维护映射。我的经验是对外暴露的 Agent 用固定地址加网关转发内部子 Agent 之间用动态服务发现这样兼顾稳定性和灵活性。3. 核心细节解析调度、工作空间、网关三块硬骨头3.1 ax 调度的核心参数与计算逻辑Agent 调度最容易被忽视的是资源请求的设置。很多人拍脑袋写requests: cpu 500m, memory 1Gi结果要么调度不上去要么节点被压垮。正确的做法是先测出单个 Agent 实例的基线资源和峰值资源。基线资源是 Agent 空闲等待时的占用比如一个常驻的 Agent 进程不处理任务时可能占 200MB 内存、50m CPU。峰值资源是处理任务时的占用可能飙到 2GB 内存、1 核 CPU。调度请求应该按基线设限制按峰值设这样调度器能装下更多实例同时用 limit 防止单个实例失控。具体计算可以这样假设节点有 16 核 64GB预留 2 核 8GB 给系统组件可用 14 核 56GB。单 Agent 基线 50m CPU、200MB 内存那么理论上能装 280 个实例按 CPU 算或 280 个按内存算。但实际要考虑峰值如果峰值是基线的 4 倍那实际安全并发数要打对折。我一般会留 30% 余量也就是单节点跑 100 到 150 个 Agent 实例比较稳。注意Agent 的内存峰值往往出现在模型响应解析和工具调用返回处理阶段这两个时刻要重点监控。用kubectl top pod配合 Prometheus 抓一段时间的数据比拍脑袋靠谱得多。3.2 Workspace 的持久化与初始化陷阱Workspace 这块坑最多。热词里“setting up workspace: loading packages...卡住”和“couldnt complete the workspace policy acknowledgment”都是初始化阶段的问题。Agent 的工作空间通常需要预装依赖包、初始化配置文件、拉取工具链这个过程如果放在 Pod 启动时做很容易超时或卡住。我的做法是把 workspace 初始化拆成两步基础镜像预置和运行时挂载。基础镜像里把常用的依赖、工具链、Python 包全部装好做成一个几百 MB 到 1GB 的镜像。运行时只挂载用户数据目录和会话目录这两个目录用 PVC 持久化。这样 Pod 启动时不需要再装包秒级就绪。PVC 的 StorageClass 选择也有讲究。如果 Agent 读写频繁用本地 SSD 的 StorageClass如果只是存会话记录用网络存储就行。读写性能差的工作空间会让 Agent 响应变慢用户感知很明显。apiVersion: v1 kind: PersistentVolumeClaim metadata: name: agent-workspace-pvc spec: accessModes: - ReadWriteOnce storageClassName: local-ssd resources: requests: storage: 20Gi这段 PVC 定义里ReadWriteOnce表示同一时间只能被一个节点挂载适合单 Agent 实例独占工作空间的场景。如果多个 Agent 要共享工作空间得用ReadWriteMany但性能会下降需要权衡。3.3 Gateway 配置从路由到 502 排查Gateway 配置的核心是路由规则。以 Spring Cloud Gateway 为例一条典型的 Agent 路由长这样spring: cloud: gateway: routes: - id: agent-route uri: http://agent-service:8080 predicates: - Path/agent/** filters: - StripPrefix1 - name: RequestRateLimiter args: redis-rate-limiter.replenishRate: 10 redis-rate-limiter.burstCapacity: 20这条规则的意思是所有/agent/**的请求转发到agent-service:8080转发前去掉第一层路径并且做限流每秒补充 10 个令牌突发上限 20。限流参数要根据 Agent 的处理能力来定如果单个 Agent 每秒只能处理 5 个请求那 replenishRate 设 10 就会把 Agent 打爆。502 Bad Gateway 在 Agent 场景下高频出现原因通常有三类上游 Agent 实例没就绪、网关到 Agent 的网络不通、Agent 处理超时导致连接被断。排查顺序是先用kubectl get endpoints看 Agent 的 Endpoint 是否注册再用curl从网关 Pod 内部直接访问 Agent 地址最后看 Agent 日志有没有超时或崩溃。热词里“unexpected status 502 bad gateway: cc switch local proxy failed”这种多半是本地代理层和网关层之间的连接问题要检查代理配置和网关的健康检查路径是否一致。4. 实操过程从零搭一套 Agent 调度加网关链路4.1 环境准备与基础组件安装先确认 Kubernetes 集群版本在 1.24 以上因为 Device Plugin 和调度器扩展的 API 在这个版本之后才稳定。集群至少三个节点一个控制面两个工作节点方便观察调度分布。安装顺序是先装 StorageClass 提供方比如本地盘方案或网络存储方案再装网关Spring Cloud Gateway 或类似方案最后装 Agent 运行时。网关和 Agent 之间通过 Service 通信不要直接写 Pod IP否则 Pod 重建后地址就失效了。kubectl create namespace agent-system kubectl create namespace agent-workspace kubectl apply -f storageclass.yaml kubectl apply -f gateway-deployment.yaml kubectl apply -f agent-runtime-daemonset.yaml这里把 Agent 运行时做成 DaemonSet 是有考虑的每个节点跑一个运行时守护进程负责管理该节点上所有 Agent 实例的工作空间挂载和生命周期。这样比每个 Agent 一个 Pod 更省资源启动也更快。4.2 Agent 实例的调度配置实战一个完整的 Agent 实例定义需要包含资源请求、工作空间挂载、网关注册三个部分。下面是一个精简后的模板apiVersion: apps/v1 kind: Deployment metadata: name: agent-instance namespace: agent-workspace spec: replicas: 3 selector: matchLabels: app: agent template: metadata: labels: app: agent spec: containers: - name: agent image: agent-runtime:latest resources: requests: cpu: 100m memory: 256Mi limits: cpu: 1 memory: 2Gi volumeMounts: - name: workspace mountPath: /workspace env: - name: GATEWAY_URL value: http://gateway.agent-system:8080 - name: AGENT_ID valueFrom: fieldRef: fieldPath: metadata.name volumes: - name: workspace persistentVolumeClaim: claimName: agent-workspace-pvc关键点在AGENT_ID这个环境变量它用 Pod 名字作为 Agent 的唯一标识启动后 Agent 会拿这个 ID 去网关注册。网关收到注册请求后把 ID 和 Pod IP 的映射写进路由表。这样网关就知道哪个请求该转发到哪个 Agent。调度策略上我给 Agent 加了节点亲和性让它们尽量分散到不同节点避免单节点故障导致全部 Agent 不可用affinity: podAntiAffinity: preferredDuringSchedulingIgnoredDuringExecution: - weight: 100 podAffinityTerm: labelSelector: matchLabels: app: agent topologyKey: kubernetes.io/hostnamepreferred而不是required是因为如果节点不够硬性反亲和会导致 Pod 调度不上去。用 preferred 让调度器尽量分散实在分散不了也能跑。4.3 网关注册与健康检查配置Agent 启动后要向网关注册注册内容包含 Agent ID、访问地址、健康检查路径。网关定期调健康检查路径连续失败三次就把这个 Agent 从路由表摘掉。健康检查路径建议单独做一个轻量接口不要用业务接口否则业务繁忙时健康检查超时会导致误摘。# Agent 侧注册逻辑示意 import requests import os agent_id os.environ[AGENT_ID] gateway_url os.environ[GATEWAY_URL] def register(): payload { id: agent_id, endpoint: fhttp://{os.environ[POD_IP]}:8080, health_path: /healthz } requests.post(f{gateway_url}/register, jsonpayload) def healthz(): return {status: ok}注册是幂等的Agent 重启后重新注册网关更新映射即可。这里有个细节Agent 优雅退出时要主动调注销接口否则网关要等健康检查失败才摘除这期间会有请求打到已经退出的实例上产生 502。4.4 完整链路验证与压测链路搭好后用curl从集群外部打网关地址看请求能不能正确路由到 Agent。然后做一轮压测观察三个指标网关的请求延迟、Agent 的 CPU 和内存曲线、502 出现的频率。压测工具用hey或wrk都行命令大概是这样hey -n 1000 -c 50 -m POST -d {task:test} http://gateway.example.com/agent/run1000 个请求50 并发。如果 502 比例超过 1%就要查是网关限流太严还是 Agent 处理不过来。我实测下来单 Agent 实例在 2 核 4G 的配置下处理简单任务能到每秒 20 到 30 个请求复杂任务会降到个位数。压测数据是调优限流参数的依据不要凭感觉设。5. 常见问题与排查技巧实录5.1 502 与连接超时速查表现象可能原因排查命令解决方向502 Bad GatewayAgent 实例未就绪kubectl get endpoints -n agent-workspace检查 Agent 启动日志和就绪探针502 且网关日志显示 connection refused网关到 Agent 网络不通kubectl exec gateway-pod -- curl agent-ip:8080/healthz检查 NetworkPolicy 和 Service 配置连接超时 net::ERR_CONNECTION_TIMED_OUTAgent 处理超时或网关超时设置过短查看网关 timeout 配置和 Agent 处理耗时调大网关超时优化 Agent 处理逻辑workspace 初始化卡住依赖包下载慢或镜像缺失kubectl logs agent-pod -c init预置依赖到基础镜像减少运行时下载调度失败 Pod 一直 Pending资源不足或亲和性冲突kubectl describe pod agent-pod调整资源请求或放宽亲和性这张表是我踩坑后整理的基本覆盖了 Agent 部署中最常见的几类问题。排查时按顺序来先看 Pod 状态再看网关日志最后看 Agent 日志一层层缩小范围。5.2 几个容易忽略的实操心得第一个心得是就绪探针的初始延迟要给够。Agent 启动时要加载模型配置、初始化工作空间、注册到网关这个过程可能需要 10 到 30 秒。如果initialDelaySeconds设成 5 秒探针会在 Agent 还没准备好时就判定失败导致 Pod 反复重启。我一般设 20 秒起步复杂 Agent 设 60 秒。第二个心得是网关的健康检查路径要独立。不要用/或者业务接口做健康检查单独开一个/healthz里面只做最轻量的检查比如返回一个固定字符串。这样即使业务繁忙健康检查也不会超时。第三个心得是工作空间的清理策略要明确。Agent 退出后工作空间里的临时文件要不要保留我的做法是保留会话记录清理临时文件。通过一个 init 容器在启动时清理超过 7 天的临时文件避免磁盘被占满。提示如果 Agent 用到 GPU 或其他特殊设备记得在 Pod 定义里加resources.limits里的设备资源比如nvidia.com/gpu: 1同时确保节点上装了对应的 Device Plugin。没有 Device Plugin调度器不认识这些资源Pod 会一直 Pending。5.3 Agent 安全与未授权访问的防范热词里出现了“kubernetes 未授权访问漏洞”这个在 Agent 场景下尤其要重视。Agent 的工作空间里可能有敏感数据网关的注册接口如果没鉴权任何人都能注册一个假 Agent 把流量劫持走。基本防范措施有三条网关注册接口加 Token 鉴权Agent 和网关之间走 mTLS工作空间 PVC 的访问权限限制到具体 ServiceAccount。这三条做到位大部分未授权访问风险就堵住了。另外Agent 的 API 不要直接暴露到公网所有外部请求必须经过网关网关做鉴权和限流。6. 关于 Agent 记忆与框架选型的补充思考热词里还有几个词值得单独聊agent记忆、agent框架、harness和agent区别、skill和agent的区别。这些概念在实际项目中会直接影响调度和网关的设计。Agent 记忆分短期和长期。短期记忆就是当前会话的上下文放在工作空间的会话文件里Pod 重启就丢。长期记忆需要外部存储比如向量数据库Agent 通过工具调用去读写。调度时要考虑长期记忆服务的可用性如果记忆服务挂了Agent 虽然能启动但功能不完整这时候网关的健康检查应该把记忆服务也纳入不健康就不注册。Harness 和 Agent 的区别我的理解是 Harness 是执行框架负责调度工具调用、管理执行流程Agent 是决策主体负责决定调什么工具、怎么调。一个 Harness 可以跑多个 Agent一个 Agent 也可以换不同 Harness。在 Kubernetes 上部署时Harness 通常作为 Sidecar 和 Agent 跑在同一个 Pod 里共享工作空间这样工具调用的中间产物不用跨 Pod 传输效率更高。Skill 和 Agent 的区别更简单Skill 是能力单元比如“查天气”是一个 SkillAgent 是使用 Skill 的主体。一个 Agent 可以挂多个 Skill。调度时 Skill 通常以插件形式加载不需要单独调度但 Skill 依赖的外部服务需要保证可达。这些概念理清楚调度策略和网关路由的设计就有了依据。不是所有东西都要塞进一个 Pod该拆的拆该合的合核心原则是减少跨网络调用把强耦合的组件放在一起。7. 我个人的几点经验体会搞 Agent 调度和网关这套东西最大的感受是不要过早优化。一开始就想着做多租户、做精细调度、做复杂网关规则结果往往是配置写了一堆问题更多。我的建议是先跑通最小链路一个 Agent 实例、一个网关路由、一个工作空间能正常处理请求。然后再加副本、加限流、加健康检查。每加一层压测一轮确认稳定再加下一层。另一个体会是日志要打全。Agent 出问题时光看 Pod 状态看不出所以然必须结合网关日志、Agent 日志、工作空间里的执行日志一起看。我习惯在 Agent 启动时把关键配置打印出来包括注册的网关地址、工作空间路径、资源限制这样排查时一眼就能看出配置有没有生效。最后分享一个小技巧给 Agent 的每个请求打一个 trace ID从网关一路传到 Agent 内部这样排查 502 时能快速定位是哪个环节断的。trace ID 用请求头传递网关生成Agent 记录到日志里。这个成本很低但排查效率提升非常明显。