#架构与资源模型

Alauda Build of Agent Sandbox 将工作负载生命周期编排与运行时隔离分离开来。controller 负责协调 Kubernetes 资源，而所选的 container runtime 则提供进程或虚拟机的隔离边界。

#控制平面

ACP 将 Agent Sandbox 作为 Cluster Plugin 安装。安装过程会创建 agent-sandbox-system 命名空间，并在目标业务集群中运行 agent-sandbox-controller。

controller 会监视 Agent Sandbox 自定义资源，并管理其次级资源。诸如 controller 副本数、controller Pod 资源和 controller 调度之类的平台级设置，通过 Cluster Plugin 进行配置。工作负载相关的资源和调度仍保留在各自的 Sandbox 或 SandboxTemplate 中。

#核心 Sandbox 资源

核心 API 为：

apiVersion: agents.x-k8s.io/v1beta1
kind: Sandbox

Sandbox 描述一个有状态的单例工作负载。其 podTemplate 定义了容器镜像、命令、存储、安全上下文、网络元数据、调度约束，以及可选的 runtimeClassName。

controller 维护一个与 Sandbox 具有相同稳定标识的 Pod，并通过 status conditions 报告生命周期状态。应用必须检查每个 condition 的布尔 status；仅存在 condition 本身并不表示发生了状态转换。

#可选扩展资源

可选扩展 API 组为 extensions.agents.x-k8s.io/v1beta1，其中包含：

即使其 reconcilers 已被禁用，扩展 CRD 仍然可以存在。在创建这些资源之前，请确认 controller 参数中包含 --extensions=true。Cluster Plugin 设置 controller.extensions 的默认值为 false。

#工作负载与运行时边界

Agent Sandbox 负责：

• 声明并协调 Sandbox 生命周期。
• 维护稳定的工作负载标识。
• 报告 Ready、Suspended 和错误 condition。
• 管理可选模板、claim 和 warm pool。
• 应用用户选择的 Pod 模板。

container runtime 负责底层隔离边界。请将 spec.podTemplate.spec.runtimeClassName 设置为已由集群管理员安装并配置的 RuntimeClass。Agent Sandbox 不会安装 Kata Containers、gVisor 或其他 runtime。

#请求流程

典型请求按以下顺序进行：

1. 平台管理员安装并配置 Cluster Plugin。
2. 用户或智能体服务在业务命名空间中创建一个 Sandbox。
3. controller 验证请求的生命周期状态，并创建或更新受管 Pod。
4. Kubernetes 调度 Pod，并选择已配置的 RuntimeClass。
5. controller 在 Sandbox 上发布状态 condition。
6. 客户端在连接到工作负载或在其中执行命令之前，等待 Ready=True。
7. 客户端挂起、恢复、删除 Sandbox，或让计划关闭策略处理该 Sandbox。

对于扩展工作流，SandboxClaim 会根据 SandboxTemplate 从 SandboxWarmPool 中选择一个已准备好的工作负载。生成的工作负载仍然使用相同的核心 Sandbox 以及 Pod/runtime 边界。