🐫 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
Auto-update documentation after merge
camel-docs-bot5e3d895342a8
diff --git a/docs/reference/camel.toolkits.terminal_toolkit.md b/docs/reference/camel.toolkits.terminal_toolkit.mdindex 0ba14427f..43dcf5676 100644--- a/docs/reference/camel.toolkits.terminal_toolkit.md+++ b/docs/reference/camel.toolkits.terminal_toolkit.md@@ -164,17 +164,23 @@ def file_find_in_content():```-Search for matching text within file content.+Search for text within a file's content using a regular expression.++This function is useful for finding specific patterns or lines of text+within a given file. It uses `grep` on Unix-like systems and `findstr`+on Windows.**Parameters:**-- **file** (str): Absolute path of the file to search within.-- **regex** (str): Regular expression pattern to match.-- **sudo** (bool, optional): Whether to use sudo privileges. Defaults to False. Note: Using sudo requires the process to have appropriate permissions.+- **file** (str): The absolute path of the file to search within.+- **regex** (str): The regular expression pattern to match.+- **sudo** (bool, optional): Whether to use sudo privileges for the search. Defaults to False. Note: Using sudo requires the process to have appropriate permissions. (default: :obj:`False`)**Returns:**- str: Matching content found in the file.+ str: The matching content found in the file. If no matches are+found, an empty string is returned. Returns an error message+if the file does not exist or another error occurs.<a id="camel.toolkits.terminal_toolkit.TerminalToolkit.file_find_by_name"></a>@@ -184,16 +190,22 @@ Search for matching text within file content.def file_find_by_name(self, path: str, glob: str):```-Find files by name pattern in specified directory.+Find files by name in a specified directory using a glob pattern.++This function recursively searches for files matching a given name or+pattern within a directory. It uses `find` on Unix-like systems and+`dir` on Windows.**Parameters:**-- **path** (str): Absolute path of directory to search.-- **glob** (str): Filename pattern using glob syntax wildcards.+- **path** (str): The absolute path of the directory to search in.+- **glob** (str): The filename pattern to search for, using glob syntax (e.g., "*.py", "data*").**Returns:**- str: List of files matching the pattern.+ str: A newline-separated string containing the paths of the files+that match the pattern. Returns an error message if the+directory does not exist or another error occurs.<a id="camel.toolkits.terminal_toolkit.TerminalToolkit._sanitize_command"></a>@@ -219,20 +231,39 @@ Check and modify command to ensure safety.### shell_exec```python-def shell_exec(self, id: str, command: str):+def shell_exec(+ self,+ id: str,+ command: str,+ interactive: bool = False+):```-Execute commands. This can be used to execute various commands,-such as writing code, executing code, and running commands.+Executes a shell command in a specified session.++This function creates and manages shell sessions to execute commands,+simulating a real terminal. It can run commands in both non-interactive+(capturing output) and interactive modes. 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): Unique identifier of the target shell session.-- **command** (str): Shell command to execute.+- **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.+- **interactive** (bool, optional): If `True`, the command runs in interactive mode, connecting it to the terminal's standard input. This is useful for commands that require user input, like `ssh`. Defaults to `False`. Interactive mode is only supported on macOS and Linux. (default: :obj:`False`)**Returns:**- str: Output of the command execution or error message.+ str: The standard output and standard error from the command. If an+error occurs during execution, a descriptive error message is+returned.++**Note:**++When `interactive` is set to `True`, this function may block if the+command requires input. In safe mode, some commands that are+considered dangerous are restricted.<a id="camel.toolkits.terminal_toolkit.TerminalToolkit.shell_view"></a>@@ -242,15 +273,21 @@ such as writing code, executing code, and running commands.def shell_view(self, id: str):```-View the content of a specified shell session.+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): Unique identifier of the target shell session.+- **id** (str): The unique identifier of the shell session to view.**Returns:**- str: Current output content of the shell session.+ 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>@@ -260,17 +297,22 @@ View the content of a specified shell session.def shell_wait(self, id: str, seconds: Optional[int] = None):```-Wait for the running process in a specified shell session to-return.+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): Unique identifier of the target shell session.-- **seconds** (Optional[int], optional): Wait duration in seconds. If None, wait indefinitely. Defaults to None.+- **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: Final output content after waiting.+ 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>@@ -287,15 +329,21 @@ def shell_write_to_process(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): Unique identifier of the target shell session.-- **input** (str): Input content to write to the process.-- **press_enter** (bool): Whether to press Enter key after input.+- **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: Status message indicating whether the input was sent.+ 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>@@ -307,13 +355,18 @@ 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): Unique identifier of the target shell session.+- **id** (str): The unique identifier of the shell session containing the process to be terminated.**Returns:**- str: Status message indicating whether the process was terminated.+ 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>@@ -323,22 +376,24 @@ Terminate a running process in a specified shell session.def ask_user_for_help(self, id: str):```-Pauses agent execution to ask a human for help in the terminal.+Pause the agent and ask a human for help with a command.-This function should be called when an agent is stuck or needs-assistance with a task that requires manual intervention (e.g.,-solving a CAPTCHA or complex debugging). The human will take over the-specified terminal session to execute commands and then return control-to the agent.+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): Identifier of the shell session for the human to interact with. If the session does not yet exist, it will be created automatically.+- **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.+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>