Agent Sandbox

网站 · 文档 · DeepWiki · 快速入门 · 示例 · 路线图

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

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

概述

核心：Sandbox

Sandbox CRD 是 agent-sandbox 的核心。它提供了一个声明式 API，用于管理具有稳定身份和持久化存储的单个有状态 Pod。这对于那些不适合使用 Deployment（无状态、可复制模型）或 StatefulSet（带编号、稳定模型）的工作负载非常有用。

Sandbox CRD 的主要功能包括：

• 稳定身份： 每个 Sandbox 都拥有稳定的主机名和网络身份。
• 持久化存储： Sandbox 可以配置在重启后仍保留数据的持久化存储。
• 生命周期管理： Sandbox 控制器管理 Pod 的整个生命周期，包括创建、计划删除、暂停和恢复。

扩展

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

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

架构

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

架构图

flowchart TB

    User[User]

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

    ClaimController[Claim Controller]
    Controller[Sandbox Controller]

    Pod[Sandbox Pod]
    Runtime[Sandbox Runtime Environment]

    WarmPool[SandboxWarmPool]

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

    %% Claim workflow
    Claim -->|references| Template
    Claim -->|reconciled by| ClaimController
    ClaimController -->|creates| Sandbox

    %% Pod handling
    ClaimController -->|adopts pod from| WarmPool
    Sandbox -->|reconciled by| Controller
    Controller -->|creates Pod if needed| Pod

    %% Runtime
    Pod --> Runtime

    %% Warm pool
    WarmPool -->|pre-warmed pods| Pod

安装

核心组件与扩展

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

# Replace "vX.Y.Z" with a specific version tag (e.g., "v0.1.0") from
# https://github.com/kubernetes-sigs/agent-sandbox/releases
export VERSION="vX.Y.Z"

# To install only the core components:
kubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/${VERSION}/manifest.yaml

# To install the extensions components:
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 和 worker 数量），请参阅 配置指南。

快速入门

安装控制器后，你可以通过将以下 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 在管理...