1. 从“ax”这个标题说起一个被低估的调度入口第一次看到“ax”这个标题很多人会以为是某个命令行工具的缩写或者某个内部项目的代号。但把热搜词摊开来看——ax、agentic、orchestrator、Kubernetes、CLI——这几个词凑在一起指向的其实是一个非常具体的场景用一条极简的命令行入口去驱动一个跑在 Kubernetes 上的 agentic 编排系统。我最早接触这类东西是在做内部工具链整合的时候。当时团队里已经有了一堆零散的脚本有的负责拉起容器有的负责跑批处理任务有的负责把结果回写到某个存储里。每个脚本单独看都能用但拼在一起就是灾难——参数格式不统一、日志散落各处、失败重试全靠人肉。后来我们意识到真正缺的不是“更多脚本”而是一个统一的调度入口让所有 agentic 的行为都能通过一个简短的命令触发并且这个命令背后对接的是 Kubernetes 这种已经解决了资源调度、健康检查、弹性伸缩的底座。“ax”这个标题之所以值得单独拿出来讲是因为它代表了一类很典型的需求把复杂的编排逻辑收进一个 CLI把执行环境交给 Kubernetes把智能决策交给 agentic 流程。这三者之间的边界怎么划、接口怎么定、状态怎么同步才是真正决定这套东西能不能落地的关键。热搜词里同时出现了 codex cli、claude cli、trae cli、zcode cli 这些工具名说明大家正在大量尝试各种 CLI 形态的智能体入口但真正跑通“CLI → orchestrator → Kubernetes”这条链路的并不多。这篇文章适合几类人看一是正在做内部平台工具、想把零散脚本收拢成统一入口的工程师二是对 agentic 编排感兴趣、但还没想清楚怎么和现有容器基础设施结合的人三是单纯被“ax”这个短名字吸引、想看看背后能延展出什么架构思路的读者。我会尽量把每一步的取舍讲清楚包括我踩过的坑和后来验证有效的做法。2. 整体设计思路为什么是 CLI Orchestrator Kubernetes 这个组合2.1 三个层次各管什么边界在哪里先把这三个东西的职责说清楚不然后面全是糊涂账。CLI 层负责的是“意图表达”。用户输入ax run --task summarize --input ./docs这样的命令CLI 要做的事情只有三件解析参数、做基本校验、把请求发给 orchestrator。它不应该去关心容器怎么起、镜像从哪拉、失败了重试几次。我见过一些实现把调度逻辑塞进 CLI 里结果就是每加一个功能都要重新发版客户端非常痛苦。Orchestrator 层负责的是“流程编排”。它拿到 CLI 发来的请求后要决定这个任务拆成几步、每步用哪个 agent、步骤之间怎么传递数据、失败了怎么补偿。这一层是 agentic 的核心也是最能体现“智能”的地方。热搜词里的 agentic rag 其实就是这类编排的一种典型形态——检索、生成、再检索、再生成每一步的输入都依赖上一步的输出。Kubernetes 层负责的是“执行承载”。每个 agent 的每一步最终都要落到一个 Pod 里去跑Kubernetes 管的是这个 Pod 能不能起来、资源够不够、挂了要不要重启。它不关心这个 Pod 里跑的是 RAG 还是别的什么只关心声明式的期望状态。这三层的边界如果划清楚了整个系统的可维护性会好很多。我的经验是CLI 只做无状态的事情orchestrator 持有流程状态Kubernetes 持有运行时状态。任何跨层的状态读取都要通过明确的接口不能互相直接查数据库。2.2 为什么不用现成的工作流引擎有人会问既然要编排为什么不用 Argo Workflows、Tekton 这类现成的东西我试过结论是它们适合确定性流程不适合 agentic 流程。Argo 的 DAG 是提前定义好的每一步的依赖关系在提交时就已经确定。但 agentic 的场景里下一步做什么往往取决于上一步的输出。比如一个检索 agent 返回了三条结果编排层可能决定只对其中两条做深度分析第三条直接跳过。这种动态决策用静态 DAG 表达起来非常别扭要么写一堆条件分支要么在容器里再套一层调度逻辑。所以我的选择是用 Kubernetes 做执行底座但编排逻辑自己写。编排层可以是一个常驻的服务也可以是一个轻量的状态机关键是它能根据运行时信息动态决定下一步。这样既享受了 Kubernetes 的调度能力又保留了 agentic 需要的灵活性。2.3 “ax”这个名字背后的接口设计哲学名字短通常意味着接口也要短。我给自己定的规矩是ax 后面跟的动词不超过五个每个动词的参数不超过三个必填项。比如ax run触发一次编排ax status查状态ax logs看日志ax cancel取消ax list列出历史这套接口看起来简单但背后要支撑的东西不少。ax run要能接受不同类型的任务ax status要能聚合多个 Pod 的状态ax logs要能从多个来源拉日志。接口简单不代表实现简单而是把复杂度藏在了 orchestrator 里。提示接口设计上有一个反直觉的点——不要为了让 CLI 好用而把参数设计得太灵活。参数越多用户越容易用错orchestrator 的校验逻辑也越复杂。宁可多几个专用命令也不要一个命令塞二十个 flag。3. 核心细节解析从命令到 Pod 的完整链路3.1 CLI 的参数解析与请求构造CLI 这一层看起来最简单但有几个细节如果没处理好后面会一直难受。第一是参数的类型。我建议所有参数都用字符串传由 orchestrator 去做类型转换。原因很简单CLI 的版本和 orchestrator 的版本可能不一致如果 CLI 做了强类型校验orchestrator 升级后新增的类型就没法通过旧版 CLI 传进去。用字符串传兼容性最好。第二是请求的序列化格式。JSON 是最稳妥的选择但要注意字段的命名风格要统一。我见过有的项目里 CLI 用 snake_caseorchestrator 用 camelCase结果每次加字段都要写转换代码。定一个规范全链路遵守。第三是超时和重试。CLI 发请求给 orchestrator 时超时时间不能设得太短。因为 orchestrator 可能要花几秒去决策如果 CLI 两秒就超时用户会以为失败了实际上任务已经提交。我的做法是CLI 的默认超时设 30 秒同时提供一个--async选项提交后立即返回一个 task id用户可以用ax status id去查。# 同步模式等待编排完成 ax run --task summarize --input ./docs --wait # 异步模式立即返回 task id ax run --task summarize --input ./docs --async # 输出: task-7f3a9b2c3.2 Orchestrator 的状态机设计Orchestrator 是整个系统的核心它的状态机设计直接决定了系统的可靠性。我把每个任务的状态分成这么几类pending、planning、executing、aggregating、completed、failed、cancelled。pending 是刚收到请求还没开始处理planning 是在决定怎么拆步骤executing 是有步骤在跑aggregating 是在汇总结果后面三个是终态。状态之间的转换必须是有向无环的不能出现从 completed 又回到 executing 的情况。每次状态转换都要写一条记录包含时间戳、触发原因、当前步骤。这样出问题的时候可以完整回放。状态存储我建议用关系型数据库不要用 Redis 或者内存。原因很简单任务可能跑很久中间 orchestrator 可能重启内存里的状态一丢就全没了。关系型数据库虽然慢一点但可靠。表结构大概是这样字段类型说明task_idvarchar任务唯一标识statusvarchar当前状态planjson编排计划current_stepint当前执行到第几步created_attimestamp创建时间updated_attimestamp更新时间errortext失败原因3.3 Kubernetes 侧的 Pod 模板设计每个 agent 的每一步最终都要变成一个 Pod。Pod 模板的设计有几个关键点。镜像要统一。不要为每个 agent 单独打一个镜像而是做一个基础镜像里面装好运行时和常用依赖agent 的具体逻辑通过挂载或者参数传入。这样镜像数量可控拉取速度快也方便统一升级。资源限制要明确。每个 Pod 都要设 requests 和 limits不能留空。我见过因为没设 limits 导致一个 agent 把节点内存吃满、把其他任务全拖垮的案例。CPU 和内存的 requests 可以设小一点limits 设大一点给突发留空间。重启策略要选对。对于一次性的 agent 任务restartPolicy 用 Never 或者 OnFailure。用 Always 的话任务成功后 Pod 还会重启反而添乱。日志要输出到 stdout。不要往文件里写Kubernetes 的日志收集机制默认就是从 stdout 抓的。如果 agent 有结构化日志用 JSON 格式输出方便后续解析。apiVersion: v1 kind: Pod metadata: name: ax-agent-step-1 labels: app: ax-agent task-id: task-7f3a9b2c spec: restartPolicy: OnFailure containers: - name: agent image: registry.internal/ax-agent-base:1.4.0 command: [python, -m, ax_agent.run] args: [--step, 1, --task-id, task-7f3a9b2c] resources: requests: cpu: 500m memory: 512Mi limits: cpu: 2 memory: 2Gi env: - name: AX_ORCHESTRATOR_URL value: http://ax-orchestrator:80803.4 步骤之间的数据传递这是最容易出问题的地方。步骤 A 的输出要给步骤 B 用怎么传不要用共享存储卷。虽然看起来方便但多个 Pod 同时读写一个卷会有并发问题而且卷的生命周期管理很麻烦。推荐用对象存储或者数据库。步骤 A 完成后把输出写到一个约定的位置比如s3://ax-tasks/task-7f3a9b2c/step-1/output.json然后把路径告诉 orchestrator。步骤 B 启动时orchestrator 把这个路径作为参数传进去步骤 B 自己去拉。这样做的好处是解耦。步骤 A 和步骤 B 不需要同时存在也不需要共享文件系统。即使步骤 A 的 Pod 已经销毁了它的输出还在。而且对象存储天然支持大文件不会像数据库那样有字段长度限制。注意数据传递的路径要有统一的命名规范并且要设置过期清理策略。我见过任务跑完后输出文件堆了几百 GB 没人清理的情况最后存储账单爆炸。4. 实操过程从零搭一个最小可用的 ax 系统4.1 环境准备与依赖安装先列一下需要的东西一个 Kubernetes 集群1.24 以上版本。本地测试可以用 kind 或者 minikube。一个关系型数据库PostgreSQL 或者 MySQL 都行。一个对象存储本地测试可以用 MinIO。Python 3.10 以上用来写 orchestrator 和 CLI。安装 CLI 的方式我建议用 pipx这样不会污染系统 Python 环境pipx install ax-cli ax --version如果是从源码装先 clone 仓库然后cd ax pip install -e .orchestrator 的部署用 Helm chart 最方便但第一次搭的时候我建议手动 apply YAML这样能看清楚每个资源是怎么创建的。4.2 数据库表结构的初始化orchestrator 启动前要先建表。我写了一个简单的 migration 脚本CREATE TABLE tasks ( task_id VARCHAR(64) PRIMARY KEY, status VARCHAR(32) NOT NULL, plan JSONB, current_step INT DEFAULT 0, created_at TIMESTAMP DEFAULT NOW(), updated_at TIMESTAMP DEFAULT NOW(), error TEXT ); CREATE INDEX idx_tasks_status ON tasks(status); CREATE INDEX idx_tasks_created_at ON tasks(created_at);索引是必须的。ax list要按状态过滤ax status要按时间排序没有索引的话任务一多查询就慢。4.3 Orchestrator 的核心循环orchestrator 的主循环逻辑大概是这样的从数据库里捞出所有非终态的任务。对每个任务根据当前状态决定下一步动作。如果是 planning 状态调用规划逻辑生成 plan。如果是 executing 状态检查当前步骤的 Pod 状态。如果 Pod 成功推进到下一步如果失败根据重试策略决定重试还是标记失败。如果是 aggregating 状态收集所有步骤的输出生成最终结果。这个循环可以是一个定时任务每 5 秒跑一次。也可以用事件驱动Pod 状态变化时触发。定时任务实现简单但会有延迟事件驱动实时性好但复杂度高。我建议先用定时任务等规模上来了再考虑事件驱动。def reconcile(): tasks db.query(SELECT * FROM tasks WHERE status NOT IN (completed, failed, cancelled)) for task in tasks: if task.status pending: plan generate_plan(task) db.update(task.id, statusplanning, planplan) elif task.status planning: db.update(task.id, statusexecuting, current_step0) elif task.status executing: step task.plan[task.current_step] pod k8s.get_pod(fax-agent-{task.id}-{task.current_step}) if pod.status Succeeded: if task.current_step len(task.plan) - 1: db.update(task.id, statusaggregating) else: db.update(task.id, current_steptask.current_step 1) elif pod.status Failed: handle_failure(task)4.4 一个完整的任务执行示例假设我们要跑一个文档摘要任务输入是三个 markdown 文件。第一步用户执行ax run --task summarize --input ./docs --asyncCLI 把请求发给 orchestratororchestrator 创建一条 task 记录状态是 pending返回 task id。第二步orchestrator 的 reconcile 循环发现这个 pending 任务调用规划逻辑。规划逻辑决定拆成三步先合并文档再分段摘要最后汇总。第三步orchestrator 为第一步创建 Pod。Pod 启动后从对象存储拉取三个 markdown 文件合并成一个写回对象存储。第四步Pod 成功后orchestrator 推进到第二步创建新的 Pod。这个 Pod 读取合并后的文档分段调用摘要模型把结果写回。第五步第二步成功后推进到第三步汇总所有分段摘要生成最终结果。第六步所有步骤完成orchestrator 把状态改成 completed用户可以用ax status id看到结果路径。整个过程里用户只需要执行一条命令剩下的都由 orchestrator 和 Kubernetes 完成。4.5 参数计算资源怎么估资源估算是个经验活但有几个公式可以参考。CPU每个 agent 步骤的 CPU 需求大概等于“模型推理时间 × 并发数”。如果一步要跑 10 秒并发 4 个请求那大概需要 2 核左右。保守一点requests 设 500mlimits 设 2 核。内存主要看模型大小和输入数据量。一个 7B 参数的模型加载后大概占 14GB 内存FP16。如果输入数据很大还要额外留空间。我的经验是内存 limits 至少是模型大小的 1.5 倍。存储如果步骤之间用对象存储传递数据Pod 本身不需要持久化存储。但如果 agent 需要缓存模型文件可以挂一个 emptyDir大小根据模型大小来定。步骤类型CPU requestsCPU limits内存 requests内存 limits轻量处理200m1256Mi1Gi模型推理500m22Gi8Gi大模型推理148Gi32Gi这些数字不是绝对的要根据实际压测调整。但有一个原则requests 要保守limits 要留余量。requests 设太大Pod 调度不上去limits 设太小任务容易被 OOM kill。5. 常见问题与排查技巧实录5.1 Pod 一直 Pending 起不来这是最常见的问题。原因通常有三个资源不够、镜像拉不下来、节点选择器不匹配。排查顺序先kubectl describe pod name看 Events。如果是Insufficient cpu或Insufficient memory说明集群资源不够要么加节点要么调小 requests。如果是ImagePullBackOff检查镜像地址和拉取凭证。如果是node(s) didnt match node selector检查 nodeSelector 配置。我遇到过一次很隐蔽的情况Pod 一直 PendingEvents 里什么错误都没有。后来发现是命名空间设置了 ResourceQuota配额用完了。所以排查的时候也要看看kubectl describe quota -n namespace。5.2 任务卡在 executing 状态不动这说明 orchestrator 没有正确推进状态。可能的原因Pod 状态没被正确读取、orchestrator 挂了、数据库连接断了。先看 orchestrator 的日志确认 reconcile 循环还在跑。然后手动查一下 Pod 的状态看是不是已经成功了但 orchestrator 没感知到。如果是 Pod 状态读取的问题检查 orchestrator 的 ServiceAccount 有没有权限读 Pod。还有一种情况是 Pod 处于Running但一直不结束。这通常是 agent 内部逻辑卡住了比如在等一个永远不会来的网络请求。这时候要看 Pod 的日志定位卡在哪一步。如果 agent 没有超时机制要在 orchestrator 层面加一个步骤超时超过时间就强制标记失败。5.3 步骤之间数据传丢了表现是步骤 B 启动后找不到步骤 A 的输出。排查思路先确认步骤 A 是不是真的成功了再看输出路径是不是和步骤 B 读取的路径一致。我踩过的一个坑是步骤 A 写文件时用了相对路径Pod 的工作目录和预期不一致文件写到了别的地方。后来统一改成绝对路径并且路径由 orchestrator 统一生成后传给两个步骤问题就没了。另一个坑是对象存储的权限。步骤 A 用的凭证有写权限步骤 B 用的凭证只有读权限但读的 bucket 不对。这种问题日志里往往不明显要在 orchestrator 里把路径和凭证都打出来。5.4 常见问题速查表现象可能原因排查方法解决方式Pod Pending资源不足describe pod 看 Events调小 requests 或加节点Pod Pending镜像拉取失败看 Events 里的镜像地址检查镜像和凭证任务卡 executingorchestrator 挂了看 orchestrator 日志重启 orchestrator任务卡 executingPod 状态没同步手动查 Pod 状态检查 RBAC 权限数据传丢路径不一致对比两个步骤的路径参数统一由 orchestrator 生成路径数据传丢权限问题检查对象存储凭证统一凭证或明确授权Pod OOM内存 limits 太小看 Pod 的 OOMKilled 事件调大 limits任务超时agent 内部卡住看 Pod 日志加步骤超时机制5.5 几个独家避坑技巧技巧一给每个 Pod 打上 task-id 和 step 的标签。这样排查的时候可以用kubectl get pods -l task-idxxx一次性看到所有相关 Pod不用一个个找。技巧二orchestrator 的日志要包含 task-id。这样出问题的时候可以grep task-id快速定位。日志格式建议用 JSON方便后续用工具分析。技巧三步骤的输出要带校验。步骤 A 写完后写一个_SUCCESS标记文件。步骤 B 启动时先检查这个标记没有就报错。这样可以避免读到不完整的数据。技巧四重试要有上限。我见过一个任务因为一个步骤一直失败重试了几百次把集群资源全占了。每个步骤的重试次数建议不超过 3 次超过就标记失败人工介入。技巧五定期清理已完成任务的 Pod。Kubernetes 默认会保留已完成的 Pod时间长了会积累很多。可以设置ttlSecondsAfterFinished让 Pod 完成后自动删除。spec: ttlSecondsAfterFinished: 3600这个配置表示 Pod 完成后 1 小时自动删除。对于调试阶段可以设长一点生产环境可以设短一点。6. 扩展方向ax 还能怎么用6.1 接入更多 agent 类型现在的设计里每个步骤对应一个 PodPod 里跑什么由镜像决定。这意味着只要做一个新的镜像就能接入新的 agent 类型。比如一个专门做代码生成的 agent一个专门做数据清洗的 agent一个专门做图表生成的 agentorchestrator 不需要知道这些 agent 的具体逻辑只需要知道它们的输入输出格式。这样扩展起来非常灵活。6.2 支持更复杂的编排模式现在的编排是线性的步骤一个接一个。但实际场景里可能需要并行、条件分支、循环。这些都可以在 orchestrator 层面扩展。并行的话orchestrator 可以同时创建多个 Pod等所有 Pod 都成功后再推进。条件分支的话可以在 plan 里加条件表达式根据上一步的输出决定走哪条路。循环的话可以设置一个最大迭代次数每次迭代创建一个新 Pod。这些扩展不需要改 Kubernetes 侧的东西只需要改 orchestrator 的规划逻辑。6.3 和现有 CI/CD 集成ax 可以作为 CI/CD 流水线里的一个步骤。比如在代码合并后触发一个 ax 任务去做代码审查、生成文档、跑测试。这样就把 agentic 的能力嵌入了现有的开发流程。集成方式很简单在 CI 的配置文件里加一行- name: Run ax task run: | ax run --task code-review --input ./src --wait如果任务失败CI 就失败阻止合并。这样可以用 agentic 的能力做质量门禁。6.4 监控和告警生产环境里ax 系统本身也需要监控。要关注的指标包括任务成功率、平均执行时间、各步骤的耗时分布、Pod 的失败率。这些指标可以从 orchestrator 的数据库里算出来也可以从 Kubernetes 的 metrics 里拿。我建议做一个简单的 dashboard把关键指标可视化。告警的话任务失败率超过阈值、或者有任务卡在 executing 超过一定时间就发通知。监控这块不用一开始就做得很复杂先有一个能看的地方就行。等系统跑稳了再逐步完善。6.5 多集群调度如果任务量大了单个 Kubernetes 集群可能不够用。这时候可以考虑多集群调度。orchestrator 可以根据任务的资源需求选择一个合适的集群去创建 Pod。多集群的难点在于状态同步。orchestrator 要能感知到每个集群的 Pod 状态这需要每个集群都暴露一个统一的接口。可以用 Kubernetes 的 federation 机制也可以自己写一个适配层。这块我还在探索中目前的做法是给每个集群部署一个 agentorchestrator 通过 agent 来操作集群。这样 orchestrator 不需要直接持有每个集群的凭证安全性更好。7. 一些个人体会搭这套东西的过程中我最大的感受是简单的东西往往最难做对。CLI 就几个命令orchestrator 就一个循环Pod 模板就几十行 YAML但要把它们串起来稳定运行需要处理的边界情况非常多。另一个体会是不要过早优化。一开始我想把 orchestrator 做成分布式的支持水平扩展结果复杂度飙升bug 一堆。后来退回到单实例先把功能跑通等真的有性能瓶颈了再考虑扩展。事实证明单实例撑到了每天几千个任务才需要优化。还有就是日志和可观测性要尽早做。我一开始觉得日志随便打打就行结果出问题的时候完全不知道发生了什么。后来花了一天时间把日志规范化排查效率提升了好几倍。这个投入非常值得。最后分享一个小技巧给每个任务生成一个短 id并且在所有相关资源上都打上这个 id 的标签。这样无论是查 Pod、查日志、查数据库都可以用这个 id 串起来。我用的格式是task-加 8 位随机字符比如task-7f3a9b2c。短 id 的好处是输入方便8 位随机字符的碰撞概率也足够低。