🐫 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"></a>
<a id="camel.toolkits.terminal_toolkit.TerminalToolkit"></a>
## TerminalToolkit
```python
class TerminalToolkit(BaseToolkit):
```
A toolkit for terminal operations across multiple operating systems.
This toolkit provides a set of functions for terminal operations such as
searching for files by name or content, executing shell commands, and
managing terminal sessions.
**Parameters:**
- **timeout** (Optional[float]): The timeout for terminal operations. (default: :obj:`20.0`)
- **shell_sessions** (Optional[Dict[str, Any]]): A dictionary to store shell session information. If :obj:`None`, an empty dictionary will be used. (default: :obj:`None`)
- **working_directory** (Optional[str]): The working directory for operations. If not provided, it will be determined by the `CAMEL_WORKDIR` environment variable (if set). If the environment variable is not set, it defaults to `./workspace`. All execution and write operations will be restricted to this directory. Read operations can access paths outside this directory. (default: :obj:`None`)
- **need_terminal** (bool): Whether to create a terminal interface. (default: :obj:`True`)
- **use_shell_mode** (bool): Whether to use shell mode for command execution. (default: :obj:`True`)
- **clone_current_env** (bool): Whether to clone the current Python environment. (default: :obj:`False`)
- **safe_mode** (bool): Whether to enable safe mode to restrict operations. (default: :obj:`True`)
- **interactive** (bool): Whether to use interactive mode for shell commands, connecting them to the terminal's standard input. This is useful for commands that require user input, like `ssh`. Interactive mode is only supported on macOS and Linux. (default: :obj:`False`)
- **log_dir** (Optional[str]): Custom directory path for log files. If None, logs are saved to the current working directory. (default: :obj:`None`)
**Note:**
Most functions are compatible with Unix-based systems (macOS, Linux).
For Windows compatibility, additional implementation details are
needed.
<a id="camel.toolkits.terminal_toolkit.TerminalToolkit.__init__"></a>
### __init__
```python
def __init__(
self,
timeout: Optional[float] = 20.0,
shell_sessions: Optional[Dict[str, Any]] = None,
working_directory: Optional[str] = None,
need_terminal: bool = True,
use_shell_mode: bool = True,
clone_current_env: bool = False,
safe_mode: bool = True,
interactive: bool = False,
log_dir: Optional[str] = None
):
```
<a id="camel.toolkits.terminal_toolkit.TerminalToolkit._setup_file_output"></a>
### _setup_file_output
```python
def _setup_file_output(self):
```
Set up file output to replace GUI, using a fixed file to simulate
terminal.
<a id="camel.toolkits.terminal_toolkit.TerminalToolkit._clone_current_environment"></a>
### _clone_current_environment
```python
def _clone_current_environment(self):
```
Create a new Python virtual environment.
<a id="camel.toolkits.terminal_toolkit.TerminalToolkit._is_uv_environment"></a>
### _is_uv_environment
```python
def _is_uv_environment(self):
```
Detect whether the current Python runtime is managed by uv.
<a id="camel.toolkits.terminal_toolkit.TerminalToolkit._ensure_uv_available"></a>
### _ensure_uv_available
```python
def _ensure_uv_available(self):
```
**Returns:**
bool: True if uv is available (either already installed or
successfully installed), False otherwise.
<a id="camel.toolkits.terminal_toolkit.TerminalToolkit._prepare_initial_environment"></a>
### _prepare_initial_environment
```python
def _prepare_initial_environment(self):
```
Prepare initial environment with Python 3.10, pip, and other
essential tools.
<a id="camel.toolkits.terminal_toolkit.TerminalToolkit._setup_initial_env_with_uv"></a>
### _setup_initial_env_with_uv
```python
def _setup_initial_env_with_uv(self):
```
Set up initial environment using uv.
<a id="camel.toolkits.terminal_toolkit.TerminalToolkit._setup_initial_env_with_venv"></a>
### _setup_initial_env_with_venv
```python
def _setup_initial_env_with_venv(self):
```
Set up initial environment using standard venv.
<a id="camel.toolkits.terminal_toolkit.TerminalToolkit._check_nodejs_availability"></a>
### _check_nodejs_availability
```python
def _check_nodejs_availability(self):
```
Check if Node.js is available without modifying the system.
<a id="camel.toolkits.terminal_toolkit.TerminalToolkit._create_terminal"></a>
### _create_terminal
```python
def _create_terminal(self):
```
Create a terminal GUI. If GUI creation fails, fallback
to file output.
<a id="camel.toolkits.terminal_toolkit.TerminalToolkit._update_terminal_output"></a>
### _update_terminal_output
```python
def _update_terminal_output(self, output: str):
```
Update terminal output and send to agent.
**Parameters:**
- **output** (str): The output to be sent to the agent
<a id="camel.toolkits.terminal_toolkit.TerminalToolkit._is_path_within_working_dir"></a>
### _is_path_within_working_dir
```python
def _is_path_within_working_dir(self, path: str):
```
Check if the path is within the working directory.
**Parameters:**
- **path** (str): The path to check
**Returns:**
bool: Returns True if the path is within the working directory,
otherwise returns False
<a id="camel.toolkits.terminal_toolkit.TerminalToolkit._enforce_working_dir_for_execution"></a>
### _enforce_working_dir_for_execution
```python
def _enforce_working_dir_for_execution(self, path: str):
```
Enforce working directory restrictions, return error message
if execution path is not within the working directory.
**Parameters:**
- **path** (str): The path to be used for executing operations
**Returns:**
Optional[str]: Returns error message if the path is not within
the working directory, otherwise returns None
<a id="camel.toolkits.terminal_toolkit.TerminalToolkit._copy_external_file_to_workdir"></a>
### _copy_external_file_to_workdir
```python
def _copy_external_file_to_workdir(self, external_file: str):
```
Copy external file to working directory.
**Parameters:**
- **external_file** (str): The path of the external file
**Returns:**
Optional[str]: New path after copying to the working directory,
returns None on failure
<a id="camel.toolkits.terminal_toolkit.TerminalToolkit._sanitize_command"></a>
### _sanitize_command
```python
def _sanitize_command(self, command: str, exec_dir: str):
```
Check and modify command to ensure safety.
**Parameters:**
- **command** (str): The command to check
- **exec_dir** (str): The directory to execute the command in
**Returns:**
Tuple: (is safe, modified command or error message)
<a id="camel.toolkits.terminal_toolkit.TerminalToolkit.shell_exec"></a>
### shell_exec
```python
def shell_exec(self, id: str, command: str):
```
Executes a shell command in a specified session.
This function creates and manages shell sessions to execute commands,
simulating a real terminal. The behavior depends on the toolkit's
interactive mode setting. Each session is identified by a unique ID.
If a session with the given ID does not exist, it will be created.
**Parameters:**
- **id** (str): A unique identifier for the shell session. This is used to manage multiple concurrent shell processes.
- **command** (str): The shell command to be executed.
**Returns:**
str: The standard output and standard error from the command. If an
error occurs during execution, a descriptive error message is
returned.
**Note:**
When the toolkit is initialized with interactive mode, commands may
block if they require input. In safe mode, some commands that are
considered dangerous are restricted.
<a id="camel.toolkits.terminal_toolkit.TerminalToolkit.shell_view"></a>
### shell_view
```python
def shell_view(self, id: str):
```
View the full output history of a specified shell session.
Retrieves the accumulated output (both stdout and stderr) generated by
commands in the specified session since its creation. This is useful
for checking the complete history of a session, especially after a
command has finished execution.
**Parameters:**
- **id** (str): The unique identifier of the shell session to view.
**Returns:**
str: The complete output history of the shell session. Returns an
error message if the session is not found.
<a id="camel.toolkits.terminal_toolkit.TerminalToolkit.shell_wait"></a>
### shell_wait
```python
def shell_wait(self, id: str, seconds: Optional[int] = None):
```
Wait for a command to finish in a specified shell session.
Blocks execution and waits for the running process in a shell session
to complete. This is useful for ensuring a long-running command has
finished before proceeding.
**Parameters:**
- **id** (str): The unique identifier of the target shell session.
- **seconds** (Optional[int], optional): The maximum time to wait, in seconds. If `None`, it waits indefinitely. (default: :obj:`None`)
**Returns:**
str: A message indicating that the process has completed, including
the final output. If the process times out, it returns a
timeout message.
<a id="camel.toolkits.terminal_toolkit.TerminalToolkit.shell_write_to_process"></a>
### shell_write_to_process
```python
def shell_write_to_process(
self,
id: str,
input: str,
press_enter: bool
):
```
Write input to a running process in a specified shell session.
Sends a string of text to the standard input of a running process.
This is useful for interacting with commands that require input. This
function cannot be used with a command that was started in
interactive mode.
**Parameters:**
- **id** (str): The unique identifier of the target shell session.
- **input** (str): The text to write to the process's stdin.
- **press_enter** (bool): If `True`, a newline character (`\n`) is appended to the input, simulating pressing the Enter key.
**Returns:**
str: A status message indicating whether the input was sent, or an
error message if the operation fails.
<a id="camel.toolkits.terminal_toolkit.TerminalToolkit.shell_kill_process"></a>
### shell_kill_process
```python
def shell_kill_process(self, id: str):
```
Terminate a running process in a specified shell session.
Forcibly stops a command that is currently running in a shell session.
This is useful for ending processes that are stuck, running too long,
or need to be cancelled.
**Parameters:**
- **id** (str): The unique identifier of the shell session containing the process to be terminated.
**Returns:**
str: A status message indicating that the process has been
terminated, or an error message if the operation fails.
<a id="camel.toolkits.terminal_toolkit.TerminalToolkit.ask_user_for_help"></a>
### ask_user_for_help
```python
def ask_user_for_help(self, id: str):
```
Pause the agent and ask a human for help with a command.
This function should be used when the agent is stuck and requires
manual intervention, such as solving a CAPTCHA or debugging a complex
issue. It pauses the agent's execution and allows a human to take
control of a specified shell session. The human can execute one
command to resolve the issue, and then control is returned to the
agent.
**Parameters:**
- **id** (str): The identifier of the shell session for the human to interact with. If the session does not exist, it will be created.
**Returns:**
str: A status message indicating that the human has finished,
including the number of commands executed. If the takeover
times out or fails, an error message is returned.
<a id="camel.toolkits.terminal_toolkit.TerminalToolkit.__del__"></a>
### __del__
```python
def __del__(self):
```
Clean up resources when the object is being destroyed.
Terminates all running processes and closes any open file handles.
<a id="camel.toolkits.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.