专为 Managed Agents 而生的 Harness 底座：AgentScope 2.0

Managed Agents 让 Agent 运行在云端环境中：一方面，推理、编排、Harness 管理等核心环节均由云端统一托管，架构稳定性与运行效果由平台保障；另一方面，长周期任务不再依赖本地设备持续在线——即使个人电脑关机，任务依然可以在云端持续运行。

• 把 AgentScope 2.0 中已经工程化的 Harness Agent 直接作为 Brain 运行时，托管内核提供稳定的推理与 Harness 能力，文件系统、workspace、工具执行则完全隔离在 Sandbox 沙箱环境。
• 平台层负责租户、权限、版本、事件和执行面选型。控制面（Agent、Environment、Memory、Vault、Deployment）和数据面（Session、Events、SSE）把这些能力组织成可多租、可审计、可运维的托管产品。

市面上包括百炼、Claude Code、LangChain 等都有类似的 Managed Agents 产品发布。从本质上来讲，我不认为 Managed Agents 产品与以往的低代码 Agent 平台在产品形态上有本质区别，它们都是给你一个包含“Agent 定义 & 运行”能力的托管平台，只不过在产品表现形式上，Managed Agents 在 harness 时代更突出以下两点：

第 1 点真正改变的是平台的抽象层级。传统低代码平台往往让用户决定“什么时候总结记忆、超长上下文怎么截断、工具异常重试几次、子任务怎样回收”。这些选项看起来灵活，实际上把 Harness 的工程责任转嫁给了业务开发者：同一个 Agent 因为配置者经验不同，效果和稳定性可能完全不同。Managed Agents 则只暴露业务差异，例如角色提示、Skills、MCP、工具权限和 Environment；至于压缩时机、会话恢复、工具结果淘汰、长期记忆刷新等，交给持续演进的 Harness。平台升级 Harness 后，所有 Agent 都能获得同一套工程改进，而不必逐个修改流程图。

第 2 点改变的是信任边界。模型决定“要调用什么”，不等于模型所在的进程必须“亲自执行什么”。只要工具调用被表示为稳定的 schema、tool_use_id 和结果事件，Hands 就可以被迁移到平台云沙箱或客户 VPC，而不改变 Brain 中的推理循环。这让安全团队能够分别回答三个问题：模型能看到哪些上下文？工具能访问哪些网络和文件？工具结果中哪些内容可以回传给 Brain？这三个问题被拆开以后，权限审核和故障定位都比“一整个 Agent 容器”清晰得多。

以 Claude Managed Agents 为例，它被开发者接受的一个重要背景，是 Claude Code 已经证明了成熟 Coding Agent Harness 的产品价值。用户看到的是模型推理和任务结果，平台真正托管的却是可恢复的会话状态、工程化运行策略和可替换的 Hands。AgentScope 2.0 采用了相似的分层思路：HarnessAgent 处理长任务、上下文溢出、状态恢复和任务委派，Managed Agents 再向外补上多租户资源、Environment 与稳定的数据面契约。

有了 Managed Agents 后，Anthropic 在个人、企业用户之间几个不同层次都有对应的解决方案，层层递进：

• Claude Code CLI 面向个人或单机开发工作流，Agent 与本地工作区、终端和会话记录直接结合。
• Claude Agent SDK 把 Session、事件流和工具交互 API 化，适合嵌入企业应用；身份、租户和资源隔离仍由接入方负责。
• Managed Agents 进一步把 Agent、Environment、Session 与执行面变成托管资源，由平台处理版本、权限和运行时治理。

这三层的区别不只是“封装越来越厚”，而是状态归属逐步上移：

AgentScope 2.0 的模型抽象、工具与 MCP、消息与事件、状态存储、远程文件系统 / 分布式 BaseStore，以及可插拔沙箱，都为进程外持久化和多副本部署预留了扩展点。这使 Managed Agents 无需从零实现会话恢复、工具结果落盘与跨请求上下文延续，数据面副本必须共享 AgentStateStore、Workspace 后端，并正确处理 turn 租约与节点切换。

