AS AgentScopeAPI 手册 / API Reference
类class agentscope.tool

BackendBase

class BackendBase(ABC)
源码Source agentscope/tool/_builtin/_backend.py:138–712

Backend 基类，让智能体以受控方式调用外部能力。位于 agentscope.tool 包，继承自 ABC。核心成员包括 join_path、dirname、basename、isabs、normpath、abspath。

Subclasses must implement three abstract primitives — exec_shell, read_file, and write_file — which are the only operations whose mechanism genuinely differs per environment. The remaining filesystem helpers are implemented here on top of exec_shell and work for any backend whose shell is POSIX-like; a backend with a cheaper native path may override them (see :class:LocalBackend).

属性摘要Attribute Summary

属性Attribute类型Type说明Description值Value
os_namestr
os 名称字段。
'posix'

方法摘要Method Summary

方法Method说明Description
def join_path(path: str, *paths: str) -> str
连接路径。
Join one or more path components using the backend's separator.
def dirname(path: str) -> str
设置该参数。
Return the directory component of ``path``.
def basename(path: str) -> str
设置该参数。
Return the final component of ``path``.
def isabs(path: str) -> bool
执行 `isabs` 方法。
Return ``True`` if ``path`` is absolute in the backend.
def normpath(path: str) -> str
设置该参数。
Normalize ``path`` (collapse ``..``, ``.``, duplicate seps).
def abspath(path: str, *, cwd: str) -> str
执行 `abspath` 方法。
Return an absolute, normalized version of ``path``.
async def exec_shell(command: list[str], *, cwd: str | None = None, timeout: float | None = None) -> ExecResultasyncabstractabstractmethod
执行 `exec_shell` 方法。
Run a program directly from an argument vector.
async def read_file(path: str) -> bytesasyncabstractabstractmethod
设置读取文件。
Read the full contents of ``path`` as raw bytes.
async def write_file(path: str, data: bytes) -> Noneasyncabstractabstractmethod
执行写入文件相关操作。
Write ``data`` to ``path``, creating parent directories.
async def write_stream(path: str, stream: AsyncIterator[bytes]) -> Noneasync
执行写入流相关操作。
Write a byte stream to ``path``, creating parent directories.
async def read_stream(path: str, chunk_size: int = DEFAULT_READ_CHUNK_SIZE) -> AsyncIterator[bytes]async
执行读取流相关操作。
Read ``path`` as a byte stream.
async def getcwd() -> strasync
返回 `getcwd` 结果。
Return the backend environment's current working directory.
async def expanduser(path: str) -> strasync
设置该参数。
Expand a leading ``~`` / ``~/`` to the backend's home directory.
async def file_exists(path: str) -> boolasync
设置该参数。
Return ``True`` if ``path`` exists (file or directory).
async def is_dir(path: str) -> boolasync
判断是否目录。
Return ``True`` if ``path`` is an existing directory.
async def list_dir(path: str, *, recursive: bool = False) -> list[str]async
列出目录。
List entries under ``path``.
async def scandir(path: str) -> list[DirEntry]async
设置该参数。
List one directory level with each entry's metadata.
async def stat(path: str) -> DirEntry | Noneasync
设置该参数。
Return one path's type, size and mtime in a single call.
async def stat_mtime(path: str) -> float | Noneasync
设置该参数。
Return the modification time of ``path``, or ``None``.
async def delete_path(path: str) -> Noneasync
删除路径。
Delete ``path`` (file or directory tree).

属性详情Attribute Detail

os_name

str = 'posix'

os 名称字段。声明为 str。

The os name field.

源码Source agentscope/tool/_builtin/_backend.py:186

方法详情Method Detail

join_path

def join_path(path: str, *paths: str) -> str

连接路径。

Join one or more path components using the backend's separator.

参数Parameters
名称Name类型Type说明Description
pathstr路径（类型 `str`）。The first path component.
pathsstrpaths（类型 `str`）。The paths.
返回Returns str
返回字符串结果。`str`:
源码Source agentscope/tool/_builtin/_backend.py:190–204

dirname

def dirname(path: str) -> str

设置该参数。

Return the directory component of path.

参数Parameters
名称Name类型Type说明Description
pathstr路径（类型 `str`）。A path inside the backend's environment.
返回Returns str
返回字符串结果。`str`:
源码Source agentscope/tool/_builtin/_backend.py:206–218

basename

def basename(path: str) -> str

设置该参数。

Return the final component of path.

