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

LocalBackend

class LocalBackend(BackendBase)
源码Source agentscope/tool/_builtin/_backend.py:741–1089

本地 Backend，让智能体以受控方式调用外部能力。位于 agentscope.tool 包，继承自 BackendBase。核心成员包括 exec_shell、read_file、write_file、write_stream、read_stream、getcwd。

Uses asyncio.create_subprocess_exec, aiofiles, and the os module. This is the default backend injected when no explicit one is given to a builtin tool. Commands are spawned directly from their argument vector (no shell), which avoids the POSIX-vs-cmd.exe quoting mismatch and makes the backend work on Windows. The derived filesystem helpers are overridden with native os.* calls — faster and more robust than shelling out, and portable to Windows where test / find / stat are unavailable.

属性摘要Attribute Summary

属性Attribute类型Type说明Description值Value
os_name—
os 名称字段。
os.name

方法摘要Method Summary

方法Method说明Description
async def exec_shell(command: list[str], *, cwd: str | None = None, timeout: float | None = None) -> ExecResultasync
执行 `exec_shell` 方法。
Run a program via ``asyncio.create_subprocess_exec``.
async def read_file(path: str) -> bytesasync
设置读取文件。
Read a local file as raw bytes.
async def write_file(path: str, data: bytes) -> Noneasync
执行写入文件相关操作。
Write *data* to a local file, creating parent dirs.
async def write_stream(path: str, stream: AsyncIterator[bytes]) -> Noneasync
执行写入流相关操作。
Write a byte stream to a local file, chunk by chunk.
async def read_stream(path: str, chunk_size: int = DEFAULT_READ_CHUNK_SIZE) -> AsyncIterator[bytes]async
执行读取流相关操作。
Read a local file chunk by chunk, never holding it whole.
async def getcwd() -> strasync
返回 `getcwd` 结果。
Return the host process's current working directory.
async def expanduser(path: str) -> strasync
设置该参数。
Expand ``~`` using the host process's ``$HOME``.
async def file_exists(path: str) -> boolasync
设置该参数。
Check if a local path exists.
async def is_dir(path: str) -> boolasync
检查if 本地路径是目录。
Check if a local path is a directory.
async def list_dir(path: str, *, recursive: bool = False) -> list[str]async
列出目录。
List local directory entries.
async def scandir(path: str) -> list[DirEntry]async
设置该参数。
List a local directory with each entry's metadata.
async def stat(path: str) -> DirEntry | Noneasync
设置该参数。
Return one local path's type, size and mtime.
async def stat_mtime(path: str) -> float | Noneasync
设置该参数。
Return the modification time of a local file.
async def delete_path(path: str) -> Noneasync
删除路径。
Delete a local file or directory tree.

属性详情Attribute Detail

os_name

 = os.name

os 名称字段。

The os name field.

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

方法详情Method Detail

exec_shell

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

执行 exec_shell 方法。

The program is spawned directly from command without an intervening shell, so no argument quoting is required and the same code path works on POSIX and Windows.

参数Parameters
名称Name类型Type说明Description
commandlist[str]命令（类型 `list[str]`）。Executable path/name followed by its arguments.
cwdkw默认default Nonestr | Nonecwd（类型 `str | None`）。Working directory for the subprocess. When `None` the current process working directory is used.
timeoutkw默认default Nonefloat | None超时时间（类型 `float | None`）。Maximum number of seconds to wait before the process is killed and an `exit_code` of `-1` is returned.
返回Returns ExecResult
返回ExecResult。`ExecResult`:
源码Source agentscope/tool/_builtin/_backend.py:764–837

read_file

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

设置读取文件。

Read a local file as raw bytes.

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

write_file

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

执行写入文件相关操作。

Write data to a local file, creating parent dirs.

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

write_stream

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

执行写入流相关操作。

Write a byte stream to a local file, chunk by chunk.

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

read_stream

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

执行读取流相关操作。

Read a local file chunk by chunk, never holding it whole.

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

getcwd

async def getcwd() -> str
async

返回 getcwd 结果。

Return the host process's current working directory.

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

expanduser

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

设置该参数。

Expand ~ using the host process's $HOME.

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

file_exists

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

设置该参数。

Check if a local path exists.

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

is_dir

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

检查if 本地路径是目录。

Check if a local path is a directory.

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

list_dir

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

列出目录。

Mirrors the base contract using native os calls.

参数Parameters
名称Name类型Type说明Description
pathstr路径（类型 `str`）。Directory to list.
recursivekw默认default Falseboolrecursive（类型 `bool`）。When `True`, return file paths underneath `path` (`os.walk`). When `False` (default), return the immediate children's base names (`os.listdir`).
返回Returns list[str]
返回str列表。`list[str]`:
源码Source agentscope/tool/_builtin/_backend.py:958–986

scandir

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

设置该参数。

os.scandir carries the type in the directory record itself, so this is cheaper than os.listdir followed by a stat per entry — the same reason the base class batches its find.

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

stat

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

设置该参数。

Return one local path's type, size and mtime.

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

stat_mtime

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

设置该参数。

Return the modification time of a local file.

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

delete_path

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

删除路径。

Symbolic links are removed without following their targets, including when the target no longer exists.

参数Parameters
名称Name类型Type说明Description
pathstr路径（类型 `str`）。Path to delete.
返回Returns None
无返回值。No value is returned.
源码Source agentscope/tool/_builtin/_backend.py:1070–1089

继承成员Inherited Members

继承自Inherited from BackendBase
join_path, dirname, basename, isabs, normpath, abspath
基于官方固定版本源码静态生成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.