企业官网建设流程全解析

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

“ax”这个标题乍看像是一个缩写、一个代号，甚至像某个内部项目的临时命名。但把热搜词摊开来看——agentic、orchestration、runtime、Kubernetes、Karmada、agentic cloud、agentic rag——这条线索就非常清晰了：它指向的是面向智能体（Agent）的运行时编排层，也就是在 Kubernetes 之上，如何把一个个独立的 Agent 当作可调度、可观测、可治理的工作负载来管理。

我最早接触这类需求，是在一个内部工具链项目里。当时团队想把几个自动化流程串起来：一个负责拉取数据，一个负责清洗，一个负责生成报告，最后一个负责分发。最初的做法是用脚本硬串，A 跑完调 B，B 跑完调 C。结果只要中间任何一个环节超时或者返回异常，整条链路就卡死，排查起来像在迷宫里找出口。后来我们把这套东西搬到 Kubernetes 上，用 Job 和 CronJob 重新组织，才意识到一个关键问题：Agent 不是普通的无状态服务，它有自己的上下文、记忆、工具调用和决策循环。用管理微服务的那套思路去管理 Agent，就像用管理流水线工人的方式去管理一群研究员——能跑，但跑得很别扭。

“ax”要解决的，正是这个别扭。它试图在 Kubernetes 的调度能力之上，加一层专门面向 Agent 的编排抽象。你可以把它理解成：Kubernetes 管的是 Pod、Service、Deployment 这些“死”的资源，而 ax 管的是 Agent 的“活”的行为——谁先谁后、谁依赖谁、谁失败了怎么重试、谁需要更多上下文、谁该被降级。热搜词里的 orchestration 和 runtime 两个词放在一起，恰好点出了它的双重身份：既是编排器，又是运行时。

这篇文章适合谁看？如果你正在做多 Agent 协作、自动化流程编排、或者在 Kubernetes 上跑 AI 工作负载，那这里面的思路和踩坑记录应该对你有用。如果你只是听说过 agentic 这个词但还没动手，那也可以把它当作一个从零到一的参考路径。我不会讲太多虚的概念，重点放在：为什么这么设计、具体怎么落地、哪些地方容易翻车。

2. 核心设计思路拆解：为什么要在 Kubernetes 上再包一层

2.1 Agent 工作负载和普通微服务的本质差异

先把问题定义清楚。普通微服务是无状态的、请求驱动的、生命周期相对固定的。一个 HTTP 服务启动后就在那里等着，来一个请求处理一个，处理完返回结果，自己不记得上次请求是谁发的。Kubernetes 对这类工作负载的支持已经非常成熟：Deployment 保证副本数，Service 做负载均衡，HPA 根据 CPU 或 QPS 自动扩缩容。

Agent 完全不是这个模式。一个 Agent 通常有以下几个特征：

• 有状态：它记得之前的对话、之前的工具调用结果、之前的决策路径。这些状态可能存储在内存里，也可能持久化到外部存储。
• 长时运行：一个 Agent 任务可能跑几秒，也可能跑几小时甚至几天。它可能在等待外部事件，可能在轮询某个 API，可能在等人类审批。
• 决策驱动：它不是收到请求就执行固定逻辑，而是根据当前上下文决定下一步做什么。这意味着它的资源消耗是不可预测的。
• 工具依赖：Agent 通常需要调用外部工具——搜索引擎、数据库、代码执行器、消息队列。这些工具的可用性和延迟直接影响 Agent 的行为。
• 失败模式复杂：普通服务失败就是返回 5xx，Agent 失败可能是“决策错了但没报错”、“工具调用超时但没重试”、“上下文丢失导致行为异常”。

把这些特征放到 Kubernetes 的语境里，问题就来了。你用 Deployment 跑一个 Agent，副本数设多少？设 1 个，吞吐上不去；设 10 个，它们之间怎么共享状态？你用 Job 跑一个 Agent，超时时间设多少？设短了任务没跑完就被杀，设长了资源一直占着。你用 CronJob 定时触发，但 Agent 的执行时间可能超过触发间隔，导致任务堆积。

