类class agentscope.tool

Grep

class Grep(ToolBase)

源码Source agentscope/tool/_builtin/_grep.py:39–489

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

The grep tool for searching file contents using ripgrep. Declared in agentscope.tool. Extends ToolBase.

构造器摘要Constructor Summary

构造器Constructor	说明Description
`def __init__(middlewares: List[ToolMiddlewareBase] \| None = None, backend: BackendBase \| None = None) -> None`	初始化 `Grep` 实例。 Initialize the grep tool.

属性摘要Attribute Summary

属性Attribute	类型Type	说明Description	值Value
`name`	str	名称字段。	`'Grep'`
`description`	str	`description` 字段。	'A powerful search tool built on ripgrep\n\n Usage:\n- ALWAYS use Grep for search tasks. NEVER invoke `grep` or `rg` as a Bash command. The Grep tool has been optimized for correct permissions and access.\n- Supports full regex syntax (e.g., "log.Error", "function\\s+\\w+")\n- Filter files with glob parameter (e.g., ".js", "*/.tsx") or type parameter (e.g., "js", "py", "rust")\n- Output modes: "content" shows matching lines, "files_with_matches" shows only file paths (default), "count" shows match counts per file\n- Context lines: use context parameter or -A/-B/-C for lines after/before/around matches\n- Case-insensitive search: set i to true\n- Multiline regex: set multiline to true for patterns spanning multiple lines\n- Limit results: use head_limit to cap the number of results returned'
`input_schema`	dict[str, Any]	输入模式字段。	{'type': 'object', 'properties': {'pattern': {'type': 'string', 'description': 'The regular expression pattern to search for in file contents.'}, 'path': {'type': 'string', 'description': 'File or directory to search in. Defaults to current working directory.'}, 'output_mode': {'type': 'string', 'enum': ['content', 'files_with_matches', 'count'], 'description': "Output mode: 'content' shows matching lines (supports -A/-B/-C context, -n line numbers, head_limit), 'files_with_matches' shows file paths (supports head_limit), 'count' shows match counts (supports head_limit). Defaults to 'files_with_matches'.", 'default': 'files_with_matches'}, 'glob': {'type': 'string', 'description': "Glob pattern to filter files (e.g., '.js', '.{ts,tsx}')."}, 'type': {'type': 'string', 'description': 'File type to search (rg --type). Common types: js, py, rust, go, java, etc.'}, '-A': {'type': 'integer', 'description': "Number of lines to show after each match. Requires output_mode: 'content'."}, '-B': {'type': 'integer', 'description': "Number of lines to show before each match. Requires output_mode: 'content'."}, '-C': {'type': 'integer', 'description': 'Alias for context.'}, 'context': {'type': 'integer', 'description': "Number of context lines to show before and after matches. Requires output_mode: 'content'."}, 'n': {'type': 'boolean', 'description': "Show line numbers in output. Requires output_mode: 'content'. Defaults to true.", 'default': True}, 'i': {'type': 'boolean', 'description': 'Case insensitive search.', 'default': False}, 'case_insensitive': {'type': 'boolean', 'description': 'Case insensitive search (alias for i).', 'default': False}, 'multiline': {'type': 'boolean', 'description': 'Enable multiline mode where . matches newlines and patterns can span lines. Default: false.', 'default': False}, 'head_limit': {'type': 'integer', 'description': 'Limit output to first N lines/entries. Defaults to 250 when unspecified. Pass 0 for unlimited.', 'minimum': 0}, 'offset': {'type': 'integer', 'description': 'Skip first N lines/entries before applying head_limit. Defaults to 0.', 'default': 0, 'minimum': 0}}, 'required': ['pattern']}
`is_mcp`	bool	是 MCP字段。	`False`
`is_read_only`	bool	`is_read_only` 字段。	`True`
`is_concurrency_safe`	bool	`is_concurrency_safe` 字段。	`True`
`is_external_tool`	bool	是外部工具字段。	`False`
`is_state_injected`	bool	`is_state_injected` 字段。	`False`

方法摘要Method Summary

