类class agentscope.app.workspace_manager

DockerWorkspaceManager

class DockerWorkspaceManager(WorkspacePrewarmMixin[DockerWorkspace], WorkspaceManagerBase)

源码Source agentscope/app/workspace_manager/_docker_workspace_manager.py:49–470

Docker 工作区管理器，承载智能体的部署、调度与服务化运行。位于 agentscope.app.workspace_manager 包，继承自 WorkspacePrewarmMixin[DockerWorkspace], WorkspaceManagerBase。核心成员包括 get_workspace、create_workspace、close、close_all。

The manager owns a single set of image-build parameters (base_image / node_version / extra_pip) shared by every workspace it produces; the resulting image is content-hashed so rebuilds are skipped on cache hits.

Use the manager as an async with context manager: entering it starts the TTL sweeper task, exiting it stops the sweeper and then closes every cached workspace via :meth:close_all.

构造器摘要Constructor Summary

构造器Constructor	说明Description
`def __init__(basedir: str, *, isolation:` `IsolationPolicy = IsolationPolicy.PER_AGENT, base_image: str = DEFAULT_BASE_IM…`	初始化 `DockerWorkspaceManager` 实例。 Initialize the docker workspace manager.

方法摘要Method Summary

方法Method	说明Description
`async def get_workspace(user_id: str, agent_id: str, session_id: str, workspace_id: str \| None = None) -> DockerWorkspa…`async	获取工作区。 Return an initialised workspace, building one on cache miss.
`async def create_workspace(user_id: str, agent_id: str, session_id: str) ->` `DockerWorkspace`asyncdeprecateddeprecated	创建工作区。 Build a brand-new workspace and track it.
`async def close(workspace_id: str) -> None`async	关闭连接并释放相关资源。 Close and evict a single workspace from the cache.
`async def close_all() -> None`async	关闭所有。 Close every cached workspace in parallel.
`async def __aenter__() -> Self`async	进入异步上下文并返回自身。 Start the TTL sweeper task and fill the pre-warm buffer.
`async def __aexit__(*exc: object) -> None`async	退出异步上下文并清理资源。 Stop the sweeper and buffer, then close every workspace.

构造器详情Constructor Detail

DockerWorkspaceManager

def __init__(basedir: str, *, isolation: IsolationPolicy = IsolationPolicy.PER_AGENT, base_image: str = DEFAULT_BASE_IMAGE, node_version: str = '22.23.4', extra_pip: list[str] | None = None, gateway_port: int = DEFAULT_GATEWAY_PORT, env: dict[str, str] | None = None, default_mcps: list[MCPClient] | None = None, skill_paths: list[str] | None = None, ttl: float = 3600.0, sweep_interval: float = DEFAULT_SWEEP_INTERVAL, prewarm: PrewarmConfig | None = None) -> None

初始化 DockerWorkspaceManager 实例。

Initialize the docker workspace manager.

参数Parameters

名称Name	类型Type	说明Description
`basedir`	str	basedir（类型 `str`）。Host root under which per-workspace workdir are created (` / `). Each workdir is bind-mounted to `/workspace` inside its container. Keying on the workspace id — rather than on `(user, agent)` — is what lets a container be built before anyone knows who will get it. Workspaces built under the older ` / / ` layout keep mounting that directory.
`isolation`kw默认default `IsolationPolicy.PER_AGENT`	IsolationPolicy	隔离（类型 `IsolationPolicy`）。Isolation grain for :meth:`assign_workspace_id`. `PER_SESSION` → fresh UUID (one workspace per session); `PER_AGENT` / `PER_USER` → deterministic hash so sessions of the same (user, agent) or same user share a workspace. Explicit `workspace_id` on session creation always wins over this policy.
`base_image`kw默认default `DEFAULT_BASE_IMAGE`	str	基类图像（类型 `str`）。Base Docker image; must provide `python3`.
`node_version`kw默认default `'22.23.4'`	str	节点版本（类型 `str`）。Node.js image version to bake into the image.
`extra_pip`kw默认default `None`	list[str] \| None	extra pip（类型 `list[str] \| None`）。Extra Python packages to install into the gateway venv at image-build time.
`gateway_port`kw默认default `DEFAULT_GATEWAY_PORT`	int	网关 port（类型 `int`）。TCP port the in-container gateway listens on (always exposed to a randomly assigned host port).
`env`kw默认default `None`	dict[str, str] \| None	env（类型 `dict[str, str] \| None`）。Environment variables to set inside every workspace's container.
`default_mcps`kw默认default `None`	list[MCPClient] \| None	默认 mcps（类型 `list[MCPClient] \| None`）。MCP clients seeded into brand-new workspaces. Ignored on subsequent restarts of a workdir that already persists `.mcp`.
`skill_paths`kw默认default `None`	list[str] \| None	技能 paths（类型 `list[str] \| None`）。Skill directories seeded into brand-new workspaces.
`ttl`kw默认default `3600.0`	float	存活时间（类型 `float`）。Seconds before an idle cached workspace is evicted and its container torn down.
`sweep_interval`kw默认default `DEFAULT_SWEEP_INTERVAL`	float	sweep 间隔（类型 `float`）。How often (seconds) the background sweeper wakes up to look for idle workspaces. Defaults to 5 minutes.
`prewarm`kw默认default `None`	PrewarmConfig \| None	预热（类型 `PrewarmConfig \| None`）。Keep this many containers built and idle, ready to be handed to the next session that needs one. `None` disables pre-warming.