我踩过的一个坑：早期用 Job 跑一个数据清洗 Agent，超时设了 30 分钟。结果有一次数据量特别大，Agent 跑了 35 分钟才完成，但 Job 在 30 分钟时已经被终止了。更麻烦的是，Agent 在终止前已经写了一半数据到数据库，导致下游拿到的是不完整的数据集。后来我们加了 checkpoint 机制，让 Agent 每处理完一批就记录进度，重启后从断点继续。这个机制后来成了 ax 设计里的一个核心模块。

2.2 为什么不是直接扩展 Kubernetes，而是加一层编排

有人可能会问：Kubernetes 本身就有 Operator 模式，我写一个 AgentOperator 不就行了吗？为什么要单独搞一个 ax？

这个问题我认真想过。Operator 模式确实能解决一部分问题——你可以定义 CRD（Custom Resource Definition），然后写控制器来管理 Agent 的生命周期。但 Operator 的问题在于：它把编排逻辑和 Kubernetes 的控制器逻辑耦合在一起了。你的 Agent 编排规则如果变了，你得重新编译控制器、重新部署。而且 Operator 的调试成本很高，出了问题你得去看 controller 的日志、看 event、看 reconcile 循环，排查链路很长。

ax 的思路不一样。它把编排逻辑抽出来，做成一个独立的运行时层。Kubernetes 只负责最底层的资源调度——给 Pod、给存储、给网络。ax 负责上层的 Agent 编排——定义 DAG、管理状态、处理重试、做可观测性。这两层之间通过标准接口通信，ax 不关心 Kubernetes 具体是哪个版本、跑在哪个云上，Kubernetes 也不关心 ax 内部怎么编排 Agent。

这种分层的好处是：编排逻辑可以独立演进。你今天用简单的串行编排，明天想改成并行加条件分支，只需要改 ax 的配置，不需要动 Kubernetes 的任何东西。反过来，你想把底层从 Kubernetes 换成别的调度器，只要 ax 的接口不变，上层 Agent 也不用改。

热搜词里有个 Karmada 正式毕业的消息，华为云携手社区共建 agentic cloud 坚实底座。Karmada 是做什么的？它是 Kubernetes 的多集群管理项目。为什么它和 agentic cloud 扯上关系？因为 Agent 工作负载往往需要跨集群调度——有的 Agent 需要 GPU，有的需要特定数据源，有的需要低延迟网络。单集群搞不定，就得上多集群。Karmada 提供了多集群调度的能力，而 ax 这样的编排层则提供了 Agent 级别的抽象。两者结合，才能撑起 agentic cloud 这个愿景。

2.3 运行时（Runtime）在 ax 里的角色

Runtime 这个词在热搜里出现了很多次：codemeter runtime、webview2 runtime、container runtime、labview runtime engine、NDI runtime、llama-server runtime。每个语境下 runtime 的含义不太一样，但核心都是“让某样东西跑起来的那套环境”。

在 ax 的语境里，runtime 指的是Agent 的执行环境。它要解决几个问题：

第一，隔离。不同 Agent 可能依赖不同的库、不同的 Python 版本、不同的系统工具。你不能让它们互相污染。容器化是标准答案，但容器化之后怎么管理镜像、怎么挂载数据、怎么暴露端口，这些都需要 runtime 来统一处理。

第二，资源限制。一个 Agent 可能突然需要大量内存来做推理，另一个 Agent 可能只需要很少资源来做简单的文本处理。Runtime 要根据 Agent 的类型和当前负载，动态分配 CPU、内存、GPU。

第三，生命周期管理。Agent 启动、暂停、恢复、终止，这些操作需要 runtime 来执行。特别是暂停和恢复——Agent 可能因为等待外部事件而暂停，这时候要保存它的状态，等事件到了再恢复。这比普通容器的 stop/start 复杂得多。

