Agent Sandbox

agent-sandbox 能够轻松管理隔离的、有状态的单例（singleton）工作负载，非常适合 AI agent 运行时等使用场景。

该项目正在 Kubernetes 中开发一个 Sandbox 自定义资源定义（CRD）和控制器，隶属于 SIG Apps。其目标是提供一种声明式的、标准化的 API，用于管理那些需要长期运行、有状态、单实例容器且具备稳定标识的工作负载，其体验类似于构建在 Kubernetes 原生基础之上的轻量级单容器虚拟机。

概述

核心：Sandbox

Sandbox CRD 是 agent-sandbox 的核心。它提供了一个声明式 API，用于管理单个具有稳定标识和持久化存储的有状态 Pod。这对于那些不适合 Deployment 的无状态/多副本模式，也不适合 StatefulSet 的带编号/稳定模式的工作负载非常有用。

Sandbox CRD 的主要特性包括：

稳定标识： 每个 Sandbox 都有一个稳定的主机名和网络标识。
持久化存储： 可以配置 Sandbox 以使用在重启后依然存在的持久化存储。
生命周期管理： Sandbox 控制器负责管理 Pod 的生命周期，包括创建、定时删除、暂停和恢复。

扩展

extensions 模块提供了额外的 CRD 和控制器，它们构建在核心 Sandbox API 之上，以提供更高级的功能。

SandboxTemplate：提供了一种定义可重用模板的方法，用于创建 Sandbox，从而更轻松地管理大量相似的 Sandbox。
SandboxClaim：允许用户根据模板创建 Sandbox，屏蔽了底层 Sandbox 配置的细节。
SandboxWarmPool：管理一个预热（pre-warmed）的 Sandbox 池，可以快速分配给用户，减少启动新 Sandbox 所需的时间。

架构

agent-sandbox 遵循 Kubernetes 控制器模式。用户创建 Sandbox 自定义资源，控制器负责管理底层的运行时资源。

架构图

flowchart LR

    User[User]

    Claim[SandboxClaim]
    Template[SandboxTemplate]
    Sandbox[Sandbox]

    Pod[Pod]
    Runtime[Sandbox Runtime]

    WarmPool[SandboxWarmPool]

    subgraph Extensions[Extensions]
      Claim
      Template
      WarmPool
    end

    %% User paths
    User -->|creates| Sandbox
    User -->|creates| Claim

    %% Claim workflow
    Claim -->|references| Template
    Claim -->|adopts| Sandbox

    %% Pod handling
    Claim -->|adopts sandboxes from| WarmPool
    Sandbox -->|creates Pod| Pod

    %% Runtime
    Pod --> Runtime

    %% Warm pool
    WarmPool -->|pre-warms sandboxes| Sandbox

安装

核心组件与扩展

你可以使用以下命令安装 agent-sandbox 控制器及其 CRD。

# 将 "vX.Y.Z" 替换为来自以下地址的具体版本标签（例如 "v0.1.0"）
# https://github.com/kubernetes-sigs/agent-sandbox/releases
export VERSION="vX.Y.Z"

# 仅安装核心组件：
kubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/${VERSION}/manifest.yaml

# 安装扩展组件：
kubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/${VERSION}/extensions.yaml

Python SDK

要以编程方式与 agent-sandbox 进行交互，可以使用 Python SDK。该客户端库提供了用于创建和管理 Sandbox 的高级接口。

有关详细的安装和使用说明，请参考 Python SDK README。

配置

关于高级扩展和并发调优（例如 API QPS 和工作线程数），请参阅配置指南。

快速入门

安装控制器后，你可以通过将以下 YAML 应用到集群来创建一个简单的 Sandbox：

apiVersion: agents.x-k8s.io/v1alpha1
kind: Sandbox
metadata:
  name: my-sandbox
spec:
  podTemplate:
    spec:
      containers:
      - name: my-container
        image:

这将创建一个名为 my-sandbox 的新 Sandbox，并运行你指定的镜像。之后，你可以使用其稳定的主机名 my-sandbox 来访问该 Sandbox。

如需了解更复杂的示例（包括如何使用扩展），请查阅 examples/ 和 extensions/examples/ 目录。

动机

Kubernetes 在管理无状态、多副本应用程序（Deployments）以及稳定的带编号有状态 Pod 集合（StatefulSets）方面表现卓越。