Python Tool

A Python tool is any object satisfying the ToolBase interface. AgentScope ships built-in tools for common operations and exposes the same interface for developers to build their own:

Topic	Covers
ToolBase Interface	The attributes and methods every tool implements
Built-in Tools	Ready-to-use tools: `Bash`, file tools, plan tools
Switch Tool Backend	Run built-in tools against Docker, E2B, or other environments
Create Custom Tool	Subclass `ToolBase` with your own schema and permission logic
Wrap Function as Tool	Turn a plain Python function into a tool with `FunctionTool`
External Execution Tool	Delegate execution to a human or an external system
Tool Middleware	Attach onion-style hooks to a tool instance

ToolBase Interface

ToolBase is the abstract base class every tool satisfies. The tables below list its attributes and methods. Attributes that describe the tool to the agent and the runtime:

Attribute	Type	Description
`name`	`str`	The tool name presented to the agent
`description`	`str`	Agent-oriented description of what the tool does
`input_schema`	`dict`	JSON Schema defining the tool’s parameters
`is_concurrency_safe`	`bool`	Whether the tool is safe to call in parallel
`is_read_only`	`bool`	Whether the tool only reads data without side effects
`is_external_tool`	`bool`	If `True`, execution is delegated externally (see Define External Execution Tool)
`is_state_injected`	`bool`	If `True`, the agent state is injected via the `_agent_state` argument
`is_mcp`	`bool`	Whether the tool comes from an MCP server
`mcp_name`	`str \| None`	The MCP server name when `is_mcp` is `True`

Methods that hook into execution and the permission system:

Method	Required	Description
`check_permissions(tool_input, context)`	Yes	Runtime permission check before execution; returns `PermissionDecision`
`check_read_only(tool_input)`	Optional	Per-invocation read-only check; returns `bool`. Defaults to `self.is_read_only`. Override when read-only-ness depends on the input (e.g. `Bash`: `ls` is read-only, `rm` is not). Used by the permission engine to decide auto-allow in EXPLORE / ACCEPT_EDITS.
`match_rule(rule_content, tool_input)`	Optional	Custom rule-matching logic for the permission system; returns `bool`
`generate_suggestions(tool_input)`	Optional	Generate suggested permission rules from a tool call; returns `list[PermissionRule]`
`call(**kwargs)`	Yes*	The tool’s execution logic, the subclass override point. Returns `ToolChunk` or `AsyncGenerator[ToolChunk, None]`. Not required for external execution tools (`is_external_tool = True`).
`__call__(**kwargs)`	—	Framework dispatch entry point. Runs the middleware chain (if any), then delegates to `call()`. Do not override.

Use Built-in Tools

AgentScope ships a set of ready-to-use tools covering common agent operations. Instantiate them and pass into Toolkit(tools=[...]):

Tool	Description	Read-only
`Bash`	Execute shell commands	No
`Read`	Read file contents with line numbers	Yes
`Write`	Create or overwrite files	No
`Edit`	Perform exact string replacements in files	No
`Glob`	Find files by glob pattern	Yes
`Grep`	Search file contents using ripgrep	Yes
`TaskCreate`	Create a structured task for progress tracking	No
`TaskGet`	Retrieve task details by ID	Yes
`TaskList`	List all tasks and their status	Yes
`TaskUpdate`	Update task status or metadata	No

Two more tools, the reset_tools meta tool and the Skill viewer, are auto-registered by Toolkit whenever extra tool groups or skills exist. Developers do not instantiate them directly. See Meta Tool and Skill.

Bash

The Bash tool executes shell commands and returns stdout/stderr. It implements every optional interface method to provide fine-grained permission control. check_permissions() runs a layered safety analysis on the command string:

Injection risk detection: flags dynamic shell structures ($(...), backticks, process substitution) that cannot be statically analyzed → ASK
Read-only command detection: auto-allows safe commands (git status, ls, cat, grep, docker ps, etc.), including compound commands where every subcommand is read-only → ALLOW
Dangerous command patterns: detects destructive operations (e.g. chmod 777, mkfs) → ASK
Sed constraint check: blocks in-place sed -i against dangerous files → ASK
Dangerous path protection: checks if the command operates on sensitive config files (.bashrc, .ssh/, .env) → ASK
Dangerous removal detection: catches rm / rmdir targeting critical system paths (/, ~, /usr) → ASK
ACCEPT_EDITS mode: auto-allows filesystem commands (mkdir, touch, rm, rmdir, mv, cp, sed) only when every target path resolves inside a configured working directory. A command that touches any path outside the working set (e.g. cp /etc/hosts /tmp/x) falls through to PASSTHROUGH instead of auto-allowing.

