类class agentscope.tool

Bash

class Bash(ToolBase)

源码Source agentscope/tool/_builtin/_bash.py:25–789

Bash，让智能体以受控方式调用外部能力。位于 agentscope.tool 包，继承自 ToolBase。核心成员包括 check_read_only、check_permissions、match_rule、generate_suggestions、call。

The bash tool. Declared in agentscope.tool. Extends ToolBase.

构造器摘要Constructor Summary

构造器Constructor	说明Description
`def __init__(dangerous_files: list[str] = DEFAULT_DANGEROUS_FILES, dangerous_directories: list[str] = DEFAULT_DANGEROUS…`	初始化 `Bash` 实例。 Initialize the bash tool.

属性摘要Attribute Summary

属性Attribute	类型Type	说明Description	值Value
`name`	str	名称字段。	`'Bash'`
`description`	str	`description` 字段。	'Executes a bash command and returns its output.\n\nThe working directory persists between commands, but shell state does\nnot. The shell environment is initialized from the user\'s profile\n(bash or zsh).\n\nIMPORTANT: Avoid using this tool to run `find`, `grep`, `cat`, `head`,\n`tail`, `sed`, `awk`, or `echo` commands, unless explicitly instructed\nor after you have verified that a dedicated tool cannot accomplish your\ntask. Instead, use the appropriate dedicated tool as this will provide\na much better experience for the user:\n\n - File search: Use Glob (NOT find or ls)\n - Content search: Use Grep (NOT grep or rg)\n - Read files: Use Read (NOT cat/head/tail)\n - Edit files: Use Edit (NOT sed/awk)\n - Write files: Use Write (NOT echo >/cat <<EOF)\n - Communication: Output text directly (NOT echo/printf)\n\nWhile the Bash tool can do similar things, it\'s better to use the\nbuilt-in tools as they provide a better user experience and make it\neasier to review tool calls and give permission.\n\n# Instructions\n - If your command will create new directories or files, first use\n this tool to run `ls` to verify the parent directory exists and is\n the correct location.\n - Always quote file paths that contain spaces with double quotes in\n your command (e.g., cd "path with spaces/file.txt")\n - Try to maintain your current working directory throughout the\n session by using absolute paths and avoiding usage of `cd`. You may\n use `cd` if the User explicitly requests it.\n - You may specify an optional timeout in milliseconds (up to 600000ms\n / 10 minutes). By default, your command will timeout after 120000ms\n (2 minutes).\n - Write a clear, concise description of what your command does. For\n simple commands, keep it brief (5-10 words). For complex commands\n (piped commands, obscure flags, or anything hard to understand at a\n glance), include enough context so that the user can understand what\n your command will do.\n - When issuing multiple commands:\n - If the commands are independent and can run in parallel, make\n multiple Bash tool calls in a single message. Example: if you need\n to run "git status" and "git diff", send a single message with two\n Bash tool calls in parallel.\n - If the commands depend on each other and must run sequentially,\n use a single Bash call with \'&&\' to chain them together.\n - Use \';\' only when you need to run commands sequentially but don\'t\n care if earlier commands fail.\n - DO NOT use newlines to separate commands (newlines are ok in\n quoted strings).\n - For git commands:\n - Prefer to create a new commit rather than amending an existing\n commit.\n - Before running destructive operations (e.g., git reset --hard, git\n push --force, git checkout --), consider whether there is a safer\n alternative that achieves the same goal. Only use destructive\n operations when they are truly the best approach.\n - Never skip hooks (--no-verify) or bypass signing (--no-gpg-sign,\n -c commit.gpgsign=false) unless the user has explicitly asked for\n it. If a hook fails, investigate and fix the underlying issue.\n - Avoid unnecessary `sleep` commands:\n - Do not sleep between commands that can run immediately — just run\n them.\n - Do not retry failing commands in a sleep loop — diagnose the root\n cause or consider an alternative approach.\n - If you must sleep, keep the duration short (1-5 seconds) to avoid\n blocking the user.'
`input_schema`	dict[str, Any]	输入模式字段。	{'type': 'object', 'properties': {'command': {'type': 'string', 'description': 'The bash command to execute.'}, 'description': {'type': 'string', 'description': 'Clear, concise description of what this command does. For simple commands, keep it brief (5-10 words). For complex commands, include enough context.'}, 'timeout': {'type': 'integer', 'description': 'Optional timeout in milliseconds (default: 120000, max: 600000)', 'default': 120000, 'maximum': 600000, 'minimum': 0}}, 'required': ['command']}
`is_mcp`	bool	是 MCP字段。	`False`
`is_read_only`	bool	`is_read_only` 字段。	`False`
`is_concurrency_safe`	bool	`is_concurrency_safe` 字段。	`False`
`is_external_tool`	bool	是外部工具字段。	`False`
`is_state_injected`	bool	`is_state_injected` 字段。	`False`

