类class agentscope.workspace

LocalWorkspace

class LocalWorkspace(WorkspaceBase)

源码Source agentscope/workspace/_local_workspace.py:65–1003

本地工作区，在隔离环境中安全执行代码和工具。位于 agentscope.workspace 包，继承自 WorkspaceBase。核心成员包括 list_tools、initialize、get_instructions、close、reset、list_skills。

Layout::

{workdir}/
├── .mcp          # declared MCP configs per agent/session
├── data/         # offloaded multimodal files
├── skills/       # .seed template, plus one partition per agent
└── sessions/     # per-session context and tool-result files

构造器摘要Constructor Summary

构造器Constructor	说明Description
`def __init__(*, workdir: str, workspace_id: str \| None = None, default_mcps: list[MCPClient] \| None = None, skill_paths…`	初始化 `LocalWorkspace` 实例。 Construct a :class:`LocalWorkspace`.

方法摘要Method Summary

方法Method	说明Description
`async def list_tools() -> list[ToolBase]`async	列出当前连接可用的工具。 Return builtin tools, using PowerShell as the shell on Windows.
`async def initialize() -> None`async	初始化 `LocalWorkspace` 实例。 Initialise the workspace.
`async def get_instructions() -> str`async	获取工作区指令。 Get the workspace instructions.
`async def close() -> None`async	关闭连接并释放相关资源。 Close every stateful MCP attached to this workspace.
`async def reset() -> None`async	返回工作区到工厂状态。 Return the workspace to a factory state.
`async def list_skills(*, agent_id: str \| None = None) -> list[Skill]`async	列出技能。 List the skills one agent can use.
`async def add_mcp(mcp_client:` `MCPClient, *, agent_id: str \| None = None, session_id: str \| None = None) -> MCPClient`async	添加MCP。 Add an MCP client for one agent/session and persist it.
`async def remove_mcp(name: str, *, agent_id: str \| None = None, session_id: str \| None = None) -> None`async	移除MCP。 Remove an MCP client by name, disconnecting it if stateful.
`async def add_skill(skill_path: str, *, agent_id: str \| None = None) -> None`async	添加技能。 Add a skill to an agent's partition by copying from a path.
`async def add_skill_archive(stream: AsyncIterator[bytes], fmt: Literal['zip', 'tar', 'tar.gz'], dir_name: str, max_extr…`async	添加技能归档。 Expand a skill archive, then install it as a local directory.
`async def remove_skill(name: str, *, agent_id: str \| None = None) -> None`async	移除技能。 Remove a skill from the workspace by its agent-facing name.

构造器详情Constructor Detail

LocalWorkspace

def __init__(*, workdir: str, workspace_id: str | None = None, default_mcps: list[MCPClient] | None = None, skill_paths: list[str] | None = None, instructions: str = DEFAULT_WORKSPACE_INSTRUCTIONS, max_live_stateful_mcps: int | None = None) -> None

初始化 LocalWorkspace 实例。

Construct a :class:LocalWorkspace.

参数Parameters

名称Name	类型Type	说明Description
`workdir`kw	str	workdir（类型 `str`）。Filesystem path to the workspace root. Created on demand. Always resolved to an absolute path.
`workspace_id`kw默认default `None`	str \| None	工作区标识（类型 `str \| None`）。Existing workspace identifier to adopt. `None` generates a fresh UUID.
`default_mcps`kw默认default `None`	list[MCPClient] \| None	默认 mcps（类型 `list[MCPClient] \| None`）。MCP clients seeded into every agent/session that has not added or removed one of its own.
`skill_paths`kw默认default `None`	list[str] \| None	技能 paths（类型 `list[str] \| None`）。Local skill directories written to the seed template on first :meth:`initialize`, from which every agent's partition is equipped.
`instructions`kw默认default `DEFAULT_WORKSPACE_INSTRUCTIONS`	str	指令（类型 `str`）。System-prompt fragment template returned by :meth:`get_instructions`. Supports the `{workdir}` placeholder.
`max_live_stateful_mcps`kw默认default `None`	int \| None	最大 live stateful mcps（类型 `int \| None`）。Cap on concurrently live stateful MCP instances across all agents and sessions.

源码Source agentscope/workspace/_local_workspace.py:77–130

方法详情Method Detail

list_tools

async def list_tools() -> list[ToolBase]

async

列出当前连接可用的工具。

Return builtin tools, using PowerShell as the shell on Windows.

返回Returns list[ToolBase]

返回ToolBase列表。Returns a list of tool base.

源码Source agentscope/workspace/_local_workspace.py:141–162

initialize

async def initialize() -> None

async

初始化 LocalWorkspace 实例。

MCP declarations are restored from .mcp; sessions absent from it fall back to default_mcps.

返回Returns None

无返回值。No value is returned.

源码Source agentscope/workspace/_local_workspace.py:164–283

get_instructions

async def get_instructions() -> str

async

获取工作区指令。

Get the workspace instructions.

返回Returns str

返回字符串结果。Returns a string.

源码Source agentscope/workspace/_local_workspace.py:285–287

close

async def close() -> None

async

关闭连接并释放相关资源。

LocalWorkspace itself owns no resources (the workdir is the persistence layer and is left untouched), but stdio / stateful HTTP MCPs hold long-lived sessions that have to be closed explicitly.

返回Returns None

无返回值。No value is returned.

源码Source agentscope/workspace/_local_workspace.py:414–425

reset

async def reset() -> None

async

返回工作区到工厂状态。

Closes and drops all MCPs (including the persisted .mcp) and deletes skills/, sessions/, and data/.

返回Returns None

无返回值。No value is returned.

