RAGFlow is an agent-native database: a Retrieval-Augmented Generation (RAG) engine that grew into context infrastructure.
Go agent-harnessagent-native-databaseagentic-aiagentic-retrievalagentic-searchaiai-agentscontext-enginecontext-engineeringcontext-managementharness-engineeringknowledge-compilationragretrieval-augmented-generationretrieval-harnesssearch-harness
feat: add UCloud agent sandbox provider (#18088)
wenqianc589a5d0508b
diff --git a/admin/server/services.py b/admin/server/services.pyindex a59c921c3b..c7bd352e37 100644--- a/admin/server/services.py+++ b/admin/server/services.py@@ -504,6 +504,11 @@ class SandboxMgr:"description": "Tenki - Disposable microVM code sandboxes","tags": ["saas", "cloud", "microvm", "isolated"],},+ "ucloud_agent_sandbox": {+ "name": "UCloud Agent Sandbox",+ "description": "UCloud Agent Sandbox - Disposable cloud sandboxes for agent code execution",+ "tags": ["saas", "cloud", "isolated", "ucloud"],+ },}@staticmethod@@ -524,6 +529,7 @@ class SandboxMgr:AliyunCodeInterpreterProvider,E2BProvider,TenkiProvider,+ UCloudAgentSandboxProvider,)schemas = {@@ -533,6 +539,7 @@ class SandboxMgr:"aliyun_codeinterpreter": AliyunCodeInterpreterProvider.get_config_schema(),"e2b": E2BProvider.get_config_schema(),"tenki": TenkiProvider.get_config_schema(),+ "ucloud_agent_sandbox": UCloudAgentSandboxProvider.get_config_schema(),}if provider_id not in schemas:@@ -599,6 +606,7 @@ class SandboxMgr:AliyunCodeInterpreterProvider,E2BProvider,TenkiProvider,+ UCloudAgentSandboxProvider,)try:@@ -644,6 +652,7 @@ class SandboxMgr:"aliyun_codeinterpreter": AliyunCodeInterpreterProvider,"e2b": E2BProvider,"tenki": TenkiProvider,+ "ucloud_agent_sandbox": UCloudAgentSandboxProvider,}provider = provider_classes[provider_type]()is_valid, error_msg = provider.validate_config(config)@@ -692,6 +701,7 @@ class SandboxMgr:AliyunCodeInterpreterProvider,E2BProvider,TenkiProvider,+ UCloudAgentSandboxProvider,)# Instantiate provider based on type@@ -702,6 +712,7 @@ class SandboxMgr:"aliyun_codeinterpreter": AliyunCodeInterpreterProvider,"e2b": E2BProvider,"tenki": TenkiProvider,+ "ucloud_agent_sandbox": UCloudAgentSandboxProvider,}if provider_type not in provider_classes:diff --git a/agent/sandbox/client.py b/agent/sandbox/client.pyindex cdcced4b0a..9c28048bfc 100644--- a/agent/sandbox/client.py+++ b/agent/sandbox/client.py@@ -78,6 +78,7 @@ def _load_provider_from_settings() -> None:LocalProvider,SSHProvider,TenkiProvider,+ UCloudAgentSandboxProvider,)provider_classes = {@@ -87,6 +88,7 @@ def _load_provider_from_settings() -> None:"local": LocalProvider,"ssh": SSHProvider,"tenki": TenkiProvider,+ "ucloud_agent_sandbox": UCloudAgentSandboxProvider,}if provider_type not in provider_classes:@@ -99,7 +101,7 @@ def _load_provider_from_settings() -> None:# Initialize the providerif not provider.initialize(config):message = f"Failed to initialize sandbox provider: {provider_type}. Config keys: {list(config.keys())}"- if provider_type in {"local", "ssh", "tenki"}:+ if provider_type in {"local", "ssh", "tenki", "ucloud_agent_sandbox"}:raise SandboxProviderConfigError(message)logger.error(message)returndiff --git a/agent/sandbox/providers/__init__.py b/agent/sandbox/providers/__init__.pyindex a1bb7c6c6e..e0935ea124 100644--- a/agent/sandbox/providers/__init__.py+++ b/agent/sandbox/providers/__init__.py@@ -27,6 +27,7 @@ This package contains:- local.py: Local process provider implementation- ssh.py: Remote SSH provider implementation- tenki.py: Tenki disposable microVM provider implementation+- ucloud_agent_sandbox.py: UCloud Agent Sandbox provider implementation"""from .base import SandboxProvider, SandboxInstance, ExecutionResult, SandboxProviderConfigError@@ -37,6 +38,7 @@ from .e2b import E2BProviderfrom .local import LocalProviderfrom .ssh import SSHProviderfrom .tenki import TenkiProvider+from .ucloud_agent_sandbox import UCloudAgentSandboxProvider__all__ = ["SandboxProvider",@@ -50,4 +52,5 @@ __all__ = ["LocalProvider","SSHProvider","TenkiProvider",+ "UCloudAgentSandboxProvider",]diff --git a/agent/sandbox/providers/ucloud_agent_sandbox.py b/agent/sandbox/providers/ucloud_agent_sandbox.pynew file mode 100644index 0000000000..774c548764--- /dev/null+++ b/agent/sandbox/providers/ucloud_agent_sandbox.py@@ -0,0 +1,471 @@+#+# Copyright 2026 The InfiniFlow Authors. All Rights Reserved.+#+# Licensed under the Apache License, Version 2.0 (the "License");+# you may not use this file except in compliance with the License.+# You may obtain a copy of the License at+#+# http://www.apache.org/licenses/LICENSE-2.0+#+# Unless required by applicable law or agreed to in writing, software+# distributed under the License is distributed on an "AS IS" BASIS,+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.+# See the License for the specific language governing permissions and+# limitations under the License.+#++"""UCloud Agent Sandbox provider for remote code execution."""++from __future__ import annotations++import base64+import json+import logging+import mimetypes+import os+import posixpath+import shlex+import time+import uuid+from typing import Any++from agent.sandbox.result_protocol import build_javascript_wrapper, build_python_wrapper, extract_structured_result++from .base import ExecutionResult, SandboxInstance, SandboxProvider, SandboxProviderConfigError++logger = logging.getLogger(__name__)++ALLOWED_ARTIFACT_EXTENSIONS = {".csv", ".html", ".jpeg", ".jpg", ".json", ".pdf", ".png", ".svg"}+DEFAULT_REGION = "cn-wlcb"+DOMAIN_SUFFIX = "sandbox.ucloudai.com"+SANDBOX_HOME = "/home/user"+MAX_ARTIFACT_DEPTH = 16+++class UCloudAgentSandboxProvider(SandboxProvider):+ """Execute Python and JavaScript in disposable UCloud Agent Sandboxes."""++ def __init__(self):+ """Initialize the provider with safe defaults and no active instances."""+ self.api_key = ""+ self.region = DEFAULT_REGION+ self.domain = ""+ self.api_url = ""+ self.template = "base"+ self.allow_internet_access = False+ self.insecure_http = False+ self.timeout = 30+ self.sandbox_timeout = 300+ self.max_output_bytes = 1024 * 1024+ self.max_artifacts = 20+ self.max_artifact_bytes = 10 * 1024 * 1024+ self._initialized = False+ self._instances: dict[str, dict[str, Any]] = {}++ def initialize(self, config: dict[str, Any]) -> bool:+ """Validate and apply provider configuration.++ Args:+ config: Provider credentials, endpoint options, and execution limits.++ Returns:+ True when the provider is ready to create sandboxes.++ Raises:+ SandboxProviderConfigError: If the configuration or SDK is invalid.+ """+ self.api_key = str(config.get("api_key", "") or "").strip()+ self.region = str(config.get("region", DEFAULT_REGION) or DEFAULT_REGION).strip()+ self.domain = str(config.get("domain", "") or "").strip()+ self.api_url = str(config.get("api_url", "") or "").strip()+ self.template = str(config.get("template", "base") or "base").strip()+ self.allow_internet_access = bool(config.get("allow_internet_access", False))+ self.insecure_http = bool(config.get("insecure_http", False))+ self.timeout = int(config.get("timeout", 30) or 30)+ self.sandbox_timeout = int(config.get("sandbox_timeout", 300) or 300)+ self.max_output_bytes = int(config.get("max_output_bytes", 1024 * 1024) or 1024 * 1024)+ self.max_artifacts = int(config.get("max_artifacts", 20) or 20)+ self.max_artifact_bytes = int(config.get("max_artifact_bytes", 10 * 1024 * 1024) or 10 * 1024 * 1024)++ is_valid, error_message = self.validate_config(config | {"api_key": self.api_key})+ if not is_valid:+ raise SandboxProviderConfigError(error_message or "Invalid UCloud Agent Sandbox configuration.")++ _get_ucloud_sandbox_module()+ self._initialized = True+ logger.info("UCloud Agent Sandbox provider initialized")+ return True++ def create_instance(self, template: str = "python") -> SandboxInstance:+ """Create a disposable sandbox and its isolated execution workspace.++ Args:+ template: Requested language identifier used to validate the runtime.++ Returns:+ A RAGFlow sandbox instance handle.+ """+ if not self._initialized:+ raise RuntimeError("Provider not initialized. Call initialize() first.")++ language = self._normalize_language(template)+ if language not in {"python", "nodejs"}:+ raise RuntimeError(f"Unsupported language for UCloud Agent Sandbox provider: {template}")++ sdk = _get_ucloud_sandbox_module()+ try:+ sandbox = sdk.Sandbox.create(+ template=self.template,+ timeout=self.sandbox_timeout,+ metadata={"source": "ragflow"},+ secure=True,+ allow_internet_access=self.allow_internet_access,+ **self._api_options(),+ )+ except sdk.AuthenticationException as exc:+ raise SandboxProviderConfigError("UCloud Agent Sandbox authentication failed: check the API key.") from exc+ except sdk.RateLimitException as exc:+ raise RuntimeError(f"UCloud Agent Sandbox rate limited, please retry: {exc}") from exc+ except sdk.TimeoutException as exc:+ raise TimeoutError("Timed out while creating a UCloud Agent Sandbox.") from exc+ except Exception as exc:+ raise RuntimeError(f"Failed to create UCloud Agent Sandbox: {exc}") from exc++ remote_work_dir = posixpath.join(SANDBOX_HOME, f"ragflow-codeexec-{uuid.uuid4().hex}")+ try:+ sandbox.commands.run(+ f"mkdir -p {shlex.quote(posixpath.join(remote_work_dir, 'artifacts'))}",+ timeout=min(self.timeout, 10),+ request_timeout=self.timeout,+ )+ except Exception:+ self._safe_kill(sandbox)+ raise++ instance_id = str(uuid.uuid4())+ self._instances[instance_id] = {"sandbox": sandbox, "remote_work_dir": remote_work_dir, "language": language}+ return SandboxInstance(+ instance_id=instance_id,+ provider="ucloud_agent_sandbox",+ status="running",+ metadata={+ "language": language,+ "remote_work_dir": remote_work_dir,+ "sandbox_id": sandbox.sandbox_id,+ "template": self.template,+ },+ )++ def execute_code(+ self,+ instance_id: str,+ code: str,+ language: str,+ timeout: int = 10,+ arguments: dict[str, Any] | None = None,+ ) -> ExecutionResult:+ """Execute wrapped code in an existing UCloud sandbox.++ Args:+ instance_id: RAGFlow instance identifier returned by create_instance.+ code: User-provided source code defining a main function.+ language: Python or JavaScript language identifier.+ timeout: Maximum execution duration in seconds.+ arguments: Values passed to the user-defined main function.++ Returns:+ Captured output, structured result metadata, and allowed artifacts.+ """+ if not self._initialized:+ raise RuntimeError("Provider not initialized. Call initialize() first.")+ if instance_id not in self._instances:+ raise RuntimeError(f"Unknown UCloud Agent Sandbox instance: {instance_id}")++ normalized_lang = self._normalize_language(language)+ instance = self._instances[instance_id]+ sandbox = instance["sandbox"]+ remote_work_dir: str = instance["remote_work_dir"]+ script_path, executable = self._prepare_script(sandbox, remote_work_dir, normalized_lang, code, arguments or {})++ requested_timeout = self.timeout if timeout is None else int(timeout)+ if requested_timeout <= 0:+ raise RuntimeError(f"Execution timeout must be greater than 0 seconds, got {requested_timeout}.")+ exec_timeout = min(requested_timeout, self.timeout)+ sdk = _get_ucloud_sandbox_module()++ start_time = time.time()+ try:+ sandbox.set_timeout(max(self.sandbox_timeout, exec_timeout + 30), request_timeout=self.timeout)+ result = sandbox.commands.run(+ f"{executable} {shlex.quote(script_path)}",+ cwd=remote_work_dir,+ timeout=exec_timeout,+ request_timeout=max(self.timeout, exec_timeout),+ )+ except sdk.CommandExitException as exc:+ result = exc+ except sdk.TimeoutException as exc:+ raise TimeoutError(f"Execution timed out after {exec_timeout} seconds") from exc+ except Exception as exc:+ raise RuntimeError(f"UCloud Agent Sandbox execution failed: {exc}") from exc+ execution_time = time.time() - start_time++ stdout = result.stdout or ""+ stderr = result.stderr or ""+ exit_code = int(result.exit_code)+ self._validate_output_size(stdout, stderr)+ stdout, structured_result = extract_structured_result(stdout)++ return ExecutionResult(+ stdout=stdout,+ stderr=stderr,+ exit_code=exit_code,+ execution_time=execution_time,+ metadata={+ "instance_id": instance_id,+ "sandbox_id": sandbox.sandbox_id,+ "language": normalized_lang,+ "script_path": script_path,+ "remote_work_dir": remote_work_dir,+ "status": "ok" if exit_code == 0 else "error",+ "timeout": exec_timeout,+ "artifacts": self._collect_artifacts(sandbox, posixpath.join(remote_work_dir, "artifacts")),+ "result_present": structured_result.get("present", False),+ "result_value": structured_result.get("value"),+ "result_type": structured_result.get("type"),+ },+ )++ def destroy_instance(self, instance_id: str) -> bool:+ """Destroy a sandbox instance if it is still tracked by the provider."""+ if not self._initialized:+ raise RuntimeError("Provider not initialized. Call initialize() first.")+ instance = self._instances.pop(instance_id, None)+ if instance is None:+ return True+ self._safe_kill(instance["sandbox"])+ return True++ def health_check(self) -> bool:+ """Return whether the provider is initialized with an API key."""+ return self._initialized and bool(self.api_key)++ def get_supported_languages(self) -> list[str]:+ """Return the language identifiers accepted by this provider."""+ return ["python", "javascript"]++ @staticmethod+ def get_config_schema() -> dict[str, dict]:+ """Return the Admin UI configuration schema for this provider."""+ return {+ "api_key": {+ "type": "string",+ "required": True,+ "label": "API Key",+ "secret": True,+ "description": "UCloud Agent Sandbox API key.",+ },+ "region": {+ "type": "string",+ "required": False,+ "label": "Region",+ "default": DEFAULT_REGION,+ "description": "UCloud Agent Sandbox region, for example cn-wlcb or us-ca.",+ },+ "domain": {+ "type": "string",+ "required": False,+ "label": "Domain",+ "description": "Override the sandbox domain. Leave empty to derive it from Region.",+ },+ "api_url": {+ "type": "string",+ "required": False,+ "label": "API URL",+ "description": "Override the UCloud Agent Sandbox control-plane API URL.",+ },+ "template": {+ "type": "string",+ "required": False,+ "label": "Template",+ "default": "base",+ "description": "Sandbox template. The base template includes Python and Node.js.",+ },+ "allow_internet_access": {+ "type": "boolean",+ "required": False,+ "label": "Allow Internet Access",+ "default": False,+ "description": "Allow sandboxed code to access the internet. Disabled by default.",+ },+ "insecure_http": {+ "type": "boolean",+ "required": False,+ "label": "Use Insecure HTTP",+ "default": False,+ "description": "Use HTTP instead of HTTPS. Enable only for trusted private deployments.",+ },+ "timeout": {+ "type": "integer",+ "required": False,+ "label": "Execution Timeout (seconds)",+ "default": 30,+ "min": 1,+ "max": 600,+ },+ "sandbox_timeout": {+ "type": "integer",+ "required": False,+ "label": "Sandbox Lifetime (seconds)",+ "default": 300,+ "min": 60,+ "max": 86400,+ },+ "max_output_bytes": {+ "type": "integer",+ "required": False,+ "label": "Max Output Bytes",+ "default": 1048576,+ "min": 1024,+ "max": 10485760,+ },+ "max_artifacts": {+ "type": "integer",+ "required": False,+ "label": "Max Artifacts",+ "default": 20,+ "min": 0,+ "max": 100,+ },+ "max_artifact_bytes": {+ "type": "integer",+ "required": False,+ "label": "Max Artifact Bytes",+ "default": 10485760,+ "min": 1024,+ "max": 104857600,+ },+ }++ def validate_config(self, config: dict[str, Any]) -> tuple[bool, str | None]:+ """Validate required credentials and numeric execution limits."""+ if not str(config.get("api_key", "") or "").strip():+ return False, "UCloud Agent Sandbox API key is required"+ if not str(config.get("template", "base") or "").strip():+ return False, "template is required"+ for key in ("timeout", "sandbox_timeout", "max_output_bytes", "max_artifact_bytes"):+ try:+ value = int(config.get(key, self.get_config_schema()[key]["default"]) or 0)+ except (TypeError, ValueError):+ return False, f"{key} must be an integer"+ if value <= 0:+ return False, f"{key} must be greater than 0"+ try:+ max_artifacts = int(config.get("max_artifacts", 20) or 0)+ except (TypeError, ValueError):+ return False, "max_artifacts must be an integer"+ if max_artifacts < 0:+ return False, "max_artifacts must be greater than or equal to 0"+ return True, None++ def _api_options(self) -> dict[str, Any]:+ """Build keyword arguments shared by UCloud SDK API calls."""+ options: dict[str, Any] = {+ "api_key": self.api_key,+ "domain": self.domain or f"{self.region}.{DOMAIN_SUFFIX}",+ "insecure_http": self.insecure_http,+ "request_timeout": float(self.timeout),+ "integration": "ragflow",+ }+ if self.api_url:+ options["api_url"] = self.api_url+ return options++ def _prepare_script(self, sandbox, remote_work_dir: str, language: str, code: str, arguments: dict[str, Any]) -> tuple[str, str]:+ """Wrap user code, upload it, and return its path and executable."""+ args_json = json.dumps(arguments, ensure_ascii=False)+ if language == "python":+ script_name = "main.py"+ script_content = build_python_wrapper(code, args_json)+ executable = "python3"+ elif language == "nodejs":+ script_name = "main.js"+ script_content = build_javascript_wrapper(code, args_json)+ executable = "node"+ else:+ raise RuntimeError(f"Unsupported language for UCloud Agent Sandbox provider: {language}")+ script_path = posixpath.join(remote_work_dir, script_name)+ sandbox.files.write(script_path, script_content, request_timeout=self.timeout)+ return script_path, executable++ def _validate_output_size(self, stdout: str, stderr: str) -> None:+ """Reject combined standard output that exceeds the configured limit."""+ output_size = len(stdout.encode("utf-8")) + len(stderr.encode("utf-8"))+ if output_size > self.max_output_bytes:+ raise RuntimeError(f"UCloud Agent Sandbox execution output exceeded {self.max_output_bytes} bytes.")++ def _collect_artifacts(self, sandbox, artifacts_dir: str) -> list[dict[str, Any]]:+ """Collect allowed files from the execution artifact directory."""+ artifacts: list[dict[str, Any]] = []+ self._collect_artifacts_recursive(sandbox, artifacts_dir, "", artifacts, depth=0)+ return artifacts++ def _collect_artifacts_recursive(self, sandbox, current_dir: str, relative_dir: str, artifacts: list[dict[str, Any]], depth: int) -> None:+ """Traverse artifact directories while enforcing type, size, and depth limits."""+ if depth > MAX_ARTIFACT_DEPTH:+ raise RuntimeError(f"Artifact directory nesting exceeds {MAX_ARTIFACT_DEPTH} levels: {relative_dir}")+ sdk = _get_ucloud_sandbox_module()+ try:+ entries = sandbox.files.list(current_dir, depth=1, request_timeout=self.timeout)+ except sdk.FileNotFoundException:+ return+ for entry in sorted(entries, key=lambda item: item.path):+ name = posixpath.basename(entry.path)+ relative_path = posixpath.join(relative_dir, name) if relative_dir else name+ if entry.symlink_target is not None:+ raise RuntimeError(f"Artifact symlinks are not allowed: {relative_path}")+ if entry.type == sdk.FileType.DIR:+ self._collect_artifacts_recursive(sandbox, entry.path, relative_path, artifacts, depth + 1)+ continue+ if len(artifacts) >= self.max_artifacts:+ raise RuntimeError(f"UCloud Agent Sandbox execution produced more than {self.max_artifacts} artifacts.")+ if entry.size > self.max_artifact_bytes:+ raise RuntimeError(f"Artifact exceeds {self.max_artifact_bytes} bytes: {relative_path}")+ extension = os.path.splitext(name)[1].lower()+ if extension not in ALLOWED_ARTIFACT_EXTENSIONS:+ raise RuntimeError(f"Unsupported artifact type: {relative_path}")+ content = bytes(sandbox.files.read(entry.path, format="bytes", request_timeout=self.timeout))+ artifacts.append(+ {+ "name": relative_path,+ "content_b64": base64.b64encode(content).decode("ascii"),+ "mime_type": mimetypes.guess_type(name)[0] or "application/octet-stream",+ "size": entry.size,+ }+ )++ def _safe_kill(self, sandbox) -> None:+ """Best-effort terminate a remote sandbox during cleanup."""+ try:+ sandbox.kill(request_timeout=self.timeout)+ except Exception as exc: # noqa: BLE001 - cleanup is deliberately best-effort+ logger.warning("Failed to kill UCloud Agent Sandbox %s: %s", sandbox.sandbox_id, exc)++ @staticmethod+ def _normalize_language(language: str) -> str:+ """Normalize supported language aliases to provider runtime names."""+ value = (language or "python").lower()+ if value in {"python", "python3"}:+ return "python"+ if value in {"javascript", "js", "node", "nodejs"}:+ return "nodejs"+ return value+++def _get_ucloud_sandbox_module():+ """Import and return the UCloud SDK with a provider-specific error."""+ try:+ import ucloud_sandbox+ except ImportError as exc:+ raise SandboxProviderConfigError("ucloud-sandbox is required for the UCloud Agent Sandbox provider.") from exc+ return ucloud_sandboxdiff --git a/conf/system_settings.json b/conf/system_settings.jsonindex f123e4508d..78d154b0bd 100644--- a/conf/system_settings.json+++ b/conf/system_settings.json@@ -83,6 +83,12 @@"source": "variable","data_type": "json","value": "{}"+ },+ {+ "name": "sandbox.ucloud_agent_sandbox",+ "source": "variable",+ "data_type": "json",+ "value": "{}"}]}diff --git a/docs/administrator/admin/admin_ui/configure_code_execution_sandbox.md b/docs/administrator/admin/admin_ui/configure_code_execution_sandbox.mdindex be0c3514f6..2ab1394f57 100644--- a/docs/administrator/admin/admin_ui/configure_code_execution_sandbox.md+++ b/docs/administrator/admin/admin_ui/configure_code_execution_sandbox.md@@ -19,6 +19,7 @@ The current page supports the following `Provider` options:| `SSH` | Execute code on a remote machine through SSH. || `AliyunCodeInterpreter` | Use Alibaba Cloud Function Compute Code Interpreter. || `E2B` | Use E2B Cloud Code Execution Sandboxes. |+| `UCloud Agent Sandbox` | Run code in disposable UCloud cloud sandboxes. |After selecting a `Provider`, the page displays the corresponding configuration area.@@ -33,6 +34,7 @@ After selecting a `Provider`, the page displays the corresponding configuration| `SSH` | Existing independent execution servers | Executes code on a remote host through SSH. | Suitable for reusing existing servers or custom runtime environments. || `AliyunCodeInterpreter` | Alibaba Cloud-related services | Uses a cloud service to provide the code execution environment, making elastic scaling easier. | Suitable for organizations already using the corresponding cloud service. || `E2B` | Fast access to a cloud sandbox | Executes code in an isolated environment provided by E2B. | Suitable for scenarios that need quick use without deployment. |+| `UCloud Agent Sandbox` | UCloud-hosted agent workloads | Creates a disposable sandbox from a template containing Python and Node.js. | Suitable for teams using UCloud or needing managed sandboxes in China or North America. |## Test and Save Configuration@@ -152,3 +154,29 @@ Alibaba Cloud `CodeInterpreter` configuration connects to Alibaba Cloud CodeInte| `API Key` | API key provided by E2B Cloud for authentication. | Log in to the E2B platform, create the corresponding API key, and enter it. || `Region` | Region where the E2B service is located. | Enter the actual region, such as `us`. || `Request Timeout (seconds)` | Timeout for requests to the E2B service. | The default is 30 seconds. Increase it if the network is slow or execution takes longer. |++## UCloud Agent Sandbox Configuration++`UCloud Agent Sandbox` creates a fresh cloud sandbox for each code execution and destroys it when execution finishes. RAGFlow uses UCloud's native SDK and supports Python and JavaScript with the built-in `base` template.++1. Obtain an API key from [UCloud ModelVerse API Keys](https://astraflow.ucloud.cn/modelverse/api-keys).+2. Go to **UCloud Agent Sandbox Configuration**.+3. Enter the API key and select the desired region.+4. Click **Test connection**, then click **Save** after the test succeeds.++| Parameter | Description | Recommendation |+| --- | --- | --- |+| `API Key` | UCloud Agent Sandbox API key used for authentication. | Keep it secret and rotate it according to your organization's credential policy. |+| `Region` | Sandbox region. Supported values include `cn-wlcb` and `us-ca`. | Keep `cn-wlcb` unless workloads should run in North America. |+| `Domain` | Optional sandbox domain override. | Leave empty to derive `<region>.sandbox.ucloudai.com` from `Region`. |+| `API URL` | Optional control-plane endpoint override. | Leave empty for the public service endpoint. |+| `Template` | UCloud sandbox template. | Use `base`, which includes both Python and Node.js. |+| `Allow Internet Access` | Allows executed code to make outbound network requests. | Disabled by default. Enable only when the code needs external services or package downloads. |+| `Use Insecure HTTP` | Uses HTTP rather than HTTPS. | Keep disabled except in a trusted private test deployment. |+| `Execution Timeout` | Maximum duration of one code execution. | The default is 30 seconds. |+| `Sandbox Lifetime` | Maximum lifetime of the disposable sandbox. | The default is 300 seconds and is extended when needed for an allowed execution. |+| Output and artifact limits | Bound console output and files returned from `artifacts/`. | Keep the defaults unless the workload has a known need for larger results. |++Files written under the execution workspace's `artifacts/` directory are returned to RAGFlow. Supported artifact extensions are `.csv`, `.html`, `.jpeg`, `.jpg`, `.json`, `.pdf`, `.png`, and `.svg`.++See the [UCloud Agent Sandbox prerequisites](https://astraflow.ucloud.cn/docs/agent-sandbox/product/prerequisites) and [region documentation](https://astraflow.ucloud.cn/docs/agent-sandbox/product/region) for service-side details.diff --git a/docs/guides/agent/agent_quickstarts/sandbox_quickstart.md b/docs/guides/agent/agent_quickstarts/sandbox_quickstart.mdindex d286cd0b61..6258989ed0 100644--- a/docs/guides/agent/agent_quickstarts/sandbox_quickstart.md+++ b/docs/guides/agent/agent_quickstarts/sandbox_quickstart.md@@ -26,7 +26,7 @@ Configure sandbox providers from the admin page:- `self_managed`: Uses the executor manager service.- `local`: Runs code on the current machine.- `ssh`: Runs code on a remote machine over SSH.-- `aliyun_codeinterpreter`, `e2b`, and `tenki`: Cloud providers.+- `aliyun_codeinterpreter`, `e2b`, `tenki`, and `ucloud_agent_sandbox`: Cloud providers.## Provider Options@@ -40,6 +40,7 @@ Admin > Sandbox Settings after the services are up.- `ssh`: Runs code on a remote machine over SSH.- `aliyun_codeinterpreter` and `e2b`: Cloud-hosted providers that remain available in the admin provider list.- `tenki`: Cloud-hosted provider that runs each execution in a disposable [Tenki](https://tenki.cloud) microVM. See [Tenki](#tenki) below.+- `ucloud_agent_sandbox`: Cloud-hosted provider that runs each execution in a disposable [UCloud Agent Sandbox](https://astraflow.ucloud.cn/docs/agent-sandbox). See [UCloud Agent Sandbox](#ucloud-agent-sandbox) below.### Tenki@@ -65,6 +66,28 @@ Notes:- Files written to the `artifacts/` directory of the working directory are returned as run artifacts.- The provider uses only Tenki's create/exec/destroy operations; it does not use volumes or snapshots.+### UCloud Agent Sandbox++`ucloud_agent_sandbox` uses UCloud's native Sandbox SDK to create one disposable sandbox for each CodeExec run. No local sandbox service or Docker runtime is required.++Configure it in **Admin > Sandbox Settings**:++- `api_key` (required): obtain one from [UCloud ModelVerse API Keys](https://astraflow.ucloud.cn/modelverse/api-keys).+- `region`: defaults to `cn-wlcb`; `us-ca` is also supported.+- `domain` and `api_url`: optional endpoint overrides for private or custom deployments.+- `template`: defaults to `base`, which includes Python and Node.js runtimes.+- `allow_internet_access`: defaults to `false`; enable it only when sandboxed code needs outbound network access.+- `timeout`, `sandbox_timeout`, and the output/artifact limits can be tuned for the workload.++Notes:++- Supported languages are Python and JavaScript.+- RAGFlow uses HTTPS with TLS certificate verification. The `insecure_http` option is intended only for trusted test deployments.+- Files written to the execution workspace's `artifacts/` directory are returned as run artifacts.+- The Python runtime dependency is installed with RAGFlow. The Go runtime uses UCloud's native Go SDK.++See [UCloud Agent Sandbox prerequisites](https://astraflow.ucloud.cn/docs/agent-sandbox/product/prerequisites) and [regions](https://astraflow.ucloud.cn/docs/agent-sandbox/product/region).+## Prerequisites- Linux distribution compatible with gVisor.diff --git a/go.mod b/go.modindex ac7bcf1e06..795e1bf498 100644--- a/go.mod+++ b/go.mod@@ -51,6 +51,7 @@ require (github.com/signintech/gopdf v0.36.1github.com/siongui/gojianfan v0.0.0-20210926212422-2f175ac615degithub.com/spf13/viper v1.18.2+ github.com/ucloud/ucloud-sandbox-sdk-go v0.0.0-20260807065450-08464aef9ed5github.com/xuri/excelize/v2 v2.11.0github.com/yfedoseev/office_oxide/go v0.1.8github.com/yfedoseev/pdf_oxide/go v0.3.67diff --git a/go.sum b/go.sumindex 15246d8c7b..355378b132 100644--- a/go.sum+++ b/go.sum@@ -510,6 +510,8 @@ github.com/tjfoc/gmsm v1.4.1 h1:aMe1GlZb+0bLjn+cKTPEvvn9oUEBlJitaZiiBwsbgho=github.com/tjfoc/gmsm v1.4.1/go.mod h1:j4INPkHWMrhJb38G+J6W4Tw0AbuN8Thu3PbdVYhVcTE=github.com/twitchyliquid64/golang-asm v0.15.1 h1:SU5vSMR7hnwNxj24w34ZyCi/FmDZTkS4MhqMhdFk5YI=github.com/twitchyliquid64/golang-asm v0.15.1/go.mod h1:a1lVb/DtPvCB8fslRZhAngC2+aY1QWCk3Cedj/Gdt08=+github.com/ucloud/ucloud-sandbox-sdk-go v0.0.0-20260807065450-08464aef9ed5 h1:okVowRVpknqiBSurlOrG3YIqp5j4VxXtdS938XVAiWY=+github.com/ucloud/ucloud-sandbox-sdk-go v0.0.0-20260807065450-08464aef9ed5/go.mod h1:097WABFNud50hH2KImyZ8WOJeb0lM2A4+gLvQ1kllsc=github.com/ugorji/go/codec v1.3.1 h1:waO7eEiFDwidsBN6agj1vJQ4AG7lh2yqXyOXqhgQuyY=github.com/ugorji/go/codec v1.3.1/go.mod h1:pRBVtBSKl77K30Bv8R2P+cLSGaTtex6fsA2Wjqmfxj4=github.com/wk8/go-ordered-map/v2 v2.1.8 h1:5h/BUHu93oj4gIdvHHHGsScSTMijfx5PeYkE/fJgbpc=diff --git a/internal/agent/sandbox/manager.go b/internal/agent/sandbox/manager.goindex dbdb8859c5..86adf2f6bd 100644--- a/internal/agent/sandbox/manager.go+++ b/internal/agent/sandbox/manager.go@@ -24,7 +24,7 @@// Go port reads this via `internal/dao.SystemSettingsDAO`.// 2. SANDBOX_PROVIDER_TYPE env var — defaults to "self_managed".// 3. SANDBOX_EXECUTOR_MANAGER_URL / AGENTRUN_* / LOCAL_* / SSH_*-// / E2B_* env vars for the per-provider knobs. The+// / E2B_* / UCLOUD_SANDBOX_* env vars for the per-provider knobs. The// `xxxConfigFromEnv` helpers in each provider file build the// same config map the admin-panel JSON would, so the// `FromConfig` constructor is the single source of truth.@@ -301,8 +301,10 @@ func buildProvider(t ProviderType) (SandboxProvider, error) {return newSSHProviderFromEnv(), nilcase ProviderTenki:return newTenkiProviderFromEnv(), nil+ case ProviderUCloudAgentSandbox:+ return newUCloudAgentSandboxProviderFromEnv(), nildefault:- return nil, fmt.Errorf("unknown provider type %q (known: self_managed, aliyun_codeinterpreter, e2b, local, ssh, tenki)", t)+ return nil, fmt.Errorf("unknown provider type %q (known: self_managed, aliyun_codeinterpreter, e2b, local, ssh, tenki, ucloud_agent_sandbox)", t)}}@@ -324,7 +326,9 @@ func buildProviderFromConfig(t ProviderType, cfg map[string]any) (SandboxProvidereturn newSSHProviderFromConfig(cfg), nilcase ProviderTenki:return newTenkiProviderFromConfig(cfg), nil+ case ProviderUCloudAgentSandbox:+ return newUCloudAgentSandboxProviderFromConfig(cfg), nildefault:- return nil, fmt.Errorf("unknown provider type %q (known: self_managed, aliyun_codeinterpreter, e2b, local, ssh, tenki)", t)+ return nil, fmt.Errorf("unknown provider type %q (known: self_managed, aliyun_codeinterpreter, e2b, local, ssh, tenki, ucloud_agent_sandbox)", t)}}diff --git a/internal/agent/sandbox/manager_test.go b/internal/agent/sandbox/manager_test.goindex 2f4200a9e6..0910c955e9 100644--- a/internal/agent/sandbox/manager_test.go+++ b/internal/agent/sandbox/manager_test.go@@ -80,7 +80,7 @@ func (s *stubProvider) SupportedLanguages() []stringfunc TestProviderManager_BuildProvider_KnownTypes(t *testing.T) {t.Parallel()- for _, ptype := range []ProviderType{ProviderSelfManaged, ProviderAliyun, ProviderE2B, ProviderLocal, ProviderSSH} {+ for _, ptype := range []ProviderType{ProviderSelfManaged, ProviderAliyun, ProviderE2B, ProviderLocal, ProviderSSH, ProviderUCloudAgentSandbox} {t.Run(string(ptype), func(t *testing.T) {p, err := buildProvider(ptype)if err != nil {diff --git a/internal/agent/sandbox/provider.go b/internal/agent/sandbox/provider.goindex e14204bd1a..e8d275f4dc 100644--- a/internal/agent/sandbox/provider.go+++ b/internal/agent/sandbox/provider.go@@ -69,6 +69,10 @@ const (// ProviderTenki runs each execution in a disposable Tenki// microVM (TenkiCloud Go SDK). Matches Python's TenkiProvider.ProviderTenki ProviderType = "tenki"++ // ProviderUCloudAgentSandbox runs each execution in a disposable+ // UCloud Agent Sandbox using UCloud's native Go SDK.+ ProviderUCloudAgentSandbox ProviderType = "ucloud_agent_sandbox")// ErrE2BProviderNotImplemented is returned when an operator configuresdiff --git a/internal/agent/sandbox/ucloud_agent_sandbox.go b/internal/agent/sandbox/ucloud_agent_sandbox.gonew file mode 100644index 0000000000..1f593ea119--- /dev/null+++ b/internal/agent/sandbox/ucloud_agent_sandbox.go@@ -0,0 +1,400 @@+//+// Copyright 2026 The InfiniFlow Authors. All Rights Reserved.+//+// Licensed under the Apache License, Version 2.0 (the "License");+// you may not use this file except in compliance with the License.+// You may obtain a copy of the License at+//+// http://www.apache.org/licenses/LICENSE-2.0+//+// Unless required by applicable law or agreed to in writing, software+// distributed under the License is distributed on an "AS IS" BASIS,+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.+// See the License for the specific language governing permissions and+// limitations under the License.+//++package sandbox++import (+ "context"+ "encoding/base64"+ "errors"+ "fmt"+ "mime"+ "path"+ "ragflow/internal/common"+ "sort"+ "strings"+ "sync"+ "time"++ "github.com/google/uuid"+ ucloudsdk "github.com/ucloud/ucloud-sandbox-sdk-go"+)++const (+ ucloudAgentSandboxDefaultRegion = "cn-wlcb"+ ucloudAgentSandboxDomainSuffix = "sandbox.ucloudai.com"+ ucloudAgentSandboxDefaultTemplate = "base"+ ucloudAgentSandboxHome = "/home/user"+ ucloudAgentSandboxMaxArtifactDepth = 16+ ucloudAgentSandboxDefaultTimeout = 30+ ucloudAgentSandboxDefaultLifetime = 300+ ucloudAgentSandboxDefaultMaxOutputBytes = 1024 * 1024+ ucloudAgentSandboxDefaultMaxArtifacts = 20+ ucloudAgentSandboxDefaultMaxArtifactSize = 10 * 1024 * 1024+)++type ucloudAgentSandboxInstance struct {+ sandbox *ucloudsdk.Sandbox+ remoteWorkDir string+}++// UCloudAgentSandboxProvider executes code in disposable UCloud Agent Sandboxes.+type UCloudAgentSandboxProvider struct {+ client *ucloudsdk.Client+ apiKey string+ region string+ domain string+ apiURL string+ template string+ allowInternetAccess bool+ insecureHTTP bool+ timeoutSec int+ sandboxTimeoutSec int+ maxOutputBytes int+ maxArtifacts int+ maxArtifactBytes int++ mu sync.RWMutex+ initialized bool+ instances map[string]*ucloudAgentSandboxInstance+}++func newUCloudAgentSandboxProviderFromEnv() *UCloudAgentSandboxProvider {+ return newUCloudAgentSandboxProviderFromConfig(ucloudAgentSandboxConfigFromEnv())+}++func ucloudAgentSandboxConfigFromEnv() map[string]any {+ return map[string]any{+ "api_key": common.GetEnv(common.EnvUCloudSandboxAPIKey),+ "region": common.GetEnv(common.EnvUCloudSandboxRegion),+ "domain": common.GetEnv(common.EnvUCloudSandboxDomain),+ "api_url": common.GetEnv(common.EnvUCloudSandboxAPIURL),+ "template": common.GetEnv(common.EnvUCloudSandboxTemplate),+ "allow_internet_access": common.GetEnv(common.EnvUCloudSandboxAllowInternetAccess),+ "insecure_http": common.GetEnv(common.EnvUCloudSandboxInsecureHTTP),+ "timeout": common.GetEnv(common.EnvUCloudSandboxExecutionTimeout),+ "sandbox_timeout": common.GetEnv(common.EnvUCloudSandboxTimeout),+ "max_output_bytes": common.GetEnv(common.EnvUCloudSandboxMaxOutputBytes),+ "max_artifacts": common.GetEnv(common.EnvUCloudSandboxMaxArtifacts),+ "max_artifact_bytes": common.GetEnv(common.EnvUCloudSandboxMaxArtifactBytes),+ }+}++func newUCloudAgentSandboxProviderFromConfig(cfg map[string]any) *UCloudAgentSandboxProvider {+ region := strings.TrimSpace(configString(cfg, "region"))+ if region == "" {+ region = ucloudAgentSandboxDefaultRegion+ }+ template := strings.TrimSpace(configString(cfg, "template"))+ if template == "" {+ template = ucloudAgentSandboxDefaultTemplate+ }+ return &UCloudAgentSandboxProvider{+ apiKey: strings.TrimSpace(configString(cfg, "api_key")),+ region: region,+ domain: strings.TrimSpace(configString(cfg, "domain")),+ apiURL: strings.TrimSpace(configString(cfg, "api_url")),+ template: template,+ allowInternetAccess: strings.EqualFold(configString(cfg, "allow_internet_access"), "true"),+ insecureHTTP: strings.EqualFold(configString(cfg, "insecure_http"), "true"),+ timeoutSec: configInt(cfg, "timeout", ucloudAgentSandboxDefaultTimeout),+ sandboxTimeoutSec: configInt(cfg, "sandbox_timeout", ucloudAgentSandboxDefaultLifetime),+ maxOutputBytes: configInt(cfg, "max_output_bytes", ucloudAgentSandboxDefaultMaxOutputBytes),+ maxArtifacts: configInt(cfg, "max_artifacts", ucloudAgentSandboxDefaultMaxArtifacts),+ maxArtifactBytes: configInt(cfg, "max_artifact_bytes", ucloudAgentSandboxDefaultMaxArtifactSize),+ instances: make(map[string]*ucloudAgentSandboxInstance),+ }+}++// ProviderType returns ProviderUCloudAgentSandbox.+func (p *UCloudAgentSandboxProvider) ProviderType() ProviderType {+ return ProviderUCloudAgentSandbox+}++// Initialize creates the UCloud SDK client. Connectivity is verified by the+// admin connection test, which creates and executes in a temporary sandbox.+func (p *UCloudAgentSandboxProvider) Initialize(context.Context) error {+ if p.apiKey == "" {+ return errors.New("ucloud agent sandbox: API key is required")+ }+ if p.timeoutSec <= 0 || p.sandboxTimeoutSec <= 0 || p.maxOutputBytes <= 0 || p.maxArtifactBytes <= 0 || p.maxArtifacts < 0 {+ return errors.New("ucloud agent sandbox: timeout and size limits must be positive, and max_artifacts must be non-negative")+ }+ domain := p.domain+ if domain == "" {+ domain = p.region + "." + ucloudAgentSandboxDomainSuffix+ }+ options := []ucloudsdk.ClientOption{+ ucloudsdk.WithRequestTimeout(time.Duration(p.timeoutSec) * time.Second),+ ucloudsdk.WithInsecureHTTP(p.insecureHTTP),+ // The SDK currently defaults to skipping TLS verification. RAGFlow+ // always opts into certificate verification.+ ucloudsdk.WithInsecureSkipTLS(false),+ }+ if p.apiURL != "" {+ options = append(options, ucloudsdk.WithAPIURL(p.apiURL))+ }+ p.client = ucloudsdk.NewClient(domain, p.apiKey, options...)+ p.mu.Lock()+ p.initialized = true+ p.mu.Unlock()+ return nil+}++// SupportedLanguages returns the runtimes included in UCloud's base template.+func (p *UCloudAgentSandboxProvider) SupportedLanguages() []string {+ return []string{"python", "javascript"}+}++// CreateInstance provisions a fresh UCloud Agent Sandbox.+func (p *UCloudAgentSandboxProvider) CreateInstance(ctx context.Context, template string) (*SandboxInstance, error) {+ if !p.isInitialized() {+ return nil, errors.New("ucloud agent sandbox: provider not initialized")+ }+ language := normalizeLanguage(template)+ if language == "" {+ return nil, fmt.Errorf("ucloud agent sandbox: unsupported language %q", template)+ }+ sbx, err := p.client.CreateSandbox(ctx,+ ucloudsdk.WithTemplate(p.template),+ ucloudsdk.WithTimeout(p.sandboxTimeoutSec),+ ucloudsdk.WithMetadata(map[string]string{"source": "ragflow"}),+ ucloudsdk.WithManageBy("ragflow"),+ ucloudsdk.WithSecure(true),+ ucloudsdk.WithAllowInternetAccess(p.allowInternetAccess),+ )+ if err != nil {+ return nil, fmt.Errorf("ucloud agent sandbox: create sandbox: %w", err)+ }+ remoteWorkDir := path.Join(ucloudAgentSandboxHome, "ragflow-codeexec-"+uuid.NewString())+ if _, err := sbx.Commands.Run(ctx, "mkdir -p "+shq(path.Join(remoteWorkDir, "artifacts")), ucloudsdk.WithCommandTimeout(minTimeout(p.timeoutSec, 10))); err != nil {+ _, _ = sbx.Kill(ctx)+ return nil, fmt.Errorf("ucloud agent sandbox: create workspace: %w", err)+ }+ p.mu.Lock()+ p.instances[sbx.ID] = &ucloudAgentSandboxInstance{sandbox: sbx, remoteWorkDir: remoteWorkDir}+ p.mu.Unlock()+ return &SandboxInstance{+ InstanceID: sbx.ID,+ Provider: ProviderUCloudAgentSandbox,+ Status: "running",+ Metadata: map[string]any{+ "language": language,+ "remote_work_dir": remoteWorkDir,+ "sandbox_id": sbx.ID,+ "template": p.template,+ },+ }, nil+}++// ExecuteCode writes the shared RAGFlow wrapper into the sandbox and runs it.+func (p *UCloudAgentSandboxProvider) ExecuteCode(+ ctx context.Context,+ inst *SandboxInstance,+ code, language string,+ timeoutSec int,+ args map[string]any,+) (*ExecutionResult, error) {+ if !p.isInitialized() {+ return nil, errors.New("ucloud agent sandbox: provider not initialized")+ }+ if inst == nil || inst.InstanceID == "" {+ return nil, errors.New("ucloud agent sandbox: instance id required")+ }+ p.mu.RLock()+ instance := p.instances[inst.InstanceID]+ p.mu.RUnlock()+ if instance == nil {+ return nil, fmt.Errorf("ucloud agent sandbox: unknown instance %q", inst.InstanceID)+ }+ normalizedLanguage := normalizeLanguage(language)+ if normalizedLanguage == "" {+ return nil, fmt.Errorf("ucloud agent sandbox: unsupported language %q", language)+ }+ executionTimeout, err := validateTimeout(timeoutSec)+ if err != nil {+ return nil, err+ }+ if executionTimeout == 0 || executionTimeout > p.timeoutSec {+ executionTimeout = p.timeoutSec+ }+ argsJSON, err := argsToJSON(args)+ if err != nil {+ return nil, err+ }++ var scriptName, scriptContent, executable string+ if normalizedLanguage == "python" {+ scriptName = "main.py"+ scriptContent = BuildPythonWrapper(code, argsJSON)+ executable = "python3"+ } else {+ scriptName = "main.js"+ scriptContent = BuildJavaScriptWrapper(code, argsJSON)+ executable = "node"+ }+ scriptPath := path.Join(instance.remoteWorkDir, scriptName)+ if _, err := instance.sandbox.Files.Write(ctx, scriptPath, scriptContent); err != nil {+ return nil, fmt.Errorf("ucloud agent sandbox: write script: %w", err)+ }+ if err := instance.sandbox.SetTimeout(ctx, max(p.sandboxTimeoutSec, executionTimeout+30)); err != nil {+ return nil, fmt.Errorf("ucloud agent sandbox: extend sandbox timeout: %w", err)+ }++ started := time.Now()+ commandResult, runErr := instance.sandbox.Commands.Run(+ ctx,+ executable+" "+shq(scriptPath),+ ucloudsdk.WithCwd(instance.remoteWorkDir),+ ucloudsdk.WithCommandTimeout(executionTimeout),+ )+ executionTime := time.Since(started).Seconds()+ if runErr != nil {+ var exitErr *ucloudsdk.CommandExitError+ if errors.As(runErr, &exitErr) {+ commandResult = &ucloudsdk.CommandResult{Stdout: exitErr.Stdout, Stderr: exitErr.Stderr, ExitCode: exitErr.ExitCode, Error: exitErr.Message}+ } else {+ var timeoutErr *ucloudsdk.TimeoutError+ if errors.As(runErr, &timeoutErr) || errors.Is(runErr, context.DeadlineExceeded) {+ return nil, fmt.Errorf("ucloud agent sandbox: execution timed out after %d seconds: %w", executionTimeout, runErr)+ }+ return nil, fmt.Errorf("ucloud agent sandbox: execute code: %w", runErr)+ }+ }+ if commandResult == nil {+ return nil, errors.New("ucloud agent sandbox: command returned no result")+ }+ if len(commandResult.Stdout)+len(commandResult.Stderr) > p.maxOutputBytes {+ return nil, fmt.Errorf("ucloud agent sandbox: execution output exceeded %d bytes", p.maxOutputBytes)+ }+ stdout, structured := ExtractStructuredResult(commandResult.Stdout)+ artifacts := make([]map[string]any, 0)+ if err := p.collectArtifacts(ctx, instance.sandbox, path.Join(instance.remoteWorkDir, "artifacts"), "", &artifacts, 0); err != nil {+ return nil, err+ }+ return &ExecutionResult{+ Stdout: stdout,+ Stderr: commandResult.Stderr,+ ExitCode: commandResult.ExitCode,+ ExecutionTime: executionTime,+ Metadata: map[string]any{+ "instance_id": inst.InstanceID,+ "sandbox_id": instance.sandbox.ID,+ "language": normalizedLanguage,+ "script_path": scriptPath,+ "remote_work_dir": instance.remoteWorkDir,+ "status": map[bool]string{true: "ok", false: "error"}[commandResult.ExitCode == 0],+ "timeout": executionTimeout,+ "artifacts": artifacts,+ "result_present": structured["present"],+ "result_value": structured["value"],+ "result_type": structured["type"],+ },+ }, nil+}++// DestroyInstance terminates the sandbox. A missing instance is already clean.+func (p *UCloudAgentSandboxProvider) DestroyInstance(ctx context.Context, inst *SandboxInstance) error {+ if !p.isInitialized() {+ return errors.New("ucloud agent sandbox: provider not initialized")+ }+ if inst == nil || inst.InstanceID == "" {+ return errors.New("ucloud agent sandbox: instance id required")+ }+ p.mu.Lock()+ instance := p.instances[inst.InstanceID]+ delete(p.instances, inst.InstanceID)+ p.mu.Unlock()+ if instance == nil {+ return nil+ }+ if _, err := instance.sandbox.Kill(ctx); err != nil {+ return fmt.Errorf("ucloud agent sandbox: kill sandbox: %w", err)+ }+ return nil+}++// HealthCheck reports whether the provider has a configured client.+func (p *UCloudAgentSandboxProvider) HealthCheck(context.Context) error {+ if !p.isInitialized() || p.client == nil {+ return errors.New("ucloud agent sandbox: provider not initialized")+ }+ return nil+}++func (p *UCloudAgentSandboxProvider) collectArtifacts(+ ctx context.Context,+ sbx *ucloudsdk.Sandbox,+ currentDir, relativeDir string,+ artifacts *[]map[string]any,+ depth int,+) error {+ if depth > ucloudAgentSandboxMaxArtifactDepth {+ return fmt.Errorf("ucloud agent sandbox: artifact directory nesting exceeds %d levels: %s", ucloudAgentSandboxMaxArtifactDepth, relativeDir)+ }+ entries, err := sbx.Files.List(ctx, currentDir, ucloudsdk.WithDepth(1))+ if err != nil {+ if errors.Is(err, ucloudsdk.ErrNotFound) {+ return nil+ }+ return fmt.Errorf("ucloud agent sandbox: list artifacts: %w", err)+ }+ sort.Slice(entries, func(i, j int) bool { return entries[i].Path < entries[j].Path })+ for _, entry := range entries {+ name := path.Base(entry.Path)+ relativePath := path.Join(relativeDir, name)+ if entry.SymlinkTarget != nil {+ return fmt.Errorf("ucloud agent sandbox: artifact symlinks are not allowed: %s", relativePath)+ }+ if entry.Type == ucloudsdk.EntryTypeDir {+ if err := p.collectArtifacts(ctx, sbx, entry.Path, relativePath, artifacts, depth+1); err != nil {+ return err+ }+ continue+ }+ if len(*artifacts) >= p.maxArtifacts {+ return fmt.Errorf("ucloud agent sandbox: execution produced more than %d artifacts", p.maxArtifacts)+ }+ if entry.Size > int64(p.maxArtifactBytes) {+ return fmt.Errorf("ucloud agent sandbox: artifact exceeds %d bytes: %s", p.maxArtifactBytes, relativePath)+ }+ extension := strings.ToLower(path.Ext(name))+ if _, allowed := allowedArtifactExts[extension]; !allowed {+ return fmt.Errorf("ucloud agent sandbox: unsupported artifact type: %s", relativePath)+ }+ content, err := sbx.Files.ReadBytes(ctx, entry.Path)+ if err != nil {+ return fmt.Errorf("ucloud agent sandbox: read artifact %s: %w", relativePath, err)+ }+ mimeType := mime.TypeByExtension(extension)+ if mimeType == "" {+ mimeType = "application/octet-stream"+ }+ *artifacts = append(*artifacts, map[string]any{+ "name": relativePath,+ "content_b64": base64.StdEncoding.EncodeToString(content),+ "mime_type": mimeType,+ "size": entry.Size,+ })+ }+ return nil+}++func (p *UCloudAgentSandboxProvider) isInitialized() bool {+ p.mu.RLock()+ defer p.mu.RUnlock()+ return p.initialized+}diff --git a/internal/agent/sandbox/ucloud_agent_sandbox_test.go b/internal/agent/sandbox/ucloud_agent_sandbox_test.gonew file mode 100644index 0000000000..97395ede4b--- /dev/null+++ b/internal/agent/sandbox/ucloud_agent_sandbox_test.go@@ -0,0 +1,269 @@+//+// Copyright 2026 The InfiniFlow Authors. All Rights Reserved.+//+// Licensed under the Apache License, Version 2.0 (the "License");+// you may not use this file except in compliance with the License.+// You may obtain a copy of the License at+//+// http://www.apache.org/licenses/LICENSE-2.0+//+// Unless required by applicable law or agreed to in writing, software+// distributed under the License is distributed on an "AS IS" BASIS,+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.+// See the License for the specific language governing permissions and+// limitations under the License.+//++package sandbox++import (+ "context"+ "strings"+ "testing"+)++func TestUCloudAgentSandboxProvider_ProviderTypeAndLanguages(t *testing.T) {+ t.Parallel()+ p := newUCloudAgentSandboxProviderFromConfig(map[string]any{})+ if p.ProviderType() != ProviderUCloudAgentSandbox {+ t.Errorf("ProviderType = %q, want %q", p.ProviderType(), ProviderUCloudAgentSandbox)+ }++ want := map[string]bool{"python": true, "javascript": true}+ got := map[string]bool{}+ for _, language := range p.SupportedLanguages() {+ if !want[language] {+ t.Errorf("unexpected language: %q", language)+ }+ got[language] = true+ }+ for language := range want {+ if !got[language] {+ t.Errorf("missing required language: %q", language)+ }+ }+}++func TestUCloudAgentSandboxProvider_Defaults(t *testing.T) {+ t.Parallel()+ p := newUCloudAgentSandboxProviderFromConfig(map[string]any{})++ if p.region != ucloudAgentSandboxDefaultRegion {+ t.Errorf("region = %q, want %q", p.region, ucloudAgentSandboxDefaultRegion)+ }+ if p.template != ucloudAgentSandboxDefaultTemplate {+ t.Errorf("template = %q, want %q", p.template, ucloudAgentSandboxDefaultTemplate)+ }+ if p.allowInternetAccess {+ t.Error("allowInternetAccess = true, want false by default")+ }+ if p.insecureHTTP {+ t.Error("insecureHTTP = true, want false by default")+ }+ if p.timeoutSec != ucloudAgentSandboxDefaultTimeout {+ t.Errorf("timeoutSec = %d, want %d", p.timeoutSec, ucloudAgentSandboxDefaultTimeout)+ }+ if p.sandboxTimeoutSec != ucloudAgentSandboxDefaultLifetime {+ t.Errorf("sandboxTimeoutSec = %d, want %d", p.sandboxTimeoutSec, ucloudAgentSandboxDefaultLifetime)+ }+ if p.maxOutputBytes != ucloudAgentSandboxDefaultMaxOutputBytes {+ t.Errorf("maxOutputBytes = %d, want %d", p.maxOutputBytes, ucloudAgentSandboxDefaultMaxOutputBytes)+ }+ if p.maxArtifacts != ucloudAgentSandboxDefaultMaxArtifacts {+ t.Errorf("maxArtifacts = %d, want %d", p.maxArtifacts, ucloudAgentSandboxDefaultMaxArtifacts)+ }+ if p.maxArtifactBytes != ucloudAgentSandboxDefaultMaxArtifactSize {+ t.Errorf("maxArtifactBytes = %d, want %d", p.maxArtifactBytes, ucloudAgentSandboxDefaultMaxArtifactSize)+ }+}++func TestUCloudAgentSandboxProvider_ConfigOverrides(t *testing.T) {+ t.Parallel()+ p := newUCloudAgentSandboxProviderFromConfig(map[string]any{+ "api_key": "ucloud-key",+ "region": "us-ca",+ "domain": "sandbox.example.com",+ "api_url": "https://api.example.com",+ "template": "custom-template",+ "allow_internet_access": true,+ "insecure_http": true,+ "timeout": float64(45),+ "sandbox_timeout": float64(600),+ "max_output_bytes": float64(2_000_000),+ "max_artifacts": float64(50),+ "max_artifact_bytes": float64(20_000_000),+ })++ if p.apiKey != "ucloud-key" {+ t.Errorf("apiKey = %q", p.apiKey)+ }+ if p.region != "us-ca" || p.domain != "sandbox.example.com" || p.apiURL != "https://api.example.com" {+ t.Errorf("endpoint config = region:%q domain:%q apiURL:%q", p.region, p.domain, p.apiURL)+ }+ if p.template != "custom-template" {+ t.Errorf("template = %q", p.template)+ }+ if !p.allowInternetAccess || !p.insecureHTTP {+ t.Errorf("boolean overrides not applied: internet=%v insecureHTTP=%v", p.allowInternetAccess, p.insecureHTTP)+ }+ if p.timeoutSec != 45 || p.sandboxTimeoutSec != 600 {+ t.Errorf("timeouts = execution:%d sandbox:%d", p.timeoutSec, p.sandboxTimeoutSec)+ }+ if p.maxOutputBytes != 2_000_000 || p.maxArtifacts != 50 || p.maxArtifactBytes != 20_000_000 {+ t.Errorf("limits = output:%d artifacts:%d artifactBytes:%d", p.maxOutputBytes, p.maxArtifacts, p.maxArtifactBytes)+ }+}++func TestUCloudAgentSandboxProvider_EnvOverrides(t *testing.T) {+ t.Setenv("UCLOUD_SANDBOX_API_KEY", "env-key")+ t.Setenv("UCLOUD_SANDBOX_REGION", "us-ca")+ t.Setenv("UCLOUD_SANDBOX_TEMPLATE", "env-template")+ t.Setenv("UCLOUD_SANDBOX_ALLOW_INTERNET_ACCESS", "true")+ t.Setenv("UCLOUD_SANDBOX_INSECURE_HTTP", "true")+ t.Setenv("UCLOUD_SANDBOX_EXECUTION_TIMEOUT", "60")+ t.Setenv("UCLOUD_SANDBOX_TIMEOUT", "900")+ t.Setenv("UCLOUD_SANDBOX_MAX_OUTPUT_BYTES", "2000")+ t.Setenv("UCLOUD_SANDBOX_MAX_ARTIFACTS", "4")+ t.Setenv("UCLOUD_SANDBOX_MAX_ARTIFACT_BYTES", "3000")++ p := newUCloudAgentSandboxProviderFromEnv()+ if p.apiKey != "env-key" || p.region != "us-ca" || p.template != "env-template" {+ t.Errorf("env string overrides not applied: key:%q region:%q template:%q", p.apiKey, p.region, p.template)+ }+ if !p.allowInternetAccess || !p.insecureHTTP {+ t.Errorf("env boolean overrides not applied: internet=%v insecureHTTP=%v", p.allowInternetAccess, p.insecureHTTP)+ }+ if p.timeoutSec != 60 || p.sandboxTimeoutSec != 900 {+ t.Errorf("env timeouts = execution:%d sandbox:%d", p.timeoutSec, p.sandboxTimeoutSec)+ }+ if p.maxOutputBytes != 2000 || p.maxArtifacts != 4 || p.maxArtifactBytes != 3000 {+ t.Errorf("env limits = output:%d artifacts:%d artifactBytes:%d", p.maxOutputBytes, p.maxArtifacts, p.maxArtifactBytes)+ }+}++func TestUCloudAgentSandboxProvider_Initialize(t *testing.T) {+ t.Parallel()++ t.Run("missing API key", func(t *testing.T) {+ p := newUCloudAgentSandboxProviderFromConfig(map[string]any{})+ err := p.Initialize(context.Background())+ if err == nil {+ t.Fatal("Initialize with no API key: got nil error, want one")+ }+ if !strings.Contains(err.Error(), "API key") {+ t.Errorf("err = %v, want to mention API key", err)+ }+ })++ t.Run("valid local configuration", func(t *testing.T) {+ p := newUCloudAgentSandboxProviderFromConfig(map[string]any{"api_key": "fake-key"})+ if err := p.Initialize(context.Background()); err != nil {+ t.Fatalf("Initialize: %v", err)+ }+ if !p.isInitialized() || p.client == nil {+ t.Error("provider did not retain an initialized SDK client")+ }+ if err := p.HealthCheck(context.Background()); err != nil {+ t.Errorf("HealthCheck after Initialize: %v", err)+ }+ })++ t.Run("invalid limits", func(t *testing.T) {+ p := newUCloudAgentSandboxProviderFromConfig(map[string]any{+ "api_key": "fake-key",+ "max_artifacts": -1,+ })+ if err := p.Initialize(context.Background()); err == nil {+ t.Fatal("Initialize with invalid limits: got nil error, want one")+ }+ })+}++func TestUCloudAgentSandboxProvider_AllOpsBeforeInit(t *testing.T) {+ t.Parallel()+ p := newUCloudAgentSandboxProviderFromConfig(map[string]any{})+ inst := &SandboxInstance{InstanceID: "x", Provider: ProviderUCloudAgentSandbox}++ if _, err := p.CreateInstance(context.Background(), "python"); err == nil {+ t.Error("CreateInstance before init: got nil error, want one")+ }+ if _, err := p.ExecuteCode(context.Background(), inst, "x", "python", 5, nil); err == nil {+ t.Error("ExecuteCode before init: got nil error, want one")+ }+ if err := p.DestroyInstance(context.Background(), inst); err == nil {+ t.Error("DestroyInstance before init: got nil error, want one")+ }+ if err := p.HealthCheck(context.Background()); err == nil {+ t.Error("HealthCheck before init: got nil error, want one")+ }+}++func TestUCloudAgentSandboxProvider_ExecuteCodeRejectsBadInputs(t *testing.T) {+ t.Parallel()+ p := newUCloudAgentSandboxProviderFromConfig(map[string]any{"api_key": "fake-key"})+ if err := p.Initialize(context.Background()); err != nil {+ t.Fatalf("Initialize: %v", err)+ }+ p.instances["x"] = &ucloudAgentSandboxInstance{}++ cases := []struct {+ name string+ inst *SandboxInstance+ lang string+ time int+ want string+ }{+ {name: "nil instance", inst: nil, lang: "python", time: 5, want: "instance id"},+ {name: "empty instance id", inst: &SandboxInstance{}, lang: "python", time: 5, want: "instance id"},+ {name: "unknown instance", inst: &SandboxInstance{InstanceID: "missing"}, lang: "python", time: 5, want: "unknown instance"},+ {name: "unsupported language", inst: &SandboxInstance{InstanceID: "x"}, lang: "ruby", time: 5, want: "unsupported language"},+ {name: "timeout too small", inst: &SandboxInstance{InstanceID: "x"}, lang: "python", time: 0, want: "timeout"},+ {name: "timeout too large", inst: &SandboxInstance{InstanceID: "x"}, lang: "python", time: 1000, want: "timeout"},+ }++ for _, tc := range cases {+ t.Run(tc.name, func(t *testing.T) {+ _, err := p.ExecuteCode(context.Background(), tc.inst, "x", tc.lang, tc.time, nil)+ if err == nil {+ t.Fatalf("got nil error, want one containing %q", tc.want)+ }+ if !strings.Contains(err.Error(), tc.want) {+ t.Errorf("err = %v, want to contain %q", err, tc.want)+ }+ })+ }+}++func TestUCloudAgentSandboxProvider_DestroyInstanceRejectsEmptyID(t *testing.T) {+ t.Parallel()+ p := newUCloudAgentSandboxProviderFromConfig(map[string]any{"api_key": "fake-key"})+ if err := p.Initialize(context.Background()); err != nil {+ t.Fatalf("Initialize: %v", err)+ }+ if err := p.DestroyInstance(context.Background(), nil); err == nil {+ t.Error("DestroyInstance(nil): got nil error, want one")+ }+ if err := p.DestroyInstance(context.Background(), &SandboxInstance{}); err == nil {+ t.Error("DestroyInstance(empty id): got nil error, want one")+ }+ if err := p.DestroyInstance(context.Background(), &SandboxInstance{InstanceID: "already-gone"}); err != nil {+ t.Errorf("DestroyInstance(unknown id): %v, want idempotent success", err)+ }+}++func TestUCloudAgentSandboxProvider_ProviderTypeStaysDistinct(t *testing.T) {+ t.Parallel()+ seen := map[ProviderType]bool{}+ for _, provider := range []SandboxProvider{+ newSelfManagedProviderFromEnv(),+ newAliyunProviderFromEnv(),+ newE2BProviderFromEnv(),+ newTenkiProviderFromEnv(),+ newUCloudAgentSandboxProviderFromConfig(map[string]any{}),+ } {+ if seen[provider.ProviderType()] {+ t.Errorf("provider type %q seen twice", provider.ProviderType())+ }+ seen[provider.ProviderType()] = true+ }+}diff --git a/internal/common/environments.go b/internal/common/environments.goindex 1b422abf53..7260cbb69f 100644--- a/internal/common/environments.go+++ b/internal/common/environments.go@@ -68,6 +68,18 @@ const (EnvTenkiImage = "TENKI_IMAGE"EnvTenkiTimeout = "TENKI_TIMEOUT"EnvTenkiAllowOutbound = "TENKI_ALLOW_OUTBOUND"+ EnvUCloudSandboxAPIKey = "UCLOUD_SANDBOX_API_KEY"+ EnvUCloudSandboxRegion = "UCLOUD_SANDBOX_REGION"+ EnvUCloudSandboxDomain = "UCLOUD_SANDBOX_DOMAIN"+ EnvUCloudSandboxAPIURL = "UCLOUD_SANDBOX_API_URL"+ EnvUCloudSandboxTemplate = "UCLOUD_SANDBOX_TEMPLATE"+ EnvUCloudSandboxAllowInternetAccess = "UCLOUD_SANDBOX_ALLOW_INTERNET_ACCESS"+ EnvUCloudSandboxInsecureHTTP = "UCLOUD_SANDBOX_INSECURE_HTTP"+ EnvUCloudSandboxExecutionTimeout = "UCLOUD_SANDBOX_EXECUTION_TIMEOUT"+ EnvUCloudSandboxTimeout = "UCLOUD_SANDBOX_TIMEOUT"+ EnvUCloudSandboxMaxOutputBytes = "UCLOUD_SANDBOX_MAX_OUTPUT_BYTES"+ EnvUCloudSandboxMaxArtifacts = "UCLOUD_SANDBOX_MAX_ARTIFACTS"+ EnvUCloudSandboxMaxArtifactBytes = "UCLOUD_SANDBOX_MAX_ARTIFACT_BYTES"EnvLocalPythonBin = "LOCAL_PYTHON_BIN"EnvLocalNodeBin = "LOCAL_NODE_BIN"EnvLocalWorkDir = "LOCAL_WORK_DIR"diff --git a/pyproject.toml b/pyproject.tomlindex 75a1386ca7..b81e1f542b 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -130,6 +130,7 @@ dependencies = ["tavily-python==0.5.1","tencentcloud-sdk-python==3.0.1478","tika==2.6.0",+ "ucloud-sandbox>=1.4.2,<2.0.0","valkey==6.0.2","volcengine==1.0.194","voyageai==0.2.3",diff --git a/test/unit_test/agent/sandbox/test_ucloud_agent_sandbox_provider.py b/test/unit_test/agent/sandbox/test_ucloud_agent_sandbox_provider.pynew file mode 100644index 0000000000..1fbb01abf3--- /dev/null+++ b/test/unit_test/agent/sandbox/test_ucloud_agent_sandbox_provider.py@@ -0,0 +1,358 @@+import base64+import posixpath+from types import SimpleNamespace++import pytest++from agent.sandbox.providers.base import SandboxProviderConfigError+from agent.sandbox.providers.ucloud_agent_sandbox import UCloudAgentSandboxProvider+from agent.sandbox.result_protocol import RESULT_MARKER_PREFIX++pytestmark = pytest.mark.p3+++class _FakeFileType:+ FILE = "file"+ DIR = "dir"+++class _AuthenticationException(Exception):+ pass+++class _RateLimitException(Exception):+ pass+++class _TimeoutException(Exception):+ pass+++class _FileNotFoundException(Exception):+ pass+++class _CommandExitException(Exception):+ def __init__(self, exit_code: int, stdout: str = "", stderr: str = "", error: str = ""):+ super().__init__(error or f"command exited with code {exit_code}")+ self.exit_code = exit_code+ self.stdout = stdout+ self.stderr = stderr+ self.error = error+++class _FakeCommandResult:+ def __init__(self, exit_code: int = 0, stdout: str = "", stderr: str = ""):+ self.exit_code = exit_code+ self.stdout = stdout+ self.stderr = stderr+++class _FakeFiles:+ def __init__(self):+ self.files: dict[str, bytes] = {}+ self.list_overrides: dict[str, list[SimpleNamespace]] = {}++ def write(self, path: str, data: str | bytes, request_timeout=None):+ self.files[path] = data.encode("utf-8") if isinstance(data, str) else data+ return SimpleNamespace(path=path)++ def read(self, path: str, format: str = "text", request_timeout=None):+ payload = self.files[path]+ if format == "bytes":+ return bytearray(payload)+ return payload.decode("utf-8")++ def list(self, path: str, depth: int = 1, request_timeout=None):+ if path in self.list_overrides:+ return self.list_overrides[path]++ prefix = path.rstrip("/") + "/"+ entries: list[SimpleNamespace] = []+ seen_dirs: set[str] = set()+ for file_path, payload in self.files.items():+ if not file_path.startswith(prefix):+ continue+ relative = file_path[len(prefix) :]+ head, _, tail = relative.partition("/")+ entry_path = posixpath.join(path, head)+ if tail:+ if head not in seen_dirs:+ seen_dirs.add(head)+ entries.append(+ SimpleNamespace(+ path=entry_path,+ size=0,+ type=_FakeFileType.DIR,+ symlink_target=None,+ )+ )+ continue+ entries.append(+ SimpleNamespace(+ path=entry_path,+ size=len(payload),+ type=_FakeFileType.FILE,+ symlink_target=None,+ )+ )+ return entries+++class _FakeCommands:+ def __init__(self, sandbox, run_handler=None):+ self._sandbox = sandbox+ self._run_handler = run_handler+ self.calls: list[dict] = []++ def run(self, cmd: str, cwd=None, timeout=None, request_timeout=None):+ self.calls.append(+ {+ "cmd": cmd,+ "cwd": cwd,+ "timeout": timeout,+ "request_timeout": request_timeout,+ }+ )+ if cmd.startswith("mkdir -p "):+ return _FakeCommandResult()+ if self._run_handler is not None:+ return self._run_handler(self._sandbox, cmd, cwd)+ return _FakeCommandResult()+++class _FakeSandbox:+ def __init__(self, run_handler=None):+ self.sandbox_id = "sbx-fake-1"+ self.files = _FakeFiles()+ self.commands = _FakeCommands(self, run_handler)+ self.timeout_calls: list[tuple[int, int | None]] = []+ self.killed = False++ def set_timeout(self, timeout: int, request_timeout=None):+ self.timeout_calls.append((timeout, request_timeout))++ def kill(self, request_timeout=None):+ self.killed = True+ return True+++class _FakeSDK:+ AuthenticationException = _AuthenticationException+ RateLimitException = _RateLimitException+ TimeoutException = _TimeoutException+ FileNotFoundException = _FileNotFoundException+ CommandExitException = _CommandExitException+ FileType = _FakeFileType++ def __init__(self, sandbox: _FakeSandbox):+ self._sandbox = sandbox+ self.create_kwargs: dict | None = None+ self.create_error: Exception | None = None+ self.Sandbox = SimpleNamespace(create=self._create)++ def _create(self, **kwargs):+ self.create_kwargs = kwargs+ if self.create_error is not None:+ raise self.create_error+ return self._sandbox+++def _build_provider(sandbox: _FakeSandbox, monkeypatch, **overrides) -> tuple[UCloudAgentSandboxProvider, _FakeSDK]:+ sdk = _FakeSDK(sandbox)+ monkeypatch.setattr("agent.sandbox.providers.ucloud_agent_sandbox._get_ucloud_sandbox_module", lambda: sdk)+ config = {+ "api_key": "ucloud-test-key",+ "region": "cn-wlcb",+ "template": "base",+ "timeout": 30,+ "sandbox_timeout": 300,+ "max_output_bytes": 1024 * 1024,+ "max_artifacts": 20,+ "max_artifact_bytes": 1024 * 1024,+ }+ config.update(overrides)+ provider = UCloudAgentSandboxProvider()+ assert provider.initialize(config) is True+ return provider, sdk+++def test_ucloud_agent_sandbox_executes_python_and_collects_artifacts(monkeypatch):+ def run_handler(sandbox, cmd, cwd):+ sandbox.files.files[posixpath.join(cwd, "artifacts", "chart.png")] = b"PNGDATA"+ payload = base64.b64encode(b'{"present":true,"value":{"message":"hello ucloud"},"type":"json"}').decode("ascii")+ return _FakeCommandResult(stdout=f"debug line\n{RESULT_MARKER_PREFIX}{payload}\n")++ sandbox = _FakeSandbox(run_handler)+ provider, sdk = _build_provider(sandbox, monkeypatch)++ instance = provider.create_instance("python")+ result = provider.execute_code(+ instance.instance_id,+ 'def main() -> dict:\n return {"message": "hello ucloud"}\n',+ "python",+ timeout=5,+ )+ provider.destroy_instance(instance.instance_id)++ assert instance.provider == "ucloud_agent_sandbox"+ assert instance.metadata["sandbox_id"] == "sbx-fake-1"+ assert sdk.create_kwargs["template"] == "base"+ assert sdk.create_kwargs["allow_internet_access"] is False+ assert sdk.create_kwargs["secure"] is True+ assert sdk.create_kwargs["domain"] == "cn-wlcb.sandbox.ucloudai.com"+ assert result.exit_code == 0+ assert result.stdout == "debug line\n"+ assert result.metadata["result_present"] is True+ assert result.metadata["result_value"] == {"message": "hello ucloud"}+ assert result.metadata["artifacts"] == [+ {+ "name": "chart.png",+ "content_b64": base64.b64encode(b"PNGDATA").decode("ascii"),+ "mime_type": "image/png",+ "size": 7,+ }+ ]+ assert sandbox.timeout_calls == [(300, 30)]+ assert sandbox.killed is True+++def test_ucloud_agent_sandbox_preserves_nonzero_exit(monkeypatch):+ sandbox = _FakeSandbox()+ provider, sdk = _build_provider(sandbox, monkeypatch)++ def run_handler(sandbox, cmd, cwd):+ raise sdk.CommandExitException(7, stderr="boom\n", error="failed")++ sandbox.commands._run_handler = run_handler+ instance = provider.create_instance("python")+ result = provider.execute_code(instance.instance_id, "def main():\n raise SystemExit(7)\n", "python", timeout=5)++ assert result.exit_code == 7+ assert result.stderr == "boom\n"+ assert result.metadata["status"] == "error"+ assert result.metadata["result_present"] is False+++def test_ucloud_agent_sandbox_maps_timeout(monkeypatch):+ sandbox = _FakeSandbox()+ provider, sdk = _build_provider(sandbox, monkeypatch)++ def run_handler(sandbox, cmd, cwd):+ raise sdk.TimeoutException("deadline exceeded")++ sandbox.commands._run_handler = run_handler+ instance = provider.create_instance("python")+ with pytest.raises(TimeoutError, match="timed out after 5 seconds"):+ provider.execute_code(instance.instance_id, "def main():\n return 1\n", "python", timeout=5)+++def test_ucloud_agent_sandbox_maps_create_errors(monkeypatch):+ sandbox = _FakeSandbox()+ provider, sdk = _build_provider(sandbox, monkeypatch)++ sdk.create_error = sdk.AuthenticationException("bad key")+ with pytest.raises(SandboxProviderConfigError, match="authentication failed"):+ provider.create_instance("python")++ sdk.create_error = sdk.RateLimitException("slow down")+ with pytest.raises(RuntimeError, match="rate limited"):+ provider.create_instance("python")+++def test_ucloud_agent_sandbox_executes_javascript(monkeypatch):+ def run_handler(sandbox, cmd, cwd):+ payload = base64.b64encode(b'{"present":true,"value":42,"type":"json"}').decode("ascii")+ return _FakeCommandResult(stdout=f"{RESULT_MARKER_PREFIX}{payload}\n")++ sandbox = _FakeSandbox(run_handler)+ provider, _ = _build_provider(sandbox, monkeypatch)+ instance = provider.create_instance("javascript")+ result = provider.execute_code(instance.instance_id, "function main(args) { return 42; }", "javascript", timeout=5)++ assert instance.metadata["language"] == "nodejs"+ assert any(path.endswith("main.js") for path in sandbox.files.files)+ assert any(call["cmd"].startswith("node ") for call in sandbox.commands.calls)+ assert result.metadata["result_value"] == 42+++def test_ucloud_agent_sandbox_config_schema_and_validation():+ schema = UCloudAgentSandboxProvider.get_config_schema()+ assert schema["api_key"]["required"] is True+ assert schema["api_key"]["secret"] is True+ assert schema["template"]["default"] == "base"+ assert schema["allow_internet_access"]["default"] is False+ assert schema["region"]["default"] == "cn-wlcb"++ provider = UCloudAgentSandboxProvider()+ ok, message = provider.validate_config(+ {+ "api_key": "key",+ "template": "base",+ "timeout": 30,+ "sandbox_timeout": 300,+ "max_output_bytes": 1024,+ "max_artifacts": 5,+ "max_artifact_bytes": 1024,+ }+ )+ assert ok is True+ assert message is None++ ok, message = provider.validate_config({"api_key": ""})+ assert ok is False+ assert "API key" in message+++def test_ucloud_agent_sandbox_enforces_output_limit(monkeypatch):+ sandbox = _FakeSandbox(lambda sandbox, cmd, cwd: _FakeCommandResult(stdout="x" * 5000))+ provider, _ = _build_provider(sandbox, monkeypatch, max_output_bytes=100)+ instance = provider.create_instance("python")++ with pytest.raises(RuntimeError, match="output exceeded"):+ provider.execute_code(instance.instance_id, "def main():\n return 1\n", "python", timeout=5)+++def test_ucloud_agent_sandbox_rejects_disallowed_artifact(monkeypatch):+ def run_handler(sandbox, cmd, cwd):+ sandbox.files.files[posixpath.join(cwd, "artifacts", "malware.exe")] = b"MZ"+ return _FakeCommandResult()++ sandbox = _FakeSandbox(run_handler)+ provider, _ = _build_provider(sandbox, monkeypatch)+ instance = provider.create_instance("python")++ with pytest.raises(RuntimeError, match="Unsupported artifact type"):+ provider.execute_code(instance.instance_id, "def main():\n return 1\n", "python", timeout=5)+++def test_ucloud_agent_sandbox_rejects_symlink_artifact(monkeypatch):+ def run_handler(sandbox, cmd, cwd):+ artifacts_dir = posixpath.join(cwd, "artifacts")+ sandbox.files.list_overrides[artifacts_dir] = [+ SimpleNamespace(+ path=posixpath.join(artifacts_dir, "evil.json"),+ size=10,+ type=_FakeFileType.FILE,+ symlink_target="/etc/passwd",+ )+ ]+ return _FakeCommandResult()++ sandbox = _FakeSandbox(run_handler)+ provider, _ = _build_provider(sandbox, monkeypatch)+ instance = provider.create_instance("python")++ with pytest.raises(RuntimeError, match="symlinks are not allowed"):+ provider.execute_code(instance.instance_id, "def main():\n return 1\n", "python", timeout=5)+++def test_ucloud_agent_sandbox_destroy_is_idempotent(monkeypatch):+ sandbox = _FakeSandbox()+ provider, _ = _build_provider(sandbox, monkeypatch)++ assert provider.destroy_instance("already-gone") is True+++def test_ucloud_agent_sandbox_supported_languages():+ assert UCloudAgentSandboxProvider().get_supported_languages() == ["python", "javascript"]diff --git a/uv.lock b/uv.lockindex ade026ef78..5dfd36b604 100644--- a/uv.lock+++ b/uv.lock@@ -948,6 +948,15 @@ wheels = [{ url = "https://mirrors.aliyun.com/pypi/packages/05/af/fec6a530efdfc3d7739d821cdcb63de7c9979954fa21ef6d16d0b678c8ed/boxsdk-10.3.0-py3-none-any.whl", hash = "sha256:3f65792834315177765c096402e35f43400c4c99c9b6e82f9ac40c8de3da4767" },]+[[package]]+name = "bracex"+version = "3.0.1"+source = { registry = "https://mirrors.aliyun.com/pypi/simple" }+sdist = { url = "https://mirrors.aliyun.com/pypi/packages/ac/01/5f394b8bcd6e5b92f73130990960423bbb19711f906bd9fe9ea5557c667c/bracex-3.0.1.tar.gz", hash = "sha256:4e38e32392e4a4780fe15d644bfc7c8514057cfc3861e060b11814ce829c25e4" }+wheels = [+ { url = "https://mirrors.aliyun.com/pypi/packages/b8/8f/6f7273a7adb8d73fc8d21ede4376a3e475e52f98435c6007f69100dec8ca/bracex-3.0.1-py3-none-any.whl", hash = "sha256:6523ad83aeb5098a4ee597cff0f964442ff74e460bd3fafaffab6a013ff2288c" },+]+[[package]]name = "brotli"version = "1.2.0"@@ -1843,6 +1852,15 @@ wheels = [{ url = "https://mirrors.aliyun.com/pypi/packages/cf/cd/b71d5bc74cde7fc6fd9b2ff9389890f45d9762cbbbf81dc5e51fd7588c4a/elastic_transport-8.17.1-py3-none-any.whl", hash = "sha256:192718f498f1d10c5e9aa8b9cf32aed405e469a7f0e9d6a8923431dbb2c59fb8" },]+[[package]]+name = "dockerfile-parse"+version = "2.0.1"+source = { registry = "https://mirrors.aliyun.com/pypi/simple" }+sdist = { url = "https://mirrors.aliyun.com/pypi/packages/92/df/929ee0b5d2c8bd8d713c45e71b94ab57c7e11e322130724d54f469b2cd48/dockerfile-parse-2.0.1.tar.gz", hash = "sha256:3184ccdc513221983e503ac00e1aa504a2aa8f84e5de673c46b0b6eee99ec7bc" }+wheels = [+ { url = "https://mirrors.aliyun.com/pypi/packages/7a/6c/79cd5bc1b880d8c1a9a5550aa8dacd57353fa3bb2457227e1fb47383eb49/dockerfile_parse-2.0.1-py2.py3-none-any.whl", hash = "sha256:bdffd126d2eb26acf1066acb54cb2e336682e1d72b974a40894fac76a4df17f6" },+]+[[package]]name = "elasticsearch"version = "8.19.3"@@ -8223,6 +8241,7 @@ dependencies = [{ name = "tavily-python" },{ name = "tencentcloud-sdk-python" },{ name = "tika" },+ { name = "ucloud-sandbox" },{ name = "valkey" },{ name = "volcengine" },{ name = "voyageai" },@@ -8387,6 +8406,7 @@ requires-dist = [{ name = "tavily-python", specifier = "==0.5.1" },{ name = "tencentcloud-sdk-python", specifier = "==3.0.1478" },{ name = "tika", specifier = "==2.6.0" },+ { name = "ucloud-sandbox", specifier = ">=1.4.2,<2.0.0" },{ name = "valkey", specifier = "==6.0.2" },{ name = "volcengine", specifier = "==1.0.194" },{ name = "voyageai", specifier = "==0.2.3" },@@ -9799,6 +9819,30 @@ wheels = [{ url = "https://mirrors.aliyun.com/pypi/packages/c2/14/e2a54fabd4f08cd7af1c07030603c3356b74da07f7cc056e600436edfa17/tzlocal-5.3.1-py3-none-any.whl", hash = "sha256:eb1a66c3ef5847adf7a834f1be0800581b683b5608e74f86ecbcef8ab91bb85d" },]+[[package]]+name = "ucloud-sandbox"+version = "1.4.2"+source = { registry = "https://mirrors.aliyun.com/pypi/simple" }+dependencies = [+ { name = "attrs" },+ { name = "dockerfile-parse" },+ { name = "h2" },+ { name = "httpcore" },+ { name = "httpx" },+ { name = "packaging" },+ { name = "pillow" },+ { name = "protobuf" },+ { name = "python-dateutil" },+ { name = "requests" },+ { name = "rich" },+ { name = "typing-extensions" },+ { name = "wcmatch" },+]+sdist = { url = "https://mirrors.aliyun.com/pypi/packages/99/a7/d708ea65985c30f84a0cee728e07e7c729364e9136483e46ecbc7f4d6525/ucloud_sandbox-1.4.2.tar.gz", hash = "sha256:671eb59dfd610456030a97e56b2735972089857dd7ec4f013d3b4291b181c469" }+wheels = [+ { url = "https://mirrors.aliyun.com/pypi/packages/b9/cd/7d6e4a70737afae28bc1b83ada67dd2aea9deaf8d003f23e4c94c7160d92/ucloud_sandbox-1.4.2-py3-none-any.whl", hash = "sha256:6b7e070e90a21744b2d3080e472775645beeed6667666b4b74b7de6f61c452d1" },+]+[[package]]name = "umap-learn"version = "0.5.9.post2"@@ -9989,6 +10033,18 @@ wheels = [{ url = "https://mirrors.aliyun.com/pypi/packages/0a/07/57ebf7a6798b016c064bd0ca81b4c6a99daa4dc377b898bc7b41eb6b5af0/weasel-1.0.0-py3-none-any.whl", hash = "sha256:89518acee027f49d743126c3502d35e6dd14f5768be5c37c9af47c171b6005cc" },]+[[package]]+name = "wcmatch"+version = "10.2.1"+source = { registry = "https://mirrors.aliyun.com/pypi/simple" }+dependencies = [+ { name = "bracex" },+]+sdist = { url = "https://mirrors.aliyun.com/pypi/packages/11/15/dc61746d8c0852f6d711ad09c774b63cf7c8211aa49e30871ac3d342b7e2/wcmatch-10.2.1.tar.gz", hash = "sha256:ecac70a5c70e62ba854b78318d3a1408e8651f8f1c96e5837743b71aa6a4fb92" }+wheels = [+ { url = "https://mirrors.aliyun.com/pypi/packages/82/ba/20b48eedeab5316bf9a502bb9eb7e3b1588bd61d0f565822fefa8f06e10b/wcmatch-10.2.1-py3-none-any.whl", hash = "sha256:2d775395b93f233af66690f62cb9d52b084ec159a31cc4084f4069d72f437acd" },+]+[[package]]name = "webdav4"version = "0.10.0"diff --git a/web/src/pages/admin/sandbox-settings.tsx b/web/src/pages/admin/sandbox-settings.tsxindex 476eb8338c..b58d27ec01 100644--- a/web/src/pages/admin/sandbox-settings.tsx+++ b/web/src/pages/admin/sandbox-settings.tsx@@ -64,6 +64,7 @@ const PROVIDER_ICONS: Record<string, React.ElementType> = {aliyun_codeinterpreter: LucideCloud,e2b: LucideZap,tenki: LucideCloudLightning,+ ucloud_agent_sandbox: LucideCloud,};function AdminSandboxSettings() {