工作区

概述

Workspace 是 agent 的执行环境，向 agent 提供三类资源 —— 工具（内置 tool 与 MCP）、skill，以及面向压缩消息与超大工具结果的上下文 offload —— 同时管理其中资源（MCP server 进程、动态加入的 skill、offload 文件）的生命周期。 AgentScope 提供三种 workspace 实现 —— 本地文件系统、Docker 容器、E2B 云沙箱 —— 以及一个 workspace manager，在 Agent Service 中负责分配和追踪 workspace，让多租户部署可以把 workspace 按 user、agent 或 session 维度映射，无需改写 agent 代码。对 Docker 与 E2B 而言，MCP server 跑在隔离环境内部；宿主侧通过 workspace 内的 gateway 访问它们，详见后文 MCP Gateway。

使用 Workspace

创建 Workspace

AgentScope 针对三种执行后端提供了对应的 workspace 实现：

类	后端
`LocalWorkspace`	宿主文件系统（内置 tool 直接在宿主侧运行）
`DockerWorkspace`	基于 `aiodocker` 的 Docker 容器
`E2BWorkspace`	基于 `AsyncSandbox` 的 E2B 云沙箱

每种后端的持久化方式与目录结构各不相同 —— 选择对应的 tab 查看：

LocalWorkspace
DockerWorkspace
E2BWorkspace

LocalWorkspace 直接把状态持久化在宿主文件系统的 workdir 下，重启时只需重新打开同一目录。目录结构如下：

{workdir}/
├── .mcp           # 注册的 MCP client 配置（JSON 数组）
├── data/          # offload 的多模态负载（按 SHA-256 去重）
├── skills/        # skill 子目录，每个含 SKILL.md
│   └── .skills    # 名称/哈希索引，用于去重
└── sessions/      # 每个 session 的 context.jsonl 与工具结果文件

from agentscope.workspace import LocalWorkspace

workspace = LocalWorkspace(
    workdir="/data/my-workspace",
    default_mcps=[],
    skill_paths=["./skills/web-search"],
)
await workspace.initialize()

DockerWorkspace 把宿主 workdir 挂载到容器内的 /workspace，因此下方目录结构存放在宿主侧，跨容器重启依旧保留。若不传 workdir，整套数据只活在容器的可写层中，容器销毁即消失。

{workdir}/         # 宿主目录，挂载到容器内 /workspace
├── .mcp           # 注册的 MCP client 配置（JSON 数组）
├── data/          # offload 的多模态负载
├── skills/        # skill 子目录，每个含 SKILL.md
└── sessions/      # 每个 session 的 context.jsonl 与工具结果文件

from agentscope.workspace import DockerWorkspace

workspace = DockerWorkspace(
    base_image="python:3.11-slim",
    workdir="/data/docker-workspaces/agent-1",  # 挂载到容器内 /workspace
    node_version="20",
    extra_pip=["numpy", "pandas"],
    default_mcps=[],
    skill_paths=["./skills/web-search"],
)
await workspace.initialize()

E2BWorkspace 把沙箱文件系统本身作为持久化层，没有宿主 workdir。每个沙箱在 E2B metadata 中带有 workspace_id，重启时 manager 通过 AsyncSandbox.list(...) 找回它，并以 connect(sandbox_id=...) 重连；pause 时磁盘状态保留，resume 时原样恢复。

$workdir/          # 位于沙箱内部
├── .mcp           # 注册的 MCP client 配置（JSON 数组）
├── data/          # offload 的多模态负载
├── skills/        # skill 子目录，每个含 SKILL.md
└── sessions/      # 每个 session 的 context.jsonl 与工具结果文件

from agentscope.workspace import E2BWorkspace

workspace = E2BWorkspace(
    template="base",
    api_key="your-e2b-api-key",   # 或设置环境变量 E2B_API_KEY
    timeout_seconds=300,
    default_mcps=[],
    skill_paths=["./skills/web-search"],
)
await workspace.initialize()

