类class agentscope.app.workspace_manager

OpenSandboxWorkspaceManager

class OpenSandboxWorkspaceManager(WorkspaceManagerBase)

源码Source agentscope/app/workspace_manager/_opensandbox_workspace_manager.py:49–356

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

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__(*, isolation:` `IsolationPolicy = IsolationPolicy.PER_AGENT, image: str = DEFAULT_IMAGE, api_key: str = '',…`	初始化 `OpenSandboxWorkspaceManager` 实例。 Initialize the OpenSandbox workspace manager.

方法摘要Method Summary

方法Method	说明Description
`async def get_workspace(user_id: str, agent_id: str, session_id: str, workspace_id: str \| None = None) -> OpenSandboxWo…`async	获取工作区。 Return an initialized workspace, reattaching on cache miss.
`async def close(workspace_id: str) -> None`async	关闭连接并释放相关资源。 Close (= pause the sandbox) and evict a single workspace.
`async def close_all() -> None`async	关闭所有。 Close every cached workspace in parallel.
`async def __aenter__() -> Self`async	进入异步上下文并返回自身。 Start the TTL sweeper task.
`async def __aexit__(*exc: object) -> None`async	退出异步上下文并清理资源。 Stop the TTL sweeper task, then close all cached workspaces.

构造器详情Constructor Detail

OpenSandboxWorkspaceManager

def __init__(*, isolation: IsolationPolicy = IsolationPolicy.PER_AGENT, image: str = DEFAULT_IMAGE, api_key: str = '', domain: str = '', protocol: Literal['http', 'https'] = 'http', request_timeout_seconds: float | None = DEFAULT_REQUEST_TIMEOUT, timeout_seconds: int = DEFAULT_TIMEOUT, gateway_port: int = DEFAULT_GATEWAY_PORT, env: dict[str, str] | None = None, sandbox_metadata: dict[str, str] | None = None, resource: dict[str, str] | None = None, entrypoint: list[str] | None = None, network_policy: Any | None = None, extra_pip: list[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) -> None

初始化 OpenSandboxWorkspaceManager 实例。

Initialize the OpenSandbox workspace manager.

参数Parameters

名称Name	类型Type	说明Description
`isolation`kw默认default `IsolationPolicy.PER_AGENT`	IsolationPolicy	隔离（类型 `IsolationPolicy`）。Isolation grain for :meth:`assign_workspace_id`, used when :meth:`get_workspace` is called without an explicit `workspace_id`.
`image`kw默认default `DEFAULT_IMAGE`	str	图像（类型 `str`）。OpenSandbox image passed to every workspace this manager produces.
`api_key`kw默认default `''`	str	API 密钥（类型 `str`）。OpenSandbox API key. `""` lets the SDK fall back to its environment-based configuration.
`domain`kw默认default `''`	str	domain（类型 `str`）。Optional OpenSandbox domain, for local or self-hosted deployments.
`protocol`kw默认default `'http'`	Literal['http', 'https']	协议（类型 `Literal['http', 'https']`）。Scheme used when OpenSandbox returns endpoint values as `host:port` without a protocol.
`request_timeout_seconds`kw默认default `DEFAULT_REQUEST_TIMEOUT`	float \| None	请求超时秒（类型 `float \| None`）。HTTP request timeout forwarded through `ConnectionConfig`. Defaults to 600 seconds so the SDK HTTP streaming layer is not shorter than bootstrap command timeout.
`timeout_seconds`kw默认default `DEFAULT_TIMEOUT`	int	超时秒数（类型 `int`）。Sandbox keep-alive / resume timeout.
`gateway_port`kw默认default `DEFAULT_GATEWAY_PORT`	int	网关 port（类型 `int`）。TCP port the in-sandbox gateway listens on.
`env`kw默认default `None`	dict[str, str] \| None	env（类型 `dict[str, str] \| None`）。Environment variables applied when creating a sandbox.
`sandbox_metadata`kw默认default `None`	dict[str, str] \| None	沙箱元数据（类型 `dict[str, str] \| None`）。Extra metadata merged with the per-workspace `agentscope.workspace.id` / `agentscope.user.id` / `agentscope.agent.id` keys.
`resource`kw默认default `None`	dict[str, str] \| None	资源（类型 `dict[str, str] \| None`）。Resource limits forwarded to OpenSandbox create.
`entrypoint`kw默认default `None`	list[str] \| None	entrypoint（类型 `list[str] \| None`）。Optional sandbox entrypoint forwarded to OpenSandbox create.
`network_policy`kw默认default `None`	Any \| None	network 策略（类型 `Any \| None`）。Creation-time OpenSandbox network policy. Runtime egress patching is intentionally left for a follow-up.
`extra_pip`kw默认default `None`	list[str] \| None	extra pip（类型 `list[str] \| None`）。Extra Python packages installed into the gateway venv during bootstrap.
`default_mcps`kw默认default `None`	list[MCPClient] \| None	默认 mcps（类型 `list[MCPClient] \| None`）。MCP clients seeded into brand-new workspaces. On reattach, the sandbox's persisted `.mcp` file wins.
`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 sandbox paused.
`sweep_interval`kw默认default `DEFAULT_SWEEP_INTERVAL`	float	sweep 间隔（类型 `float`）。How often the background sweeper wakes up to look for idle workspaces.

源码Source agentscope/app/workspace_manager/_opensandbox_workspace_manager.py:57–158

方法详情Method Detail

get_workspace

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

async

获取工作区。

On miss, the manager constructs OpenSandboxWorkspace with the requested workspace_id and relies on its initialize method to find an existing sandbox by metadata, connect or resume it depending on state, or create a fresh sandbox otherwise.

参数Parameters

名称Name	类型Type	说明Description
`user_id`	str	用户标识（类型 `str`）。Owning user identifier (forwarded as sandbox metadata only — not part of the cache key).
`agent_id`	str	智能体标识（类型 `str`）。Agent identifier (forwarded as sandbox metadata only — not part of the cache key).
`session_id`	str	会话标识（类型 `str`）。Session identifier (unused; sandboxes are per-workspace, sessions partition under `sessions/ /`).
`workspace_id`默认default `None`	str \| None	工作区标识（类型 `str \| None`）。Stable workspace identifier — the cache key and the value stored in the sandbox's `agentscope.workspace.id` metadata. When unset the manager falls back to :meth:`assign_workspace_id` under its isolation policy.

返回Returns OpenSandboxWorkspace

返回OpenSandboxWorkspace。`OpenSandboxWorkspace`:

源码Source agentscope/app/workspace_manager/_opensandbox_workspace_manager.py:199–269

close

async def close(workspace_id: str) -> None

async

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

Close (= pause the sandbox) and evict a single workspace.

参数Parameters

名称Name	类型Type	说明Description
`workspace_id`	str	工作区标识（类型 `str`）。The workspace id.

返回Returns None

无返回值。No value is returned.

源码Source agentscope/app/workspace_manager/_opensandbox_workspace_manager.py:271–278

close_all

async def close_all() -> None

async

关闭所有。

sandbox.pause() is a remote round-trip per sandbox; doing it sequentially on shutdown would produce unnecessary latency.

返回Returns None

无返回值。No value is returned.

源码Source agentscope/app/workspace_manager/_opensandbox_workspace_manager.py:280–294

aenter

async def __aenter__() -> Self

async

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

Start the TTL sweeper task.

返回Returns Self

返回自身。Returns self.

源码Source agentscope/app/workspace_manager/_opensandbox_workspace_manager.py:296–300

aexit

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

async

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

Stop the TTL sweeper task, then close all cached workspaces.

参数Parameters

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

返回Returns None

无返回值。No value is returned.

源码Source agentscope/app/workspace_manager/_opensandbox_workspace_manager.py:302–311

继承成员Inherited Members

继承自Inherited from WorkspaceManagerBase

bind_storage, assign_workspace_id