check_read_only() returns True for any command identified by the read-only detector above (step 2), and False otherwise. The permission engine uses it to decide auto-allow in EXPLORE / ACCEPT_EDITS without re-running the full safety analysis. match_rule() uses prefix-based wildcard matching against the command string:

Pattern	Matches	Does not match
`npm run:*`	`npm run build`, `npm run test`	`npm install`
`git commit:*`	`git commit -m "fix"`	`git push`
`rm:*`	`rm file.txt`, `rm -rf /tmp/x`	`ls`

generate_suggestions() extracts the command prefix (first two tokens) and proposes a prefix rule. For example, git commit -m "fix bug" produces the suggestion git commit:*. The constructor accepts optional extra entries for the dangerous-path lists:

from agentscope.tool import Bash

bash = Bash(
    additional_dangerous_files=[".secrets"],
    additional_dangerous_directories=[".credentials"],
)

File Tools (Read, Write, Edit)

The file tools enforce a read-before-write rule: Write and Edit require the target file to have been read via Read first. This prevents blind overwrites and ensures the agent always operates on current content.

Tool	Operation	Key behavior
`Read`	Read file contents	Returns content with line numbers; supports offset/limit for large files; results cached in agent state
`Write`	Create or overwrite a file	Fails if the file exists but has not been read first
`Edit`	Replace exact strings in a file	Fails if `old_string` is not found or is not unique (unless `replace_all=True`); requires prior read

check_permissions(): Write and Edit share the same permission logic:

Dangerous path protection: operations on sensitive files (.bashrc, .env, .ssh/) return a bypass-immune ASK (bypass_immune=True), so allow rules cannot silently authorize them. The ASK is still skipped in BYPASS mode (which opts out of safety prompts by design) and converted to DENY in DONT_ASK mode. See the permission system docs for the full contract.
ACCEPT_EDITS mode: auto-allows operations on files within configured working directories
PASSTHROUGH: falls through to the permission engine for rule matching

Read is read-only and always returns PASSTHROUGH (the engine handles EXPLORE-mode and ACCEPT_EDITS-mode auto-allow via check_read_only). match_rule(): all three tools use fnmatch glob matching against the file_path argument:

Pattern	Matches
`src/**`	Any file under `src/`
`src/*/.py`	Python files under `src/`
`config.json`	Exact file match