第四，可观测性。Agent 在做什么、做到哪一步了、消耗了多少资源、调用了哪些工具、返回了什么结果，这些都需要 runtime 来采集和上报。没有这层可观测性，Agent 就是个黑盒，出了问题只能靠猜。

热搜里有个错误信息：“[ERROR CRI]: container runtime is not running”。这是 Kubernetes 节点上容器运行时没启动的典型报错。在 ax 的场景里，如果 runtime 层出了问题，影响面比这还大——不只是容器跑不起来，而是整个 Agent 编排链路都会断掉。所以 ax 的 runtime 设计必须考虑高可用和自愈。

3. 核心细节解析与实操要点：从零搭一个最小可用原型

3.1 环境准备：Kubernetes 集群和基础组件

动手之前，先把地基打好。你需要一个能用的 Kubernetes 集群。版本方面，热搜里提到了 v1.26.0，这个版本不算新但足够稳定。如果你是在本地做实验，可以用 kind 或者 minikube 起一个单节点集群。如果是生产环境，建议至少三个节点，一个 master 两个 worker。

集群起来之后，确认几个基础组件：

• 容器运行时：containerd 或者 CRI-O。用crictl info检查是否正常。如果报 “container runtime is not running”，先排查运行时服务是否启动、socket 路径是否正确。
• 网络插件：Calico、Flannel 或者 Cilium。Agent 之间可能需要互相通信，网络不通什么都白搭。
• 存储类：Agent 的状态需要持久化，所以要有 StorageClass。本地实验可以用 hostPath 或者 local-path-provisioner，生产环境建议用云厂商提供的块存储或文件存储。
• Ingress 控制器：如果你需要通过 HTTP 访问 Agent 的接口，Ingress 是必须的。Nginx Ingress 或者 Traefik 都可以。

实操心得：在本地用 kind 起集群时，默认的 StorageClass 可能不存在。你需要手动装一个 local-path-provisioner，否则 PVC 会一直处于 Pending 状态。这个坑我踩过好几次，每次都要重新查文档。

3.2 定义 Agent 的 CRD：让 Kubernetes 认识你的 Agent

ax 的核心思路是：把 Agent 定义成 Kubernetes 的自定义资源。这样你就可以用 kubectl 来管理 Agent，用 Kubernetes 的 RBAC 来控制权限，用 Kubernetes 的 watch 机制来监听 Agent 状态变化。

一个最小的 Agent CRD 大概长这样：

apiVersion: ax.io/v1alpha1 kind: Agent metadata: name:>apiVersion: ax.io/v1alpha1 kind: Workflow metadata: name: daily-report spec: schedule: "0 6 * * *" nodes: - id: fetch-data agent:># Agent 代码里的 checkpoint 示例 class DataCleanerAgent: def run(self, context): start_index = context.load_checkpoint() or 0 batch_size = 1000 for i in range(start_index, len(self.data), batch_size): batch = self.data[i:i+batch_size] cleaned = self.clean(batch) self.save(cleaned) context.save_checkpoint(i + batch_size) return {"status": "completed", "total": len(self.data)}

这个模式看起来简单，但有几个细节要注意：

• 幂等性：恢复后重做的部分，必须保证不会产生重复数据。上面的例子里，save 操作需要支持 upsert 而不是 insert。
• checkpoint 存储的可靠性：如果 checkpoint 本身丢了，恢复就无从谈起。所以 checkpoint 存储要比 Agent 本身更可靠。我们用 postgres 存 checkpoint，开了同步复制。
• checkpoint 的清理：Agent 成功完成后，checkpoint 应该被清理，否则会越积越多。ax 的 runtime 会在 Agent 终止后自动清理对应的 checkpoint。

4. 实操过程与核心环节实现：把 ax 跑起来

4.1 部署 ax 控制面

ax 的控制面包括几个组件：API Server（接收 CRD 请求）、Scheduler（解析 Workflow 并触发执行）、Controller（管理 Agent 生命周期）、State Manager（管理状态和 checkpoint）。这些组件可以打包成一个 Deployment 部署到 Kubernetes 里。