源码Source agentscope/workspace/_local_workspace.py:427–449

list_skills

async def list_skills(*, agent_id: str | None = None) -> list[Skill]

async

列出技能。

Reads the agent's own partition — equipping it from the seed template on the agent's first appearance — using the partition's .index for agent-facing names.

参数Parameters

名称Name	类型Type	说明Description
`agent_id`kw默认default `None`	str \| None	智能体标识（类型 `str \| None`）。The agent asking. `None` reads the default partition, which is where an SDK caller driving the workspace without agents puts everything.

返回Returns list[Skill]

返回技能列表。`list[Skill]`:

源码Source agentscope/workspace/_local_workspace.py:451–474

add_mcp

async def add_mcp(mcp_client: MCPClient, *, agent_id: str | None = None, session_id: str | None = None) -> MCPClient

async

添加MCP。

Add an MCP client for one agent/session and persist it.

参数Parameters

名称Name	类型Type	说明Description
`mcp_client`	MCPClient	MCP 客户端到添加。The MCP client to add.
`agent_id`kw默认default `None`	str \| None	智能体标识（类型 `str \| None`）。The owning agent. `None` means the legacy `""`.
`session_id`kw默认default `None`	str \| None	会话标识（类型 `str \| None`）。The owning session. `None` means the legacy `""`.

返回Returns MCPClient

返回MCPClient。`MCPClient`:

异常Raises

可能抛出 `Exception`。`ValueError`:
可能抛出 `Exception`。If the name already exists for this agent/session.
可能抛出 `Exception`。Names are unique because they compose the model-facing
可能抛出 `Exception`。tool name `mcp__{name}__{tool}`.

源码Source agentscope/workspace/_local_workspace.py:682–729

remove_mcp

async def remove_mcp(name: str, *, agent_id: str | None = None, session_id: str | None = None) -> None

async

移除MCP。

Remove an MCP client by name, disconnecting it if stateful.

参数Parameters

名称Name	类型Type	说明Description
`name`	str	名称（类型 `str`）。The `name` field of the client to remove.
`agent_id`kw默认default `None`	str \| None	智能体标识（类型 `str \| None`）。The owning agent. `None` means the legacy `""`.
`session_id`kw默认default `None`	str \| None	会话标识（类型 `str \| None`）。The owning session. `None` means the legacy `""`.

返回Returns None

无返回值。No value is returned.

源码Source agentscope/workspace/_local_workspace.py:731–768

add_skill

async def add_skill(skill_path: str, *, agent_id: str | None = None) -> None

async

添加技能。

The skill directory must contain a valid SKILL.md file with name and description frontmatter fields.

参数Parameters

名称Name	类型Type	说明Description
`skill_path`	str	技能路径（类型 `str`）。Absolute or relative path to the skill directory to copy.
`agent_id`kw默认default `None`	str \| None	智能体标识（类型 `str \| None`）。The agent taking ownership. `None` installs into the default partition.

返回Returns None

无返回值。No value is returned.

异常Raises

ValueError 可能抛出 `ValueError`。If the skill at `skill_path` is invalid (missing or malformed `SKILL.md`).

源码Source agentscope/workspace/_local_workspace.py:770–875

add_skill_archive

async def add_skill_archive(stream: AsyncIterator[bytes], fmt: Literal['zip', 'tar', 'tar.gz'], dir_name: str, max_extracted_bytes: int = DEFAULT_MAX_EXTRACTED_BYTES, *, agent_id: str | None = None) -> None

async

添加技能归档。

Unpacks inside the workspace and hands the result to :meth:add_skill, so hash dedup, name conflict resolution and the .skills index behave exactly as for a path install — which is also why dir_name is ignored here: the directory name comes from the SKILL.md front matter.

参数Parameters

名称Name	类型Type	说明Description
`stream`	AsyncIterator[bytes]	归档字节,in 顺序。The archive bytes, in order.
`fmt`	Literal['zip', 'tar', 'tar.gz']	归档格式。The archive format.
`dir_name`	str	目录名称（类型 `str`）。Unused; kept for interface compatibility.
`max_extracted_bytes`默认default `DEFAULT_MAX_EXTRACTED_BYTES`	int	最大 extracted 字节（类型 `int`）。Ceiling on the archive's expanded size.
`agent_id`kw默认default `None`	str \| None	智能体标识（类型 `str \| None`）。The agent taking ownership. `None` installs into the default partition.

返回Returns None

无返回值。No value is returned.

异常Raises

ValueError 可能抛出 `ValueError`。If the archive holds no valid `SKILL.md`.
RuntimeError 可能抛出 `RuntimeError`。If expanding the archive fails.

源码Source agentscope/workspace/_local_workspace.py:877–942

remove_skill

async def remove_skill(name: str, *, agent_id: str | None = None) -> None

async

移除技能。

The skill directory is deleted from the agent's partition and that partition's .index is updated.

参数Parameters

名称Name	类型Type	说明Description
`name`	str	名称（类型 `str`）。The agent-facing name of the skill to remove (as stored in the `.index`, i.e. the `name` field from `SKILL.md` possibly with a numeric suffix for de-duplication).
`agent_id`kw默认default `None`	str \| None	智能体标识（类型 `str \| None`）。The agent asking. `None` uses the default partition.

返回Returns None

无返回值。No value is returned.

源码Source agentscope/workspace/_local_workspace.py:944–1003

继承成员Inherited Members

继承自Inherited from WorkspaceBase

get_backend, __aenter__, __aexit__, list_mcps, purge_session, purge_agent, offload_context, offload_tool_result, offload_data_block, is_persistent, workspace_id, workdir, is_alive, default_mcps, skill_paths, max_live_stateful_mcps