[enhance] Shared Multi Runtimes Across Toolkits (#3551)

hesamsheikh · Wendong-Fan · web-flow · commit 835618fba98f · 2025-12-17T00:59:21.000+08:00
Co-authored-by: Wendong-Fan &lt;w3ndong.fan@gmail.com&gt;
diff --git a/camel/runtimes/Dockerfile.multi-toolkit b/camel/runtimes/Dockerfile.multi-toolkit
@@ -0,0 +1,90 @@
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. 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.
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+
+# Multi-toolkit Docker image for CAMEL shared runtimes
+# Supports: BrowserToolkit, TerminalToolkit, CodeExecutionToolkit, and more
+#
+# Build (from repo root):
+#   docker build -f camel/runtimes/Dockerfile.multi-toolkit \
+#       -t camel-multi-toolkit:latest .
+#
+# Usage with DockerRuntime:
+#   runtime = (
+#       DockerRuntime("camel-multi-toolkit:latest")
+#       .add(BrowserToolkit().get_tools(), "camel.toolkits.BrowserToolkit")
+#       .add(TerminalToolkit().get_tools(), "camel.toolkits.TerminalToolkit")
+#       .add(CodeExecutionToolkit().get_tools(), "camel.toolkits.CodeExecutionToolkit")
+#       .build()
+#   )
+
+FROM python:3.10-slim
+
+# install system dependencies for various toolkits
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    # build tools (required for psutil, etc.)
+    gcc \
+    python3-dev \
+    # common tools
+    curl \
+    wget \
+    git \
+    bash \
+    # for Playwright browsers
+    libnss3 \
+    libnspr4 \
+    libatk1.0-0 \
+    libatk-bridge2.0-0 \
+    libcups2 \
+    libdrm2 \
+    libxkbcommon0 \
+    libxcomposite1 \
+    libxdamage1 \
+    libxfixes3 \
+    libxrandr2 \
+    libgbm1 \
+    libasound2 \
+    libpango-1.0-0 \
+    libcairo2 \
+    # additional dependencies
+    libdbus-1-3 \
+    libexpat1 \
+    libfontconfig1 \
+    libgcc-s1 \
+    libglib2.0-0 \
+    libgtk-3-0 \
+    libx11-6 \
+    libx11-xcb1 \
+    libxcb1 \
+    libxext6 \
+    && rm -rf /var/lib/apt/lists/*
+
+# copy local CAMEL source and install from source
+# this ensures we use local changes rather than PyPI version
+COPY . /app/camel
+WORKDIR /app/camel
+RUN pip install --no-cache-dir -e '.[all]'
+
+# install Playwright and chromium browser
+RUN pip install --no-cache-dir playwright \
+    && playwright install chromium \
+    && playwright install-deps chromium
+
+# set working directory for runtime operations
+WORKDIR /workspace
+
+# expose API port
+EXPOSE 8000
+
+# default command is sleep infinity (DockerRuntime will exec into it)
+CMD ["sleep", "infinity"]
diff --git a/camel/runtimes/api.py b/camel/runtimes/api.py
@@ -11,22 +11,31 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 # ========= Copyright 2023-2025 @ CAMEL-AI.org. All Rights Reserved. =========
+import asyncio
+import concurrent.futures
 import importlib
 import io
 import json
 import logging
 import os
 import sys
-from typing import Dict
+from typing import Any, Dict, List
 
 import uvicorn
 from fastapi import FastAPI, Request
 from fastapi.responses import JSONResponse
 
 from camel.toolkits import BaseToolkit
 
+# thread pool for running sync tools that can't run inside async event loop
+# (e.g., Playwright sync API)
+_executor = concurrent.futures.ThreadPoolExecutor(max_workers=4)
+
 logger = logging.getLogger(__name__)
 
+# set environment variable to indicate we're running inside a CAMEL runtime
+os.environ["CAMEL_RUNTIME"] = "true"
+
 sys.path.append(os.getcwd())
 
 modules_functions = sys.argv[1:]
@@ -35,6 +44,22 @@
 
 app = FastAPI()
 
+# global cache for toolkit instances to maintain state across calls
+_toolkit_instances: Dict[str, Any] = {}
+
+# track registered endpoints for health check
+_registered_endpoints: List[str] = []
+
+
+@app.get("/health")
+async def health_check():
+    r"""Health check endpoint that reports loaded toolkits and endpoints."""
+    return {
+        "status": "ok",
+        "toolkits": list(_toolkit_instances.keys()),
+        "endpoints": _registered_endpoints,
+    }
+
 
 @app.exception_handler(Exception)
 async def general_exception_handler(request: Request, exc: Exception):
@@ -49,6 +74,9 @@ async def general_exception_handler(request: Request, exc: Exception):
 
 for module_function in modules_functions:
     try:
+        # store original module_function as cache key before parsing
+        cache_key = module_function
+
         init_params = dict()
         if "{" in module_function:
             module_function, params = module_function.split("{")
@@ -62,36 +90,64 @@ async def general_exception_handler(request: Request, exc: Exception):
         module = importlib.import_module(module_name)
         function = getattr(module, function_name)
         if isinstance(function, type) and issubclass(function, BaseToolkit):
-            function = function(**init_params).get_tools()
+            # use cached instance if available to maintain state across calls
+            if cache_key not in _toolkit_instances:
+                _toolkit_instances[cache_key] = function(**init_params)
+            function = _toolkit_instances[cache_key].get_tools()
 
         if not isinstance(function, list):
             function = [function]
 
         for func in function:
-
-            @app.post(f"/{func.get_function_name()}")
-            async def dynamic_function(data: Dict, func=func):
-                redirect_stdout = data.get('redirect_stdout', False)
-                if redirect_stdout:
-                    sys.stdout = io.StringIO()
-                response_data = func.func(*data['args'], **data['kwargs'])
-                if redirect_stdout:
-                    sys.stdout.seek(0)
-                    output = sys.stdout.read()
-                    sys.stdout = sys.__stdout__
+            endpoint_name = func.get_function_name()
+            _registered_endpoints.append(endpoint_name)
+
+            def make_endpoint(tool):
+                r"""Create endpoint with tool captured in closure."""
+
+                def run_tool(data: Dict):
+                    r"""Run tool in thread pool to avoid async event loop."""
+                    redirect_stdout = data.get('redirect_stdout', False)
+                    captured_output = None
+                    if redirect_stdout:
+                        captured_output = io.StringIO()
+                        old_stdout = sys.stdout
+                        sys.stdout = captured_output
+                    try:
+                        response_data = tool.func(
+                            *data['args'], **data['kwargs']
+                        )
+                    finally:
+                        if redirect_stdout:
+                            sys.stdout = old_stdout
+                    if redirect_stdout and captured_output is not None:
+                        captured_output.seek(0)
+                        output = captured_output.read()
+                        return {
+                            "output": json.dumps(
+                                response_data, ensure_ascii=False
+                            ),
+                            "stdout": output,
+                        }
                     return {
-                        "output": json.dumps(
-                            response_data, ensure_ascii=False
-                        ),
-                        "stdout": output,
+                        "output": json.dumps(response_data, ensure_ascii=False)
                     }
-                return {
-                    "output": json.dumps(response_data, ensure_ascii=False)
-                }
+
+                async def endpoint(data: Dict):
+                    # run in thread pool to support sync tools like Playwright
+                    loop = asyncio.get_running_loop()
+                    return await loop.run_in_executor(
+                        _executor, run_tool, data
+                    )
+
+                return endpoint
+
+            app.post(f"/{endpoint_name}")(make_endpoint(func))
 
     except (ImportError, AttributeError) as e:
         logger.error(f"Error importing {module_function}: {e}")
 
 
 if __name__ == "__main__":
-    uvicorn.run("__main__:app", host="0.0.0.0", port=8000, reload=True)
+    # reload=False to avoid conflicts with async toolkits (e.g., Playwright)
+    uvicorn.run(app, host="0.0.0.0", port=8000, reload=False)
diff --git a/camel/toolkits/browser_toolkit.py b/camel/toolkits/browser_toolkit.py
@@ -147,15 +147,12 @@ def __init__(
         Returns:
             None
         """
-        from playwright.sync_api import (
-            sync_playwright,
-        )
-
         self.history: List[Any] = []
         self.headless = headless
         self.channel = channel
         self._ensure_browser_installed()
-        self.playwright: Playwright = sync_playwright().start()
+        # lazy initialization - playwright is started in init() method
+        self.playwright: Optional[Playwright] = None
         self.page_history: List[
             str
         ] = []  # stores the history of visited pages
@@ -192,7 +189,11 @@ def __init__(
 
     def init(self) -> None:
         r"""Initialize the browser."""
-        assert self.playwright is not None
+        # lazy start playwright when init() is called, not in __init__
+        if self.playwright is None:
+            from playwright.sync_api import sync_playwright
+
+            self.playwright = sync_playwright().start()
 
         browser_launch_args = [
             "--disable-blink-features=AutomationControlled",  # Basic stealth
@@ -677,7 +678,6 @@ def find_text_on_page(self, search_text: str) -> str:
         targeted text. It is equivalent to pressing Ctrl + F and searching for
         the text.
         """
-        # ruff: noqa: E501
         assert self.page is not None
         script = f"""
         (function() {{
@@ -737,7 +737,6 @@ def close(self):
         if self.playwright:
             self.playwright.stop()  # Stop playwright instance
 
-    # ruff: noqa: E501
     def show_interactive_elements(self):
         r"""Show simple interactive elements on the current page."""
         assert self.page is not None
@@ -829,6 +828,9 @@ def __init__(
 
         Args:
             headless (bool): Whether to run the browser in headless mode.
+                When running inside a CAMEL runtime container, this is
+                automatically set to True since containers typically don't
+                have a display.
             cache_dir (Union[str, None]): The directory to store cache files.
             channel (Literal["chrome", "msedge", "chromium"]): The browser
                 channel to use. Must be one of "chrome", "msedge", or
@@ -852,6 +854,17 @@ def __init__(
                 is used without saving data. (default: :obj:`None`)
         """
         super().__init__()  # Call to super().__init__() added
+
+        # auto-detect if running inside a CAMEL runtime container
+        # force headless mode since containers typically don't have a display
+        in_runtime = os.environ.get("CAMEL_RUNTIME", "").lower() == "true"
+        if in_runtime and not headless:
+            logger.info(
+                "Detected CAMEL_RUNTIME environment - enabling headless mode "
+                "since containers typically don't have a display"
+            )
+            headless = True
+
         self.browser = BaseBrowser(
             headless=headless,
             cache_dir=cache_dir,
@@ -890,17 +903,17 @@ def _initialize_agent(
 
         if web_agent_model_backend is None:
             web_agent_model_instance = ModelFactory.create(
-                model_platform=ModelPlatformType.OPENAI,
-                model_type=ModelType.GPT_4_1,
+                model_platform=ModelPlatformType.DEFAULT,
+                model_type=ModelType.DEFAULT,
                 model_config_dict={"temperature": 0, "top_p": 1},
             )
         else:
             web_agent_model_instance = web_agent_model_backend
 
         if planning_agent_model_backend is None:
             planning_model = ModelFactory.create(
-                model_platform=ModelPlatformType.OPENAI,
-                model_type=ModelType.O3_MINI,
+                model_platform=ModelPlatformType.DEFAULT,
+                model_type=ModelType.DEFAULT,
             )
         else:
             planning_model = planning_agent_model_backend
diff --git a/camel/toolkits/terminal_toolkit/terminal_toolkit.py b/camel/toolkits/terminal_toolkit/terminal_toolkit.py
@@ -100,6 +100,18 @@ def __init__(
         clone_current_env: bool = False,
         install_dependencies: Optional[List[str]] = None,
     ):
+        # auto-detect if running inside a CAMEL runtime container
+        # when inside a runtime, use local execution (already sandboxed)
+        runtime_env = os.environ.get("CAMEL_RUNTIME", "").lower()
+        self._in_runtime = runtime_env == "true"
+        if self._in_runtime and use_docker_backend:
+            logger.info(
+                "Detected CAMEL_RUNTIME environment - disabling Docker "
+                "backend since we're already inside a sandboxed container"
+            )
+            use_docker_backend = False
+            docker_container_name = None
+
         self.use_docker_backend = use_docker_backend
         self.timeout = timeout
         self.shell_sessions: Dict[str, Dict[str, Any]] = {}
@@ -219,8 +231,13 @@ def __init__(
             except APIError as e:
                 raise RuntimeError(f"Failed to connect to Docker daemon: {e}")
 
-        # Set up environments (only for local backend)
-        if not self.use_docker_backend:
+        # Set up environments (only for local backend, skip in runtime mode)
+        if self._in_runtime:
+            logger.info(
+                "[ENV] Skipping environment setup - running inside "
+                "CAMEL runtime container"
+            )
+        elif not self.use_docker_backend:
             if self.clone_current_env:
                 self._setup_cloned_environment()
             else:
diff --git a/examples/runtimes/shared_runtime_multi_toolkit.py b/examples/runtimes/shared_runtime_multi_toolkit.py
diff --git a/test/runtimes/test_shared_runtime.py b/test/runtimes/test_shared_runtime.py
