AgentRun 后端

• 数据面优先：调用 https://{accountId}.agentrun-data.{region}.aliyuncs.com + X-API-Key + X-Acs-Parent-Id 鉴权，不引入完整 Aliyun OpenAPI SDK；
• sandboxId 由 sessionId 派生：使用 SHA-256 + Crockford Base32 输出 26 字符（ULID 形状）。利用 AgentRun 允许自定义 sandboxId 的特性，把「销毁后同 id 重建」等价于 resume；
• 执行通道走 MCP：复用 io.agentscope.core.tool.mcp.McpClientBuilder.streamableHttpTransport(...)，调用模板预先启用的 process_exec_cmd / read_file / write_file；
• 持久化默认 NAS-first：workspaceRoot 指向 NAS 挂载时，AbstractBaseSandbox 的 4-分支起始命中 Branch A，doPersist/Hydrate 退化为 no-op；无 NAS 时回退到 tar-via-MCP（与 Daytona/E2B TAR 同形）。

​

1. 何时选用 AgentRun

​

2. 前置准备（必读）

1. AgentRun 模板：在 AgentRun 控制台创建 Template，containerConfiguration 选择目标运行环境（默认基于 Ubuntu）。
2. 激活 MCP 工具：通过 ActivateTemplateMCP 在模板上启用 process_exec_cmd / read_file / write_file 三件套——adapter 仅使用这三个工具。
3. 凭据：准备主账号 ID（X-Acs-Parent-Id）和数据面 API Key（X-API-Key）；adapter 不签名 ACS3，直接走 API Key。
4. RAM 角色权限：模板执行角色需具备访问 NAS / OSS 的读写权限；具体策略参考阿里云文档「Sandbox 支持实例级别动态挂载 OSS」。
5. NAS 文件系统（推荐）：准备一个与沙箱同地域、同 VPC 可达的 NAS 文件系统，记录 serverAddr；或准备标准存储、同地域的 OSS Bucket。

​

3. 最佳实践配置（NAS-first，核心推荐）

import io.agentscope.harness.agent.sandbox.impl.agentrun.*;
import io.agentscope.harness.agent.HarnessAgent;
import io.agentscope.harness.agent.sandbox.IsolationScope;

AgentRunNasMountConfig nas = new AgentRunNasMountConfig()
    .setServerAddr("12345abc-xxx.cn-hangzhou.nas.aliyuncs.com")
    .setMountDir("/mnt/nas")     // 必须以 /home、/mnt 或 /data 开头
    .setRemotePath("/")
    .setEnableTLS(false);

AgentRunFilesystemSpec spec = new AgentRunFilesystemSpec()
    .setApiKey(System.getenv("AGENTRUN_API_KEY"))
    .setAccountId(System.getenv("ALIYUN_ACCOUNT_ID"))
    .setRegion("cn-hangzhou")
    .setTemplateName("agentscope-default")
    .setMcpServerUrl(System.getenv("AGENTRUN_MCP_URL"))   // 必填,见 §8
    .setNasConfig(nas)
    .setWorkspaceRoot("/mnt/nas/workspace")               // ★ 工作区落在 NAS 内
    .setSandboxIdleTimeoutSeconds(1800)
    .isolationScope(IsolationScope.SESSION);

HarnessAgent agent = HarnessAgent.builder()
    .name("my-agent")
    .model(model)
    .filesystem(spec)
    .build();

• workspaceRoot 以 nasConfig.mountDir 为前缀,adapter 自动判定 workspaceOnNas=true,并对 Sandbox#start() 的探测分支返回 true（Branch A 常态命中）。
• 默认 snapshotSpec=NoopSnapshotSpec,AbstractBaseSandbox.stop() 内置 short-circuit,不会触发 doPersistWorkspace,仅在 NAS 模式下显式 mcp.exec("sync", 5) 让 ossfs/NFS 落盘。
• sandboxIdleTimeoutSeconds(默认 1800)是 AgentRun 侧的闲置回收阈值,超时后实例自动销毁;adapter 在下次 start() 时通过同 id 重建恢复语义。
• sessionId 与 sandboxId 的映射:AgentRunSandboxClient#deriveSandboxId 对 sessionId 做 SHA-256 后截取 26 字符 Crockford Base32 输出,匹配 AgentRun 公开示例 ULID 形状,同 sessionId → 同 sandboxId。

