Skip to content

armgit / camel

Public Imported from GitHub
0

🐫 CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org

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.md
index 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>