方法摘要Method Summary

方法Method	说明Description
`async def check_read_only(tool_input: dict[str, Any]) -> bool`async	检查 `check_read_only` 条件。 Decide whether this specific bash invocation is read-only.
`async def check_permissions(tool_input: dict[str, Any], context:` `PermissionContext) -> PermissionDecision`async	检查权限。 Check permissions for bash command execution.
`async def match_rule(rule_content: str \| None, tool_input: dict[str, Any]) -> bool`async	执行 `match_rule` 方法。 Match Bash command using regex-based wildcard matching.
`async def generate_suggestions(tool_input: dict[str, Any]) -> List['PermissionRule']`async	设置该参数。 Generate suggested permission rules for Bash commands.
`async def call(command: str, description: str = '', timeout: int = 120000) -> AsyncGenerator[ToolChunk, None]`async	向智能体发送输入并返回最终回复。 Execute the bash and return the output.

构造器详情Constructor Detail

Bash

def __init__(dangerous_files: list[str] = DEFAULT_DANGEROUS_FILES, dangerous_directories: list[str] = DEFAULT_DANGEROUS_DIRECTORIES, cwd: str | os.PathLike[str] | None = None, middlewares: List[ToolMiddlewareBase] | None = None, backend: BackendBase | None = None) -> None

初始化 Bash 实例。

Initialize the bash tool.

参数Parameters

名称Name	类型Type	说明Description
`dangerous_files`默认default `DEFAULT_DANGEROUS_FILES`	list[str]	dangerous 文件（类型 `list[str]`）。Sensitive files that require explicit user confirmation, even in BYPASS mode. Matched by basename (case-insensitive). Defaults to `DEFAULT_DANGEROUS_FILES`. Pass a custom list to fully replace the defaults, or `[]` to disable the filename check.
`dangerous_directories`默认default `DEFAULT_DANGEROUS_DIRECTORIES`	list[str]	dangerous directories（类型 `list[str]`）。Sensitive directories that require explicit user confirmation. Matched when any path segment equals an entry (case-insensitive). Defaults to `DEFAULT_DANGEROUS_DIRECTORIES`. Pass a custom list to fully replace the defaults, or `[]` to disable the directory check.
`cwd`默认default `None`	str \| os.PathLike[str] \| None	cwd（类型 `str \| os.PathLike[str] \| None`）。The working directory used when executing bash commands.
`middlewares`默认default `None`	List[ToolMiddlewareBase] \| None	中间件列表（类型 `List[ToolMiddlewareBase] \| None`）。Tool middlewares wrapping the tool execution.
`backend`默认default `None`	BackendBase \| None	backend（类型 `BackendBase \| None`）。The sandbox backend to use for shell execution. When `None`, a :class:`LocalBackend` is created.

源码Source agentscope/tool/_builtin/_bash.py:137–177

属性详情Attribute Detail

name

str = 'Bash'

名称字段。声明为 str。

The name field.

源码Source agentscope/tool/_builtin/_bash.py:28

description