# 创建命名空间 kubectl create namespace ax-system # 安装 CRD kubectl apply -f https://raw.githubusercontent.com/ax-project/ax/main/config/crd/bases/ax.io_agents.yaml kubectl apply -f https://raw.githubusercontent.com/ax-project/ax/main/config/crd/bases/ax.io_workflows.yaml # 部署控制面 kubectl apply -f https://raw.githubusercontent.com/ax-project/ax/main/config/manager/manager.yaml -n ax-system # 检查状态 kubectl get pods -n ax-system

部署完成后，你应该看到 ax-controller-manager、ax-scheduler、ax-api-server 三个 Pod 在运行。如果某个 Pod 一直 CrashLoopBackOff，先看日志：

kubectl logs -n ax-system deployment/ax-controller-manager --tail=100

常见的启动失败原因：CRD 没装好、RBAC 权限不足、etcd 连接不上。逐个排查。

4.2 提交第一个 Agent

控制面跑起来后，提交一个最简单的 Agent 试试水：

apiVersion: ax.io/v1alpha1 kind: Agent metadata: name: hello-agent namespace: default spec: image: busybox:latest command: ["sh", "-c", "echo 'Hello from ax' && sleep 10"] resources: requests: cpu: "100m" memory: "64Mi" limits: cpu: "200m" memory: "128Mi" timeout: 60

kubectl apply -f hello-agent.yaml # 查看 Agent 状态 kubectl get agents # NAME STATUS AGE # hello-agent Running 5s # 查看 Agent 详情 kubectl describe agent hello-agent # 查看日志 kubectl logs -l ax.io/agent=hello-agent

如果一切正常，你会看到 Agent 从 Pending 变成 Running，然后变成 Succeeded。这个过程涉及几个关键环节：

1. API Server 接收请求：验证 CRD 格式，写入 etcd。
2. Controller 监听到新 Agent：创建对应的 Pod，注入必要的环境变量和卷。
3. Scheduler 分配节点：根据资源请求和节点可用资源，选择合适的节点。
4. Kubelet 启动容器：拉镜像、挂载卷、启动进程。
5. Runtime 监控状态：采集日志、监控资源、检测退出码。
6. Controller 更新状态：Agent 完成后，更新 CRD 的 status 字段。

这个链路里任何一环出问题，Agent 都跑不起来。排查的时候按顺序来：先看 CRD 是否创建成功，再看 Pod 是否调度成功，再看容器是否启动成功，最后看 Agent 逻辑是否执行成功。

4.3 编排一个多 Agent 工作流

单个 Agent 跑通后，试试编排。创建一个 Workflow，包含三个节点：fetch、process、store。

apiVersion: ax.io/v1alpha1 kind: Workflow metadata: name: etl-pipeline spec: nodes: - id: fetch agent: fetcher inputs: url: "https://api.example.com/data" - id: process agent: processor dependsOn: [fetch] inputs: raw: "{{ .Nodes.fetch.outputs.body }}" - id: store agent: storer dependsOn: [process] inputs: processed: "{{ .Nodes.process.outputs.result }}"

提交后，观察执行顺序：

kubectl get workflows kubectl get agents -l ax.io/workflow=etl-pipeline # 实时观察 kubectl get agents -l ax.io/workflow=etl-pipeline -w

你会看到 fetch 先启动，完成后 process 启动，最后 store 启动。如果 fetch 失败，process 和 store 不会启动，Workflow 状态变成 Failed。

这里有个细节：节点之间的数据传递是通过 etcd 中转的。fetch 的输出写到 CRD 的 status 里，process 从 CRD 里读。这种方式简单直接，但有两个限制：一是数据量不能太大（etcd 有 1.5MB 的 value 大小限制），二是传递有延迟（需要等 controller 更新 status）。如果数据量大或者对延迟敏感，建议用对象存储中转，CRD 里只传路径。

4.4 监控与可观测性

