🐫 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
<a id="camel.toolkits.terminal_toolkit.terminal_toolkit"></a>
<a id="camel.toolkits.terminal_toolkit.terminal_toolkit._to_plain"></a>
## _to_plain
```python
def _to_plain(text: str):
```
Convert ANSI text to plain text using rich if available.
<a id="camel.toolkits.terminal_toolkit.terminal_toolkit._default_console_approval"></a>
## _default_console_approval
```python
def _default_console_approval(command: str):
```
Ask for approval in a terminal; deny non-interactive input.
**Parameters:**
- **command** (str): The command or process input requesting approval.
**Returns:**
bool: Whether the user explicitly approved the input.
<a id="camel.toolkits.terminal_toolkit.terminal_toolkit.TerminalToolkit"></a>
## TerminalToolkit
```python
class TerminalToolkit(BaseToolkit):
```
A toolkit for LLM agents to execute and interact with terminal commands
in either a local or a sandboxed Docker environment.
**Parameters:**
- **timeout** (Optional[float]): The default timeout in seconds for blocking commands. Defaults to 20.0.
- **working_directory** (Optional[str]): The base directory for operations. For the local backend, this acts as a security sandbox. For the Docker backend, this sets the working directory inside the container. If not specified, defaults to "./workspace" for local and "/workspace" for Docker.
- **use_docker_backend** (bool): If True, all commands are executed in a Docker container. Defaults to False.
- **docker_container_name** (Optional[str]): The name of the Docker container to use. Required if use_docker_backend is True.
- **session_logs_dir** (Optional[str]): The directory to store session logs. Defaults to a 'terminal_logs' subfolder in the working directory.
- **safe_mode** (bool): Whether to apply security checks to commands. Defaults to True.
- **allowed_commands** (Optional[List[str]]): List of allowed commands when safe_mode is True. If None, uses default safety rules.
- **clone_current_env** (bool): Whether to clone the current Python environment for local execution. Defaults to False.
- **install_dependencies** (List): A list of user specified libraries to install.
- **enable_other_runtimes** (list[Runtime]): List of additional language runtimes to auto-install. Supported values are `__INLINE_CODE_0____INLINE_CODE_1____INLINE_CODE_2____INLINE_CODE_3____INLINE_CODE_4__`.
- **require_approval** (Optional[Callable[[str], bool]], optional): Callback checked before starting a shell command or sending process input. Receives the sanitized command for :obj:`shell_exec`, or the raw input for :obj:`shell_write_to_process`. Return True to allow it; exceptions propagate without executing the command or input. None disables approval. Pass :obj:`_default_console_approval` for interactive approval; non-interactive applications should provide their own callback. This does not restrict actions performed internally by an approved program or replace sandbox isolation. (default: :obj:`None`)
<a id="camel.toolkits.terminal_toolkit.terminal_toolkit.TerminalToolkit.__init__"></a>
### __init__
```python
def __init__(
self,
timeout: Optional[float] = 20.0,
working_directory: Optional[str] = None,
use_docker_backend: bool = False,
docker_container_name: Optional[str] = None,
session_logs_dir: Optional[str] = None,
safe_mode: bool = True,
allowed_commands: Optional[List[str]] = None,
clone_current_env: bool = False,
install_dependencies: Optional[List[str]] = None,
enable_other_runtimes: list[Runtime] | None = None,
require_approval: Optional[Callable[[str], bool]] = None
):
```
<a id="camel.toolkits.terminal_toolkit.terminal_toolkit.TerminalToolkit._setup_cloned_environment"></a>
### _setup_cloned_environment
```python
def _setup_cloned_environment(self):
```
Set up a cloned Python environment.
<a id="camel.toolkits.terminal_toolkit.terminal_toolkit.TerminalToolkit._install_dependencies"></a>
### _install_dependencies
```python
def _install_dependencies(self):
```
Install user specified dependencies in the current environment.
<a id="camel.toolkits.terminal_toolkit.terminal_toolkit.TerminalToolkit._setup_initial_environment"></a>
### _setup_initial_environment
```python
def _setup_initial_environment(self):
```
Set up an initial environment with Python 3.10.
<a id="camel.toolkits.terminal_toolkit.terminal_toolkit.TerminalToolkit._setup_optional_runtimes"></a>
### _setup_optional_runtimes
```python
def _setup_optional_runtimes(self, update_callback):
```
Set up Go and/or Java runtimes if requested.
Stores runtime paths in `__INLINE_CODE_0__` instead of
mutating the process-global `__INLINE_CODE_1__`, so only commands
launched by this toolkit instance see the extra paths.
**Parameters:**
- **update_callback**: Callback for status messages.
<a id="camel.toolkits.terminal_toolkit.terminal_toolkit.TerminalToolkit._get_env_vars"></a>
### _get_env_vars
```python
def _get_env_vars(self):
```
**Returns:**
dict[str, str]: Environment variables for subprocess.
<a id="camel.toolkits.terminal_toolkit.terminal_toolkit.TerminalToolkit._get_venv_path"></a>
### _get_venv_path
```python
def _get_venv_path(self):
```
Get the virtual environment path if available.
<a id="camel.toolkits.terminal_toolkit.terminal_toolkit.TerminalToolkit._write_to_log"></a>
### _write_to_log
```python
def _write_to_log(self, log_file: str, content: str):
```
Write content to log file with optional ANSI stripping.
**Parameters:**
- **log_file** (str): Path to the log file
- **content** (str): Content to write
<a id="camel.toolkits.terminal_toolkit.terminal_toolkit.TerminalToolkit._docker_exec"></a>
### _docker_exec
```python
def _docker_exec(self, command: str):
```
Execute a command in the Docker container and return the result.
Consolidates the repeated `__INLINE_CODE_0__`
pattern into a single helper, reducing code duplication and improving
error handling consistency.
**Parameters:**
- **command**: The shell command to execute inside the container.
- **check_exit_code**: If True, raises RuntimeError on non-zero exit.
**Returns:**
A tuple of (exit_code, output_bytes). The exit code is `__INLINE_CODE_0__`
when `__INLINE_CODE_1__` is False.
<a id="camel.toolkits.terminal_toolkit.terminal_toolkit.TerminalToolkit._approve_command"></a>
### _approve_command
```python
def _approve_command(self, command: str):
```
Check approval for a command or process input.
<a id="camel.toolkits.terminal_toolkit.terminal_toolkit.TerminalToolkit._sanitize_command"></a>
### _sanitize_command
```python
def _sanitize_command(self, command: str):
```
A comprehensive command sanitizer for both local and
Docker backends.
<a id="camel.toolkits.terminal_toolkit.terminal_toolkit.TerminalToolkit._start_output_reader_thread"></a>
### _start_output_reader_thread
```python
def _start_output_reader_thread(self, session_id: str):
```
Starts a thread to read stdout from a non-blocking process.
<a id="camel.toolkits.terminal_toolkit.terminal_toolkit.TerminalToolkit._collect_output_until_idle"></a>
### _collect_output_until_idle
```python
def _collect_output_until_idle(
self,
id: str,
idle_duration: float = 0.5,
max_wait: float = 5.0
):
```
Collects output from a session until it's idle or a max wait time
is reached.
**Parameters:**
- **id** (str): The session ID.
- **idle_duration** (float): How long the stream must be empty to be considered idle.(default: 0.5)
- **max_wait** (float): The maximum total time to wait for the process to go idle. (default: 5.0)
**Returns:**
str: The collected output. If max_wait is reached while
the process is still outputting, a warning is appended.
<a id="camel.toolkits.terminal_toolkit.terminal_toolkit.TerminalToolkit.shell_exec"></a>
### shell_exec
```python
def shell_exec(
self,
id: str,
command: str,
block: bool = True,
timeout: float = 20.0
):
```
Executes a shell command in blocking or non-blocking mode.
**Parameters:**
- **id** (str): A unique identifier for the command's session. This ID is used to interact with non-blocking processes.
- **command** (str): The shell command to execute.
- **block** (bool, optional): Determines the execution mode. Defaults to True. If `True` (blocking mode), the function waits for the command to complete and returns the full output. Use this for most commands. If `False` (non-blocking mode), the function starts the command in the background. Use this only for interactive sessions or long-running tasks, or servers.
- **timeout** (float, optional): The maximum time in seconds to wait for the command to complete in blocking mode. If the command does not complete within the timeout, it will be converted to a tracked background session (process keeps running without restart). You can then use `shell_view(id)` to check output, or `shell_kill_process(id)` to terminate it. This parameter is ignored in non-blocking mode. (default: :obj:`20`)
**Returns:**
str: The output of the command execution, which varies by mode.
In blocking mode, returns the complete standard output and
standard error from the command.
In non-blocking mode, returns a confirmation message with the
session `id`. To interact with the background process, use
other functions: `shell_view(id)` to see output,
`shell_write_to_process(id, "input")` to send input, and
`shell_kill_process(id)` to terminate.
<a id="camel.toolkits.terminal_toolkit.terminal_toolkit.TerminalToolkit.shell_write_to_process"></a>
### shell_write_to_process
```python
def shell_write_to_process(self, id: str, command: str):
```
This function sends command to a running non-blocking
process and returns the resulting output after the process
becomes idle again. A newline \n is automatically appended
to the input command.
**Parameters:**
- **id** (str): The unique session ID of the non-blocking process.
- **command** (str): The text to write to the process's standard input.
**Returns:**
str: The output from the process after the command is sent.
<a id="camel.toolkits.terminal_toolkit.terminal_toolkit.TerminalToolkit.shell_view"></a>
### shell_view
```python
def shell_view(self, id: str):
```
Retrieves new output from a non-blocking session.
This function returns only NEW output since the last call. It does NOT
wait or block - it returns immediately with whatever is available.
**Parameters:**
- **id** (str): The unique session ID of the non-blocking process.
**Returns:**
str: New output if available, or a status message.
<a id="camel.toolkits.terminal_toolkit.terminal_toolkit.TerminalToolkit.shell_kill_process"></a>
### shell_kill_process
```python
def shell_kill_process(self, id: str):
```
This function forcibly terminates a running non-blocking process.
**Parameters:**
- **id** (str): The unique session ID of the process to kill.
**Returns:**
str: A confirmation message indicating the process was terminated.
<a id="camel.toolkits.terminal_toolkit.terminal_toolkit.TerminalToolkit.shell_ask_user_for_help"></a>
### shell_ask_user_for_help
```python
def shell_ask_user_for_help(self, id: str, prompt: str):
```
This function pauses execution and asks a human for help
with an interactive session.
This method can handle different scenarios:
1. If session exists: Shows session output and allows interaction
2. If session doesn't exist: Creates a temporary session for help
**Parameters:**
- **id** (str): The session ID of the interactive process needing help. Can be empty string for general help without session context.
- **prompt** (str): The question or instruction from the LLM to show the human user (e.g., "The program is asking for a filename. Please enter 'config.json'.").
**Returns:**
str: The output from the shell session after the user's command has
been executed, or help information for general queries.
<a id="camel.toolkits.terminal_toolkit.terminal_toolkit.TerminalToolkit.shell_write_content_to_file"></a>
### shell_write_content_to_file
```python
def shell_write_content_to_file(self, content: str, file_path: str):
```
Writes the specified content to a file at the given path.
**Parameters:**
- **content** (str): The content to write to the file.
- **file_path** (str): The path to the file where the content should be written. Can be absolute or relative to working_dir.
**Returns:**
str: A confirmation message indicating success or an error message.
<a id="camel.toolkits.terminal_toolkit.terminal_toolkit.TerminalToolkit.__enter__"></a>
### __enter__
```python
def __enter__(self):
```
Context manager entry.
<a id="camel.toolkits.terminal_toolkit.terminal_toolkit.TerminalToolkit.__exit__"></a>
### __exit__
```python
def __exit__(
self,
exc_type,
exc_val,
exc_tb
):
```
Context manager exit - clean up all sessions.
<a id="camel.toolkits.terminal_toolkit.terminal_toolkit.TerminalToolkit.cleanup"></a>
### cleanup
```python
def cleanup(self):
```
Clean up all active sessions.
<a id="camel.toolkits.terminal_toolkit.terminal_toolkit.TerminalToolkit.__del__"></a>
### __del__
```python
def __del__(self):
```
Fallback cleanup in destructor.
<a id="camel.toolkits.terminal_toolkit.terminal_toolkit.TerminalToolkit.get_tools"></a>
### get_tools
```python
def get_tools(self):
```
**Returns:**
List[FunctionTool]: A list of FunctionTool objects representing the
functions in the toolkit.