Add Kruise Sandbox deployer feature

[bcfre]

Description

[Describe what this PR does and why]

OpenKruise Agents is a CNCF sub-project under OpenKruise that provides Kubernetes-native sandbox management for AI agent workloads. It offers vendor-neutral sandboxes with features like resource pooling, rapid provisioning, sandbox hibernation, and comprehensive API/SDK support.

This PR adds a new sandbox deployer that enables deploying AI agents as Kruise Sandbox custom resources on Kubernetes. Users can deploy agents via CLI with agentscope deploy sandbox, and the platform handles image building, Sandbox CR creation, Service exposure, and lifecycle management automatically.

Changes include:

• SandboxClient: Kubernetes client for Sandbox CRD (CRUD operations, status polling, Service management)
• SandboxDeployManager: Deploy manager integrating image build, Sandbox CR creation, and Service exposure
• CLI commands: agentscope deploy sandbox and agentscope stop --platform sandbox
• Example scripts and configuration files
• Documentation updates (en/zh)
• Unit tests

Related Issue: Fixes #[issue_number] or Relates to #[issue_number]

Security Considerations: [If applicable, especially for sandbox changes]

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation
• Refactoring

Component(s) Affected

• Engine
• Sandbox
• Tools
• Common
• Documentation
• Tests
• CI/CD

Checklist

• Pre-commit hooks pass
• Tests pass locally
• Documentation updated (if needed)
• Ready for review

Testing

[How to test these changes]

Additional Notes

[Optional: any other context]

[gemini-code-assist]

Summary of Changes

Hello @bcfre, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the deployment capabilities by introducing native support for Kruise Sandbox. This new deployer allows AI agents to leverage Kubernetes-native sandbox management, providing features like resource pooling, rapid provisioning, and sandbox hibernation. The integration includes a dedicated Kubernetes client, a deployment manager, and command-line interface tools, making it straightforward for users to deploy and manage their AI agents in isolated and secure environments on Kubernetes clusters.

Highlights

• New Sandbox Deployer: Introduced a new sandbox deployer that enables deploying AI agents as Kruise Sandbox custom resources on Kubernetes, offering instance-level isolation, pause/resume capabilities, and secure multi-tenant runtime environments.
• CLI Integration: Added new CLI commands agentscope deploy sandbox and agentscope stop --platform sandbox for seamless deployment and lifecycle management of agents on Kruise Sandbox.
• Kubernetes Client for Sandbox CRD: Implemented a SandboxClient for CRUD operations on Sandbox CRDs, status polling, and Kubernetes Service management to expose deployed agents.
• Deployment Manager: Developed SandboxDeployManager to integrate image building, Sandbox CR creation, and Service exposure, automating the deployment workflow.
• Comprehensive Documentation: Updated both English and Chinese advanced deployment guides and CLI documentation to include detailed information, prerequisites, and examples for Sandbox deployment.
• Deployment Examples and Tests: Added example scripts and configuration files for Sandbox deployment, along with unit tests for the SandboxDeployManager and K8sConfig.

Changelog

• cookbook/en/advanced_deployment.md
  • Updated the advanced deployment guide to include 'Sandbox Deployment' as a new method.
  • Added a detailed section for Sandbox Deployment, outlining its features, prerequisites, and implementation steps with a Python code example.
  • Reordered deployment methods to accommodate the new Sandbox entry.
• cookbook/en/cli.md
  • Updated the CLI documentation to list 'sandbox' as a new deployment platform.
  • Added a new section '4.5. Sandbox Deployment' with command syntax, platform-specific options, prerequisites, and examples for agentscope deploy sandbox.
• cookbook/zh/advanced_deployment.md
  • Updated the Chinese advanced deployment guide to include 'Sandbox部署' as a new method.
  • Added a detailed section for Sandbox部署, outlining its features, prerequisites, and implementation steps with a Python code example.
  • Reordered deployment methods to accommodate the new Sandbox entry.
• cookbook/zh/cli.md
  • Updated the Chinese CLI documentation to list 'sandbox' as a new deployment platform.
  • Added a new section '4.5. Sandbox 部署' with command syntax, platform-specific options, prerequisites, and examples for agentscope deploy sandbox.
• examples/deployments/sandbox_deploy/README.md
  • Added a new README file providing a comprehensive guide for the Sandbox deployment example.
  • Included sections on overview, prerequisites, configuration parameters (registry, Kubernetes, runtime, sandbox), running the deployment, testing, troubleshooting, and file structure.
• examples/deployments/sandbox_deploy/app_deploy_to_sandbox.py
  • Added a new Python script demonstrating how to deploy an AgentApp to Kruise Sandbox.
  • Configured registry and Kubernetes connections, defined runtime and sandbox deployment parameters, and included functions for testing and cleaning up the deployed service.
• examples/deployments/sandbox_deploy/sandbox_deploy_config.json
  • Added a new JSON configuration example for Sandbox deployment, specifying deployment settings, Docker image details, dependencies, environment variables, and Kubernetes runtime configurations.
• examples/deployments/sandbox_deploy/sandbox_deploy_config.yaml
  • Added a new YAML configuration example for Sandbox deployment, mirroring the JSON configuration with detailed comments.
