🐫 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
doc: Add doc for runtime module (#2437)
Boer-Zhangbd4c1c0ae6f8
diff --git a/docs/index.rst b/docs/index.rstindex 1f2f84c4a..2467e96cd 100644--- a/docs/index.rst+++ b/docs/index.rst@@ -41,6 +41,7 @@ Main Documentationkey_modules/memory.mdkey_modules/tools.mdkey_modules/prompts.md+ key_modules/runtimes.mdkey_modules/tasks.mdkey_modules/loaders.mdkey_modules/storages.mddiff --git a/docs/key_modules/runtimes.md b/docs/key_modules/runtimes.mdnew file mode 100644index 000000000..e4ed74c29--- /dev/null+++ b/docs/key_modules/runtimes.md@@ -0,0 +1,150 @@+# Runtime++## 1. Concept+The runtime module in CAMEL allows functions and tools to be executed in+controlled environments, enabling the safe and isolated execution of code.+Modern AI systems, especially those involving autonomous agents, often+require more than just a simple Python interpreter. They may need to:++- Execute code with security checks to prevent malicious actions.+- Run tasks in isolated environments to manage dependencies or enhance+security (e.g., using Docker).+- Distribute computational load or access specialized resources by executing+functions on remote servers.+- Utilize sophisticated configuration management for various components.++The `camel.runtime` module addresses these needs by providing a collection of+runtime classes and supporting utilities. Each runtime offers a different+strategy for code or function execution, catering to various use cases within+the CAMEL ecosystem.++## 2. Types+Runtimes offer flexibility, isolation, and scalability by encapsulating+various execution contexts—such as local containers, cloud sandboxes,+remote servers, or guarded environments.+Each runtime implementation provides a standardized interface for adding+tools, executing commands, and managing the execution lifecycle.++### 2.1 The Base Runtime: `BaseRuntime`+All runtimes inherit from the BaseRuntime abstract class, which defines the+following core methods:++- `add(funcs)`: Registers one or more FunctionTool objects for execution++- `reset()`: Resets the runtime environment to its initial state++- `get_tools()`: Returns the list of tools managed by the runtime++### 2.2 `LLMGuardRuntime`+The `LLMGuardRuntime` is a runtime environment designed to evaluate+the potential risks associated with executing functions and tools,+particularly those that might be dynamically called by AI agents+(e.g., tool calls that write codes).+`LLMGuardRuntime` leverages a customizable LLM to+perform this risk assessment.++**Key Features:**+- Risk scores from 1 (safe) to 3 (dangerous)+- Threshold control for execution permission+- Pre-configured system prompt + structured tool for safety++### 2.3 `DockerRuntime`+The `DockerRuntime` provides a mechanism to+execute CAMEL agents or arbitrary tasks+within isolated Docker containers. This approach is highly beneficial+for managing complex dependencies,+ensuring reproducibility of experiments or agent behavior,+and enhancing security by sandboxing execution.++**Key Features**+- FastAPI server for tool exposure+- Automatic container lifecycle management via Python interface++### 2.4 `UbuntuDockerRuntime`+A specialization of `DockerRuntime` optimized for Ubuntu containers.+Adds system package installation, Python version checks,+and support for full script execution.++**Key Features**+- Preconfigures environment variables like `PYTHON_EXECUTABLE` and `PYTHONPATH`+- Supports full `.py` script execution with `exec_python_file()`+- Maintains all capabilities of DockerRuntime.++### 2.5 `RemoteHttpRuntime`+The `RemoteHttpRuntime` facilitates the execution of functions on a separate,+remote HTTP server.++**Key Features**+- Enables remote execution of tools via simple HTTP APIs+- Built on FastAPI for easy integration and rapid deployment+ of HTTP-based function execution endpoints++### 2.6 `DaytonaRuntime`+`DaytonaRuntime` uses the official daytona_sdk to create sandboxes and run user+functions inside them securely.+Each tool is uploaded as source code and executed with controlled input/output+handling.++**Key Features**+- Uploads and runs source code remotely+- Cloud-managed runtime with safety guarantees++## 3. Get Started+We'll use `RemoteHttpRuntime` as a quick examples of how to use+`runtime` module.++A runtime can be initialized with the following code. Here we use+`MathToolkit` as an example for our tools. You can use any arbitrary tools as+long as they follow the `FunctionTool` type defined by CAMEL (see [tools](+./tools.md)+module document for more details.)+```+from camel.runtime import RemoteHttpRuntime+from camel.toolkits import MathToolkit++if __name__ == "__main__":+ runtime = (+ RemoteHttpRuntime("localhost")+ .add(MathToolkit().get_tools(), "camel.toolkits.MathToolkit")+ .build()+ )++ # It might take sometime for the runtime to start+ print("Waiting for runtime to be ready...")+ runtime.wait()+ print("Runtime is ready.")+ # Example Output:+ # Waiting for runtime to be ready...+ # Runtime is ready.+```+++The tools can then be called using the code below,+following the same syntax as normal tool calls without a runtime.++```+ # There are more tools imported from MathToolkit.+ # For simplicity, we use only "add" tool here+ add = runtime.get_tools()[0]+ print(f"Add 1 + 2: {add.func(1, 2)}")++ # Example Output:+ # Add 1 + 2: 3+```++## 4. More Examples+Additional runtime usage examples can be found under the `examples/runtime/`+directory in our main repository. Each script demonstrates how to initialize+and use a specific runtime in CAMEL. These examples are simple,+self-contained, and can serve as starting points for real use cases.++## 5. Final Note+Currently, the runtime system is mainly designed to sandbox registered tool+functions only. If other parts of your agent involve+risky execution (e.g., direct code generation+and execution), you should consider handling sandboxing logic separately.++**Exception**: UbuntuDockerRuntime supports full Python script execution+through exec_python_file(). This makes it suitable for broader agent-level+sandboxing beyond `FunctionTool`, such as executing dynamically generated code+within a controlled container environment.