Agent 跑起来之后，你需要知道它在干什么。ax 提供了几个维度的可观测性：

指标（Metrics）：每个 Agent 暴露 Prometheus 格式的指标，包括执行时长、资源消耗、工具调用次数、错误率。你可以用 Grafana 做面板，实时监控 Agent 的健康状况。

# ServiceMonitor 示例 apiVersion: monitoring.coreos.com/v1 kind: ServiceMonitor metadata: name: ax-agents spec: selector: matchLabels: ax.io/monitored: "true" endpoints: - port: metrics interval: 15s

日志（Logs）：Agent 的标准输出和标准错误会被采集到日志系统。我们用 Loki 做日志聚合，配合 Grafana 查询。关键是要给日志加上结构化标签——agent_id、workflow_id、node_id、trace_id，这样排查问题时可以快速过滤。

追踪（Traces）：如果一个 Workflow 涉及多个 Agent，你需要知道请求在各个 Agent 之间的流转路径。ax 集成了 OpenTelemetry，每个 Agent 执行时会生成 span，你可以用 Jaeger 或者 Tempo 查看完整的调用链。

实操心得：可观测性这东西，平时觉得没用，出问题时才知道有多重要。我建议在项目初期就把指标和日志接好，不要等到出了问题才临时加。特别是 trace_id 的传递，如果一开始没设计好，后面补起来非常痛苦——你需要改所有 Agent 的代码，确保它们把 trace_id 从输入传到输出。

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

5.1 Agent 一直 Pending 怎么办

这是最常见的问题。Agent 创建了，但一直处于 Pending 状态，Pod 也没起来。排查思路：

我遇到最多的是资源不足。特别是 GPU 资源，如果节点上没有 GPU 或者 GPU 被占满了，Agent 就会一直 Pending。解决办法是在 CRD 里加 nodeSelector，指定有 GPU 的节点，同时设置合理的资源请求。

5.2 Agent 执行超时怎么处理

超时有两种情况：一种是 Agent 确实需要更长时间，另一种是 Agent 卡住了。

如果是第一种，调大 timeout 就行。但要注意，timeout 调大意味着资源占用时间变长，可能影响其他 Agent 的调度。我的做法是：给 Agent 分优先级，高优先级的 timeout 可以设大一些，低优先级的设小一些，超时就杀掉，让高优先级的先跑。

如果是第二种，需要排查 Agent 为什么卡住。常见原因：等待外部 API 响应但对方没返回、死锁、无限循环。ax 的 runtime 会在 Agent 超时后 dump 当前堆栈，你可以根据堆栈定位卡住的位置。

# 查看超时 Agent 的堆栈 kubectl ax logs <agent-name> --previous kubectl ax inspect <agent-name> --stacktrace

5.3 状态丢失或 checkpoint 损坏

Agent 恢复后行为异常，大概率是状态丢了或者 checkpoint 损坏。排查步骤：

1. 检查 checkpoint 存储是否可访问。如果是 redis，redis-cli ping看是否通。
2. 检查 checkpoint 的版本号。如果 Agent 代码升级了但 checkpoint 格式没升级，恢复时可能解析失败。
3. 检查 checkpoint 的完整性。我们会在写 checkpoint 时加一个 checksum，恢复时验证。如果 checksum 不匹配，说明 checkpoint 损坏，需要从头开始。

避坑技巧：checkpoint 的格式要向后兼容。新版本 Agent 要能读旧版本的 checkpoint。我们的做法是：checkpoint 里带一个 schema_version 字段，恢复时根据版本号走不同的解析逻辑。这样升级 Agent 时不会因为 checkpoint 格式变化导致恢复失败。

5.4 多 Agent 并发时的资源竞争

多个 Agent 同时跑，可能互相抢资源。表现是：某个 Agent 突然变慢，或者 OOM 被杀。

解决方案有几个层次：