• src/agentscope_runtime/cli/commands/deploy.py
  • Added SandboxDeployManager and SandboxK8sConfig imports.
  • Included 'sandbox' as a recognized platform in the deploy command's help text.
  • Implemented the sandbox subcommand with extensive options for configuring Sandbox deployments, including image details, resources, environment variables, and Kubernetes settings.
  • Added logic to load and merge configuration from files and CLI arguments for Sandbox deployments.
• src/agentscope_runtime/cli/commands/stop.py
  • Updated the _create_deployer function to recognize 'sandbox' as a valid platform for stopping deployments.
  • Added logic to instantiate SandboxDeployManager for 'sandbox' platform stops.
• src/agentscope_runtime/common/container_clients/init.py
  • Imported SandboxClient.
  • Registered SandboxClient in the _CLIENT_MAPPING and ContainerClientFactory.
• src/agentscope_runtime/common/container_clients/sandbox_client.py
  • Added a new SandboxClient class for Kubernetes interactions specific to Kruise Sandbox CRDs.
  • Implemented methods for creating, deleting, getting, and waiting for Sandbox resources.
  • Included functionality for creating and deleting Kubernetes LoadBalancer Services to expose Sandbox pods.
  • Provided utility methods for parsing port specifications and determining Sandbox status.
• src/agentscope_runtime/engine/init.py
  • Imported SandboxDeployManager.
  • Exported SandboxDeployManager in the __all__ list and _DEPLOYER_MAPPING.
• src/agentscope_runtime/engine/deployers/init.py
  • Imported SandboxDeployManager.
  • Exported SandboxDeployManager in the _DEPLOYER_MAPPING and __all__ list.
• src/agentscope_runtime/engine/deployers/sandbox_deployer.py
  • Added a new SandboxDeployManager class for deploying AgentScope runners to Kruise Sandbox.
  • Defined K8sConfig for Kubernetes settings.
  • Implemented the deploy method, which handles image building, Sandbox CR creation, and LoadBalancer Service exposure.
  • Included a stop method for cleaning up Sandbox deployments and an get_status method for retrieving deployment status.
  • Added logic for determining service endpoints based on local or remote Kubernetes environments.
• tests/deploy/test_sandbox_deployer.py
  • Added a new test file for SandboxDeployManager and K8sConfig.
  • Included unit tests for deployer creation, successful deployment, image build failures, Sandbox CR creation failures, service creation fallbacks, volume mounts, and stopping deployments.
  • Tested status retrieval for existing, nonexistent, and misconfigured deployments.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a significant new feature: a deployer for Kruise Sandbox. The changes are comprehensive, including the core SandboxDeployManager and SandboxClient, a new agentscope deploy sandbox CLI command, extensive documentation, and a full working example. The overall implementation is solid and follows existing patterns in the codebase. My review focuses on improving consistency, fixing a broken example, and addressing a potential security concern with a hardcoded URL in the example code.

[Copilot]

Pull request overview

This PR adds a new Sandbox deployer feature that enables deploying AI agents as Kruise Sandbox custom resources (agents.kruise.io/v1alpha1) on Kubernetes. The implementation integrates with the existing AgentScope Runtime deployment framework, providing a production-ready solution for deploying agents with instance-level isolation and pause/resume capabilities.

Changes:

• Adds SandboxClient for Kubernetes Sandbox CRD operations (create, delete, status polling, Service management)
• Adds SandboxDeployManager for orchestrating image builds, Sandbox CR creation, and Service exposure
• Integrates new deployer into CLI commands (agentscope deploy sandbox and agentscope stop --platform sandbox)
• Includes comprehensive unit tests with 675 lines covering creation, deployment, lifecycle management, and edge cases
• Provides example scripts demonstrating deployment patterns with detailed configuration
• Updates English and Chinese documentation with deployment guides and usage examples

Reviewed changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
src/agentscope_runtime/common/container_clients/sandbox_client.py	New Kubernetes client for Sandbox CRD operations with full CRUD support
src/agentscope_runtime/engine/deployers/sandbox_deployer.py	Main deployment manager integrating image build, CR creation, and Service management
src/agentscope_runtime/cli/commands/deploy.py	CLI command for sandbox deployment with comprehensive options
src/agentscope_runtime/cli/commands/stop.py	CLI command extension for stopping sandbox deployments
tests/deploy/test_sandbox_deployer.py	Comprehensive test suite with 675 lines covering all deployment scenarios
examples/deployments/sandbox_deploy/app_deploy_to_sandbox.py	Example script demonstrating programmatic deployment
examples/deployments/sandbox_deploy/sandbox_deploy_config.yaml	YAML configuration example
examples/deployments/sandbox_deploy/sandbox_deploy_config.json	JSON configuration example
examples/deployments/sandbox_deploy/README.md	Detailed usage guide with prerequisites and troubleshooting
cookbook/en/advanced_deployment.md	English documentation for sandbox deployment
cookbook/zh/advanced_deployment.md	Chinese documentation for sandbox deployment
cookbook/en/cli.md	English CLI reference for sandbox commands
cookbook/zh/cli.md	Chinese CLI reference for sandbox commands
Integration files	Updates to __init__.py files for proper module exports

[rayrayraykk]

LGTM

[rayrayraykk]

@all-contributors please add @bcfre for code, doc

[allcontributors]

@rayrayraykk

I've put up a pull request to add @bcfre! 🎉