Manage Resources

A workspace’s resources are not fixed at creation time. MCP servers and skills can be added or removed while the workspace is running, and every change is persisted so it survives restarts. The lifecycle methods round out the picture, taking a workspace from provisioned to released.

Manage MCP Servers

add_mcp registers a new MCP server and remove_mcp deregisters one by name. Changes are written to the .mcp file under the workspace directory, so a restarted workspace reconnects the same servers without re-seeding:

from agentscope.mcp import MCPClient, HttpMCPConfig

# Register a new MCP server; raises ValueError if the name already exists
await workspace.add_mcp(
    MCPClient(
        name="amap",
        is_stateful=False,
        mcp_config=HttpMCPConfig(url="https://mcp.amap.com/mcp?key=..."),
    ),
)

# Deregister by name; unknown names log a warning and return silently
await workspace.remove_mcp("amap")

# Enumerate the currently registered clients
mcps = await workspace.list_mcps()

Persistence follows the workspace’s own model: an ephemeral DockerWorkspace without a host workdir keeps the MCP list in memory only, and it is lost when the container goes away.

Manage Skills

add_skill copies a local skill directory (which must contain a SKILL.md) into the workspace’s skills/ directory, packaging it as a tar archive so the copy works the same against a local directory or a remote sandbox. remove_skill deletes a skill by its agent-facing name (the name field in the SKILL.md front matter):

# Copy a local skill directory into the workspace;
# raises ValueError if SKILL.md is missing or the directory already exists
await workspace.add_skill("./skills/web-search")

# Delete by the skill's front-matter name; raises KeyError if not found
await workspace.remove_skill("web-search")

# Enumerate the available skills (parsed from each SKILL.md)
skills = await workspace.list_skills()

Manage the Lifecycle

Three methods take a workspace through its life, and the async with protocol wraps initialize / close for scoped use:

Method	Effect
`initialize()`	Provision the backend (start the container / sandbox / Pod), connect MCP servers, and seed skills
`reset()`	Return the workspace to an empty state: close and remove all MCPs, delete all skills, and wipe per-session state
`close()`	Release all resources and connections

async with LocalWorkspace(workdir="./ws") as workspace:
    ...  # initialize() on entry, close() on exit

reset() empties the workspace; it does not restore the initial state. The constructor-time default_mcps and skill_paths seeds are not re-applied.

Allocate Workspaces in a Service

In a multi-tenant service, deciding which request gets which workspace (per user, per agent, or per session), caching live instances, and evicting idle ones is the job of the workspace manager, a separate service-side component. See its dedicated chapter:

Workspace Manager

Allocation, isolation policies, TTL eviction, and integration with the Agent Service.

Get Started

Building Blocks

Agent as Service

Others

Manage MCP Servers

Manage Skills

Manage the Lifecycle

Allocate Workspaces in a Service

Workspace Manager

​Manage MCP Servers

​Manage Skills

​Manage the Lifecycle

​Allocate Workspaces in a Service

Workspace Manager

Manage MCP Servers

Manage Skills

Manage the Lifecycle

Allocate Workspaces in a Service