其中，Workspace 是 Agent 使用的逻辑目录，Filesystem 和 Sandbox 是承载它的物理后端。两者通过 AbstractFileSystem 解耦：同一套文件工具既可以指向本机目录，也可以指向分布式 BaseStore 或 E2B 沙箱。正因为逻辑工作区与物理执行面分离，Agent 定义才能在不改业务提示词的情况下切换隔离策略。

具体来说，HarnessAgent 在 ReActAgent 之上通过 Hook 装配长期运行所需的工程默认项，例如：

• 工作区驱动的人格与知识：AGENTS.md / MEMORY.md / KNOWLEDGE.md 等注入系统提示。
• 会话持久化：按 sesionId 恢复 Agent 状态，进程重启后仍能续聊。
• 压缩与溢出处理：Harness 默认启用 compaction 与 tool-result eviction，并允许业务覆盖阈值或显式关闭。
• Skills / Subagents：工作区 skills、任务委派（task 等）开箱可用。
• 统一文件系统抽象：本地、远程 KV、云沙箱（E2B 等）走同一套工具语义，便于 Managed Agents 用 Environment 类型切换执行面而不改 Agent 业务定义。

这些能力不是互相独立的名词。一次长任务可能先从 AgentStateStore 恢复消息与 agent state，再由工作区 Hook 注入 AGENTS.md 和已安装 Skills；推理过程中如果上下文逼近窗口上限，压缩 Hook 会收敛历史，而较大的工具结果可以被淘汰到文件系统中，仅把可检索引用留在上下文里；需要并行研究时，主 Agent 又可以把任务交给 Subagent。最终，无论文件系统落在本地、远程 KV 还是 E2B，模型看到的工具语义保持一致。这种组合后的稳定性才是 Harness 作为平台内核的意义。

另外，HarnessAgent 与 Session 不是同一个生命周期。前者是在具备共享 AgentStateStore 与可恢复 Workspace 后端的数据面节点上重建的运行对象，后者是有稳定 ID、事件序列和持久状态的产品资源。分清这两者，才能做真正的水平扩展：节点挂掉时可以丢弃 Java 对象，但对话与长期记忆必须从共享状态恢复；工作区是否连续则取决于 BaseStore、沙箱快照或客户侧持久化，Local 目录并不具备这一保证。

从单个企业智能体应用走向 Managed Agents，关键不是改写推理内核，而是把运行能力提升为稳定的平台资源。这里所说的“增加一层平台 API”绝不只是增加几个 Controller；真正产品化还要补齐租户 ACL、Agent 版本快照、Session 状态机、append-only 事件、turn 租约、HITL ticket、Environment key、Worker 队列、共享协调存储和归档审计。Harness 让平台不必重写 AgentLoop，但这些分布式职责仍是独立的工程系统。

由此 Managed Agents 的完整形态就是：SaaS 控制面负责资源治理，AgentScope 2.0 提供运行内核，FC Sandbox / E2B 或客户 Worker 承接不同信任边界下的 Hands。

核心组件图

核心数据流转

客户端通过（session/event）接口发送任务请求到 Managed Data Plane（Brain），Brain 从共享状态恢复 Agent，进而执行整个推理、编排流程，如果中间有工具调用，Brain 再按 Environment 配置将工具调用请求路由到 Worker（可能是托管 Sandbox 环境、用户自管理 Sandbox 环境等）。

结合上面的架构分析与实现，可以把整套系统读成四层：

下面先完成最小初始化：登录 Managed Agents，创建一个可复用的 Workspace Copilot Agent，再演示 Local、Cloud Sandbox 和 Self-hosted 三种 Wroker 运行模式，可以直观的看到“Agent 定义不变，Hands 位置改变”。

下文假设 Managed Agents 已启动在 http://localhost:8080，并已配置模型密钥（如 DASHSCOPE_API_KEY）。

0. 登录

export BASE=http://localhost:8080
TOKEN=$(curl -fsS -X POST "$BASE/api/auth/login" 
  -H 'Content-Type: application/json' 
  -d '{"username":"admin","password":"admin"}' | jq -er .token)

1. 定义示例 Agent

我们创建一个「copilot 工作区助手」Agent：包含简短的系统提示词，配套 read_files、list_fukes、write_files 等工具，便于演示不同工具在不同 worker 模式下的运行情况。