default_mcps 与 skill_paths 是 seed-time 输入 —— 仅在全新 workspace 首次 initialize() 时生效。重启时 workspace 从持久化的 .mcp 文件中恢复 MCP 列表，重复传入这些 seed 不会产生影响。三种实现共享同一份 WorkspaceBase 接口，因此同一份 agent 代码可以在任意后端上无差别运行。接口按使用角色分为四组：

生命周期 (developer)

分配 / 释放 workspace，在归还到池前清空 per-session 状态；同时驱动 async with 协议。

资源发现 (agent)

列出内置 tool、活跃的 MCPClient、可用 skill，以及一段 workspace 专属的 system prompt 片段。

Offload (agent)

将压缩后的上下文或超大工具结果持久化到 sessions/<session_id>/，返回引用路径供 agent 替换原始负载。

动态管理 (user)

运行时注册或移除 MCP server 与 skill，变更会写入 .mcp 与 skills/，跨重启保留。

与 Agent 集成

Workspace 从两个角度接入 Agent —— 作为 tool / MCP / skill 的来源，以及作为上下文压缩的 offloader：

from agentscope.agent import Agent
from agentscope.tool import Toolkit
from agentscope.workspace import LocalWorkspace

workspace = LocalWorkspace(workdir="./my-workspace")
await workspace.initialize()

agent = Agent(
    name="coder",
    system_prompt="You are a coding assistant.",
    model=model,
    toolkit=Toolkit(
        tools=await workspace.list_tools(),
        mcps=await workspace.list_mcps(),
        skills_or_loaders=await workspace.list_skills(),
    ),
    offloader=workspace,
)

角度	装配	Agent 拿到什么
资源	`Toolkit(tools=..., mcps=..., skills_or_loaders=...)`	workspace 中可用的内置 tool、MCP 提供的 tool 与 skill
Offload	`Agent(offloader=workspace)`	上下文压缩触发或工具结果超过大小阈值时，agent 调用 `workspace.offload_context()` / `offload_tool_result()`，并用返回的引用路径替换原始负载

Agent 仅依赖 Offloader 协议（offload_context / offload_tool_result），任何满足该协议的对象都可以承担此角色 —— workspace 是典型实现。

Workspace 把资源以扁平列表的方式暴露出来，因此当 agent 工具数量过多、不便全部常驻激活时，可以按主题切分到不同的 ToolGroup，作为 Toolkit(tool_groups=[...]) 传入；agent 通过内置 meta-tool ResetTools 按需激活，只有保留名 basic 组始终在线。

from agentscope.tool import Toolkit, ToolGroup

mcps = await workspace.list_mcps()
skills = await workspace.list_skills()

toolkit = Toolkit(
    tools=await workspace.list_tools(),         # 始终激活（basic 组）
    tool_groups=[
        ToolGroup(name="search", description="Web 搜索与检索。",
                  mcps=[m for m in mcps if m.name.startswith("search")]),
        ToolGroup(name="coding", description="代码编辑相关 skill。",
                  skills_or_loaders=skills),
    ],
)

Workspace Manager

Workspace manager 是多租户服务中 workspace 的分配器与生命周期持有者，由 Agent Service 使用，负责把请求路由到正确的 workspace 实例并在关闭时回收。 Manager 的职责：

分配 —— create_workspace(user_id, agent_id, session_id) 构造新 workspace 并纳入追踪；get_workspace(..., workspace_id) 返回已存在的 workspace，缓存未命中时按需重建。
缓存与 TTL —— 以 workspace_id 为键在内存中缓存 workspace；空闲超过 ttl 秒后淘汰，并销毁底层资源（容器、沙箱、MCP 进程）。
隔离策略 —— manager 决定两次请求是否共享同一 workspace；内置 manager 都按 agent_id 隔离，而 WorkspaceManagerBase 是个极小的抽象类，可继承后改写为按 user 或按 session 隔离。
回收 —— close(workspace_id) 淘汰单个条目，close_all() 在应用关闭时清空缓存。