方法Method	说明Description
`async def check_permissions(tool_input: dict[str, Any], context:` `PermissionContext) -> PermissionDecision`async	检查权限。 Check permissions for grep search.
`async def match_rule(rule_content: str \| None, tool_input: dict[str, Any]) -> bool`async	执行 `match_rule` 方法。 Check if a permission rule matches the grep search path.
`async def generate_suggestions(tool_input: dict[str, Any]) -> List[PermissionRule]`async	设置该参数。 Generate suggested permission rules for the grep search path.
`async def call(pattern: str, path: str \| None = None, output_mode: Literal['content', 'files_with_matches', 'count'] =…`async	向智能体发送输入并返回最终回复。 Execute the grep search using ripgrep.

构造器详情Constructor Detail

Grep

def __init__(middlewares: List[ToolMiddlewareBase] | None = None, backend: BackendBase | None = None) -> None

初始化 Grep 实例。

Initialize the grep tool.

参数Parameters

名称Name	类型Type	说明Description
`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. Ripgrep is always invoked via `exec_shell` so that the same code path works for local, Docker, and E2B backends.

源码Source agentscope/tool/_builtin/_grep.py:159–179

属性详情Attribute Detail

name

str = 'Grep'

名称字段。声明为 str。

The name field.

源码Source agentscope/tool/_builtin/_grep.py:42

description

str = 'A powerful search tool built on ripgrep\n\n  Usage:\n- ALWAYS use Grep for search tasks. NEVER invoke `grep` or `rg` as a Bash command. The Grep tool has been optimized for correct permissions and access.\n- Supports full regex syntax (e.g., "log.*Error", "function\\s+\\w+")\n- Filter files with glob parameter (e.g., "*.js", "**/*.tsx") or type parameter (e.g., "js", "py", "rust")\n- Output modes: "content" shows matching lines, "files_with_matches" shows only file paths (default), "count" shows match counts per file\n- Context lines: use context parameter or -A/-B/-C for lines after/before/around matches\n- Case-insensitive search: set i to true\n- Multiline regex: set multiline to true for patterns spanning multiple lines\n- Limit results: use head_limit to cap the number of results returned'

description 字段。声明为 str。

The description field.

源码Source agentscope/tool/_builtin/_grep.py:45

input_schema

dict[str, Any] = {'type': 'object', 'properties': {'pattern': {'type': 'string', 'description': 'The regular expression pattern to search for in file contents.'}, 'path': {'type': 'string', 'description': 'File or directory to search in. Defaults to current working directory.'}, 'output_mode': {'type': 'string', 'enum': ['content', 'files_with_matches', 'count'], 'description': "Output mode: 'content' shows matching lines (supports -A/-B/-C context, -n line numbers, head_limit), 'files_with_matches' shows file paths (supports head_limit), 'count' shows match counts (supports head_limit). Defaults to 'files_with_matches'.", 'default': 'files_with_matches'}, 'glob': {'type': 'string', 'description': "Glob pattern to filter files (e.g., '*.js', '*.{ts,tsx}')."}, 'type': {'type': 'string', 'description': 'File type to search (rg --type). Common types: js, py, rust, go, java, etc.'}, '-A': {'type': 'integer', 'description': "Number of lines to show after each match. Requires output_mode: 'content'."}, '-B': {'type': 'integer', 'description': "Number of lines to show before each match. Requires output_mode: 'content'."}, '-C': {'type': 'integer', 'description': 'Alias for context.'}, 'context': {'type': 'integer', 'description': "Number of context lines to show before and after matches. Requires output_mode: 'content'."}, 'n': {'type': 'boolean', 'description': "Show line numbers in output. Requires output_mode: 'content'. Defaults to true.", 'default': True}, 'i': {'type': 'boolean', 'description': 'Case insensitive search.', 'default': False}, 'case_insensitive': {'type': 'boolean', 'description': 'Case insensitive search (alias for i).', 'default': False}, 'multiline': {'type': 'boolean', 'description': 'Enable multiline mode where . matches newlines and patterns can span lines. Default: false.', 'default': False}, 'head_limit': {'type': 'integer', 'description': 'Limit output to first N lines/entries. Defaults to 250 when unspecified. Pass 0 for unlimited.', 'minimum': 0}, 'offset': {'type': 'integer', 'description': 'Skip first N lines/entries before applying head_limit. Defaults to 0.', 'default': 0, 'minimum': 0}}, 'required': ['pattern']}

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

The input schema field.

源码Source agentscope/tool/_builtin/_grep.py:58

is_mcp

bool = False

是 MCP字段。声明为 bool。

The is mcp field.

源码Source agentscope/tool/_builtin/_grep.py:153

is_read_only

bool = True

is_read_only 字段。声明为 bool。

The is read only field.

源码Source agentscope/tool/_builtin/_grep.py:154

is_concurrency_safe

bool = True

is_concurrency_safe 字段。声明为 bool。

The is concurrency safe field.

源码Source agentscope/tool/_builtin/_grep.py:155

is_external_tool

bool = False

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

The is external tool field.

源码Source agentscope/tool/_builtin/_grep.py:156

is_state_injected

bool = False

is_state_injected 字段。声明为 bool。

The is state injected field.

源码Source agentscope/tool/_builtin/_grep.py:157

方法详情Method Detail

check_permissions

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

async

检查权限。

Check permissions for grep search.

参数Parameters

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

返回Returns PermissionDecision

返回PermissionDecision。Returns permission decision.

源码Source agentscope/tool/_builtin/_grep.py:181–190

match_rule

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

async

执行 match_rule 方法。

Matches rule_content as a glob pattern against the "path" parameter.

参数Parameters

名称Name	类型Type	说明Description
`rule_content`	str \| None	规则内容（类型 `str \| None`）。Glob pattern to match against the search path (e.g., "src/**"), or None to match all invocations
`tool_input`	dict[str, Any]	工具输入（类型 `dict[str, Any]`）。The tool input data containing optional "path" key

返回Returns bool

返回布尔值，表示判断结果。`bool`:

源码Source agentscope/tool/_builtin/_grep.py:192–223

generate_suggestions

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

async

设置该参数。

Suggests a rule based on the search path.

参数Parameters

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

返回Returns List[PermissionRule]

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

源码Source agentscope/tool/_builtin/_grep.py:225–257

call

async def call(pattern: str, path: str | None = None, output_mode: Literal['content', 'files_with_matches', 'count'] = 'files_with_matches', glob: str | None = None, type: str | None = None, i: bool = False, case_insensitive: bool = False, context: int | None = None, multiline: bool = False, head_limit: int | None = None, offset: int = 0, n: bool = True, **kwargs: Any) -> ToolChunk

async

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

Execute the grep search using ripgrep.

参数Parameters

名称Name	类型Type	说明Description
`pattern`	str	pattern（类型 `str`）。The regex pattern to search for
`path`默认default `None`	str \| None	目录或文件路径到搜索 in。The directory or file path to search in
`output_mode`默认default `'files_with_matches'`	Literal['content', 'files_with_matches', 'count']	输出模式（类型 `Literal['content', 'files_with_matches', 'count']`）。Output mode ('content', 'files_with_matches', 'count')
`glob`默认default `None`	str \| None	glob（类型 `str \| None`）。Glob pattern to filter files
`type`默认default `None`	str \| None	类型（类型 `str \| None`）。File type to filter by (rg --type)
`i`默认default `False`	bool	i（类型 `bool`）。Case-insensitive search (rg -i)
`case_insensitive`默认default `False`	bool	取值 insensitive（类型 `bool`）。Alias for i (backward compatibility)
`context`默认default `None`	int \| None	上下文（类型 `int \| None`）。Number of context lines around matches
`multiline`默认default `False`	bool	multiline（类型 `bool`）。Enable multiline regex matching
`head_limit`默认default `None`	int \| None	head 限制（类型 `int \| None`）。Maximum number of results to return (default 250, 0=unlimited)
`offset`默认default `0`	int	偏移量（类型 `int`）。Skip first N results
`n`默认default `True`	bool	n（类型 `bool`）。Show line numbers (content mode only, default True)
`kwargs`	Any	关键字参数（类型 `Any`）。The kwargs.

返回Returns ToolChunk

返回ToolChunk。Returns tool chunk.

源码Source agentscope/tool/_builtin/_grep.py:320–489

继承成员Inherited Members

继承自Inherited from ToolBase

__call__, check_external_result, check_read_only, metadata_schema, mcp_name, dangerous_files, dangerous_directories