类class agentscope.tool

PowerShell

class PowerShell(ToolBase)

源码Source agentscope/tool/_builtin/_powershell.py:23–281

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

Execute PowerShell commands through a workspace backend. Declared in agentscope.tool. Extends ToolBase.

构造器摘要Constructor Summary

构造器Constructor	说明Description
`def __init__(cwd: str \| os.PathLike[str] \| None = None, middlewares: List[ToolMiddlewareBase] \| None = None, backend: B…`	初始化 `PowerShell` 实例。 Initialize the PowerShell tool.

属性摘要Attribute Summary

属性Attribute	类型Type	说明Description	值Value
`name`	str	名称字段。	`'PowerShell'`
`description`	str	`description` 字段。	'Executes a PowerShell command and returns its output.\n\nEach command starts in the configured working directory, but PowerShell\nsession state does not persist between commands. Commands run without\nloading the user\'s PowerShell profile.\n\nIMPORTANT: Avoid using this tool for filesystem operations when a dedicated\ntool can accomplish the task. Prefer the dedicated tools because their calls\nare easier for the user to review and authorize:\n\n - File search: Use Glob (NOT Get-ChildItem)\n - Content search: Use Grep (NOT Select-String)\n - Read files: Use Read (NOT Get-Content)\n - Edit files: Use Edit\n - Write files: Use Write (NOT Set-Content or Out-File)\n - Communication: Output text directly (NOT Write-Output)\n\n# Instructions\n - Verify the parent directory before creating new directories or files.\n - Quote paths containing spaces, for example: Get-Item "path with spaces".\n - Prefer absolute paths and avoid Set-Location so the working directory is\n clear in every command.\n - You may specify an optional timeout in milliseconds (up to 600000ms /\n 10 minutes). The default timeout is 120000ms (2 minutes).\n - Write a concise description of what the command does. Include more context\n for pipelines, uncommon parameters, or commands with side effects.\n - Run independent commands in parallel tool calls. Keep dependent commands\n together and use PowerShell-native error handling when later work depends\n on earlier work succeeding.\n - Prefer new git commits over amending existing commits. Avoid destructive\n git operations and never bypass hooks unless the user explicitly asks.'
`input_schema`	dict[str, Any]	输入模式字段。	`{'type': 'object', 'properties': {'command': {'type': 'string', 'description': 'The PowerShell command to execute.'}, 'description': {'type': 'string', 'description': 'Clear, concise description of what this command does.'}, '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_permissions(tool_input: dict[str, Any], context:` `PermissionContext) -> PermissionDecision`async	检查权限。 Ask the user to confirm every PowerShell command.
`async def generate_suggestions(tool_input: dict[str, Any]) -> List[PermissionRule]`async	设置该参数。 Return no automatic allow-rule suggestions.
`async def call(command: str, description: str = '', timeout: int = 120000) -> AsyncGenerator[ToolChunk, None]`async	向智能体发送输入并返回最终回复。 Execute a PowerShell command through the configured backend.

构造器详情Constructor Detail

PowerShell

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

初始化 PowerShell 实例。

Initialize the PowerShell tool.

参数Parameters

名称Name	类型Type	说明Description
`cwd`默认default `None`	str \| os.PathLike[str] \| None	cwd（类型 `str \| os.PathLike[str] \| None`）。Working directory used when executing commands.
`middlewares`默认default `None`	List[ToolMiddlewareBase] \| None	中间件列表（类型 `List[ToolMiddlewareBase] \| None`）。Tool middlewares wrapping command execution.
`backend`默认default `None`	BackendBase \| None	backend（类型 `BackendBase \| None`）。Backend used for subprocess execution. Defaults to the host-local backend.

源码Source agentscope/tool/_builtin/_powershell.py:95–115

属性详情Attribute Detail

name

str = 'PowerShell'

名称字段。声明为 str。

The name field.

源码Source agentscope/tool/_builtin/_powershell.py:26

description

str = 'Executes a PowerShell command and returns its output.\n\nEach command starts in the configured working directory, but PowerShell\nsession state does not persist between commands. Commands run without\nloading the user\'s PowerShell profile.\n\nIMPORTANT: Avoid using this tool for filesystem operations when a dedicated\ntool can accomplish the task. Prefer the dedicated tools because their calls\nare easier for the user to review and authorize:\n\n - File search: Use Glob (NOT Get-ChildItem)\n - Content search: Use Grep (NOT Select-String)\n - Read files: Use Read (NOT Get-Content)\n - Edit files: Use Edit\n - Write files: Use Write (NOT Set-Content or Out-File)\n - Communication: Output text directly (NOT Write-Output)\n\n# Instructions\n - Verify the parent directory before creating new directories or files.\n - Quote paths containing spaces, for example: Get-Item "path with spaces".\n - Prefer absolute paths and avoid Set-Location so the working directory is\n   clear in every command.\n - You may specify an optional timeout in milliseconds (up to 600000ms /\n   10 minutes). The default timeout is 120000ms (2 minutes).\n - Write a concise description of what the command does. Include more context\n   for pipelines, uncommon parameters, or commands with side effects.\n - Run independent commands in parallel tool calls. Keep dependent commands\n   together and use PowerShell-native error handling when later work depends\n   on earlier work succeeding.\n - Prefer new git commits over amending existing commits. Avoid destructive\n   git operations and never bypass hooks unless the user explicitly asks.'

description 字段。声明为 str。

The description field.

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

input_schema

dict[str, Any] = {'type': 'object', 'properties': {'command': {'type': 'string', 'description': 'The PowerShell command to execute.'}, 'description': {'type': 'string', 'description': 'Clear, concise description of what this command does.'}, '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/_powershell.py:62

is_mcp

bool = False

是 MCP字段。声明为 bool。

The is mcp field.

源码Source agentscope/tool/_builtin/_powershell.py:89

is_read_only

bool = False

is_read_only 字段。声明为 bool。

The is read only field.

源码Source agentscope/tool/_builtin/_powershell.py:90

is_concurrency_safe

bool = False

is_concurrency_safe 字段。声明为 bool。

The is concurrency safe field.

源码Source agentscope/tool/_builtin/_powershell.py:91

is_external_tool

bool = False

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

The is external tool field.

源码Source agentscope/tool/_builtin/_powershell.py:92

is_state_injected

bool = False

is_state_injected 字段。声明为 bool。

The is state injected field.

源码Source agentscope/tool/_builtin/_powershell.py:93

方法详情Method Detail

check_permissions

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

async

检查权限。

PowerShell-specific command validation is intentionally outside this implementation.

参数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/_powershell.py:139–155

generate_suggestions

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

async

设置该参数。

A broad rule would weaken the conservative permission boundary before PowerShell-specific command validation is available.

参数Parameters

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

返回Returns List[PermissionRule]

返回PermissionRule列表。Returns a list of permission rule.

源码Source agentscope/tool/_builtin/_powershell.py:157–166

call

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

async

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

Execute a PowerShell command through the configured backend.

参数Parameters

名称Name	类型Type	说明Description
`command`	str	命令（类型 `str`）。PowerShell source text to execute.
`description`默认default `''`	str	描述（类型 `str`）。Human-readable description of the command.
`timeout`默认default `120000`	int	超时时间（类型 `int`）。Timeout in milliseconds, capped at 600000.

返回Returns AsyncGenerator[ToolChunk, None]

以异步流的形式返回ToolChunk,None。`ToolChunk`:

源码Source agentscope/tool/_builtin/_powershell.py:168–281

继承成员Inherited Members

继承自Inherited from ToolBase

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