str = 'Executes a bash command and returns its output.\n\nThe working directory persists between commands, but shell state does\nnot. The shell environment is initialized from the user\'s profile\n(bash or zsh).\n\nIMPORTANT: Avoid using this tool to run `find`, `grep`, `cat`, `head`,\n`tail`, `sed`, `awk`, or `echo` commands, unless explicitly instructed\nor after you have verified that a dedicated tool cannot accomplish your\ntask. Instead, use the appropriate dedicated tool as this will provide\na much better experience for the user:\n\n - File search: Use Glob (NOT find or ls)\n - Content search: Use Grep (NOT grep or rg)\n - Read files: Use Read (NOT cat/head/tail)\n - Edit files: Use Edit (NOT sed/awk)\n - Write files: Use Write (NOT echo >/cat <<EOF)\n - Communication: Output text directly (NOT echo/printf)\n\nWhile the Bash tool can do similar things, it\'s better to use the\nbuilt-in tools as they provide a better user experience and make it\neasier to review tool calls and give permission.\n\n# Instructions\n - If your command will create new directories or files, first use\n   this tool to run `ls` to verify the parent directory exists and is\n   the correct location.\n - Always quote file paths that contain spaces with double quotes in\n   your command (e.g., cd "path with spaces/file.txt")\n - Try to maintain your current working directory throughout the\n   session by using absolute paths and avoiding usage of `cd`. You may\n   use `cd` if the User explicitly requests it.\n - You may specify an optional timeout in milliseconds (up to 600000ms\n   / 10 minutes). By default, your command will timeout after 120000ms\n   (2 minutes).\n - Write a clear, concise description of what your command does. For\n   simple commands, keep it brief (5-10 words). For complex commands\n   (piped commands, obscure flags, or anything hard to understand at a\n   glance), include enough context so that the user can understand what\n   your command will do.\n - When issuing multiple commands:\n  - If the commands are independent and can run in parallel, make\n    multiple Bash tool calls in a single message. Example: if you need\n    to run "git status" and "git diff", send a single message with two\n    Bash tool calls in parallel.\n  - If the commands depend on each other and must run sequentially,\n    use a single Bash call with \'&&\' to chain them together.\n  - Use \';\' only when you need to run commands sequentially but don\'t\n    care if earlier commands fail.\n  - DO NOT use newlines to separate commands (newlines are ok in\n    quoted strings).\n - For git commands:\n  - Prefer to create a new commit rather than amending an existing\n    commit.\n  - Before running destructive operations (e.g., git reset --hard, git\n    push --force, git checkout --), consider whether there is a safer\n    alternative that achieves the same goal. Only use destructive\n    operations when they are truly the best approach.\n  - Never skip hooks (--no-verify) or bypass signing (--no-gpg-sign,\n    -c commit.gpgsign=false) unless the user has explicitly asked for\n    it. If a hook fails, investigate and fix the underlying issue.\n - Avoid unnecessary `sleep` commands:\n  - Do not sleep between commands that can run immediately — just run\n    them.\n  - Do not retry failing commands in a sleep loop — diagnose the root\n    cause or consider an alternative approach.\n  - If you must sleep, keep the duration short (1-5 seconds) to avoid\n    blocking the user.'

description 字段。声明为 str。

The description field.

源码Source agentscope/tool/_builtin/_bash.py:31

input_schema

dict[str, Any] = {'type': 'object', 'properties': {'command': {'type': 'string', 'description': 'The bash command to execute.'}, 'description': {'type': 'string', 'description': 'Clear, concise description of what this command does. For simple commands, keep it brief (5-10 words). For complex commands, include enough context.'}, 'timeout': {'type': 'integer', 'description': 'Optional timeout in milliseconds (default: 120000, max: 600000)', 'default': 120000, 'maximum': 600000, 'minimum': 0}}, 'required': ['command']}

输入模式字段。声明为 dict[str, Any]。

The input schema field.

源码Source agentscope/tool/_builtin/_bash.py:101

is_mcp

bool = False

是 MCP字段。声明为 bool。

The is mcp field.

源码Source agentscope/tool/_builtin/_bash.py:131

is_read_only