参数Parameters
名称Name类型Type说明Description
pathstr路径（类型 `str`）。A path inside the backend's environment.
返回Returns str
返回字符串结果。`str`:
源码Source agentscope/tool/_builtin/_backend.py:220–232

isabs

def isabs(path: str) -> bool

执行 isabs 方法。

Return True if path is absolute in the backend.

参数Parameters
名称Name类型Type说明Description
pathstr路径（类型 `str`）。A path inside the backend's environment.
返回Returns bool
返回布尔值，表示判断结果。`bool`:
源码Source agentscope/tool/_builtin/_backend.py:234–246

normpath

def normpath(path: str) -> str

设置该参数。

Pure string operation — does not touch the filesystem.

参数Parameters
名称Name类型Type说明Description
pathstr路径（类型 `str`）。A path inside the backend's environment.
返回Returns str
返回字符串结果。`str`:
源码Source agentscope/tool/_builtin/_backend.py:248–261

abspath

def abspath(path: str, *, cwd: str) -> str

执行 abspath 方法。

Unlike :func:os.path.abspath, this helper never reads the host process's working directory: when path is relative it is joined with the explicitly supplied cwd, which must itself be a path that is meaningful inside the backend's environment.

参数Parameters
名称Name类型Type说明Description
pathstr路径（类型 `str`）。A path inside the backend's environment.
cwdkwstrcwd（类型 `str`）。Directory to resolve a relative `path` against. Ignored when `path` is already absolute.
返回Returns str
返回字符串结果。`str`:
源码Source agentscope/tool/_builtin/_backend.py:263–289

exec_shell

async def exec_shell(command: list[str], *, cwd: str | None = None, timeout: float | None = None) -> ExecResult
asyncabstractabstractmethod

执行 exec_shell 方法。

command* is an executable followed by its arguments — it is not passed through a shell, so callers never have to quote or escape arguments and there is no platform-specific quoting bug.

参数Parameters
名称Name类型Type说明Description
commandlist[str]命令（类型 `list[str]`）。Executable path/name followed by its arguments.
cwdkw默认default Nonestr | Nonecwd（类型 `str | None`）。Working directory to run the command in. When `None` the backend's default working directory is used.
timeoutkw默认default Nonefloat | None超时时间（类型 `float | None`）。Maximum number of seconds to wait. When `None` the call waits indefinitely. On timeout the result carries an `exit_code` of `-1`.
返回Returns ExecResult
返回ExecResult。`ExecResult`:
源码Source agentscope/tool/_builtin/_backend.py:294–328

read_file

async def read_file(path: str) -> bytes
asyncabstractabstractmethod

设置读取文件。

Read the full contents of path as raw bytes.

参数Parameters
名称Name类型Type说明Description
pathstr路径（类型 `str`）。Path to the file inside the backend's environment.
返回Returns bytes
返回字节。`bytes`:
源码Source agentscope/tool/_builtin/_backend.py:331–341

write_file

async def write_file(path: str, data: bytes) -> None
asyncabstractabstractmethod

执行写入文件相关操作。

Write data to path, creating parent directories.

参数Parameters
名称Name类型Type说明Description
pathstr路径（类型 `str`）。Destination path inside the backend's environment.
databytes原始字节到写入。The raw bytes to write.
返回Returns None
无返回值。No value is returned.
源码Source agentscope/tool/_builtin/_backend.py:344–352

write_stream

async def write_stream(path: str, stream: AsyncIterator[bytes]) -> None
async

执行写入流相关操作。

The default buffers the whole stream and delegates to :meth:write_file, so peak memory is the payload size; only backends that override this (LocalBackend, BubblewrapBackend, K8sBackend) are constant-memory.

参数Parameters
名称Name类型Type说明Description
pathstr路径（类型 `str`）。Destination path inside the backend's environment.
streamAsyncIterator[bytes]流（类型 `AsyncIterator[bytes]`）。The chunks to write, in order.
返回Returns None
无返回值。No value is returned.
源码Source agentscope/tool/_builtin/_backend.py:354–375

read_stream

async def read_stream(path: str, chunk_size: int = DEFAULT_READ_CHUNK_SIZE) -> AsyncIterator[bytes]
async

执行读取流相关操作。

The default reads the whole file through :meth:read_file and re-slices it, so peak memory is the file size; only backends that override this (LocalBackend) are constant-memory.