AGENT=$(curl -fsS -X POST "$BASE/api/agents" 
  -H "Authorization: Bearer $TOKEN" 
  -H 'Content-Type: application/json' 
  -d '{
    "name": "Workspace Copilot",
    "description": "blog demo agent",
    "system": "You are a workspace copilot. Prefer tools when listing or reading files. Keep answers concise.",
    "tools": [{
      "type": "agent_toolset",
      "defaultConfig": {
        "enabled": true,
        "permissionPolicy": { "type": "always_allow" }
      },
      "configs": [
        { "name": "read_file", "enabled": true },
        { "name": "list_files", "enabled": true },
        { "name": "write_file", "enabled": true }
      ]
    }]
  }')
AGENT_ID=$(echo "$AGENT" | jq -er .id)
echo "AGENT_ID=$AGENT_ID"

接下来是三种 worker 模式的展示，同一个 Agent，同一套 Brain 推理编排执行环境，在三条 Hands 路径上的运行方式：

已有 Session 不支持中途切换 worker 执行环境；要更换信任边界，应创建新 Session，以免同一条事件历史跨越不同执行语义。

Worker in Local 模式

Local 模式最适合开发联调。Session、Harness 推理、模型请求和工具执行都由 Managed 集群发起，文件与 shell 直接落在 Brain 进程可见的本地环境中。

在 Local 模式下，Environment type=local：文件系统与（若启用的）shell 都在托管集群宿主机命名空间内完成，没有独立 Hands 队列，也不调用云沙箱。适合开发联调与可信内网。

Worker in Cloud Sandbox 模式

Cloud Sandbox 保留托管 Brain，但把文件和 shell 移入独立沙箱。Harness 推理、模型请求以及工具调用的发起方仍在 Managed 集群；真正的命令执行和文件读写发生在 FC Sandbox / E2B 兼容环境中。

Agent 通过 E2B 客户端协议申请容器，并在容器内执行 shell / FS 操作，Brain 主动发起调用，Worker 不参与。若使用兼容 E2B 协议的 Aliyun FC Sandbox，需要先准备服务地址、模板和 API Key。

Cloud Sandbox 的托管边界可以拆成三个动作：创建沙箱、在沙箱里执行、在 Session 结束或超时后回收/持久化。Managed Agents 通过 E2bFilesystemSpec 把文件和 shell 工具映射到同一沙箱上下文；isolationScope=SESSION 时，不同 Session 默认不会共享工作目录。若选择快照或 TAR 等持久化模式，恢复策略还需要与 AgentStateStore 一起考虑：恢复了模型上下文却没有恢复文件，或反过来，都会造成“Agent 记得做过、工作区却不存在”的不一致。生产系统必须把两者当作一个恢复单元设计。

Worker in Self-hosted 模式

Self-hosted 把 Hands 进一步移动到客户环境。Brain 仍在 Managed 集群中完成 Harness 推理，但工具任务进入队列，由客户侧 Worker 主动出站轮询、管理本地工作目录或沙箱，并把结果回传给 Brain。整个过程中，Brain 不需要进入客户网络。

在 Self-hosted 下，Brain 关闭本地 shell/FS 实执行，把相关工具注册为外化 schema；模型一旦 tool_use，事件落库并进入挂起/排队，由用户侧 Worker 持 Environment Key 出站 poll → 管理本地工作目录并执行，或接入客户自有沙箱 → 回传 user.tool_result 续跑。这与 Cloud Sandbox「Brain 主动打沙箱 API」正好相反：执行发起权在用户侧；是否使用以及如何管理沙箱，也由客户侧实现决定。

Self-hosted 的目标场景是让数据库、代码仓库和发布系统等企业资源留在客户边界内，但当前参考 Worker 开箱支持的范围是内置 shell / FS 工具。数据库、自定义业务工具与内网 MCP 仍需要后续 Worker 扩展 SPI，或由使用方自行在 Worker 外封装。对于已经接入 Worker 协议的工具，Brain 能看到 schema、调用参数和最终回传结果，但不必直接连入客户 VPC；Worker 只需主动向平台发起 HTTPS 请求，并可在回传前做结果脱敏、大小限制和审计。

定义多个 Agent

下面用 AgentDev 场景展示一个三角色团队，输入是一项 Java 库发布规划任务：