bool = False

is_read_only 字段。声明为 bool。

The is read only field.

源码Source agentscope/tool/_builtin/_bash.py:132

is_concurrency_safe

bool = False

is_concurrency_safe 字段。声明为 bool。

The is concurrency safe field.

源码Source agentscope/tool/_builtin/_bash.py:133

is_external_tool

bool = False

是外部工具字段。声明为 bool。

The is external tool field.

源码Source agentscope/tool/_builtin/_bash.py:134

is_state_injected

bool = False

is_state_injected 字段。声明为 bool。

The is state injected field.

源码Source agentscope/tool/_builtin/_bash.py:135

方法详情Method Detail

check_read_only

async def check_read_only(tool_input: dict[str, Any]) -> bool

async

检查 check_read_only 条件。

Inspects the command and returns True for known-safe read-only commands (e.g.

参数Parameters

名称Name	类型Type	说明Description
`tool_input`	dict[str, Any]	工具输入（类型 `dict[str, Any]`）。The tool input.

返回Returns bool

返回布尔值，表示判断结果。Returns a boolean result.

源码Source agentscope/tool/_builtin/_bash.py:179–202

check_permissions

async def check_permissions(tool_input: dict[str, Any], context: PermissionContext) -> PermissionDecision

async

检查权限。

This method implements Bash-specific permission checks: 0.

参数Parameters

名称Name	类型Type	说明Description
`tool_input`	dict[str, Any]	工具输入（类型 `dict[str, Any]`）。The tool input containing "command" key
`context`	PermissionContext	权限上下文使用模式和规则。The permission context with mode and rules

返回Returns PermissionDecision

返回PermissionDecision。`PermissionDecision`:

源码Source agentscope/tool/_builtin/_bash.py:204–394

match_rule

async def match_rule(rule_content: str | None, tool_input: dict[str, Any]) -> bool

async

执行 match_rule 方法。

Implements wildcard matching with escape sequences: - Supports * for literal asterisk and \ for literal backslash - Special optimization: "git " matches both "git" and "git add" - Prefix pattern (e.g., "git:"): matches commands starting with "git " - Wildcard pattern: conver…

参数Parameters

名称Name	类型Type	说明Description
`rule_content`	str \| None	规则内容（类型 `str \| None`）。The command pattern to match, or None to match all
`tool_input`	dict[str, Any]	工具输入（类型 `dict[str, Any]`）。Must contain a "command" key with the command string

返回Returns bool

返回布尔值，表示判断结果。True if pattern matches the command

源码Source agentscope/tool/_builtin/_bash.py:396–491

generate_suggestions

async def generate_suggestions(tool_input: dict[str, Any]) -> List['PermissionRule']

async

设置该参数。

Generates prefix rules based on command + subcommand (two words).

参数Parameters

名称Name	类型Type	说明Description
`tool_input`	dict[str, Any]	工具输入（类型 `dict[str, Any]`）。The tool input data containing "command" key

返回Returns List['PermissionRule']

返回'PermissionRule'列表。`List[PermissionRule]`:

源码Source agentscope/tool/_builtin/_bash.py:493–537

call

async def call(command: str, description: str = '', timeout: int = 120000) -> AsyncGenerator[ToolChunk, None]

async

向智能体发送输入并返回最终回复。

Execute the bash and return the output.

参数Parameters

名称Name	类型Type	说明Description
`command`	str	命令（类型 `str`）。The bash command to execute.
`description`默认default `''`	str	描述（类型 `str`）。Optional description of what the command does.
`timeout`默认default `120000`	int	超时时间（类型 `int`）。Timeout in milliseconds (default: 120000, max: 600000).

返回Returns AsyncGenerator[ToolChunk, None]

以异步流的形式返回ToolChunk,None。The tool execution result with stdout/stderr content.

源码Source agentscope/tool/_builtin/_bash.py:681–789

继承成员Inherited Members

继承自Inherited from ToolBase

__call__, check_external_result, metadata_schema, mcp_name, dangerous_files, dangerous_directories