参数Parameters
名称Name类型Type说明Description
pathstr路径（类型 `str`）。Path to the file inside the backend's environment.
chunk_size默认default DEFAULT_READ_CHUNK_SIZEint分块大小（类型 `int`）。The size of each yielded chunk.
返回Returns AsyncIterator[bytes]
以异步流的形式返回字节。`bytes`:
源码Source agentscope/tool/_builtin/_backend.py:377–402

getcwd

async def getcwd() -> str
async

返回 getcwd 结果。

This is the directory that bare exec_shell invocations (those with cwd=None) execute in.

返回Returns str
返回字符串结果。`str`:
源码Source agentscope/tool/_builtin/_backend.py:406–426

expanduser

async def expanduser(path: str) -> str
async

设置该参数。

Tools should call this — instead of :func:os.path.expanduser — whenever they need to expand ~ in a path that lives inside the backend's environment, because the host process's $HOME is meaningless for remote backends.

参数Parameters
名称Name类型Type说明Description
pathstr路径（类型 `str`）。A path inside the backend's environment, possibly starting with `~`.
返回Returns str
返回字符串结果。`str`:
源码Source agentscope/tool/_builtin/_backend.py:428–462

file_exists

async def file_exists(path: str) -> bool
async

设置该参数。

Return True if path exists (file or directory).

参数Parameters
名称Name类型Type说明Description
pathstr路径（类型 `str`）。Path to test inside the backend's environment.
返回Returns bool
返回布尔值，表示判断结果。`bool`:
源码Source agentscope/tool/_builtin/_backend.py:464–476

is_dir

async def is_dir(path: str) -> bool
async

判断是否目录。

Return True if path is an existing directory.

参数Parameters
名称Name类型Type说明Description
pathstr路径（类型 `str`）。Path to test inside the backend's environment.
返回Returns bool
返回布尔值，表示判断结果。`bool`:
源码Source agentscope/tool/_builtin/_backend.py:478–490

list_dir

async def list_dir(path: str, *, recursive: bool = False) -> list[str]
async

列出目录。

Output is NUL-delimited (find -print0 / -printf '%f\0') and split on \0 so that file names containing spaces or newlines are handled correctly.

参数Parameters
名称Name类型Type说明Description
pathstr路径（类型 `str`）。Directory to list inside the backend's environment.
recursivekw默认default Falseboolrecursive（类型 `bool`）。When `True`, return all files underneath `path` as paths (like `find path -type f`). When `False` (default), return the immediate children's base names (like `os.listdir`).
返回Returns list[str]
返回str列表。`list[str]`:
源码Source agentscope/tool/_builtin/_backend.py:492–540

scandir

async def scandir(path: str) -> list[DirEntry]
async

设置该参数。

The type, size and mtime come back from the same find run as the names, so listing a directory of N entries costs one round trip rather than 1 + 3N.

参数Parameters
名称Name类型Type说明Description
pathstr路径（类型 `str`）。Directory to list inside the backend's environment.
返回Returns list[DirEntry]
返回DirEntry列表。`list[DirEntry]`:
源码Source agentscope/tool/_builtin/_backend.py:542–576

stat

async def stat(path: str) -> DirEntry | None
async

设置该参数。

The single-path counterpart of :meth:scandir, the way :func:os.stat sits beside :func:os.scandir.

参数Parameters
名称Name类型Type说明Description
pathstr路径（类型 `str`）。Path to stat inside the backend's environment.
返回Returns DirEntry | None
返回DirEntry|None。`DirEntry | None`:
源码Source agentscope/tool/_builtin/_backend.py:578–601

stat_mtime

async def stat_mtime(path: str) -> float | None
async

设置该参数。

Tries GNU stat -c %Y first and falls back to BSD stat -f %m so the same call works across coreutils and BSD/macOS userlands.

参数Parameters
名称Name类型Type说明Description
pathstr路径（类型 `str`）。Path to stat inside the backend's environment.
返回Returns float | None
返回float|None。`float | None`:
源码Source agentscope/tool/_builtin/_backend.py:669–700

delete_path

async def delete_path(path: str) -> None
async

删除路径。

If path does not exist the call is a silent no-op (like rm -rf).

参数Parameters
名称Name类型Type说明Description
pathstr路径（类型 `str`）。Path to delete inside the backend's environment.
返回Returns None
无返回值。No value is returned.
源码Source agentscope/tool/_builtin/_backend.py:702–712
基于官方固定版本源码静态生成Generated from pinned official sources · Python 2.0.11 · Java 2.0.4
签名与文档为静态抽取；如有疑问请以源码为准。Signatures and docs are extracted statically; verify against the source when in doubt.