• Repo Surgeon 从代码质量视角给出检查项，只拥有工作区读取与检索能。
• Ops Publisher 从发布流程视角生成工单草案，在本次演示中只生成文本草案，外部 MCP 接入作为可选配置单独说明。
• Team Lead 汇总风险与验收清单，Team Lead 尽量不直接接触业务数据，只负责委派和汇总。

拆成三个 Agent 不是为了堆叠角色，而是为了分别约束工作区权限、外部系统接入和汇总职责，这样做的收益是最小权限与独立审计，而不是把所有工具塞进一个超级 Agent 后只靠提示词约束。

先创建可直接参与 fan-out 的 Ops Publisher。它只生成发布草案，不调用外部系统，因此不会让 /api/multiagent/run 卡在人工确认阶段：

OPS_BODY=$(jq -n '{
  name: "Ops Publisher",
  system: "Draft changelogs and ticket outlines. Do not invoke tools or modify external systems.",
  tools: [{
    type: "agent_toolset",
    defaultConfig: {
      enabled: false,
      permissionPolicy: {type: "deny"}
    },
    configs: [{
      name: "read_file",
      enabled: true,
      permissionPolicy: {type: "always_allow"}
    }]
  }]
}')
# 发布规划 Agent：本次只生成文本草案
OPS=$(curl -fsS -X POST "$BASE/api/agents" 
  -H "Authorization: Bearer $TOKEN" 
  -H 'Content-Type: application/json' 
  -d "$OPS_BODY")
OPS_ID=$(echo "$OPS" | jq -er .id)

如果要在生产中接入工单 MCP，可在 Agent body 中增加如下片段；enableTools 只暴露明确允许的工具，URL 与工具名必须替换为真实值：

{
  "mcpServers": [{
    "name": "ticket-mcp",
    "url": "https://mcp.example.com/tickets",
    "transport": "http",
    "enableTools": ["draft_ticket"]
  }]
}

如需发布 Skill，也可以在确认 Workspace 已安装对应内容后增加 “skills”: [{“type”: “workspace”, “name”: “release-notes”}]。当前 mcp_toolset.defaultConfig.permissionPolicy 不会进入 ToolConfirmationMiddleware，因此高风险 MCP 写操作还需要在 MCP 网关侧做身份、审批与幂等控制，不能只依赖 Agent body 中的 always_ask。随后创建只读访问代码工作区的 Repo Surgeon：

# 操作用户侧资源 —— 例如「代码/仓库」类 Agent：偏 filesystem tools + skills
REPO=$(curl -fsS -X POST "$BASE/api/agents" 
  -H "Authorization: Bearer $TOKEN" 
  -H 'Content-Type: application/json' 
  -d '{
    "name": "Repo Surgeon",
    "system": "You review the user workspace in read-only mode and report release risks.",
    "tools": [{
      "type": "agent_toolset",
      "defaultConfig": { "enabled": true, "permissionPolicy": { "type": "always_allow" } },
      "configs": [
        { "name": "read_file", "enabled": true },
        { "name": "grep_files", "enabled": true },
        { "name": "list_files", "enabled": true }
      ]
    }]
  }')
REPO_ID=$(echo "$REPO" | jq -er .id)

如果已安装代码审查 Skill，可再加入 “skills”: [{“type”: “workspace”, “name”: “code-review”}]。最后创建 Team Lead。它保留委派与结果收集工具，并通过真实 MultiagentSpec 记录前两个成员；当前运行入口不会仅凭这个字段自动启动成员，实际执行仍由下面的 Harness 委派或平台 fan-out 发起。

LEAD_BODY=$(jq -n --arg repo "$REPO_ID" --arg ops "$OPS_ID" '{
  name: "Team Lead",
  system: "You coordinate Repo Surgeon and Ops Publisher. For a direct task, delegate concrete work and collect results. When the prompt already contains member results, do not call tools or spawn sessions; only summarize risks and produce the final checklist. Use sessions_pending_completions for finished child sessions and wait_async_results only for the generic async inbox.",
  tools: [{
    type: "agent_toolset",
    defaultConfig: {
      enabled: true,
      permissionPolicy: {type: "always_allow"}
    },
    configs: [
      {name: "sessions_spawn", enabled: true},
      {name: "sessions_list", enabled: true},
      {name: "sessions_pending_completions", enabled: true},
      {name: "wait_async_results", enabled: true}
    ]
  }],
  multiagent: {
    type: "agent_team",
    agents: [
      {type: "agent", id: $repo},
      {type: "agent", id: $ops}
    ]
  }
}')
LEAD=$(curl -fsS -X POST "$BASE/api/agents" 
  -H "Authorization: Bearer $TOKEN" 
  -H 'Content-Type: application/json' 
  -d "$LEAD_BODY")