​

4. 退路方案 A:无 NAS,纯 tar 快照

AgentRunFilesystemSpec spec = new AgentRunFilesystemSpec()
    .setApiKey(...)
    .setAccountId(...)
    .setRegion("cn-hangzhou")
    .setTemplateName("agentscope-default")
    .setMcpServerUrl(...)
    .setWorkspaceRoot("/home/agentscope/workspace")
    .snapshotSpec(new OssSnapshotSpec(...));     // ← 必须显式挂 SnapshotSpec

• doPersistWorkspace 在 stop() 时通过 MCP 远程执行 tar -cf - -C <root> . | base64 -w0,再走 OssSnapshotSpec 上传——大工作区(>100MB)上耗时显著;
• doHydrateWorkspace 在 start() 时分块 base64 写入 /tmp/agentscope-ws.b64 后再 python3 -c "tar xf -" 解压,链路较长。

仅在 NAS/OSS 挂载暂时不可用时使用,生产环境优先选 §3。

​

5. 进阶方案 B:NAS 运行时 + OSS Snapshot 冷备

AgentRunFilesystemSpec spec = new AgentRunFilesystemSpec()
    .setApiKey(...).setAccountId(...).setRegion("cn-hangzhou")
    .setTemplateName("agentscope-default")
    .setMcpServerUrl(...)
    .setNasConfig(nas)
    .setWorkspaceRoot("/mnt/nas/workspace")
    .snapshotSpec(new OssSnapshotSpec(                  // 与 NAS 不同的 bucket / key prefix
        ossClient,
        "agentscope-snapshots",
        "agentrun/workspaces/"));

• 快照 bucket 必须与挂载 bucket 隔离(或至少 key prefix 错开),避免循环引用;
• adapter 在 stop() 时:先 mcp.exec("sync", 5) 让 NAS 落盘 → 再触发上层 SnapshotSpec 的 tar 持久化;
• next start() 优先走 NAS(Branch A);若 NAS 卷不可达(Branch B/C),从 OSS Snapshot 恢复。

​

6. AgentRun 原生持久化 vs SandboxSnapshotSpec

question: 你需要工作区跨「沙箱销毁/重建」恢复吗?
├── 否(短时任务、CI 场景) → NoopSnapshotSpec, 无 NAS  → §4 退路模式纯运行时
├── 是 + 单一 region/账号 + 低延迟优先 → §3 NAS-only
└── 是 + 需要跨 region 备份 / 审计 / 离线分析 → §5 NAS + OSS Snapshot

​

7. 限制清单

• 单实例 ≤ 5 个 OSS 挂载点(AgentRunSandboxClientOptions.MAX_OSS_MOUNTS),超出 adapter 在 validate() 阶段抛 SandboxConfigurationException;
• mountDir 必须以 /home/、/mnt/ 或 /data/ 开头(AgentRun 模板侧约束),否则 validate() 失败;
• OSS Bucket 必须是标准存储,且与沙箱同地域;归档/低频存储不支持(平台限制,adapter 不主动校验);
• 沙箱实例最小内存 ≥ 512 MiB(AgentRun 模板侧;adapter 不校验);
• StopSandbox 在 AgentRun 侧是终态,不可恢复——adapter 不调用 StopSandbox,而是通过 DeleteSandbox + 同 sandboxId 重建模拟 resume 语义;
• MCP URL 必填:adapter 不从 GetSandbox 响应自动发现 MCP URL,需要从控制台/控制面查到完整 URL 后填入 setMcpServerUrl(...)(后续若 AgentRun 暴露 accessEndpoint,会升级为自动发现);
• SandboxIdleTimeoutSeconds:超时后实例被回收,任何未 sync 到 NAS 的临时文件丢失;NAS 模式下 adapter 在 stop() 显式 sync,但建议把关键文件写到 workspaceRoot 子目录里。

​

8. 排错速查

GET https://{accountId}.agentrun-data.{region}.aliyuncs.com/2025-09-10/sandboxes/{sandboxId}
   X-API-Key: ...
   X-Acs-Parent-Id: {accountId}

​

9. 延伸阅读

• Sandbox — 沙箱总体设计与隔离范围
• Filesystem — 三种 filesystem 模式与选型
• AgentRun 官方文档 — CreateSandbox
• AgentRun 官方文档 — 实例级 OSS/NAS 动态挂载