🐫 CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org
Python agentai-societiesartificial-intelligencecommunicative-aicooperative-aideep-learninglarge-language-modelsmulti-agent-systemsnatural-language-processing
[enhance] Shared Multi Runtimes Across Toolkits (#3551)
Hesam Sheikh835618fba98f
diff --git a/camel/runtimes/Dockerfile.multi-toolkit b/camel/runtimes/Dockerfile.multi-toolkitnew file mode 100644index 000000000..14c2e7624--- /dev/null+++ 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.pyindex 84a850adc..4ed54541f 100644--- a/camel/runtimes/api.py+++ b/camel/runtimes/api.py@@ -11,13 +11,15 @@# 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.futuresimport importlibimport ioimport jsonimport loggingimport osimport sys-from typing import Dict+from typing import Any, Dict, Listimport uvicornfrom fastapi import FastAPI, Request@@ -25,8 +27,15 @@ from fastapi.responses import JSONResponsefrom 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 @@ logger.info(f"Modules and functions: {modules_functions}")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] = []++[email protected]("/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 @@ for module_function in modules_functions: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.pyindex 6a260114e..2b5431410 100644--- a/camel/toolkits/browser_toolkit.py+++ b/camel/toolkits/browser_toolkit.py@@ -147,15 +147,12 @@ class BaseBrowser:Returns:None"""- from playwright.sync_api import (- sync_playwright,- )-self.history: List[Any] = []self.headless = headlessself.channel = channelself._ensure_browser_installed()- self.playwright: Playwright = sync_playwright().start()+ # lazy initialization - playwright is started in init() method+ self.playwright: Optional[Playwright] = Noneself.page_history: List[str] = [] # stores the history of visited pages@@ -192,7 +189,11 @@ class BaseBrowser: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 @@ class BaseBrowser:targeted text. It is equivalent to pressing Ctrl + F and searching forthe text."""- # ruff: noqa: E501assert self.page is not Nonescript = f"""(function() {{@@ -737,7 +737,6 @@ class BaseBrowser:if self.playwright:self.playwright.stop() # Stop playwright instance- # ruff: noqa: E501def show_interactive_elements(self):r"""Show simple interactive elements on the current page."""assert self.page is not None@@ -829,6 +828,9 @@ class BrowserToolkit(BaseToolkit):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 browserchannel to use. Must be one of "chrome", "msedge", or@@ -852,6 +854,17 @@ class BrowserToolkit(BaseToolkit):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,8 +903,8 @@ class BrowserToolkit(BaseToolkit):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:@@ -899,8 +912,8 @@ class BrowserToolkit(BaseToolkit):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_backenddiff --git a/camel/toolkits/terminal_toolkit/terminal_toolkit.py b/camel/toolkits/terminal_toolkit/terminal_toolkit.pyindex 30fa1f691..83c69faee 100644--- a/camel/toolkits/terminal_toolkit/terminal_toolkit.py+++ b/camel/toolkits/terminal_toolkit/terminal_toolkit.py@@ -100,6 +100,18 @@ class TerminalToolkit(BaseToolkit):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_backendself.timeout = timeoutself.shell_sessions: Dict[str, Dict[str, Any]] = {}@@ -219,8 +231,13 @@ class TerminalToolkit(BaseToolkit):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.pynew file mode 100644index 000000000..d7e129c92--- /dev/null+++ b/examples/runtimes/shared_runtime_multi_toolkit.py@@ -0,0 +1,307 @@+# ========= Copyright 2023-2025 @ 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-2025 @ CAMEL-AI.org. All Rights Reserved. =========+"""+Example: Shared Runtime with Multiple Toolkits++This example demonstrates how to run multiple toolkits (TerminalToolkit,+CodeExecutionToolkit, SearchToolkit, BrowserToolkit) in a single shared+Docker container. All toolkits share the same filesystem, enabling workflows+where one toolkit can operate on files created by another.++Prerequisites:+ Build the multi-toolkit Docker image first:+ ```+ docker build -f camel/runtimes/Dockerfile.multi-toolkit \+ -t camel-multi-toolkit:latest .+ ```++Usage:+ python examples/runtimes/shared_runtime_multi_toolkit.py+"""++import os+import tempfile+from pathlib import Path++import requests++from camel.runtimes import DockerRuntime+from camel.toolkits import (+ BrowserToolkit,+ CodeExecutionToolkit,+ SearchToolkit,+ TerminalToolkit,+)+++def test_terminal_and_code(runtime):+ """Test TerminalToolkit and CodeExecutionToolkit sharing filesystem."""+ # check the health endpoint to see loaded toolkits+ health = requests.get(f"http://localhost:{runtime.port}/health")+ print(f"\nHealth check: {health.json()}")++ # get all tools from the runtime+ tools = runtime.get_tools()+ print(f"\nAvailable tools: {[t.get_function_name() for t in tools]}")++ # find specific tools+ shell_exec = next(+ (t for t in tools if t.get_function_name() == "shell_exec"), None+ )+ execute_code = next(+ (t for t in tools if t.get_function_name() == "execute_code"), None+ )++ if not shell_exec or not execute_code:+ print("ERROR: Could not find required tools")+ return False++ # test 1: use terminal to create a file+ print("\n--- Test 1: Create file using TerminalToolkit ---")+ result = shell_exec.func(+ id="test1",+ command="echo 'Hello from shared runtime!' > /workspace/test.txt",+ block=True,+ )+ print(f"Terminal result: {result}")++ # test 2: use terminal to verify file exists+ print("\n--- Test 2: Verify file with TerminalToolkit ---")+ result = shell_exec.func(+ id="test2",+ command="cat /workspace/test.txt",+ block=True,+ )+ print(f"File contents: {result}")++ # test 3: use code execution to read the same file+ print("\n--- Test 3: Read file using CodeExecutionToolkit ---")+ code = """+with open('/workspace/test.txt', 'r') as f:+ content = f.read()+print(f"Read from Python: {content}")+"""+ result = execute_code.func(code=code)+ print(f"Code execution result: {result}")++ # test 4: use code execution to create another file+ print("\n--- Test 4: Create file using CodeExecutionToolkit ---")+ code = """+with open('/workspace/from_python.txt', 'w') as f:+ f.write('Created by CodeExecutionToolkit!')+print('File created successfully')+"""+ result = execute_code.func(code=code)+ print(f"Code execution result: {result}")++ # test 5: use terminal to read the file created by code execution+ print("\n--- Test 5: Read Python-created file with TerminalToolkit ---")+ result = shell_exec.func(+ id="test5",+ command="cat /workspace/from_python.txt",+ block=True,+ )+ print(f"File contents: {result}")++ return True+++def test_with_search(runtime):+ """Test SearchToolkit in the shared runtime."""+ tools = runtime.get_tools()++ # find search tool (using search_wiki as it requires no API key)+ search_wiki = next(+ (t for t in tools if t.get_function_name() == "search_wiki"), None+ )++ if not search_wiki:+ print("ERROR: Could not find search_wiki tool")+ return False++ print("\n--- Test Search: Wikipedia search ---")+ result = search_wiki.func(entity="Python programming language")+ print(f"Search result (truncated): {str(result)[:500]}...")++ return True+++def test_with_browser(runtime):+ """Test BrowserToolkit in the shared runtime."""+ tools = runtime.get_tools()++ # find browse_url tool+ browse_url = next(+ (t for t in tools if t.get_function_name() == "browse_url"), None+ )++ if not browse_url:+ print("ERROR: Could not find browse_url tool")+ return False++ print("\n--- Test Browser: Browse camel-ai.org ---")+ result = browse_url.func(+ task_prompt="What is the main heading on this page?",+ start_url="https://www.camel-ai.org/",+ )+ print(f"Browse result (truncated): {str(result)[:500]}...")++ return True+++def main():+ # create toolkits (they will auto-detect CAMEL_RUNTIME inside container)+ terminal_toolkit = TerminalToolkit()+ code_toolkit = CodeExecutionToolkit(verbose=True)+ search_toolkit = SearchToolkit()+ browser_toolkit = BrowserToolkit(headless=True)++ # create a local workspace directory that will be mounted to the container+ workspace_dir = Path(tempfile.mkdtemp(prefix="camel_workspace_"))+ print(f"Local workspace directory: {workspace_dir}")++ # build runtime configuration+ print(+ "Creating shared runtime with TerminalToolkit, "+ "CodeExecutionToolkit, SearchToolkit, and BrowserToolkit..."+ )++ # pass API keys to container for BrowserToolkit's web agent+ env_vars = {+ "CAMEL_RUNTIME": "true",+ }+ # pass through common API key environment variables if set+ for key in [+ "OPENAI_API_KEY",+ "AZURE_OPENAI_API_KEY",+ "AZURE_OPENAI_BASE_URL",+ "AZURE_API_VERSION",+ "AZURE_DEPLOYMENT_NAME",+ "DEFAULT_MODEL_PLATFORM_TYPE",+ "DEFAULT_MODEL_TYPE",+ ]:+ if os.environ.get(key):+ env_vars[key] = os.environ[key]++ runtime = DockerRuntime(+ "camel-multi-toolkit:latest", port=8000, environment=env_vars+ )+ runtime = runtime.mount(str(workspace_dir), "/workspace")+ runtime = runtime.add(+ terminal_toolkit.get_tools(),+ "camel.toolkits.TerminalToolkit",+ )+ runtime = runtime.add(+ code_toolkit.get_tools(),+ "camel.toolkits.CodeExecutionToolkit",+ arguments={"verbose": True},+ )+ runtime = runtime.add(+ search_toolkit.get_tools(),+ "camel.toolkits.SearchToolkit",+ )+ runtime = runtime.add(+ browser_toolkit.get_tools(),+ "camel.toolkits.BrowserToolkit",+ arguments={"headless": True},+ )+ runtime = runtime.build()++ with runtime:+ # wait for the API server to be ready+ print("Waiting for runtime to be ready...")+ if not runtime.wait(timeout=30):+ print("ERROR: Runtime failed to start")+ return++ print("Runtime is ready!")++ # run terminal and code tests+ success = test_terminal_and_code(runtime)++ # run search tests+ if success:+ success = test_with_search(runtime)++ # run browser tests+ if success:+ success = test_with_browser(runtime)++ if success:+ print("\n--- All tests completed successfully! ---")+ print("All toolkits successfully shared the same runtime.")+ print(f"\nFiles created during tests at: {workspace_dir}")+ else:+ print("\n--- Some tests failed ---")+++if __name__ == "__main__":+ main()+++# ruff: noqa: E501+"""+===============================================================================+Example Output:+===============================================================================+Local workspace directory: /tmp/camel_workspace_xyz123+Creating shared runtime with TerminalToolkit, CodeExecutionToolkit,+SearchToolkit, and BrowserToolkit...+Waiting for runtime to be ready...+Runtime is ready!++Health check: {'status': 'ok', 'toolkits': [...], 'endpoints': [...]}++Available tools: ['shell_exec', 'shell_view', ..., 'browse_url']++--- Test 1: Create file using TerminalToolkit ---+Terminal result: Command executed successfully (no output).++--- Test 2: Verify file with TerminalToolkit ---+File contents: Hello from shared runtime!++--- Test 3: Read file using CodeExecutionToolkit ---+Code execution result: Executed the code below:+```python+with open('/workspace/test.txt', 'r') as f:+ content = f.read()+print(f"Read from Python: {content}")+```+> Executed Results:+Read from Python: Hello from shared runtime!++--- Test 4: Create file using CodeExecutionToolkit ---+Code execution result: Executed the code below:+```python+with open('/workspace/from_python.txt', 'w') as f:+ f.write('Created by CodeExecutionToolkit!')+print('File created successfully')+```+> Executed Results:+File created successfully++--- Test 5: Read Python-created file with TerminalToolkit ---+File contents: Created by CodeExecutionToolkit!++--- Test Search: Wikipedia search ---+Search result (truncated): Python is a high-level programming language...++--- Test Browser: Browse camel-ai.org ---+Browse result (truncated): The main heading is "Building Multi-Agent+Systems for Task"...++--- All tests completed successfully! ---+All toolkits successfully shared the same runtime.+===============================================================================+"""diff --git a/test/runtimes/test_shared_runtime.py b/test/runtimes/test_shared_runtime.pynew file mode 100644index 000000000..83b3182e3--- /dev/null+++ b/test/runtimes/test_shared_runtime.py@@ -0,0 +1,57 @@+# ========= Copyright 2023-2025 @ 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-2025 @ CAMEL-AI.org. All Rights Reserved. =========+import pytest++from camel.runtimes import DockerRuntime+from camel.toolkits import CodeExecutionToolkit, TerminalToolkit++[email protected](reason="Need Docker environment to run this test.")+def test_shared_runtime_filesystem():+ """Test that multiple toolkits share the same filesystem in a runtime."""+ runtime = (+ DockerRuntime("camel-multi-toolkit:latest", port=8000)+ .add(TerminalToolkit().get_tools(), "camel.toolkits.TerminalToolkit")+ .add(+ CodeExecutionToolkit().get_tools(),+ "camel.toolkits.CodeExecutionToolkit",+ arguments={"verbose": True},+ )+ .build()+ )++ with runtime as r:+ r.wait(timeout=30)+ tools = r.get_tools()++ # find tools by name+ shell_exec = next(+ t for t in tools if t.get_function_name() == "shell_exec"+ )+ execute_code = next(+ t for t in tools if t.get_function_name() == "execute_code"+ )++ # terminal creates a file+ shell_exec.func(+ id="test1",+ command="echo 'shared content' > /workspace/shared.txt",+ block=True,+ )++ # code execution reads the same file+ result = execute_code.func(+ code="print(open('/workspace/shared.txt').read().strip())"+ )+ assert "shared content" in result