LEAD_ID=$(echo "$LEAD" | jq -er .id)
printf 'OPS_ID=%snREPO_ID=%snLEAD_ID=%sn' "$OPS_ID" "$REPO_ID" "$LEAD_ID"

MultiagentSpec 的 wire schema 是 type + agents[]，成员引用包含 type、id 和可选 version。wait_async_results 用于阻塞等待通用异步 inbox；sessions_pending_completions 用于枚举已经完成但尚未消费的子 Session 结果。两者服务于不同的异步模式，因此 Team Lead 同时启用它们，但应由 system prompt 明确什么时候使用哪一种。

编排在一起

系统提供两种不同的多 Agent 运行方式：

• Harness 原生委派：Team Lead 在推理过程中使用 sessions_spawn / Subagent 工具动态拆解任务，父子任务之间存在明确的委派与结果回收关系。
• 平台 fan-out：/api/multiagent/run 为多个 Agent 分别创建 Managed Session，并把同一消息顺序或并行发送给它们，适合独立分析、批处理和投票。

前文从使用者视角介绍了 Brain、Hands 协调工作过程，并通过一个 Agent Team 示例演示了多 Agent 编排场景。下面进一步拆开控制面、数据面与 Worker，说明每一层保存什么状态、承担什么故障责任，以及 AgentScope 2.0 在其中扮演什么角色。

一句话：控制面管「定义与权限」，数据面管「跑起来并记下来」，Worker 管「在谁的机器上动手」；AgentScope 2.0 的 HarnessAgent + 文件系统/沙箱抽象是数据面与 Hands 的内核，SaaS API 做好平台层语义建设，不重新实现推理循环。

控制面

控制面负责“定义什么可以运行，以及谁可以使用它”。它管理 Agent 静态定义及其版本，也管理 Model、Skills、MCP、Tools、Environment、Memory、Vault 和 Resources 等可复用资源。资源既可以属于单个用户并按 owner / ACL 隔离，也可以由平台全局预置，例如公共 Skill、MCP 目录和内置工具集。

这些资源可以按“定义、引用、挂载”三种关系理解。Model、Tools、MCP、Skills 进入 Agent 版本定义；Environment 独立存在，由 Session 引用；Memory Store、Vault、Files/Resources 则在 Session 创建时挂载。全局预置资源提供平台默认能力，用户资源带 owner / share ACL。这样既避免每个 Agent 重复复制公共 Skill，也不会因为共享目录而让不同租户相互看见数据。

控制面还承担变更治理。Agent 更新生成新版本，旧 Session 可以继续记录并恢复当前已支持的历史字段；Environment key 可以 rotate；资源可以 archive 而不是立即物理删除；高风险内置工具权限随版本记录。对生产平台而言，这些能力往往比“能否调用一个新模型”更关键，因为它们决定回滚、灰度和事故追责是否可行。

Environment 与 Session 容易混淆，但两者属于不同层次。本文采用如下边界：

• Environment 归属控制面：它是「执行面模板」（local / sandbox / remote / self_hosted + config + environment key），可被多个 Session 引用，带归档与分享，本身不产生对话事件。
• Session 归属数据面：它是 Agent × Environment 的一次运行实例，带状态机与事件日志；创建参数会引用控制面的 agentId / environmentId，但生命周期 API（events / stream / interrupt）是数据面核心。

因此：

• 发起 session → 数据面（下一节展开）。
• 定义 Environment → 控制面（POST /api/environments，rotate key，archive）。

数据面

数据面负责“让一个记录了 Agent 版本的 Session 真正运行起来，并完整记录过程”。它承载模型调用、ReAct loop、Harness hooks、turn 租约、Session 状态机、事件持久化与 SSE 推送，也处理 interrupt、HITL 和外化工具结果续跑。

