类class agentscope.tool

Write

class Write(ToolBase)

源码Source agentscope/tool/_builtin/_write.py:26–345

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

The write 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…`	初始化 `Write` 实例。 Initialize the write tool.

属性摘要Attribute Summary

属性Attribute	类型Type	说明Description	值Value
`name`	str	名称字段。	`'Write'`
`description`	str	`description` 字段。	"Writes a file to the local filesystem.\n\nUsage:\n- This tool will overwrite the existing file if there is one at the provided path.\n- If this is an existing file, you MUST use the Read tool first to read the file's contents. This tool will fail if you did not read the file first.\n- ALWAYS prefer editing existing files in the codebase. NEVER write new files unless explicitly required.\n- NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested by the User.\n- Only use emojis if the user explicitly requests it. Avoid writing emojis to files unless asked."
`input_schema`	dict[str, Any]	输入模式字段。	`{'type': 'object', 'properties': {'file_path': {'type': 'string', 'description': 'The absolute path to the file to write (must be absolute, not relative)'}, 'content': {'type': 'string', 'description': 'The content to write to the file'}}, 'required': ['file_path', 'content']}`
`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` 字段。	`True`

方法摘要Method Summary

方法Method	说明Description
`async def check_permissions(tool_input: dict[str, Any], context:` `PermissionContext) -> PermissionDecision`async	检查权限。 Check permissions for file writing.
`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, content: str, _agent_state:` `AgentState \| None = None) -> ToolChunk`async	向智能体发送输入并返回最终回复。 Write content to a file and return the result.

构造器详情Constructor Detail

Write

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

初始化 Write 实例。

Initialize the write 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.
`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/_write.py:65–100

属性详情Attribute Detail

name

str = 'Write'

名称字段。声明为 str。

The name field.

源码Source agentscope/tool/_builtin/_write.py:29

description

str = "Writes a file to the local filesystem.\n\nUsage:\n- This tool will overwrite the existing file if there is one at the provided path.\n- If this is an existing file, you MUST use the Read tool first to read the file's contents. This tool will fail if you did not read the file first.\n- ALWAYS prefer editing existing files in the codebase. NEVER write new files unless explicitly required.\n- NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested by the User.\n- Only use emojis if the user explicitly requests it. Avoid writing emojis to files unless asked."

description 字段。声明为 str。

The description field.

源码Source agentscope/tool/_builtin/_write.py:33

input_schema

dict[str, Any] = {'type': 'object', 'properties': {'file_path': {'type': 'string', 'description': 'The absolute path to the file to write (must be absolute, not relative)'}, 'content': {'type': 'string', 'description': 'The content to write to the file'}}, 'required': ['file_path', 'content']}

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

The input schema field.

源码Source agentscope/tool/_builtin/_write.py:43

is_mcp

bool = False

是 MCP字段。声明为 bool。

The is mcp field.

源码Source agentscope/tool/_builtin/_write.py:59

is_read_only

bool = False

is_read_only 字段。声明为 bool。

The is read only field.

源码Source agentscope/tool/_builtin/_write.py:60

is_concurrency_safe

bool = False

is_concurrency_safe 字段。声明为 bool。

The is concurrency safe field.

源码Source agentscope/tool/_builtin/_write.py:61

is_external_tool

bool = False

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

The is external tool field.

源码Source agentscope/tool/_builtin/_write.py:62

is_state_injected

bool = True

is_state_injected 字段。声明为 bool。

The is state injected field.

源码Source agentscope/tool/_builtin/_write.py:63

方法详情Method Detail

check_permissions

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

async

检查权限。

This method implements Write-specific permission checks: 1.

参数Parameters

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

返回Returns PermissionDecision

返回PermissionDecision。`PermissionDecision`:

源码Source agentscope/tool/_builtin/_write.py:102–164

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/_write.py:166–194

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/_write.py:196–233

call

async def call(file_path: str, content: str, _agent_state: AgentState | None = None) -> ToolChunk

async

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

Write content to a file and return the result.

参数Parameters

名称Name	类型Type	说明Description
`file_path`	str	文件路径（类型 `str`）。The file path.
`content`	str	内容（类型 `str`）。The content.
`_agent_state`默认default `None`	AgentState \| None	智能体状态（类型 `AgentState \| None`）。The agent state.

返回Returns ToolChunk

返回ToolChunk。Returns tool chunk.

源码Source agentscope/tool/_builtin/_write.py:235–345

继承成员Inherited Members

继承自Inherited from ToolBase

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