适用于 ADK 的 Bash 工具¶

Supported in ADKPython v1.27.0

ExecuteBashTool 允许 ADK 智能体在本地工作区目录中执行 bash 命令。该工具可用于文件系统操作、运行脚本或通过智能体直接与本地环境交互。该工具仅适用于 Python 版 ADK。

安装¶

Bash 工具默认包含在核心 Agent Development Kit (ADK) 中。你无需安装任何单独的集成包，只需安装主库即可：

pip install google-adk

与智能体配合使用¶

仅支持 POSIX 系统

ExecuteBashTool 目前仅支持 POSIX 系统，如 Linux 或 macOS。在 Windows 系统上执行此工具将导致硬错误。

要使用 Bash 工具，需实例化 ExecuteBashTool 并将其包含在智能体的 tools 列表中。请确保在运行代码片段之前已将 my_workspace_path 定义为一个有效的目录路径字符串：

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)

安全性和执行保障措施¶

由于执行任意代码存在固有风险，ExecuteBashTool 在生成的子进程上强制执行若干必要的和可选的安全功能。

默认策略允许所有命令¶

默认情况下，BashToolPolicy 使用 allowed_command_prefixes=("*",) 进行初始化。这意味着默认允许所有命令。要保护你的应用程序，你必须在初始化策略时明确限制允许的命令：

# 安全实现示例
from google.adk.tools.bash_tool import BashToolPolicy

strict_policy = BashToolPolicy(
    allowed_command_prefixes=("ls ", "cat ", "pwd")
)

内置保护机制¶

用户确认： 该工具在执行命令前始终会请求用户确认。框架会暂停执行，等待用户或客户端应用程序通过 adk_request_confirmation 流程批准该命令。
命令验证： 你可以使用 allowed_command_prefixes 白名单指定允许的命令，并使用 blocked_operators 严格禁止某些字符串模式。
资源限制： 操作系统级别的限制（setrlimit）用于约束内存消耗、文件大小和子进程数量，以防止 fork 炸弹或内存耗尽。
禁用核心转储： 为防止敏感内存泄露，执行子进程的核心转储被严格禁用，即 RLIMIT_CORE 设置为 0。
进程组终止： 如果命令执行超过 timeout_seconds，该工具会向整个进程组发送 SIGKILL 信号，以确保不会留下孤儿后台进程。

可用工具¶

工具名称	类名	描述
`execute_bash`	`ExecuteBashTool`	在工作区中执行 bash 命令。仅支持 POSIX 系统