这些操作不是普通 CRUD 的补充，而是围绕状态机展开：创建 Session 记录 Agent 版本和 Environment 引用，user.message 把状态从 idle 推向 running，工具确认把 requires_action 恢复为 running，interrupt 尝试取消当前 turn，archive 终止后续使用但保留审计历史，delete 才清理会话及事件。客户端应该根据事件驱动 UI，而不是轮询某个内部线程是否仍然存活。

数据面由对等 SaaS 副本组成，请求可以到达任意实例。副本先通过 agentId 找到控制面的版本定义，再根据 Agent 版本、Environment 与挂载信息计算构建键：命中缓存就复用 HarnessAgent，未命中才重新构建。每个 turn 都通过包含 userId、sessionId 的 RuntimeContext 定位会话状态，因此这里的“无状态副本”是指不持有不可替代的权威状态，而不是每个请求都重新创建 Java 对象。

RuntimeContext 可以理解为一次运行的“身份与资源定位器”，而不是把所有状态塞进一个 Map。userId 决定多租命名空间与 ACL，sessionId 定位可恢复的短期 brain state；Environment 决定文件系统/沙箱实现；Memory Store 与 Vault 则在构建阶段解析成文件系统路由和凭证。Harness 只依赖这些稳定抽象，因此同一个请求打到另一台副本时，可以重新装配出语义等价的运行环境。

数据面实际托管了四类生命周期不同的状态：

这四层不能用一个“保存对话历史”概括。比如 Session 事件能证明模型曾请求写文件，但不能代替文件本身；AgentStateStore 能恢复上下文，却不自动恢复外部数据库的副作用。恢复流程必须分别恢复每一层，再用事件 ID、tool call ID 和资源引用把它们重新关联起来。

当 Harness 推理需要调用工具时，具体怎么执行由 Environment 决定。Cloud Sandbox 直接复用 Harness 的 filesystem / sandbox 抽象，由 Brain 发起 E2B 兼容调用；Self-hosted 则把工具替换为 schema-only 定义，在 agent.tool_use 后挂起 turn，经 work queue 和 Worker 协议回传结果。

AgentScope 2.0 在这里的角色非常明确：提供 HarnessAgent 与 FS/Sandbox 抽象，保证「效果默认项」和「执行面可替换」；Managed Agents 负责租约、事件契约、多租与 ACL，而不是再包一层私有化的 ReAct。

Worker

Worker 关注工具如何从 Brain 到达真正的执行环境，系统有两条路径，区别在于谁发起工具调用、谁管理沙箱生命周期。

在全托管模式下，Brain 负责创建和回收 Sandbox，也主动通过 AgentScope 提供的 E2B 兼容 API 发起文件或 shell 调用。后台可以由 FC Sandbox 等兼容服务承接，工具进程与工作目录都位于沙箱实例中。平台掌握完整句柄，因此可以统一设置超时、隔离范围和持久化策略。

在 Self-hosted 模式下，Brain 收到模型的 tool call 后，不会连接客户 VPC，而是持久化 agent.tool_use 并创建 work item。客户侧 Worker 主动 poll 队列，在自己的主机或沙箱中执行工具，再通过 user.tool_result 回传结果，使 Brain 恢复下一轮推理。

两者在故障恢复上的责任也不同。全托管模式下，Brain 知道沙箱句柄并可以统一设置超时、快照和回收策略；Self-hosted 下，Brain 只知道 work 状态和工具结果，客户 Worker 必须负责本地沙箱是否仍存活、重复任务是否安全、结果是否需要脱敏。平台提供协议和状态机，但不能替客户定义业务工具的幂等语义。

Work 状态机为 queued → starting → active → stopping → stopped。

部署独立 Worker 时，需要同时配置 Brain 和客户侧进程。下面给出最小启动方式与生产检查项。

AgentScope 2.0 定位面向企业级分布式场景，它既可以做分布式 Agent Framework，用来开发企业内的 DataAgent、SreAgent 等，又可以用同一套 Harness 撑起企业内的 Managed Agents，成为 Managed Agents 底层的 Agent Runtime。可以让企业不必在「自己拼积木」和「完全黑盒托管」之间二选一，同一套 Harness 内核两种模式都能实现。