[FEAT][Bash tool for agent.auto] [Docs]

kyegomez · kyegomez · commit 4d6301ac73bd · 2026-02-02T18:50:40.000-05:00
diff --git a/docs/examples/autonomous_looper_run_bash_tutorial.md b/docs/examples/autonomous_looper_run_bash_tutorial.md
@@ -0,0 +1,68 @@
+# Run Bash Tool Tutorial
+
+Use the **`run_bash`** tool so an autonomous agent can run shell commands on the terminal.
+
+## When to use it
+
+- The agent needs to run CLI commands (e.g. `ls`, `python script.py`, `git status`).
+- You use `max_loops="auto"` and want the agent to have terminal access.
+- You want to keep other tools restricted and only add bash execution.
+
+## Enable the tool
+
+Include `"run_bash"` in `selected_tools` when creating the agent:
+
+```python
+from swarms import Agent
+
+agent = Agent(
+    agent_name="Terminal-Agent",
+    agent_description="Agent that can run bash commands on the terminal",
+    model_name="anthropic/claude-sonnet-4-5",
+    max_loops="auto",
+    dynamic_context_window=True,
+    selected_tools=[
+        "create_plan",
+        "think",
+        "subtask_done",
+        "complete_task",
+        "respond_to_user",
+        "read_file",
+        "list_directory",
+        "run_bash",
+    ],
+)
+```
+
+## Run a task
+
+The agent will plan and call `run_bash` when it needs to run a command:
+
+```python
+result = agent.run(
+    task="Use the terminal to list the current directory, then run 'echo Hello from bash' and report the output."
+)
+print(result)
+```
+
+## Tool parameters
+
+| Parameter           | Type    | Description |
+|--------------------|---------|-------------|
+| `command`           | string  | The bash/shell command to run (e.g. `ls -la`, `python script.py`). |
+| `timeout_seconds`  | integer | (Optional) Max seconds to wait; default is 60. |
+
+Commands run in the agent’s workspace directory when available. Stdout and stderr are returned; long-running commands should use a higher `timeout_seconds` or be avoided.
+
+## Example file
+
+A full runnable example is in the repo:
+
+```
+v9_examples/example_autonomous_looper_run_bash.py
+```
+
+## See also
+
+- [Autonomous Looper Tools](autonomous_looper_tools.md) – Configuring `selected_tools`
+- [Agent Reference](../swarms/structs/agent.md) – `selected_tools` and autonomous loop
diff --git a/docs/examples/autonomous_looper_tools.md b/docs/examples/autonomous_looper_tools.md
@@ -25,6 +25,9 @@ The `selected_tools` parameter gives you fine-grained control over which tools t
 | `read_file` | Read the contents of a file |
 | `list_directory` | List files and directories in a path |
 | `delete_file` | Delete a file (use with caution) |
+| `run_bash` | Execute bash/shell commands on the terminal (returns stdout/stderr) |
+| `create_sub_agent` | Create specialized sub-agents for delegation |
+| `assign_task` | Assign tasks to sub-agents for asynchronous execution |
 
 ## Usage
 
@@ -79,6 +82,30 @@ agent = Agent(
 )
 ```
 
+### File Operations + Terminal (run_bash)
+
+Enable file operations and terminal command execution:
+
+```python
+agent = Agent(
+    agent_name="File-and-Terminal-Agent",
+    model_name="anthropic/claude-sonnet-4-5",
+    max_loops="auto",
+    selected_tools=[
+        "create_plan",
+        "think",
+        "subtask_done",
+        "complete_task",
+        "respond_to_user",
+        "create_file",
+        "update_file",
+        "read_file",
+        "list_directory",
+        "run_bash",
+    ],
+)
+```
+
 ### Minimal Configuration
 
 ```python
