类class agentscope.tool

Read

class Read(ToolBase)

源码Source agentscope/tool/_builtin/_read.py:82–576

读取工具。位于 agentscope.tool 包，继承自 ToolBase。核心成员包括 check_permissions、match_rule、generate_suggestions、call、description。

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

构造器摘要Constructor Summary

构造器Constructor	说明Description
`def __init__(max_line_characters: int = 2000, model_input_types: list[str] \| None = None, middlewares: List[ToolMiddlew…`	初始化 `Read` 实例。 Initialize the read tool.

属性摘要Property Summary

属性Property	说明Description
`description`	读取 `description` 属性。 The description presented to the agent, with the image and PDF bullets rendered from the model's accepted input types.

属性摘要Attribute Summary

属性Attribute	类型Type	说明Description	值Value
`name`	str	名称字段。	`'Read'`
`input_schema`	dict[str, Any]	输入模式字段。	`_ReadParams.model_json_schema()`
`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` 字段。	`True`

方法摘要Method Summary

方法Method	说明Description
`async def check_permissions(tool_input: dict[str, Any], context:` `PermissionContext) -> PermissionDecision`async	检查权限。 Check permissions for file reading.
`async def match_rule(rule_content: str \| None, tool_input: dict[str, Any]) -> bool`async	执行 `match_rule` 方法。 Check if a permission rule matches the file path.
`async def generate_suggestions(tool_input: dict[str, Any]) -> List[PermissionRule]`async	设置该参数。 Generate suggested permission rules for the file path.
`async def call(file_path: str, offset: int = 1, limit: int = 2000, pages: str \| None = None, _agent_state:` `AgentState \|…`async	向智能体发送输入并返回最终回复。 Read a file and return content as appropriate block types.

构造器详情Constructor Detail

Read

def __init__(max_line_characters: int = 2000, model_input_types: list[str] | None = None, middlewares: List[ToolMiddlewareBase] | None = None, backend: BackendBase | None = None) -> None

初始化 Read 实例。

Initialize the read tool.

参数Parameters

名称Name	类型Type	说明Description
`max_line_characters`默认default `2000`	int	最大 line characters（类型 `int`）。The maximum number of characters to include for each line when reading files. Lines longer than this will be truncated with a "[truncated]" suffix. This prevents overwhelming the agent with excessively long lines while still providing useful content.
`model_input_types`默认default `None`	list[str] \| None	模型输入类型（类型 `list[str] \| None`）。The media types the downstream model accepts as input, aligned with the model card's `input_types` field so it can be passed through directly, e.g. `Read(model_input_types=model_card.input_types)`. Glob patterns like `"image/*"` are accepted. Files whose media type is listed are returned as `DataBlock` for the model to consume natively; otherwise images return an error and PDFs fall back to local text extraction. Defaults to `image/png`, `image/jpeg`, `image/gif` and `image/webp`.
`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 file I/O. When `None`, a :class:`LocalBackend` is created.

源码Source agentscope/tool/_builtin/_read.py:131–174

属性详情Attribute Detail

name

str = 'Read'

名称字段。声明为 str。

The name field.

源码Source agentscope/tool/_builtin/_read.py:85

input_schema

dict[str, Any] = _ReadParams.model_json_schema()

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

The input schema field.

源码Source agentscope/tool/_builtin/_read.py:123

is_mcp

bool = False

是 MCP字段。声明为 bool。

The is mcp field.

源码Source agentscope/tool/_builtin/_read.py:125

is_read_only

bool = True

is_read_only 字段。声明为 bool。

The is read only field.

源码Source agentscope/tool/_builtin/_read.py:126

is_concurrency_safe

bool = True

is_concurrency_safe 字段。声明为 bool。

The is concurrency safe field.

源码Source agentscope/tool/_builtin/_read.py:127

is_external_tool

bool = False

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

The is external tool field.

源码Source agentscope/tool/_builtin/_read.py:128

is_state_injected

bool = True

is_state_injected 字段。声明为 bool。

The is state injected field.

源码Source agentscope/tool/_builtin/_read.py:129

属性详情Property Detail

description

def description() -> str

读取 description 属性。

The description presented to the agent, with the image and PDF bullets rendered from the model's accepted input types.

返回Returns str

返回字符串结果。Returns a string.

源码Source agentscope/tool/_builtin/_read.py:99–121

方法详情Method Detail

check_permissions

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

async

检查权限。

Read is a read-only tool.

参数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/_read.py:176–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 "file_path" parameter using fnmatch.

参数Parameters

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

返回Returns bool

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

源码Source agentscope/tool/_builtin/_read.py:192–221

generate_suggestions

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

async

设置该参数。

Suggests a glob pattern covering the parent directory of the file, allowing the user to grant permission for the entire directory at once.

参数Parameters

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

返回Returns List[PermissionRule]

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

源码Source agentscope/tool/_builtin/_read.py:223–257

call

async def call(file_path: str, offset: int = 1, limit: int = 2000, pages: str | None = None, _agent_state: AgentState | None = None) -> ToolChunk

async

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

Dispatches to format-specific readers based on file extension: - PDF: text extraction via RAG parser - Image: base64-encoded DataBlock - Other: line-numbered text (TextBlock)

参数Parameters

名称Name	类型Type	说明Description
`file_path`	str	文件路径（类型 `str`）。The file path.
`offset`默认default `1`	int	偏移量（类型 `int`）。The offset.
`limit`默认default `2000`	int	数量上限（类型 `int`）。The limit.
`pages`默认default `None`	str \| None	分页（类型 `str \| None`）。The pages.
`_agent_state`默认default `None`	AgentState \| None	智能体状态（类型 `AgentState \| None`）。The agent state.

返回Returns ToolChunk

返回ToolChunk。Returns tool chunk.

源码Source agentscope/tool/_builtin/_read.py:259–333

继承成员Inherited Members

继承自Inherited from ToolBase

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