You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/en/Components/Tools.md
+66Lines changed: 66 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -53,6 +53,72 @@ Parameters:
53
53
54
54
- path: `str`, relative directory based on the `output` in yaml configuration. If empty, lists all files in the root directory.
55
55
56
+
### code_executor
57
+
58
+
Code execution tool that can run Python code either in a sandboxed environment or directly in the local Python environment. The behavior is controlled by the `tools.code_executor.implementation` field.
59
+
60
+
- When omitted or set to `sandbox`:
61
+
- Uses an [ms-enclave](https://github.com/modelscope/ms-enclave) based sandbox. The sandbox can be created locally with Docker or via a remote HTTP service.
62
+
- Currently supports two sandbox types: `docker` and `docker_notebook`. The former is suitable for non-interactive/stateless execution; the latter maintains notebook-style state across calls.
63
+
- The configured `output_dir` on the host is mounted into the sandbox at `/data` so code can read and write persistent artifacts there.
64
+
65
+
- When set to `python_env`:
66
+
- Runs code in the local Python environment. The tool API is aligned with the sandbox version and supports both Jupyter-kernel based execution and plain Python interpreter execution.
67
+
- Required dependencies should be installed locally; on the first run, common data-analysis and execution dependencies (such as `numpy`, `pandas`, etc.) will be installed automatically when missing.
68
+
69
+
#### notebook_executor
70
+
71
+
-**Sandbox mode**: Executes code inside a `docker_notebook` sandbox, preserving state (variables, imports, dataframes, etc.) across calls. Files under the mounted data directory are available at `/data/...`, and you can also run simple shell commands from code cells using the standard `!` prefix.
72
+
-**Local mode**: Executes code in a local Jupyter kernel, with environment isolation and state persistence across calls. In the notebook environment you can also use simple shell commands via the standard `!` syntax.
73
+
74
+
**Parameters**:
75
+
76
+
-**code**: `string` – Python code to execute.
77
+
-**description**: `string` – Short description of what the code is doing.
78
+
-**timeout**: `integer` – Optional execution timeout in seconds; if omitted, the tool-level default is used.
79
+
80
+
#### python_executor
81
+
82
+
-**Sandbox mode**: Executes Python code in a `docker`-type sandbox using the sandbox’s Python interpreter, typically used when you do not need full notebook-style interaction.
83
+
-**Local mode**: Executes code with the local Python interpreter in a stateless fashion; each call has its own execution context and does not share variables with previous calls.
84
+
85
+
**Parameters**:
86
+
87
+
-**code**: `string` – Python code to execute.
88
+
-**description**: `string` – Short description of what the code is doing.
89
+
-**timeout**: `integer` – Optional execution timeout in seconds; if omitted, the tool-level default is used.
90
+
91
+
#### shell_executor
92
+
93
+
-**Sandbox mode**: Dedicated to `docker`-type sandboxes and executes shell commands inside the sandbox using `bash`, supporting basic operations like `ls`, `cd`, `mkdir`, `rm`, etc., and access to files under `/data`.
94
+
-**Local mode**: Executes shell commands using the local `bash` interpreter with the working directory set to `output_dir`; this is convenient for development but generally not recommended for production.
95
+
96
+
**Parameters**:
97
+
98
+
-**command**: `string` – Shell command to execute.
99
+
-**timeout**: `integer` – Optional execution timeout in seconds; if omitted, the tool-level default is used.
100
+
101
+
#### file_operation
102
+
103
+
-**Sandbox mode**: Dedicated to `docker`-type sandboxes and performs basic file operations inside the sandbox (create, read, write, delete, list, exists). Paths are interpreted as sandbox-internal paths; in most cases you should work under `/data/...`.
104
+
-**Local mode**: Performs the same basic file operations on the local filesystem but always constrained under `output_dir` to prevent accessing arbitrary locations.
105
+
106
+
**Parameters**:
107
+
108
+
-**operation**: `string` – Type of file operation to perform; one of `'create'`, `'read'`, `'write'`, `'delete'`, `'list'`, `'exists'`.
109
+
-**file_path**: `string` – File or directory path (sandbox-internal in sandbox mode; relative to or under `output_dir` in local mode).
110
+
-**content**: `string` – Optional, content to write when `operation` is `'write'`.
-**Sandbox mode**: Recreates the sandbox (or restarts the notebook kernel) to clear all variables and session state when the environment becomes unstable.
116
+
-**Local mode**: Restarts the local Jupyter kernel used by `notebook_executor`, dropping all in-memory state.
117
+
118
+
#### get_executor_info
119
+
120
+
-**Sandbox mode**: Returns the current sandbox status and configuration summary (such as memory/CPU limits, available tools, etc.).
121
+
-**Local mode**: Returns basic information about the local execution environment (working directory, whether it is initialized, current execution count, uptime, etc.).
If you prefer not to install Docker and related dependencies, you can configure a local code execution tool instead. In both `analyst.yaml` and `collector.yaml`, change the default `tools` configuration to:
84
+
85
+
```yaml
86
+
tools:
87
+
code_executor:
88
+
mcp: false
89
+
implementation: python_env
90
+
exclude:
91
+
- python_executor
92
+
- shell_executor
93
+
- file_operation
94
+
```
95
+
96
+
With this configuration, code is executed via a Jupyter kernel–based notebook executor that isolates environment variables and supports shell command execution; the necessary dependencies (for data analysis and code execution) will be installed automatically on the first run.
97
+
98
+
If you only need a lighter-weight Python execution environment and do not want to introduce notebook-related dependencies, you can instead use:
99
+
100
+
```yaml
101
+
tools:
102
+
code_executor:
103
+
mcp: false
104
+
implementation: python_env
105
+
exclude:
106
+
- notebook_executor
107
+
- file_operation
108
+
```
109
+
110
+
This configuration uses an independent Python executor together with a shell command executor and is suitable for lightweight code execution scenarios.
111
+
81
112
### Environment Variables
82
113
83
114
Configure API keys in your system environment or in YAML.
0 commit comments