• 资源配额：给每个 Agent 设置 requests 和 limits，Kubernetes 会保证 requests，限制 limits。
• 优先级和抢占：给关键 Agent 设高优先级，资源不足时抢占低优先级的 Agent。
• 并发控制：在 Workflow 层面限制同时执行的节点数。ax 支持maxParallelism字段，你可以设置最多同时跑几个节点。
• 队列和限流：如果 Agent 调用外部 API，加一个令牌桶限流，避免把对方打挂。

spec: maxParallelism: 3 # 最多同时跑 3 个节点 nodes: - id: task1 agent: worker resources: requests: cpu: "1" memory: "1Gi"

5.5 常见错误信息速查

这些错误信息看起来五花八门，但本质都是“运行时环境不完整”。ax 的 runtime 层要做的事情之一，就是确保 Agent 的执行环境是完整的。我们的做法是：在 Agent 镜像构建阶段，用一个基础镜像把所有常见依赖都装好，然后各个 Agent 镜像基于这个基础镜像构建。这样虽然镜像大一点，但能避免很多“缺库”的问题。

6. 从 ax 到 agentic cloud：编排层的演进方向

6.1 多集群调度与 Karmada 的配合

单集群的 ax 能解决大部分问题，但当 Agent 数量多到一定程度，单集群的资源不够用了，就得上多集群。Karmada 提供了多集群调度的能力，ax 可以和它配合：ax 负责 Agent 级别的编排，Karmada 负责把 Agent 调度到合适的集群。

具体怎么配合？ax 的 Scheduler 在决定 Agent 跑在哪个节点时，可以查询 Karmada 的集群列表和资源状态，然后选择一个合适的集群。Agent 的 CRD 里可以加一个clusterAffinity字段，指定偏好哪个集群。

spec: clusterAffinity: preferred: - cluster: gpu-cluster weight: 80 - cluster: cpu-cluster weight: 20

这种多集群架构的好处是：不同集群可以有不同的硬件配置，GPU 集群跑推理 Agent，CPU 集群跑数据处理 Agent，各取所需。坏处是网络延迟增加了，Agent 之间的数据传递需要跨集群，可能成为瓶颈。

6.2 Agentic RAG 与编排的结合

热搜里有个词叫 agentic rag。RAG 是检索增强生成，agentic rag 就是把 RAG 做成 Agent 的形式——Agent 自己决定什么时候检索、检索什么、怎么用检索结果。

在 ax 的框架里，agentic rag 可以这样实现：定义一个 RAG Agent，它接收查询，然后决定调用哪些工具（向量检索、关键词检索、数据库查询），汇总结果后生成回答。这个 Agent 可以被编排到更大的 Workflow 里，比如“客服工单处理”流程：先分类工单，再检索知识库，再生成回复，最后人工审核。

apiVersion: ax.io/v1alpha1 kind: Agent metadata: name: rag-agent spec: image: registry.example.com/agents/rag:v2.0.0 tools: - name: vector-search type: milvus connectionString: "milvus-service:19530" - name: keyword-search type: elasticsearch connectionString: "http://es-service:9200" - name: llm type: openai-compatible endpoint: "http://llm-service:8080/v1" state: backend: redis connectionString: "redis://redis-service:6379/1"

这个 Agent 的关键在于：它不是固定地先检索再生成，而是根据查询的复杂度动态决定。简单查询可能直接走关键词检索，复杂查询才走向量检索加 LLM 重排。这种动态决策能力，正是 agentic 的核心。

6.3 运行时安全与隔离

Agent 跑在共享集群里，安全隔离是个大问题。一个 Agent 如果被注入了恶意代码，可能影响其他 Agent 甚至整个集群。

ax 的 runtime 层做了几层隔离：

• 容器隔离：每个 Agent 跑在独立的容器里，有独立的文件系统和网络命名空间。
• 资源隔离：通过 cgroups 限制 CPU、内存、磁盘 IO。
• 网络隔离：用 NetworkPolicy 限制 Agent 之间的网络访问，只允许必要的通信。
• 权限隔离：Agent 的 ServiceAccount 只有最小必要权限，不能访问 Kubernetes API 的敏感资源。
• 工具隔离：Agent 调用外部工具时，通过一个代理层，代理层做鉴权和审计。

