mirror of
https://github.com/google/adk-docs.git
synced 2026-09-14 16:16:59 +08:00
Zyan
a7584a1dc9
* Create bashtool.md This PR adds the integration documentation for the new ExecuteBashTool in the Python ADK. Rendered view: Agent's PR: #1442 Original Issue: #1438 Key additions: - Documented the tool's core capabilities and experimental status. - Added security and execution safeguards (User Confirmation, Command Validation, Resource Limits, Disabled Core Dumps, and Process Group Termination). - Reviewed against ADK integration-create and review guidelines - Checked against the repository> https://github.com/google/adk-python/blob/ecb759cc16bc870aa190d01c4c3f0e1e3e97afab/src/google/adk/tools/bash_tool.py Icon PR: #2047 * Update bashtool.md * Update bashtool.md * Add files via upload * Add files via upload
77 lines
3.4 KiB
Markdown
77 lines
3.4 KiB
Markdown
---
|
|
catalog_title: Bash Tool
|
|
catalog_description: Execute bash commands within a secure, resource-limited local sandbox
|
|
catalog_icon: /integrations/assets/bash.png
|
|
catalog_tags: ["code", "google"]
|
|
---
|
|
|
|
# Bash Tool for ADK
|
|
|
|
<div class="language-support-tag">
|
|
<span class="lst-supported">Supported in ADK</span><span class="lst-python">Python v1.27.0</span>
|
|
</div>
|
|
|
|
The `ExecuteBashTool` allows an ADK agent to execute bash commands within a local workspace directory. This tool is useful for file system operations, running scripts, or interacting with the local environment directly through the agent.
|
|
The tool is only available for Python ADK.
|
|
|
|
## Installation
|
|
|
|
The Bash Tool is included by default in the core Agent Development Kit (ADK). You don't need to install any separate integration packages; simply install the main library:
|
|
|
|
```bash
|
|
pip install google-adk
|
|
```
|
|
|
|
## Use with agent
|
|
|
|
!!! warning "POSIX-only"
|
|
|
|
`ExecuteBashTool` is currently supported **only on POSIX systems** such as Linux or macOS. Executing this tool on a Windows system will result in a hard error.
|
|
|
|
To use the Bash Tool, instantiate `ExecuteBashTool` and include it in your agent's `tools` list. Ensure `my_workspace_path` is defined prior to running the snippet as a valid directory path string:
|
|
|
|
```python
|
|
from google.adk.tools.bash_tool import ExecuteBashTool, BashToolPolicy
|
|
|
|
policy = BashToolPolicy(
|
|
allowed_command_prefixes=("ls", "cat", "grep"),
|
|
timeout_seconds=30,
|
|
max_memory_bytes=1024 * 1024 * 512, # 512MB
|
|
max_file_size_bytes=1024 * 1024 * 10, # 10MB
|
|
max_child_processes=5
|
|
)
|
|
|
|
tool = ExecuteBashTool(workspace=my_workspace_path, policy=policy)
|
|
```
|
|
|
|
## Security and execution safeguards
|
|
|
|
Because executing arbitrary code carries inherent risks, the `ExecuteBashTool` includes several mandatory and optional security features enforced upon the spawned subprocess.
|
|
|
|
### Default policy allows all commands
|
|
|
|
By default, `BashToolPolicy` is initialized with `allowed_command_prefixes=("*",)`. This means that **all commands are permitted by default**. To secure your application, you must explicitly restrict the allowed commands when initializing the policy:
|
|
|
|
```python
|
|
# Secure implementation example
|
|
from google.adk.tools.bash_tool import BashToolPolicy
|
|
|
|
strict_policy = BashToolPolicy(
|
|
allowed_command_prefixes=("ls ", "cat ", "pwd")
|
|
)
|
|
```
|
|
|
|
### Built-in protections
|
|
|
|
1. **User Confirmation:** The tool **always** requests user confirmation before executing a command. The framework pauses execution and waits for the user or client application to approve the command via the `adk_request_confirmation` flow.
|
|
2. **Command Validation:** You can whitelist specific commands using `allowed_command_prefixes` and strictly forbid certain string patterns using `blocked_operators`.
|
|
3. **Resource Limits:** OS-level limits,`setrlimit`, are applied to restrict memory consumption, file sizes, and the number of child processes to prevent fork bombs or memory exhaustion.
|
|
4. **Core Dumps Disabled:** To prevent sensitive memory leaks, core dumps are strictly disabled, `RLIMIT_CORE` set to `0`, for the executing subprocess.
|
|
5. **Process Group Termination:** If a command exceeds the `timeout_seconds`, the tool issues a `SIGKILL` to the entire process group to ensure no orphan background processes are left running.
|
|
|
|
## Available tools
|
|
|
|
| Tool Name | Class Name | Description |
|
|
| :--- | :--- | :--- |
|
|
| `execute_bash` | `ExecuteBashTool` | Executes a bash command within a workspace. POSIX only |
|