Add Kruise Sandbox deployer feature (#442)

Author: bcfre

cookbook/en/advanced_deployment.md

@@ -14,7 +14,7 @@ kernelspec:
 
 # Advanced Deployment Guide
 
-This guide covers the multiple advanced deployment methods available in AgentScope Runtime, providing production-ready solutions for different scenarios: **Local Daemon**, **Detached Process**, **Kubernetes Deployment**, **ModelStudio Deployment**, **AgentRun Deployment**, **PAI Deployment**, **Knative Deployment** and **Function Compute (FC) Deployment**.
+This guide covers the multiple advanced deployment methods available in AgentScope Runtime, providing production-ready solutions for different scenarios: **Local Daemon**, **Detached Process**, **Kubernetes Deployment**, **ModelStudio Deployment**, **AgentRun Deployment**, **PAI Deployment**, **Knative Deployment**, **Kruise Deployment** and **Function Compute (FC) Deployment**.
 
 ## Overview of Deployment Methods
 
@@ -29,6 +29,7 @@ AgentScope Runtime offers multiple distinct deployment approaches, each tailored
 | **AgentRun**              | AgentRun Platform | Cloud-managed | Platform-managed | Container-level |
 | **PAI**                   | Alibaba Cloud PAI Platform | Cloud-managed | Platform-managed | Container-level |
 | **Knative**               | Enterprise & Cloud | Single-node (multi-node support coming) | Orchestrated | Container-level |
+| **Kruise**                | Enterprise & Cloud | Single-node | Orchestrated | Container-level / MicroVM-level |
 | **Function Compute (FC)** | Alibaba Cloud Serverless | Cloud-managed | Platform-managed | MicroVM-level |
 
 ### Deployment Modes (DeploymentMode)
@@ -1222,7 +1223,104 @@ if __name__ == "__main__":
 - Provides automatic scaling from zero to thousands of instances, intelligent traffic routing
 - Resource limits and health checks configured
 
-## Method 8: Serverless Deployment: Function Compute (FC)
+## Method 8: Kruise Deployment
+
+**Best For**: Scenarios requiring instance-level isolation, pause/resume capabilities, and secure multi-tenant runtime environments.
+
+### Features
+- Custom resource deployment based on Kruise Sandbox CRD (`agents.kruise.io/v1alpha1`)
+- Instance-level isolation, ensuring secure runtime environments across different agents
+- Supports pausing and resuming, effectively saving resource consumption
+- Automatically creates LoadBalancer Service for external access
+- Deployment state persistence management
+
+### Kruise Deployment Prerequisites
+
+```bash
+# Ensure Docker is running
+docker --version
+
+# Verify Kubernetes access
+kubectl cluster-info
+
+# Check registry access (e.g., Alibaba Cloud)
+docker login your-registry
+
+# Check Kruise Sandbox is installed
+# Installation guide: https://github.com/openkruise/agents
+kubectl get crd sandboxes.agents.kruise.io
+```
+
+### Implementation
+
+Using the agent and endpoints defined in the {ref}`Common Agent Setup <en-common-agent-setup>` section:
+
+```{code-cell}
+# kruise_deploy.py
+import asyncio
+import os
+from agentscope_runtime.engine.deployers.kruise_deployer import (
+    KruiseDeployManager,
+    K8sConfig,
+)
+from agentscope_runtime.engine.deployers.utils.docker_image_utils import (
+    RegistryConfig,
+)
+from agent_app import app  # Import the configured app
+
+async def deploy_to_kruise():
+    """Deploy AgentApp to Kruise Sandbox"""
+
+    # Configure registry and K8s connection
+    deployer = KruiseDeployManager(
+        kube_config=K8sConfig(
+            k8s_namespace="agentscope-runtime",
+            kubeconfig_path=None,
+        ),
+        registry_config=RegistryConfig(
+            registry_url="your-registry-url",
+            namespace="agentscope-runtime",
+        ),
+    )
+
+    # Execute deployment
+    result = await app.deploy(
+        deployer,
+        port="8090",
+        image_name="agent_app",
+        image_tag="v1.0",
+        requirements=["agentscope", "fastapi", "uvicorn"],
+        base_image="python:3.10-slim-bookworm",
+        environment={
+            "PYTHONPATH": "/app",
+            "DASHSCOPE_API_KEY": os.environ.get("DASHSCOPE_API_KEY"),
+        },
+        labels={
+            "app": "agent-kruise",
+        },
+        runtime_config={
+            "resources": {
+                "requests": {"cpu": "200m", "memory": "512Mi"},
+                "limits": {"cpu": "1000m", "memory": "2Gi"},
+            },
+        },
+        platform="linux/amd64",
+        push_to_registry=True,
+    )
+
+    print(f"Deployment successful: {result['url']}")
+    return result, deployer
+
+if __name__ == "__main__":
+    asyncio.run(deploy_to_kruise())
+```
+
+**Key Points**:
+- Isolated deployment based on Kruise Sandbox CRD, each agent runs in an independent environment
+- Automatically creates LoadBalancer Service, supports automatic switching between local and cloud environments
+- Deployment state is automatically persisted, supports lifecycle management via CLI
+
+## Method 9: Serverless Deployment: Function Compute (FC)
 
 **Best For**: Alibaba Cloud users who need to deploy agents to Function Compute (FC) service with automated build, upload, and deployment workflows. FC provides a true serverless experience with pay-per-use pricing and automatic scaling.
 

cookbook/en/cli.md

@@ -402,6 +402,8 @@ agentscope deploy PLATFORM SOURCE [OPTIONS]
 - `modelstudio`: Alibaba Cloud ModelStudio
 - `agentrun`: Alibaba Cloud AgentRun
 - `k8s`: Kubernetes/ACK
+- `knative`: Knative/ACK Knative
+- `kruise`: Kruise Sandbox
 
 #### Common Options (All Platforms)
 
@@ -645,6 +647,73 @@ agentscope deploy knative app_agent.py \
 
 **Note:** `USE_LOCAL_RUNTIME=True` uses local agentscope runtime instead of PyPI version.
 
+#### 4.5. Kruise Deployment
+
+Deploy to Kruise Sandbox custom resource (`agents.kruise.io/v1alpha1`) on a Kubernetes cluster.
+
+Key differences from standard K8s Deployment and Knative:
+- **Instance-level isolation**: Ensures secure environment isolation across different agents
+- **Pause/Resume**: Supports pausing and resuming, effectively saving resource consumption
+- **Auto-created LoadBalancer Service**: Automatically creates load balancer service for external access
+
+##### Command Syntax
+
+```bash
+agentscope deploy kruise SOURCE [OPTIONS]
+```
+
+##### Platform-Specific Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `--namespace` | string | `"agentscope-runtime"` | Kubernetes namespace |
+| `--kube-config-path` | path | `None` | Path to kubeconfig file |
+| `--port` | integer | `8080` | Container port |
+| `--image-name` | string | `"agent_app"` | Docker image name |
+| `--image-tag` | string | `"linux-amd64"` | Docker image tag |
+| `--registry-url` | string | `"localhost"` | Remote registry URL |
+| `--registry-namespace` | string | `"agentscope-runtime"` | Remote registry namespace |
+| `--push` | flag | `False` | Push image to registry |
+| `--base-image` | string | `"python:3.10-slim-bookworm"` | Base Docker image |
+| `--requirements` | string | `None` | Python requirements (comma-separated or file path) |
+| `--cpu-request` | string | `"200m"` | CPU resource request (e.g., '200m', '1') |
+| `--cpu-limit` | string | `"1000m"` | CPU resource limit (e.g., '1000m', '2') |
+| `--memory-request` | string | `"512Mi"` | Memory resource request (e.g., '512Mi', '1Gi') |
+| `--memory-limit` | string | `"2Gi"` | Memory resource limit (e.g., '2Gi', '4Gi') |
+| `--image-pull-policy` | choice | `"IfNotPresent"` | Image pull policy: `Always`, `IfNotPresent`, `Never` |
+| `--deploy-timeout` | integer | `300` | Deployment timeout in seconds |
+| `--platform` | string | `"linux/amd64"` | Target platform (e.g., 'linux/amd64', 'linux/arm64') |
+| `--pypi-mirror` | string | `None` | PyPI mirror URL for pip package installation (e.g., 'https://pypi.tuna.tsinghua.edu.cn/simple'). If not specified, uses pip default |
+
+##### Prerequisites
+
+- Kubernetes cluster access
+- Kruise Sandbox CRD (`agents.kruise.io/v1alpha1`) installed, see [Kruise Agents](https://github.com/openkruise/agents)
+- Docker installed (for building images)
+- `kubectl` configured
+
+##### Examples
+
+```bash
+# Basic deployment
+export USE_LOCAL_RUNTIME=True
+agentscope deploy kruise app_agent.py \
+  --image-name agent_app \
+  --env DASHSCOPE_API_KEY=sk-xxx \
+  --image-tag linux-amd64-1 \
+  --registry-url your-registry.com \
+  --push
+
+# Custom namespace and resources
+agentscope deploy kruise app_agent.py \
+  --namespace production \
+  --cpu-limit 2 \
+  --memory-limit 4Gi \
+  --env DASHSCOPE_API_KEY=sk-xxx
+```
+
+**Note:** `USE_LOCAL_RUNTIME=True` uses local agentscope runtime instead of PyPI version.
+
 ### 5. Deployment Management
 
 #### 5.1. List Deployments

cookbook/zh/advanced_deployment.md

@@ -14,7 +14,7 @@ kernelspec:
 
 # 高级部署
 
-章节演示了AgentScope Runtime中可用的八种高级部署方法，为不同场景提供生产就绪的解决方案：**本地守护进程**、**独立进程**、**Kubernetes部署**、**ModelStudio部署**、**AgentRun部署**、**PAI部署**、**Knative**和**函数计算（Function Compute, FC）部署**。
+章节演示了AgentScope Runtime中可用的九种高级部署方法，为不同场景提供生产就绪的解决方案：**本地守护进程**、**独立进程**、**Kubernetes部署**、**ModelStudio部署**、**AgentRun部署**、**PAI部署**、**Knative**、**Kruise部署**和**函数计算（Function Compute, FC）部署**。
 
 ## 部署方法概述
 
@@ -28,7 +28,8 @@ AgentScope Runtime提供多种不同的部署方式，每种都针对特定的
 | **ModelStudio**                | 百炼应用开发平台   | 云端管理 | 平台管理 | 容器级 |
 | **AgentRun**                   | AgentRun平台 | 云端管理 | 平台管理 | 容器级 |
 | **PAI**                       | 阿里云PAI平台   | 云端管理 | 平台管理 | 容器级 |
-| **Knative**                    | 企业与云端 | 单节点（将支持多节点） | 编排 | 容器级 |
+| **Knative**                    | 企业与云端 | 单节点（未来支持多节点） | 编排 | 容器级 |
+| **Kruise**                     | 企业与云端 | 单节点 | 编排 | 容器级/微虚拟机级 |
 | **函数计算(FC)** | 阿里云 Serverless | 云端管理 | 平台管理 | 微虚拟机级 |
 
 
@@ -1219,7 +1220,104 @@ if __name__ == "__main__":
 - 支持基于请求自动弹性、缩容至 0
 - 配置资源限制和健康检查
 
-## 方法8：Serverless部署：函数计算（Function Compute, FC）
+## 方法8：Kruise部署
+
+**最适合**：需要实例级隔离、暂停恢复能力和安全多租户运行环境的场景。
+
+### 特性
+- 基于 Kruise Sandbox CRD（`agents.kruise.io/v1alpha1`）的自定义资源部署
+- 实例级隔离，确保不同 agent 运行环境安全
+- 支持暂停和恢复，有效节省资源消耗
+- 自动创建 LoadBalancer Service 提供外部访问
+- 部署状态持久化管理
+
+### Kruise 部署前置条件
+
+```bash
+# 确保Docker正在运行
+docker --version
+
+# 验证Kubernetes访问
+kubectl cluster-info
+
+# 检查镜像仓库访问（以阿里云为例）
+docker login your-registry
+
+# 检查 Kruise Sandbox CRD 已安装
+# 安装指南：https://github.com/openkruise/agents
+kubectl get crd sandboxes.agents.kruise.io
+```
+
+### 实现
+
+使用 {ref}`通用智能体配置<zh-common-agent-setup>` 部分定义的智能体和端点：
+
+```{code-cell}
+# kruise_deploy.py
+import asyncio
+import os
+from agentscope_runtime.engine.deployers.kruise_deployer import (
+    KruiseDeployManager,
+    K8sConfig,
+)
+from agentscope_runtime.engine.deployers.utils.docker_image_utils import (
+    RegistryConfig,
+)
+from agent_app import app  # 导入已配置的 app
+
+async def deploy_to_kruise():
+    """将 AgentApp 部署到 Kruise Sandbox"""
+
+    # 配置镜像仓库和 K8s 连接
+    deployer = KruiseDeployManager(
+        kube_config=K8sConfig(
+            k8s_namespace="agentscope-runtime",
+            kubeconfig_path=None,
+        ),
+        registry_config=RegistryConfig(
+            registry_url="your-registry-url",
+            namespace="agentscope-runtime",
+        ),
+    )
+
+    # 执行部署
+    result = await app.deploy(
+        deployer,
+        port="8090",
+        image_name="agent_app",
+        image_tag="v1.0",
+        requirements=["agentscope", "fastapi", "uvicorn"],
+        base_image="python:3.10-slim-bookworm",
+        environment={
+            "PYTHONPATH": "/app",
+            "DASHSCOPE_API_KEY": os.environ.get("DASHSCOPE_API_KEY"),
+        },
+        labels={
+            "app": "agent-kruise",
+        },
+        runtime_config={
+            "resources": {
+                "requests": {"cpu": "200m", "memory": "512Mi"},
+                "limits": {"cpu": "1000m", "memory": "2Gi"},
+            },
+        },
+        platform="linux/amd64",
+        push_to_registry=True,
+    )
+
+    print(f"✅ 部署成功：{result['url']}")
+    return result, deployer
+
+if __name__ == "__main__":
+    asyncio.run(deploy_to_kruise())
+```
+
+**关键点**：
+- 基于 Kruise Sandbox CRD 的隔离部署，每个 agent 独立运行环境
+- 自动创建 LoadBalancer Service，支持本地和云端环境自动切换
+- 部署状态自动持久化，支持通过 CLI 管理生命周期
+
+## 方法9：Serverless部署：函数计算（Function Compute, FC）
 
 **最适合**：阿里云用户，需要将智能体部署到函数计算（FC）服务，实现自动化的构建、上传和部署流程。FC 提供真正的 Serverless 体验，按量付费并自动扩缩容。