AgentScope 提供三种 manager，分别配合一种 workspace 后端，全部按 agent 隔离：

类	配套 workspace	隔离键	缓存键
`LocalWorkspaceManager`	`LocalWorkspace`	`agent_id`（workdir = `<basedir>/<agent_id>`）	`workspace_id`
`DockerWorkspaceManager`	`DockerWorkspace`	`(user_id, agent_id)`（workdir = `<basedir>/<user_id>/<agent_id>`）	`workspace_id`
`E2BWorkspaceManager`	`E2BWorkspace`	`agent_id`（沙箱 metadata，无宿主 workdir）	`workspace_id`

构造 manager 后即可像 workspace 分配器一样使用：

from agentscope.app._manager import LocalWorkspaceManager

manager = LocalWorkspaceManager(
    basedir="/data/workspaces",
    skill_paths=["./skills/coding"],
    ttl=3600.0,
)

ws = await manager.create_workspace(
    user_id="user-1",
    agent_id="agent-42",
    session_id="session-abc",
)

# 后续请求复用同一 workspace：
ws = await manager.get_workspace(
    user_id="user-1",
    agent_id="agent-42",
    session_id="session-abc",
    workspace_id=ws.workspace_id,
)

要换用其他隔离策略（按 user、按 session 或混合），继承 WorkspaceManagerBase 并按自己的键重写 get_workspace / create_workspace —— 关于 manager 如何接入服务请求生命周期，详见 Agent Service · Workspace 实现与隔离。

Agent Service 在 lifespan 期间把 workspace manager 绑定到 FastAPI 应用状态上，所有请求共享；router 通过 get_workspace_manager 依赖注入获取 workspace。完整集成方式见 Agent Service。

MCP Gateway

DockerWorkspace 与 E2BWorkspace 无法直接在宿主侧注册 MCP client —— MCP server 跑在容器或沙箱内部，stdio 会话也无法跨越该边界。AgentScope 用一套 MCP gateway 抽象解决此问题：在 workspace 内部运行一个轻量 FastAPI 进程，它持有上游 MCP 会话，并通过单一带鉴权的 HTTP 端点对宿主暴露这些会话。 Gateway 暴露一组小型 REST 接口 —— GET /health、GET/POST/DELETE /mcps、GET /mcps/{name}/tools、POST /mcps/{name}/tools/{tool} —— 通过每次 initialize() 重新生成的 per-workspace bearer token 鉴权。宿主侧两个适配器保持标准接口不变：

GatewayMCPClient —— MCPClient 子类，把 connect / close / list_tools 等调用替换为对 gateway 的 HTTP 请求，其它 toolkit 代码无法将它与本地 MCP client 区分开。
GatewayMCPTool —— ToolBase 子类，__call__ 直接 POST 到 /mcps/{name}/tools/{tool} 并重建返回的 ToolChunk。

正因这层抽象，agent 侧代码在三种 workspace 后端上完全一致 —— 无论上游 MCP 会话在宿主侧（LocalWorkspace）还是在隔离环境内（DockerWorkspace / E2BWorkspace），workspace 的 list_mcps() 都返回 MCPClient 实例。

Agent

Agent 抽象、ReAct 循环与 offloader 集成

Tool

内置 tool、MCP 集成与 toolkit 组装

Agent Service

驱动 workspace manager 的多租户服务

Context

上下文压缩与 offload 触发条件

快速开始

核心模块

部署

其他

概述

使用 Workspace

创建 Workspace

与 Agent 集成

Workspace Manager

MCP Gateway

延伸阅读

Agent

Tool

Agent Service

Context

​概述

​使用 Workspace

​创建 Workspace

​与 Agent 集成

​Workspace Manager

​MCP Gateway

​延伸阅读

Agent

Tool

Agent Service

Context

概述

使用 Workspace

创建 Workspace

与 Agent 集成

Workspace Manager

MCP Gateway

延伸阅读