实操心得：安全这东西，不要等到出事才重视。我在项目初期觉得“内部工具而已，不用搞那么严”，结果有一次一个 Agent 的代码 bug 导致它疯狂调用数据库，把连接池占满了，影响了其他所有服务。后来我们加了工具调用的限流和熔断，才避免类似问题。

6.4 成本控制与资源优化

Agent 跑在云上，成本是个绕不开的话题。GPU 实例贵，长时间跑 Agent 更贵。ax 提供了几个成本优化的手段：

• 自动缩容：没有 Agent 任务时，把节点缩到最小。有任务时再扩容。
• Spot 实例：非关键 Agent 跑在 Spot 实例上，成本能降 60% 到 70%。但 Spot 实例可能被回收，所以 Agent 必须支持 checkpoint 和恢复。
• 资源超卖：Agent 的 requests 设小一点，limits 设大一点，提高节点利用率。但这有风险，如果多个 Agent 同时达到 limits，可能 OOM。
• 执行时间优化：通过分析 Agent 的执行日志，找出耗时最长的环节，针对性优化。比如某个 Agent 大部分时间在等 API 响应，可以考虑加缓存或者批量请求。

我们内部算过一笔账：一个中等规模的 agentic 工作流，每天跑 1000 次，每次平均消耗 2 核 4G 跑 5 分钟。如果用按需实例，一个月大概几百块。如果用 Spot 实例加自动缩容，能降到一百多块。对于大规模部署，这个差距就很可观了。

7. 一些零散但重要的经验

7.1 版本兼容性

ax 本身在演进，Kubernetes 也在演进。版本兼容性是个容易被忽视的问题。我的建议是：

• ax 的 CRD 要带版本号，并且支持多版本共存。这样升级 ax 时，旧的 Agent 定义还能用。
• Kubernetes 的 API 版本要关注弃用公告。比如extensions/v1beta1被弃用后，很多旧的 YAML 就不能用了。
• Agent 镜像的 tag 要明确，不要用latest。latest会导致每次拉取的镜像可能不一样，排查问题时很麻烦。

7.2 测试策略

Agent 的测试比普通服务难，因为它的行为是不确定的。我们的测试策略分三层：

• 单元测试：测试 Agent 的各个组件，比如工具调用、状态管理、决策逻辑。用 mock 替代外部依赖。
• 集成测试：在本地 Kubernetes 集群里跑完整的 Workflow，验证 Agent 之间的协作。
• 混沌测试：故意注入故障——杀掉 Agent、断开网络、填满磁盘——看系统是否能自愈。

混沌测试特别重要。我们有一次在测试环境模拟了 etcd 故障，发现 ax 的 controller 在 etcd 恢复后无法正确重建状态，导致所有 Agent 都卡住了。后来加了状态重建逻辑才解决。

7.3 文档和知识沉淀

Agent 编排系统涉及的东西很多：CRD 定义、Workflow 语法、工具配置、状态管理、监控告警。如果没有好的文档，新人上手成本很高。

我们的做法是：每个 Agent 的 CRD 里都带注释，说明这个 Agent 是做什么的、输入输出是什么、依赖哪些工具。Workflow 的 YAML 里也带注释，说明每个节点的作用。另外维护一个内部 Wiki，记录常见问题和解决方案。

最后分享一个小技巧：给 Agent 起名字的时候，用“动词-名词”的格式，比如fetch-data、clean-data、generate-report。这样一看名字就知道它是干什么的，比agent-1、agent-2强多了。而且在 Workflow 的 DAG 图里，名字清晰的话，整个流程一目了然。

这个领域还在快速变化，新的工具和模式不断出现。我目前关注的方向是：Agent 的自动扩缩容策略怎么更智能、多 Agent 之间的协商机制怎么设计、以及怎么把成本控制做得更细粒度。如果你也在做类似的事情，欢迎交流踩坑经验。