@@ -153,6 +180,28 @@ analysis_agent = Agent(
 )
 ```
 
+### Terminal / DevOps Agent (With run_bash)
+For agents that need to run shell commands (e.g. scripts, CLI tools, git):
+
+```python
+terminal_agent = Agent(
+    agent_name="Terminal-Agent",
+    max_loops="auto",
+    selected_tools=[
+        "create_plan",
+        "think",
+        "subtask_done",
+        "complete_task",
+        "respond_to_user",
+        "read_file",
+        "list_directory",
+        "run_bash",
+    ],
+)
+```
+
+See [Run Bash Tool Tutorial](autonomous_looper_run_bash_tutorial.md) for a step-by-step guide.
+
 ## Best Practices
 
 1. **Start Restrictive**: Begin with a minimal set of tools and add more as needed
@@ -169,6 +218,7 @@ analysis_agent = Agent(
 
 ## See Also
 
+- [Run Bash Tool Tutorial](autonomous_looper_run_bash_tutorial.md) – Using `run_bash` to execute terminal commands
 - [Autonomous Loop Documentation](./autonomous_loop.md)
 - [Agent Configuration Guide](./agent_configuration.md)
 - [Tool System Overview](./tools.md)
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
@@ -328,6 +328,7 @@ nav:
       - Overview: "swarms_tools/overview.md"
       - BaseTool Reference: "swarms/tools/base_tool.md"
       - MCP Client Utils: "swarms/tools/mcp_client_call.md"
+      - Run Bash Tool Tutorial: "examples/autonomous_looper_run_bash_tutorial.md"
 
       - Vertical Tools:
         - Finance: "swarms_tools/finance.md"
diff --git a/docs/swarms/structs/agent.md b/docs/swarms/structs/agent.md
@@ -143,7 +143,7 @@ The `Agent` class establishes a conversational loop with a language model, allow
 | `mode` | `Literal["interactive", "fast", "standard"]` | Execution mode: "interactive" for real-time interaction, "fast" for optimized performance, "standard" for default behavior. |
 | `publish_to_marketplace` | `bool` | Boolean indicating whether to publish the agent's prompt to the Swarms marketplace. |
 | `marketplace_prompt_id` | `Optional[str]` | Unique UUID identifier of a prompt from the Swarms marketplace. When provided, the agent will automatically fetch and load the prompt as the system prompt. |
-| `selected_tools` | `Optional[Union[str, List[str]]]` | Controls which tools are available in autonomous mode (`max_loops="auto"`). Use `"all"` for all tools or provide a list of specific tool names. Available tools: `"create_plan"`, `"think"`, `"subtask_done"`, `"complete_task"`, `"respond_to_user"`, `"create_file"`, `"update_file"`, `"read_file"`, `"list_directory"`, `"delete_file"`, `"create_sub_agent"`, `"assign_task"`. |
+| `selected_tools` | `Optional[Union[str, List[str]]]` | Controls which tools are available in autonomous mode (`max_loops="auto"`). Use `"all"` for all tools or provide a list of specific tool names. Available tools: `"create_plan"`, `"think"`, `"subtask_done"`, `"complete_task"`, `"respond_to_user"`, `"create_file"`, `"update_file"`, `"read_file"`, `"list_directory"`, `"delete_file"`, `"run_bash"`, `"create_sub_agent"`, `"assign_task"`. |
 
 ## `Agent` Methods
 
@@ -848,6 +848,7 @@ When `max_loops="auto"` and `interactive=False`, the agent has access to special
 | `read_file` | Read the contents of a file | `file_path` (str) |
 | `list_directory` | List files and directories in a specified path | `directory_path` (str, optional) |
 | `delete_file` | Delete a file (with safety checks) | `file_path` (str) |
+| `run_bash` | Execute a bash/shell command on the terminal (returns stdout/stderr) | `command` (str), `timeout_seconds` (int, optional, default 60) |
 | `create_sub_agent` | Create specialized sub-agents for task delegation | `agents` (array): list of agent specs with `agent_name` (str), `agent_description` (str), `system_prompt` (str, optional) |
 | `assign_task` | Assign tasks to sub-agents for asynchronous execution | `assignments` (array): list with `agent_id` (str), `task` (str), `task_id` (str, optional); `wait_for_completion` (bool, optional) |
 
diff --git a/example_autonomous_looper_run_bash.py b/example_autonomous_looper_run_bash.py
@@ -0,0 +1,36 @@
+"""
+Example: Autonomous looper using the run_bash tool
+
+This example shows an agent with max_loops="auto" that can execute
+terminal commands via the run_bash tool. The agent plans and runs
+shell commands to complete the task.
+"""
+
+from swarms import Agent
+
+# Agent with autonomous looping and terminal (bash) access
+agent = Agent(
+    agent_name="Terminal-Agent",
+    agent_description="Agent that can plan tasks and run bash commands on the terminal",
+    model_name="anthropic/claude-sonnet-4-5",
+    dynamic_temperature_enabled=True,
+    max_loops="auto",
+    dynamic_context_window=True,
+    selected_tools=[
+        "create_plan",
+        "think",
+        "subtask_done",
+        "complete_task",
+        "respond_to_user",
+        "read_file",
+        "list_directory",
+        "run_bash",
+    ],
+    top_p=None,
+)
+
+if __name__ == "__main__":
+    result = agent.run(
+        task="Use the terminal to list the current directory, and see what files are in it."
+    )
+    print(result)
diff --git a/swarms/structs/agent.py b/swarms/structs/agent.py
@@ -77,6 +77,7 @@
     list_directory_tool,
     read_file_tool,
     respond_to_user_tool,
+    run_bash_tool,
     update_file_tool,
 )
 from swarms.structs.conversation import Conversation
@@ -276,8 +277,8 @@ class Agent:
             Example: skills_dir="./skills" loads from ./skills/*/SKILL.md
         selected_tools (Union[str, List[str]]): Tools to enable for the autonomous looper when max_loops="auto".
             Available tools: "create_plan", "think", "subtask_done", "complete_task", "respond_to_user",
-            "create_file", "update_file", "read_file", "list_directory", "delete_file", "create_sub_agent",
-            "assign_task".
+            "create_file", "update_file", "read_file", "list_directory", "delete_file", "run_bash",
+            "create_sub_agent", "assign_task".
             Defaults to "all" (all tools enabled). Pass a list of tool names to restrict tools, or "all"
             for unrestricted access. Use this to control which tools the agent can use during autonomous execution.
 
@@ -2297,6 +2298,9 @@ def _run_autonomous_loop(
                 "delete_file": lambda **kwargs: delete_file_tool(
                     self, **kwargs
                 ),
+                "run_bash": lambda **kwargs: run_bash_tool(
+                    self, **kwargs
+                ),
                 "create_sub_agent": lambda **kwargs: create_sub_agent_tool(
                     self, **kwargs
                 ),
diff --git a/swarms/structs/autonomous_loop_utils.py b/swarms/structs/autonomous_loop_utils.py
@@ -20,12 +20,14 @@
 - read_file: Read file contents
 - list_directory: List directory contents
 - delete_file: Delete files
+- run_bash: Execute bash/shell commands on the terminal
 - create_sub_agent: Create specialized sub-agents for delegation
 - assign_task: Assign tasks to sub-agents asynchronously
 """
 
 import asyncio
 import os
+import subprocess
 from typing import Any, Dict, List
 from loguru import logger
 
@@ -392,6 +394,27 @@ def get_autonomous_planning_tools() -> List[Dict[str, Any]]:
                 },
             },
         },
+        {
+            "type": "function",
+            "function": {
+                "name": "run_bash",
+                "description": "Execute a bash/shell command on the terminal. Use this to run system commands, scripts, or any shell operations. Returns stdout and stderr.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "command": {
+                            "type": "string",
+                            "description": "The bash/shell command to execute (e.g. 'ls -la', 'python script.py')",
+                        },
+                        "timeout_seconds": {
+                            "type": "integer",
+                            "description": "Maximum seconds to wait for the command (default: 60). Use to avoid hanging on long-running commands.",
+                        },
+                    },
+                    "required": ["command"],
+                },
+            },
+        },
         {
             "type": "function",
             "function": {
@@ -802,6 +825,79 @@ def delete_file_tool(agent: Any, file_path: str, **kwargs) -> str:
         return error_msg
 
 
+def run_bash_tool(
+    agent: Any, command: str, timeout_seconds: int = 60, **kwargs
+) -> str:
+    """
+    Execute a bash/shell command on the terminal.
+
+    Args:
+        agent: The agent instance
+        command: The bash/shell command to execute
+        timeout_seconds: Maximum seconds to wait (default: 60)
+        **kwargs: Additional arguments
+
+    Returns:
+        str: Command stdout and stderr, or error message
+    """
+    try:
+        # Run in process cwd (where the user started the script) so commands like
+        # ls -la and python script.py see the project directory, not the agent workspace.
+        result = subprocess.run(
+            command,
+            shell=True,
+            capture_output=True,
+            text=True,
+            timeout=timeout_seconds,
+            cwd=None,  # use process current working directory
+            encoding="utf-8",
+            errors="replace",
+        )
+
+        stdout = result.stdout or ""
+        stderr = result.stderr or ""
+
+        output_parts = []
+        if stdout:
+            output_parts.append(f"stdout:\n{stdout}")
+        if stderr:
+            output_parts.append(f"stderr:\n{stderr}")
+        if not output_parts:
+            output_parts.append("(no output)")
+
+        result_msg = (
+            f"Command exited with code {result.returncode}\n"
+            + "\n".join(output_parts)
+        )
+
+        # Add to memory
+        agent.short_memory.add(
+            role="Terminal",
+            content=f"Executed: {command[:100]}{'...' if len(command) > 100 else ''} -> exit {result.returncode}",
+        )
+
+        if agent.verbose:
+            logger.info(f"Executed bash command: {command[:80]}...")
+
+        return result_msg.strip()
+    except subprocess.TimeoutExpired:
+        error_msg = f"Error: Command timed out after {timeout_seconds} seconds"
+        logger.error(error_msg)
+        agent.short_memory.add(
+            role="Terminal",
+            content=f"Timeout: {command[:80]}...",
+        )
+        return error_msg
+    except Exception as e:
+        error_msg = f"Error executing command: {str(e)}"
+        logger.error(error_msg)
+        agent.short_memory.add(
+            role="Terminal",
+            content=f"Error: {error_msg}",
+        )
+        return error_msg
+
+
 def create_sub_agent_tool(
     agent: Any, agents: List[Dict[str, str]], **kwargs
 ) -> str:
diff --git a/v9_examples/example_autonomous_looper_tools.py b/v9_examples/example_autonomous_looper_tools.py
@@ -15,6 +15,7 @@
 - read_file: Read file contents
 - list_directory: List directory contents
 - delete_file: Delete files
+- run_bash: Execute bash/shell commands on the terminal
 """
 
 from swarms import Agent
@@ -47,10 +48,10 @@
     ],
 )
 
-# Example 3: Agent with file operations but no planning
+# Example 3: Agent with file operations and terminal (bash) access
 agent_file_ops = Agent(
     agent_name="File-Operations-Agent",
-    agent_description="Agent with file operations capabilities",
+    agent_description="Agent with file operations and terminal execution capabilities",
     model_name="anthropic/claude-sonnet-4-5",
     dynamic_temperature_enabled=True,
     max_loops="auto",
@@ -65,6 +66,7 @@
         "update_file",
         "read_file",
         "list_directory",
+        "run_bash",
     ],
 )
 