generate_suggestions() proposes a glob covering the parent directory. For example, editing /project/src/main.py produces the suggestion src/**.

Plan Tools (TaskCreate, TaskGet, TaskList, TaskUpdate)

The plan tools give the agent a structured task list it can append to, query, and update through normal tool calls. They share a single store on agent.state.tasks_context, are state-injected, and always pass permission checks: the agent treats them as free-cost coordination primitives for breaking complex work into trackable steps. See Plan for the full task lifecycle, the storage model, and how to seed or customize tasks programmatically.

Switch Tool Backend

The Bash, Grep, Glob, Read, Write, and Edit tools in AgentScope support backend switching: delegating their execution to different runtime environments such as the local filesystem, a Docker container, an E2B sandbox, and so on. A backend is selected via the backend argument. Backend instances are obtained from a Workspace, which defaults to the local environment. See Workspace for more details.

from agentscope.workspace import DockerWorkspace

# Obtain the backend from a Docker sandbox
workspace = DockerWorkspace(...)
await workspace.initialize()

backend = workspace.get_backend()

# Configure the tool
bash = Bash(backend=backend)

# Run logic
...

await workspace.close()

from agentscope.workspace import E2BWorkspace

# Obtain the backend from an E2B sandbox
workspace = E2BWorkspace(...)
await workspace.initialize()

backend = workspace.get_backend()

# Configure the tool
bash = Bash(backend=backend)

# Run logic
...

await workspace.close()

Create Custom Tool

To create a custom tool, subclass ToolBase, declare its schema, and implement check_permissions and call:

from agentscope.tool import ToolBase, ToolChunk
from agentscope.permission import (
    PermissionContext, PermissionDecision, PermissionBehavior,
)
from agentscope.message import TextBlock

class WebSearch(ToolBase):
    name = "WebSearch"
    description = "Search the web for information on a given query."
    input_schema = {
        "type": "object",
        "properties": {
            "query": {
                "type": "string",
                "description": "The search query.",
            },
        },
        "required": ["query"],
    }
    is_concurrency_safe = True
    is_read_only = True

    async def check_permissions(
        self, tool_input: dict, context: PermissionContext,
    ) -> PermissionDecision:
        return PermissionDecision(
            behavior=PermissionBehavior.ALLOW,
            message="Web search is read-only.",
        )

    async def call(self, query: str) -> ToolChunk:
        results = await do_search(query)
        return ToolChunk(content=[TextBlock(text=results)])

Two extension hooks worth knowing about when writing custom tools with safety logic:

check_read_only(tool_input): override when whether an invocation modifies state depends on the input (like Bash: ls is read-only, rm is not). Defaults to returning the static is_read_only attribute. The permission engine calls it before deciding EXPLORE / ACCEPT_EDITS auto-allow.
PermissionDecision(..., bypass_immune=True): set on a returned ASK to mark it as a safety check that allow rules cannot silence (e.g. a DeployTool flagging prod-* targets). See the safety check contract for per-mode handling.

Wrap Function as Tool

For lightweight cases that don’t justify a full subclass, wrap a plain Python function with the FunctionTool adapter. It auto-extracts the tool name from func.__name__, the description from the function docstring, and the input schema from type hints.

from agentscope.tool import FunctionTool, Toolkit

def get_weather(city: str, unit: str = "celsius") -> str:
    """Get the current weather for a city.

    Args:
        city: The city name to look up.
        unit: Temperature unit, either "celsius" or "fahrenheit".
    """
    return f"The weather in {city} is 22°{unit[0].upper()}"

toolkit = Toolkit(tools=[FunctionTool(get_weather)])

FunctionTool accepts overrides when the auto-extracted defaults are not what you want:

Argument	Type	Description
`func`	`Callable`	The Python function to wrap
`name`	`str \| None`	Override the tool name (defaults to `func.__name__`)
`description`	`str \| None`	Override the description (defaults to the docstring)
`is_concurrency_safe`	`bool`	Whether parallel calls are safe (default `True`)
`is_read_only`	`bool`	Whether the function has side effects (default `False`)
`is_state_injected`	`bool`	Whether the agent state is injected as `_agent_state` (default `False`)

Wrapped functions default to ASK permission behavior: the user must explicitly allow each call. Subclass ToolBase directly when you need custom permission logic.

Define External Execution Tool

An external execution tool delegates its actual execution outside the agent runtime, typically to a human operator or an external system. When the agent calls one, it emits a RequireExternalExecutionEvent and pauses until the result is delivered via ExternalExecutionResultEvent. This pattern underlies the human-in-the-loop workflow, where certain actions require human approval or manual execution. To create an external execution tool, set is_external_tool = True. There is no need to implement call:

from agentscope.tool import ToolBase
from agentscope.permission import (
    PermissionContext, PermissionDecision, PermissionBehavior,
)

class HumanApproval(ToolBase):
    name = "HumanApproval"
    description = "Request human approval for a sensitive operation."
    input_schema = {
        "type": "object",
        "properties": {
            "action": {"type": "string", "description": "The action requiring approval."},
            "reason": {"type": "string", "description": "Why this action needs approval."},
        },
        "required": ["action", "reason"],
    }
    is_concurrency_safe = True
    is_read_only = False
    is_external_tool = True

    async def check_permissions(
        self, tool_input: dict, context: PermissionContext,
    ) -> PermissionDecision:
        return PermissionDecision(
            behavior=PermissionBehavior.ALLOW,
            message="External tool dispatch is always allowed.",
        )

Tool Middleware

Tool middleware attaches onion-style hooks directly to a tool instance. Every time that tool is invoked, whether by an agent or called directly, the registered middlewares fire in order, wrap the execution, and can observe or transform both inputs and outputs. This is separate from agent-level middleware (MiddlewareBase): on_acting in agent middleware wraps the entire tool-call slot inside the ReAct loop (including permission checks and event emission), while ToolMiddlewareBase hooks only inside the tool’s own call() execution chain and fires even when the tool is called outside any agent.

ToolMiddlewareBase Interface

Subclass ToolMiddlewareBase and implement the single abstract async-generator method on_tool_call:

Parameter	Type	Description
`tool`	`ToolBase`	The tool instance being invoked
`input_kwargs`	`dict[str, Any]`	Input arguments for this invocation. Pass (possibly modified) arguments to `next_handler` to control what the inner layers receive
`next_handler`	`Callable[..., AsyncGenerator[ToolChunk, None]]`	Call as `next_handler(**input_kwargs)` to continue to the next layer. Always returns an async generator regardless of whether the underlying tool is streaming or not

Execution Model

The first registered middleware is the outermost layer: its pre-logic runs first, its post-logic runs last.
next_handler(**input_kwargs) always returns AsyncGenerator[ToolChunk, None]. Streaming and non-streaming tools are unified, so a middleware never needs to handle the two shapes separately.
The innermost layer calls the tool’s own call().

middlewares[0].on_tool_call
  └─ middlewares[1].on_tool_call
       └─ ... → tool.call()

Attach Middleware

Pass a list of middleware instances to the tool constructor via the middlewares argument:

from agentscope.tool import Bash

bash = Bash(middlewares=[LoggingMiddleware(), MetricsMiddleware()])
# Execution order: LoggingMiddleware → MetricsMiddleware → Bash.call()

Example

A logging middleware that prints before and after each invocation, and a retry middleware that re-attempts on failure:

from typing import AsyncGenerator, Any, Callable
from agentscope.tool import ToolMiddlewareBase, ToolBase, ToolChunk, Bash


class LoggingMiddleware(ToolMiddlewareBase):
    async def on_tool_call(
        self,
        tool: ToolBase,
        input_kwargs: dict[str, Any],
        next_handler: Callable[..., AsyncGenerator[ToolChunk, None]],
    ) -> AsyncGenerator[ToolChunk, None]:
        print(f"→ Calling {tool.name} with {input_kwargs}")
        async for chunk in next_handler(**input_kwargs):
            yield chunk
        print(f"✓ {tool.name} finished")


class RetryMiddleware(ToolMiddlewareBase):
    def __init__(self, max_attempts: int = 3):
        self.max_attempts = max_attempts

    async def on_tool_call(
        self,
        tool: ToolBase,
        input_kwargs: dict[str, Any],
        next_handler: Callable[..., AsyncGenerator[ToolChunk, None]],
    ) -> AsyncGenerator[ToolChunk, None]:
        for attempt in range(1, self.max_attempts + 1):
            try:
                async for chunk in next_handler(**input_kwargs):
                    yield chunk
                return
            except Exception as e:
                if attempt == self.max_attempts:
                    raise
                print(f"Attempt {attempt} failed: {e}, retrying…")


bash = Bash(middlewares=[LoggingMiddleware(), RetryMiddleware(max_attempts=3)])

Tool middleware vs. agent middleware: use ToolMiddlewareBase for cross-cutting concerns that belong to the tool itself (logging, metrics, retry). Use MiddlewareBase.on_acting when you need access to the broader agent context, such as permission decisions, the tool-call event, or the surrounding ReAct round. See Middleware for the full agent-level hook reference.

Get Started

Building Blocks

Agent as Service

Others

ToolBase Interface

Use Built-in Tools

Bash

File Tools (Read, Write, Edit)

Plan Tools (TaskCreate, TaskGet, TaskList, TaskUpdate)

Switch Tool Backend

Create Custom Tool

Wrap Function as Tool

Define External Execution Tool

Tool Middleware

ToolMiddlewareBase Interface

Execution Model

Attach Middleware

Example

​ToolBase Interface

​Use Built-in Tools

​Bash

​File Tools (Read, Write, Edit)

​Plan Tools (TaskCreate, TaskGet, TaskList, TaskUpdate)

​Switch Tool Backend

​Create Custom Tool

​Wrap Function as Tool

​Define External Execution Tool

​Tool Middleware

​ToolMiddlewareBase Interface

​Execution Model

​Attach Middleware

​Example

ToolBase Interface

Use Built-in Tools

Bash

File Tools (Read, Write, Edit)

Plan Tools (TaskCreate, TaskGet, TaskList, TaskUpdate)

Switch Tool Backend

Create Custom Tool

Wrap Function as Tool

Define External Execution Tool

Tool Middleware

ToolMiddlewareBase Interface

Execution Model

Attach Middleware

Example