源码Source agentscope/app/workspace_manager/_docker_workspace_manager.py:65–146

方法详情Method Detail

get_workspace

async def get_workspace(user_id: str, agent_id: str, session_id: str, workspace_id: str | None = None) -> DockerWorkspace

async

获取工作区。

On miss the manager calls DockerWorkspace(workspace_id=…) with a deterministic workdir derived from (user_id, agent_id).

参数Parameters

名称Name	类型Type	说明Description
`user_id`	str	用户标识（类型 `str`）。Owning user identifier.
`agent_id`	str	智能体标识（类型 `str`）。Agent identifier (controls the workdir).
`session_id`	str	会话标识（类型 `str`）。Session identifier (unused for isolation; sessions share a workdir and partition under `sessions/ /`).
`workspace_id`默认default `None`	str \| None	工作区标识（类型 `str \| None`）。Stable workspace identifier — used both as the cache key and the container name suffix. When unset the manager falls back to :meth:`assign_workspace_id`; the session flow should pre-resolve this so container names stay stable across restarts.

返回Returns DockerWorkspace

返回DockerWorkspace。`DockerWorkspace`:

源码Source agentscope/app/workspace_manager/_docker_workspace_manager.py:243–311

create_workspace

async def create_workspace(user_id: str, agent_id: str, session_id: str) -> DockerWorkspace

asyncdeprecateddeprecated

创建工作区。

Build a brand-new workspace and track it.

说明Notes

注意：该行为受运行时配置或底层实现影响，建议结合对应源码与版本说明确认。Deprecated: Use :meth:`get_workspace` with `workspace_id=None` — it falls back to :meth:`assign_workspace_id` under the manager's isolation policy and reuses the cache path.

已弃用。Deprecated. 已弃用，请改用受支持的替代 API。Use :meth:`get_workspace` with `workspace_id=None` — it falls back to :meth:`assign_workspace_id` under the manager's isolation policy and reuses the cache path.

参数Parameters

名称Name	类型Type	说明Description
`user_id`	str	用户标识（类型 `str`）。Owning user identifier.
`agent_id`	str	智能体标识（类型 `str`）。Agent identifier (controls the workdir).
`session_id`	str	会话标识（类型 `str`）。Session identifier (accepted for parity; not used here).

返回Returns DockerWorkspace

返回DockerWorkspace。`DockerWorkspace`:

源码Source agentscope/app/workspace_manager/_docker_workspace_manager.py:318–349

close

async def close(workspace_id: str) -> None

async

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

No-op when the workspace_id is not tracked.

参数Parameters

名称Name	类型Type	说明Description
`workspace_id`	str	工作区到关闭。The workspace to close.

返回Returns None

无返回值。No value is returned.

源码Source agentscope/app/workspace_manager/_docker_workspace_manager.py:351–365

close_all

async def close_all() -> None

async

关闭所有。

Docker kill + delete is slow per container; doing it sequentially on app shutdown produces a noticeable stall, so we fan the calls out with :func:asyncio.gather.

返回Returns None

无返回值。No value is returned.

源码Source agentscope/app/workspace_manager/_docker_workspace_manager.py:367–382

aenter

async def __aenter__() -> Self

async

进入异步上下文并返回自身。

Start the TTL sweeper task and fill the pre-warm buffer.

返回Returns Self

返回自身。Returns self.

源码Source agentscope/app/workspace_manager/_docker_workspace_manager.py:405–410

aexit

async def __aexit__(*exc: object) -> None

async

退出异步上下文并清理资源。

Stop the sweeper and buffer, then close every workspace.

参数Parameters

名称Name	类型Type	说明Description
`exc`	object	exc（类型 `object`）。The exc.

返回Returns None

无返回值。No value is returned.

源码Source agentscope/app/workspace_manager/_docker_workspace_manager.py:412–422

继承成员Inherited Members

继承自Inherited from WorkspaceManagerBase

bind_storage, assign_workspace_id