finalState = agent.stateDict();
+ if (finalState != null && !finalState.isEmpty()) {
+ stateService.saveState(userId, finalState, sessionId, null)
+ .exceptionally(e -> {
+ logger.error("保存会话状态失败: {}", e.getMessage(), e);
+ return null;
+ });
+ }
+ } catch (Exception e) {
+ logger.error("保存状态时发生异常: {}", e.getMessage(), e);
+ }
+ }
+ })
+ .doOnError(error -> logger.error("智能体流式推理出错: {}", error.getMessage(), error));
+
+ } catch (Exception e) {
+ logger.error("streamQuery 执行异常: {}", e.getMessage(), e);
+ return Flux.error(e);
+ }
+}
+```
+
+### 关键特性
+
+1. **函数签名**：
+ - `request`：封装了本次智能体调用的**请求信息**
+ - `messages`：表示传入的**消息内容**，可能为单条消息、消息列表、或其他中间表示
+2. **流式输出**：函数作为生成器，使用流式返回结果
+3. **状态管理**：可以使用 `this.stateService` 进行状态保存和恢复
+4. **沙箱管理**：可以使用 `this.sandboxService` 构建沙箱工具
+5. **会话历史**：可以使用 `this.sessionHistoryService` 管理会话历史
+6. **记忆管理**：可以使用 `this.memoryService` 管理长期记忆
+
+
+### 完整示例：带状态管理的 AgentApp
+
+**AgentScopeDeployExample.java**
+
+```java
+import io.agentscope.runtime.app.AgentApp;
+import io.agentscope.runtime.engine.services.agent_state.InMemoryStateService;
+import io.agentscope.runtime.engine.services.memory.persistence.memory.service.InMemoryMemoryService;
+import io.agentscope.runtime.engine.services.memory.persistence.session.InMemorySessionHistoryService;
+import io.agentscope.runtime.engine.services.sandbox.SandboxService;
+import io.agentscope.runtime.sandbox.manager.SandboxManager;
+import io.agentscope.runtime.sandbox.manager.client.config.KubernetesClientConfig;
+import io.agentscope.runtime.sandbox.manager.model.ManagerConfig;
+import org.jetbrains.annotations.NotNull;
+
+/**
+ * AgentScope 智能体部署示例。
+ *
+ * 本示例演示如何启动一个基于 ReActAgent 的本地智能体服务，包含以下能力：
+ *
+ * - 会话状态管理（内存存储）
+ * - 短期记忆（会话历史）与长期记忆（用户级记忆库）
+ * - Python 沙箱工具支持（通过 Kubernetes 启动隔离执行环境）
+ * - 通过 HTTP 接口提供流式智能体推理服务
+ *
+ *
+ * 启动前请确保已设置环境变量 {@code AI_DASHSCOPE_API_KEY}。
+ */
+public class AgentScopeDeployExample {
+
+ public static void main(String[] args) {
+ // 校验 DashScope API 密钥是否已配置
+ if (System.getenv("AI_DASHSCOPE_API_KEY") == null) {
+ System.err.println("错误：未设置环境变量 AI_DASHSCOPE_API_KEY");
+ System.exit(1);
+ }
+
+ runAgent();
+ }
+
+ /**
+ * 初始化并启动智能体服务。
+ */
+ private static void runAgent() {
+ // 创建自定义智能体处理器
+ MyAgentScopeAgentHandler agentHandler = new MyAgentScopeAgentHandler();
+
+ // 配置内存版状态与记忆服务（适用于开发/测试）
+ agentHandler.setStateService(new InMemoryStateService());
+ agentHandler.setSessionHistoryService(new InMemorySessionHistoryService());
+ agentHandler.setMemoryService(new InMemoryMemoryService());
+
+ // 配置沙箱服务（用于安全执行 Python 工具代码）
+ agentHandler.setSandboxService(buildSandboxService());
+
+ // 启动 Agent 服务应用，监听 localhost:10001
+ AgentApp agentApp = new AgentApp(agentHandler);
+ agentApp.run("localhost", 10001);
+ }
+
+ /**
+ * 构建沙箱服务实例，默认使用 Kubernetes 客户端配置。
+ *
+ * @return 配置完成的 SandboxService 实例
+ */
+ @NotNull
+ private static SandboxService buildSandboxService() {
+ // 使用默认 Kubernetes 配置（实际部署时可替换为真实集群配置）
+ var clientConfig = KubernetesClientConfig.builder().build();
+ var managerConfig = ManagerConfig.builder()
+ .containerDeployment(clientConfig)
+ .build();
+
+ return new SandboxService(new SandboxManager(managerConfig));
+ }
+}
+```
+
+**MyAgentScopeAgentHandler.java**
+
+```java
+import java.util.List;
+import java.util.Map;
+
+import io.agentscope.core.ReActAgent;
+import io.agentscope.core.agent.EventType;
+import io.agentscope.core.agent.StreamOptions;
+import io.agentscope.core.formatter.dashscope.DashScopeChatFormatter;
+import io.agentscope.core.memory.LongTermMemoryMode;
+import io.agentscope.core.message.Msg;
+import io.agentscope.core.model.DashScopeChatModel;
+import io.agentscope.core.tool.Toolkit;
+import io.agentscope.runtime.adapters.agentscope.AgentScopeAgentHandler;
+import io.agentscope.runtime.adapters.agentscope.memory.LongTermMemoryAdapter;
+import io.agentscope.runtime.adapters.agentscope.memory.MemoryAdapter;
+import io.agentscope.runtime.engine.agents.agentscope.tools.ToolkitInit;
+import io.agentscope.runtime.engine.schemas.AgentRequest;
+import io.agentscope.runtime.sandbox.box.BaseSandbox;
+import io.agentscope.runtime.sandbox.box.Sandbox;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import reactor.core.publisher.Flux;
+
+/**
+ * AgentScope 智能体处理器的示例实现。
+ *
+ *
该实现支持以下核心功能：
+ *
+ * - 从状态服务加载和保存会话状态
+ * - 集成短期记忆（基于会话历史）与长期记忆（基于用户记忆库）
+ * - 动态注册工具（如 Python 沙箱执行环境）
+ * - 使用 Qwen 大模型进行流式推理
+ * - 以事件流形式返回推理全过程（包括推理步骤、工具调用等）
+ *
+ */
+public class MyAgentScopeAgentHandler extends AgentScopeAgentHandler {
+ private static final Logger logger = LoggerFactory.getLogger(MyAgentScopeAgentHandler.class);
+ private final String apiKey;
+
+ /**
+ * 构造函数：从环境变量加载 DashScope API 密钥。
+ */
+ public MyAgentScopeAgentHandler() {
+ this.apiKey = System.getenv("AI_DASHSCOPE_API_KEY");
+ }
+
+ @Override
+ public Flux streamQuery(AgentRequest request, Object messages) {
+ String sessionId = request.getSessionId();
+ String userId = request.getUserId();
+
+ try {
+ // 1. 尝试从状态服务加载当前会话的持久化状态
+ Map state = null;
+ if (stateService != null) {
+ try {
+ state = stateService.exportState(userId, sessionId, null).join();
+ } catch (Exception e) {
+ logger.warn("加载会话状态失败: {}", e.getMessage());
+ }
+ }
+
+ // 2. 初始化工具集并注册可用工具
+ Toolkit toolkit = new Toolkit();
+ if (sandboxService != null) {
+ try {
+ Sandbox sandbox = sandboxService.connect(userId, sessionId, BaseSandbox.class);
+ toolkit.registerTool(ToolkitInit.RunPythonCodeTool(sandbox));
+ logger.debug("已注册 Python 代码执行工具");
+ } catch (Exception e) {
+ logger.warn("沙箱初始化或工具注册失败，跳过工具支持: {}", e.getMessage());
+ }
+ }
+
+ // 3. 创建短期记忆适配器（用于管理当前会话消息历史）
+ MemoryAdapter memory = null;
+ if (sessionHistoryService != null) {
+ memory = new MemoryAdapter(sessionHistoryService, userId, sessionId);
+ }
+
+ // 4. 创建长期记忆适配器（用于访问用户级别的持久化记忆）
+ LongTermMemoryAdapter longTermMemory = null;
+ if (memoryService != null) {
+ longTermMemory = new LongTermMemoryAdapter(memoryService, userId, sessionId);
+ }
+
+ // 5. 构建 ReAct 智能体实例
+ ReActAgent.Builder agentBuilder = ReActAgent.builder()
+ .name("Friday")
+ .sysPrompt("你是一个名为 Friday 的智能助手。")
+ .toolkit(toolkit)
+ .model(
+ DashScopeChatModel.builder()
+ .apiKey(apiKey)
+ .modelName("qwen-max")
+ .stream(true)
+ .formatter(new DashScopeChatFormatter())
+ .build()
+ );
+
+ if (longTermMemory != null) {
+ agentBuilder.longTermMemory(longTermMemory)
+ .longTermMemoryMode(LongTermMemoryMode.BOTH);
+ logger.debug("已启用长期记忆");
+ }
+
+ if (memory != null) {
+ agentBuilder.memory(memory);
+ logger.debug("已配置短期记忆适配器");
+ }
+
+ ReActAgent agent = agentBuilder.build();
+
+ // 6. 若存在状态数据，则恢复智能体内部状态
+ if (state != null && !state.isEmpty()) {
+ try {
+ agent.loadStateDict(state);
+ logger.debug("成功恢复会话状态，会话 ID: {}", sessionId);
+ } catch (Exception e) {
+ logger.warn("恢复状态失败: {}", e.getMessage());
+ }
+ }
+
+ // 7. 将输入消息转换为标准 Msg 列表
+ List agentMessages;
+ if (messages instanceof List) {
+ @SuppressWarnings("unchecked")
+ List msgList = (List) messages;
+ agentMessages = msgList;
+ } else if (messages instanceof Msg) {
+ agentMessages = List.of((Msg) messages);
+ } else {
+ logger.warn("不支持的消息类型: {}，使用空消息列表",
+ messages != null ? messages.getClass().getName() : "null");
+ agentMessages = List.of();
+ }
+
+ // 8. 准备查询消息：多条消息时，前 N-1 条存入记忆，最后一条作为当前查询
+ Msg queryMessage;
+ if (agentMessages.isEmpty()) {
+ queryMessage = Msg.builder()
+ .role(io.agentscope.core.message.MsgRole.USER)
+ .build();
+ } else if (agentMessages.size() == 1) {
+ queryMessage = agentMessages.get(0);
+ } else {
+ for (int i = 0; i < agentMessages.size() - 1; i++) {
+ agent.getMemory().addMessage(agentMessages.get(i));
+ }
+ queryMessage = agentMessages.get(agentMessages.size() - 1);
+ }
+
+ // 9. 配置流式输出选项：包含推理过程和工具调用结果，启用增量模式
+ StreamOptions streamOptions = StreamOptions.builder()
+ .eventTypes(EventType.REASONING, EventType.TOOL_RESULT)
+ .incremental(true)
+ .build();
+
+ // 10. 启动流式推理，并在流结束时自动保存最终状态
+ return agent.stream(queryMessage, streamOptions)
+ .doOnNext(event -> logger.info("智能体事件: {}", event))
+ .doFinally(signalType -> {
+ if (stateService != null) {
+ try {
+ Map finalState = agent.stateDict();
+ if (finalState != null && !finalState.isEmpty()) {
+ stateService.saveState(userId, finalState, sessionId, null)
+ .exceptionally(e -> {
+ logger.error("保存会话状态失败: {}", e.getMessage(), e);
+ return null;
+ });
+ }
+ } catch (Exception e) {
+ logger.error("保存状态时发生异常: {}", e.getMessage(), e);
+ }
+ }
+ })
+ .doOnError(error -> logger.error("智能体流式推理出错: {}", error.getMessage(), error));
+
+ } catch (Exception e) {
+ logger.error("streamQuery 执行异常: {}", e.getMessage(), e);
+ return Flux.error(e);
+ }
+ }
+
+ @Override
+ public boolean isHealthy() {
+ return true;
+ }
+
+ @Override
+ public String getName() {
+ return "DemoAgent";
+ }
+
+ @Override
+ public String getDescription() {
+ return "基于 AgentScope 实现的智能助手示例。";
+ }
+}
+```
+
+## 本地部署
+
+**功能**
+
+通过 `run()` 方法一键拉起本地应用。
+
+**用法示例**
+
+```java
+agentApp.run("localhost", 10001);
+```
+
+更多部署选项和详细说明，请参考 [高级部署](deployment/advanced_deployment.md) 文档。
+
+AgentScope Runtime 提供了 Serverless 的部署方案，您可以将您的 Agent 应用部署到 K8s 或 AgentRun 上。参考 [高级部署](deployment/advanced_deployment.md) 文档，查看 K8s 和 AgentRun 部署部分获取更多配置详情.
diff --git a/cookbook/new-zh/deployment/react_agent.md b/cookbook/new-zh/deployment/react_agent.md
new file mode 100644
index 00000000..e69de29b
diff --git a/cookbook/new-zh/install.md b/cookbook/new-zh/install.md
new file mode 100644
index 00000000..80f395d6
--- /dev/null
+++ b/cookbook/new-zh/install.md
@@ -0,0 +1,139 @@
+# 安装
+
+准备好开始使用 AgentScope Runtime Java 了吗？本指南将帮助您在几分钟内快速搭建和运行**AgentScope Runtime Java**。
+
+## 前置要求
+
+- **Java 17** 或更高版本
+- **Maven 3.6** 或更高版本
+- **Docker**（可选，用于沙箱工具执行）
+
+## 安装方式
+
+### 通过 Maven Central 安装（推荐）
+
+AgentScope Runtime Java 已经发布到 Maven Central，您可以直接通过 Maven 依赖使用。
+
+> 当前稳定版本：1.0.0
+>
+> 您可以在 [Maven Central](https://central.sonatype.com/artifact/io.agentscope/agentscope-runtime-core) 上查找和下载所有模块。
+
+在您的 `pom.xml` 中添加相应的依赖即可使用：
+
+#### 核心运行时 (Core)
+
+在您的 `pom.xml` 中添加核心运行时依赖：
+
+```xml
+
+ io.agentscope
+ agentscope-runtime-core
+ 1.0.0
+
+```
+
+#### AgentScope Agent 集成
+
+如果需要使用 AgentScope Agent：
+
+```xml
+
+ io.agentscope
+ agentscope-runtime-agentscope
+ 1.0.0
+
+```
+
+#### 一键部署 (Web)
+
+如果需要使用一键部署功能：
+
+```xml
+
+ io.agentscope
+ agentscope-runtime-web
+ 1.0.0
+
+```
+
+#### 协议集成
+
+如果需要使用 A2A (Agent-to-Agent) 协议：
+
+```xml
+
+ io.agentscope
+ spring-boot-starter-runtime-a2a
+ 1.0.0
+
+```
+
+#### 自动化部署
+
+如果想要自动将 Agent 应用打包为容器，并自动部署到 K8s 或 AgentRun 上，可以使用提供的插件：
+
+```xml
+
+ io.agentscope
+ deployer-maven-plugin
+ 1.0.0
+
+ deployer.yml
+ 8080
+
+
+```
+
+### （可选）从源码安装
+
+如果您想要使用最新的开发版本或为项目做贡献，可以从源码安装：
+
+```bash
+git clone https://github.com/agentscope-ai/agentscope-runtime-java.git
+
+cd agentscope-runtime-java
+
+mvn clean install -Dskiptests
+```
+
+安装完成后，依赖项将安装在本地 Maven 仓库中，您可以在项目中使用它们。
+
+> 从源码安装会使用 SNAPSHOT 版本，适合开发和测试场景。生产环境建议使用 Maven Central 上的稳定版本。
+
+### 使用 Maven 检查依赖
+
+您也可以使用 Maven 命令检查依赖是否正确解析：
+
+```bash
+mvn dependency:tree | grep agentscope
+```
+
+这将显示所有与 agentscope 相关的依赖及其版本。
+
+
+## 安装选项说明
+
+这个图展示了安装选项的层次结构，从底层核心运行时（agentscope-runtime-core）开始——其中 **包含 Agent 运行框架 和 Sandbox 依赖**。可选模块（例如 agentscope、web、a2a-starter等）堆叠在核心之上，每个模块都增加了特定的功能（如多Agent框架支持、自动化）。查看所有安装选项的详细信息，请参见项目的 [pom.xml](https://github.com/agentscope-ai/agentscope-runtime-java/blob/main/pom.xml)。
+
+| **组件** | **Maven 坐标** | **用途** |
+| --------------------- | ----------------------------------------------- | ------------------------------------------------------------ |
+| 核心运行时 | `io.agentscope:agentscope-runtime-core` | 最小依赖，提供沙箱管理、记忆管理等基础运行时能力 |
+| AgentScope Agent 集成 | `io.agentscope:agentscope-runtime-agentscope` | AgentScope 集成，支持原生 AgentScope Agent 到 Runtime Agent 的转换，并内置 Sandbox Tool 到 AgentScope Tool 的映射逻辑 |
+| 一键启动 | `io.agentscope:agentscope-runtime-web` | 通过 LocalDeployer 实现 Agent 应用的一键启动与本地运行 |
+| 协议集成 | `io.agentscope:spring-boot-starter-runtime-a2a` | 在用户构建好的 Spring Boot 应用中自动注册 A2A（Agent-to-Agent）通信端点及 Responses API 接口 |
+| 自动化部署 | `deployer-maven-plugin` | 将 Agent 应用打包为一个容器，并可选部署到 K8s 或 AgentRun 上 |
+
+## 版本信息
+
+- **当前稳定版本**：`1.0.0`
+- **发布位置**：[Maven Central](https://central.sonatype.com/artifact/io.agentscope/agentscope-runtime-core)
+- **GroupId**：`io.agentscope`
+
+### 在 Maven Central 上查找
+
+您可以在 Maven Central 上搜索和查看所有可用模块：
+
+- [agentscope-runtime-core](https://central.sonatype.com/artifact/io.agentscope/agentscope-runtime-core)
+- [agentscope-runtime-agentscope](https://central.sonatype.com/artifact/io.agentscope/agentscope-runtime-agentscope)
+- [agentscope-runtime-web](https://central.sonatype.com/artifact/io.agentscope/agentscope-runtime-web)
+- [spring-boot-starter-runtime-a2a](https://central.sonatype.com/artifact/io.agentscope/spring-boot-starter-runtime-a2a)
\ No newline at end of file
diff --git a/cookbook/new-zh/intro.md b/cookbook/new-zh/intro.md
new file mode 100644
index 00000000..9b8d640e
--- /dev/null
+++ b/cookbook/new-zh/intro.md
@@ -0,0 +1,65 @@
+# 欢迎来到AgentScope Runtime Java Cookbook
+
+[](LICENSE)
+[](https://github.com/agentscope-ai/agentscope-runtime-java/stargazers)
+[](https://github.com/agentscope-ai/agentscope-runtime-java/network)
+[](https://maven-badges.herokuapp.com/maven-central/io.agentscope/agentscope-runtime)
+[](https://github.com/agentscope-ai/agentscope-runtime/blob/main/LICENSE)
+[](https://runtime.agentscope.io)
+[](https://a2a-protocol.org/)
+[](https://modelcontextprotocol.io/)
+[](https://qr.dingtalk.com/action/joingroup?code=v1,k1,OmDlBXpjW+I2vWjKDsjvI9dhcXjGZi3bQiojOq3dlDw=&_dt_no_comment=1&origin=11)
+
+## AgentScope Runtime V1.0 发布
+
+AgentScope Runtime Java V1.0 在高效智能体部署与安全沙箱执行的坚实基础上，推出了 **统一的 “Agent 作为 API” 开发体验**，覆盖完整智能体从本地开发到生产部署的生命周期，并扩展了更多沙箱类型、协议兼容性与更丰富的内置工具集。
+
+同时，智能体服务的接入方式从过去的 **黑盒化模块替换** 升级为 ***白盒化适配器模式*** —— 开发者可以在保留原有智能体框架接口与行为的前提下，将状态管理、会话记录、工具注册等运行时能力按需嵌入应用生命周期，实现更灵活的定制与跨框架无缝集成。
+
+**V1.0 主要改进：**
+
+- **统一的开发/生产范式** —— 在开发环境与生产环境中 智能体功能性保持一致
+- **原生多智能体支持** —— 完全兼容 AgentScope Java 的多智能体范式
+- **主流 SDK 与协议集成** —— 支持 OpenAI Responses API SDK 与 Google A2A 协议
+- **可视化 Web UI** —— 部署后即可立即体验的开箱即用 Web 聊天界面
+- **扩展沙箱类型** —— GUI、浏览器、文件系统（大部分可通过 VNC 可视化）
+- **更丰富的内置工具** —— 面向生产的搜索、RAG、AIGC、支付等模块
+- **灵活的部署模式** —— 本地线程/进程、Docker、Kubernetes、或托管云端
+
+更详细的变更说明，以及迁移指南请参考：[CHANGELOG](CHANGELOG.md)
+
+## 什么是AgentScope Runtime Java？
+
+**AgentScope Runtime Java** 是一个全面的智能体运行时框架，旨在解决两个关键挑战：**高效的智能体部署**和**沙箱执行**。它内置了基础服务（长短期记忆、智能体状态持久化）和安全沙箱基础设施。无论您需要大规模部署智能体还是确保安全的工具交互，AgentScope Runtime Java 都能提供具有完整可观测性和开发者友好部署的核心基础设施。
+
+在 V1.0 中，这些运行时服务通过 **适配器模式** 对外开放，允许开发者在保留原有智能体框架接口与行为的基础上，将 AgentScope Java 的状态管理、会话记录、工具调用等模块按需嵌入到应用生命周期中。从过去的 “黑盒化替换” 变为 “白盒化集成”，开发者可以显式地控制服务初始化、工具注册与状态持久化流程，从而在不同框架间实现无缝整合，同时获得更高的扩展性与灵活性。
+
+本指南将指导您使用 **AgentScope Runtime Java** 构建服务级的智能体应用程序。
+
+## 核心架构
+
+**⚙️ 智能体web应用部署 (Web)**
+
+提供`AgentApp`作为智能体应用主入口，同时配备部署、管理和监控智能体应用的生产级基础设施，并内置了会话历史、长期记忆以及智能体状态等服务。
+
+**🔒 沙箱执行运行时 (Sandbox)**
+
+安全隔离的环境，让您的智能体能够安全地执行代码、控制浏览器、管理文件并集成MCP 工具——所有这些都不会危及您的系统安全。
+
+**🛠️ 生产级工具服务 (Tool)**
+
+基于可信第三方 API 能力（如搜索、RAG、AIGC、支付等），通过统一的 SDK 封装对外提供标准化调用接口，使智能体能够以一致的方式集成和使用这些服务，而无需关心底层 API 的差异与复杂性。
+
+**🔌 适配器模式 (Adapter)**
+
+将 Runtime 内的各类服务模块（状态管理、会话记录、工具执行等）适配到智能体框架的原生模块接口中，使开发者能够在保留原生行为的同时直接调用这些能力，实现无缝对接与灵活扩展。
+
+## 为什么选择 AgentScope Runtime Java？
+
+- 🤖 **AS原生运行时框架**：由 AgentScope 官方构建和维护，与其多智能体范式、适配器模式及工具使用深度集成，确保最佳兼容性与性能
+- **🏗️ 部署基础设施**：内置长短期记忆、智能体状态和沙箱环境控制服务
+- **🔒 沙箱执行**：隔离的沙箱确保工具安全执行，不会危及系统
+- ⚡ **开发者友好**：简单部署，功能强大的自定义选项
+- **📊 可观测性**：针对运行时操作的全面追踪和监控
+
+立即开始使用 AgentScope Runtime Java 部署你的智能体并尝试工具沙箱吧！
diff --git a/cookbook/new-zh/quickstart.md b/cookbook/new-zh/quickstart.md
new file mode 100644
index 00000000..24fd76ce
--- /dev/null
+++ b/cookbook/new-zh/quickstart.md
@@ -0,0 +1,414 @@
+# 快速开始
+
+本教程演示如何在 **AgentScope Runtime Java** 框架中构建一个简单的智能体应用并将其部署为服务。
+
+## 前置条件
+
+### 🔧 安装要求
+
+添加 AgentScope Runtime Java 针对 AgentScope 框架的适配器依赖和应用启动依赖，基础依赖已通过适配器依赖传递依赖完成：
+
+```xml
+
+ io.agentscope
+ agentscope-runtime-agentscope
+ 1.0.0
+
+
+
+ io.agentscope
+ agentscope-runtime-web
+ 1.0.0
+
+```
+
+### 🔑 API密钥配置
+
+您需要为所选的大语言模型提供商提供API密钥。本示例使用阿里云的Qwen模型，服务提供方是DashScope，所以需要使用其API_KEY，您可以按如下方式将key作为环境变量：
+
+```bash
+export DASHSCOPE_API_KEY="your_api_key_here"
+```
+
+## 分步实现
+
+### 步骤1：构建 Agent 及其执行逻辑
+
+#### 1.1 导入依赖
+
+首先导入所有必要的依赖：
+
+```java
+import java.util.List;
+import java.util.Map;
+
+import io.agentscope.core.ReActAgent;
+import io.agentscope.core.agent.EventType;
+import io.agentscope.core.agent.StreamOptions;
+import io.agentscope.core.formatter.dashscope.DashScopeChatFormatter;
+import io.agentscope.core.memory.LongTermMemoryMode;
+import io.agentscope.core.message.Msg;
+import io.agentscope.core.model.DashScopeChatModel;
+import io.agentscope.core.tool.Toolkit;
+import io.agentscope.runtime.adapters.agentscope.AgentScopeAgentHandler;
+import io.agentscope.runtime.adapters.agentscope.memory.LongTermMemoryAdapter;
+import io.agentscope.runtime.adapters.agentscope.memory.MemoryAdapter;
+import io.agentscope.runtime.engine.agents.agentscope.tools.ToolkitInit;
+import io.agentscope.runtime.engine.schemas.AgentRequest;
+import io.agentscope.runtime.sandbox.box.BaseSandbox;
+import io.agentscope.runtime.sandbox.box.Sandbox;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import reactor.core.publisher.Flux;
+```
+
+#### 1.2 构建 AgentScopeAgentHandler 接口的实现
+
+下面的四个方法分别定义了整个应用的属性和执行逻辑，`isHealthy`方法用于返回当前应用的健康状况，`getName`方法用于返回当前应用的名称，`getDescription`方法用于返回当前应用的描述，**`streamQuery`**方法则是整个AgentScopeAgentHandler的逻辑执行核心，用于用户设置记忆、构建 Agent 以及自定义 Agent 执行逻辑
+
+```java
+public class MyAgentScopeAgentHandler extends AgentScopeAgentHandler {
+ @Override
+ public boolean isHealthy() {
+ return false;
+ }
+
+ @Override
+ public String getName() {
+ return "";
+ }
+
+ @Override
+ public String getDescription() {
+ return "";
+ }
+
+ @Override
+ public Flux streamQuery(AgentRequest request, Object messages) {
+ return null;
+ }
+}
+```
+
+#### 1.3 实现核心执行逻辑 streamQuery 方法
+
+##### 1.3.1 获取到必要的 id 信息
+
+```java
+String sessionId = request.getSessionId();
+String userId = request.getUserId();
+```
+
+##### 1.3.2 从 StateService 导出历史状态
+
+```java
+Map state = null;
+if (stateService != null) {
+ try {
+ state = stateService.exportState(userId, sessionId, null).join();
+ }
+ catch (Exception e) {
+ logger.warn("Failed to export state: {}", e.getMessage());
+ }
+}
+```
+
+- **目的**：恢复该用户在该会话中的**上一轮 Agent 状态**（例如：内部变量、对话阶段、任务进度等）。
+- `roundId = null` 表示取**最新一轮**的状态。
+- 使用 `.join()` 阻塞等待（因为后续构建 Agent 需要同步状态）。
+- 失败时仅警告，不影响主流程（Agent 可从空状态开始）。
+
+##### 1.3.3 创建 Toolkit 并注册工具
+
+```java
+Toolkit toolkit = new Toolkit();
+if (sandboxService != null) {
+ Sandbox sandbox = sandboxService.connect(userId, sessionId, BaseSandbox.class);
+ toolkit.registerTool(ToolkitInit.RunPythonCodeTool(sandbox));
+}
+```
+
+- **Toolkit**：Agent 可调用的工具集合。
+- **Sandbox**：安全沙箱环境，具体包含基础沙箱、文件系统沙箱、浏览器沙箱等，每个 `(userId, sessionId)` 独立实例。
+- 注册沙箱工具。
+- 如果沙箱创建失败，跳过工具注册，Agent 仍可运行，但无法调用此工具。
+
+##### 1.3.4 创建短期记忆适配器（MemoryAdapter）
+
+```java
+MemoryAdapter memory = null;
+if (sessionHistoryService != null) {
+ memory = new MemoryAdapter(sessionHistoryService, userId, sessionId);
+}
+```
+
+- **作用**：提供**当前会话的历史消息记录**（如用户和 Agent 的对话历史）。
+- `sessionHistoryService` 是底层存储服务。
+- 适配器将通用服务接口转换为 AgentScope 框架所需的 `Memory` 接口。
+
+##### 1.3.5 创建长期记忆适配器（LongTermMemoryAdapter）
+
+```java
+LongTermMemoryAdapter longTermMemory = null;
+if (memoryService != null) {
+ longTermMemory = new LongTermMemoryAdapter(memoryService, userId, sessionId);
+}
+```
+
+- **作用**：访问用户的**跨会话长期记忆**（如个人偏好、知识库摘要等）。
+- 通常基于向量数据库或结构化存储。
+- 后续会配置 Agent 在生成回复时**同时参考短期和长期记忆**。
+
+##### 1.3.6 构建 ReActAgent 实例
+
+```java
+ReActAgent.Builder agentBuilder = ReActAgent.builder()
+ .name("Friday")
+ .sysPrompt("You're a helpful assistant named Friday.")
+ .toolkit(toolkit)
+ .model(
+ DashScopeChatModel.builder()
+ .apiKey(apiKey)
+ .modelName("qwen-max")
+ .stream(true)
+ .formatter(new DashScopeChatFormatter())
+ .build());
+```
+
+- 使用 **Builder 模式**组装 Agent：
+ - 名称、系统提示词（system prompt）
+ - 绑定工具集（`toolkit`）
+ - 配置大模型（这里用通义千问 `qwen-max`，通过 DashScope API）
+ - 启用流式输出（`.stream(true)`）
+- **注意**：此时 Agent 尚未加载状态或记忆。
+
+##### 1.3.7 注入记忆模块
+
+```java
+if (longTermMemory != null) {
+ agentBuilder.longTermMemory(longTermMemory)
+ .longTermMemoryMode(LongTermMemoryMode.BOTH);
+}
+if (memory != null) {
+ agentBuilder.memory(memory);
+}
+```
+
+- **`memory`** → 短期记忆（当前会话历史）
+- **`longTermMemory`** → 长期记忆（跨会话知识）
+- `LongTermMemoryMode.BOTH`：表示在**思考和生成**阶段都使用长期记忆。
+
+##### 1.3.8 加载历史状态到 Agent
+
+```java
+if (state != null && !state.isEmpty()) {
+ agent.loadStateDict(state);
+}
+```
+
+- 将 Step 2 获取的状态字典反序列化到 Agent 内部。
+- 使 Agent 能“接续”上一次的对话状态（如继续未完成的任务）。
+
+##### 1.3.9 处理输入消息（messages）
+
+```java
+List agentMessages;
+if (messages instanceof List) {
+ @SuppressWarnings("unchecked")
+ List msgList = (List) messages;
+ agentMessages = msgList;
+}
+else if (messages instanceof Msg) {
+ agentMessages = List.of((Msg) messages);
+}
+else {
+ logger.warn("Unexpected messages type: {}, using empty list",
+ messages != null ? messages.getClass().getName() : "null");
+ agentMessages = List.of();
+}
+
+Msg queryMessage;
+if (agentMessages.size() > 1) {
+ // 将前 N-1 条消息加入 memory
+ for (int i = 0; i < agentMessages.size() - 1; i++) {
+ agent.getMemory().addMessage(agentMessages.get(i));
+ }
+ queryMessage = agentMessages.get(agentMessages.size() - 1); // 最后一条作为当前查询
+} else {
+ queryMessage = agentMessages.get(0) or empty Msg;
+}
+```
+
+##### 1.3.10 启动流式推理并返回事件流
+
+```java
+StreamOptions streamOptions = StreamOptions.builder()
+ .eventTypes(EventType.REASONING, EventType.TOOL_RESULT)
+ .incremental(true)
+ .build();
+
+Flux agentScopeEvents = agent.stream(queryMessage, streamOptions);
+```
+
+- **`stream()`**：启动 ReAct 循环（Thought → Action → Observation → ... → Final Answer）
+- **`StreamOptions`**：
+ - `eventTypes`：只返回推理步骤和工具结果（过滤掉内部日志等）
+ - `incremental = true`：启用增量流式输出（如逐字生成）
+- 返回的是 **AgentScope 原生 Event 流**（不是 Runtime Event），由外层 `StreamAdapter` 转换。
+
+##### 1.3.11 流完成时保存最终状态
+
+```java
+return agentScopeEvents
+ .doOnNext(event -> {
+ logger.info("Agent event: {}", event);
+ })
+ .doFinally(signalType -> {
+ if (stateService != null) {
+ try {
+ Map finalState = agent.stateDict();
+ if (finalState != null && !finalState.isEmpty()) {
+ stateService.saveState(userId, finalState, sessionId, null)
+ .exceptionally(e -> {
+ logger.error("Failed to save state: {}", e.getMessage(), e);
+ return null;
+ });
+ }
+ }
+ catch (Exception e) {
+ logger.error("Error saving state: {}", e.getMessage(), e);
+ }
+ }
+ })
+ .doOnError(error -> {
+ logger.error("Error in agent stream: {}", error.getMessage(), error);
+ });
+```
+
+- **无论成功/失败/取消**，在流结束时保存 Agent 的**最终状态**。
+- `roundId = null` → 自动分配新轮次 ID（见 `InMemoryStateService` 实现）。
+- 使用 `exceptionally` 处理保存异常，避免影响主流程。
+
+> 🔁 实现了“状态持久化闭环”：加载 → 执行 → 保存。
+
+### 步骤2：构建 AgentApp
+
+#### 2.1 导入依赖
+
+```java
+import io.agentscope.runtime.app.AgentApp;
+import io.agentscope.runtime.engine.services.agent_state.InMemoryStateService;
+import io.agentscope.runtime.engine.services.memory.persistence.memory.service.InMemoryMemoryService;
+import io.agentscope.runtime.engine.services.memory.persistence.session.InMemorySessionHistoryService;
+import io.agentscope.runtime.engine.services.sandbox.SandboxService;
+import io.agentscope.runtime.sandbox.manager.SandboxManager;
+import io.agentscope.runtime.sandbox.manager.client.config.BaseClientConfig;
+import io.agentscope.runtime.sandbox.manager.client.config.KubernetesClientConfig;
+import io.agentscope.runtime.sandbox.manager.model.ManagerConfig;
+import org.jetbrains.annotations.NotNull;
+```
+
+#### 2.2 构建 SandboxService 沙箱管理服务
+
+```java
+private static SandboxService buidSandboxService() {
+ BaseClientConfig clientConfig = KubernetesClientConfig.builder().build();
+ ManagerConfig managerConfig = ManagerConfig.builder()
+ .containerDeployment(clientConfig)
+ .build();
+ return new SandboxService(
+ new SandboxManager(managerConfig)
+ );
+}
+```
+
+* 沙箱运行环境支持 **Docker**、**K8s **以及 **AgentRun**，未配置 `clientConfig` 默认使用**本地 Docker **作为运行环境
+* 使用`managerConfig`构建 **SandboxManager**，并由此构建 **SandboxService**
+
+#### 2.3 构建 AgentApp
+
+##### 2.3.1 初始化 agentHandler
+
+```java
+MyAgentScopeAgentHandler agentHandler = new MyAgentScopeAgentHandler();
+agentHandler.setStateService(new InMemoryStateService());
+agentHandler.setSessionHistoryService(new InMemorySessionHistoryService());
+agentHandler.setMemoryService(new InMemoryMemoryService());
+agentHandler.setSandboxService(buidSandboxService());
+```
+
+实例化刚刚编写的 **AgentScopeAgentHandler** 类，并注册服务
+
+##### 2.3.2 构建 AgentApp 并一键启动
+
+```java
+AgentApp agentApp = new AgentApp(agentHandler);
+agentApp.run(10001);
+```
+
+使用实例化的 **AgentScopeAgentHandler** 类初始化 **AgentApp**，并在10001端口上启动
+
+### 步骤3：通过 A2A 协议访问 Agent
+
+```bash
+curl --location --request POST 'http://localhost:10001/a2a/' \
+--header 'Content-Type: application/json' \
+--header 'Accept: */*' \
+--header 'Host: localhost:10001' \
+--header 'Connection: keep-alive' \
+--data-raw '{
+ "method": "message/stream",
+ "id": "2d2b4dc8-8ea2-437b-888d-3aaf3a8239dc",
+ "jsonrpc": "2.0",
+ "params": {
+ "configuration": {
+ "blocking": false
+ },
+ "message": {
+ "role": "user",
+ "kind": "message",
+ "metadata": {
+ "userId": "me",
+ "sessionId": "test1"
+ },
+ "parts": [
+ {
+ "text": "你好，给我用python计算一下第10个斐波那契数",
+ "kind": "text"
+ }
+ ],
+ "messageId": "c4911b64c8404b7a8bf7200dd225b152"
+ }
+ }
+}'
+```
+
+你将会看到以**Server-Sent Events（SSE）**格式流式输出的响应：
+
+```
+id:2d2b4dc8-8ea2-437b-888d-3aaf3a8239dc
+event:jsonrpc
+data:{"jsonrpc":"2.0","id":"2d2b4dc8-8ea2-437b-888d-3aaf3a8239dc","result":{"id":"92ccdc36-006f-4d66-a47c-18d0cb171506","contextId":"fd5bccd1-770f-4872-8c9a-f086c094f90a","status":{"state":"submitted","timestamp":"2025-12-09T10:53:47.612001Z"},"artifacts":[],"history":[{"role":"user","parts":[{"text":"你好，给我用python计算一下第10个斐波那契数","kind":"text"}],"messageId":"c4911b64c8404b7a8bf7200dd225b152","contextId":"fd5bccd1-770f-4872-8c9a-f086c094f90a","taskId":"92ccdc36-006f-4d66-a47c-18d0cb171506","metadata":{"userId":"me","sessionId":"test1"},"kind":"message"}],"kind":"task"}}
+
+id:2d2b4dc8-8ea2-437b-888d-3aaf3a8239dc
+event:jsonrpc
+data:{"jsonrpc":"2.0","id":"2d2b4dc8-8ea2-437b-888d-3aaf3a8239dc","result":{"taskId":"92ccdc36-006f-4d66-a47c-18d0cb171506","status":{"state":"working","timestamp":"2025-12-09T10:53:47.614736Z"},"contextId":"fd5bccd1-770f-4872-8c9a-f086c094f90a","final":false,"kind":"status-update"}}
+
+......
+
+id:2d2b4dc8-8ea2-437b-888d-3aaf3a8239dc
+event:jsonrpc
+data:{"jsonrpc":"2.0","id":"2d2b4dc8-8ea2-437b-888d-3aaf3a8239dc","result":{"taskId":"92ccdc36-006f-4d66-a47c-18d0cb171506","artifact":{"artifactId":"293bb1b0-1442-4ca2-997f-575b798dfad1","name":"agent-response","parts":[{"text":"是55。","kind":"text"}],"metadata":{"type":"chunk"}},"contextId":"fd5bccd1-770f-4872-8c9a-f086c094f90a","append":true,"lastChunk":false,"kind":"artifact-update"}}
+
+id:2d2b4dc8-8ea2-437b-888d-3aaf3a8239dc
+event:jsonrpc
+data:{"jsonrpc":"2.0","id":"2d2b4dc8-8ea2-437b-888d-3aaf3a8239dc","result":{"taskId":"92ccdc36-006f-4d66-a47c-18d0cb171506","status":{"state":"completed","message":{"role":"agent","parts":[{"text":"run_ipython_cellrun_ipython_cell第10个斐波那契数是55。","kind":"text"}],"messageId":"7b878071-d63e-4710-81e0-91d50a57c373","contextId":"fd5bccd1-770f-4872-8c9a-f086c094f90a","taskId":"92ccdc36-006f-4d66-a47c-18d0cb171506","metadata":{"type":"final_response"},"kind":"message"},"timestamp":"2025-12-09T10:53:51.538933Z"},"contextId":"fd5bccd1-770f-4872-8c9a-f086c094f90a","final":true,"kind":"status-update"}}
+```
+
+## 章节导读
+
+后续的章节包括如下几个部分
+- [沙箱与工具](tool.md): 帮助您在Agent中加入工具
+- [部署](deployment.md): 帮助您部署Agent，打包成服务
+- [使用](use.md): 帮助您调用部署后的服务
+- [如何贡献](contribute.md): 贡献代码给本项目的参考文档
\ No newline at end of file
diff --git a/cookbook/new-zh/sandbox/advanced.md b/cookbook/new-zh/sandbox/advanced.md
new file mode 100644
index 00000000..60d6f997
--- /dev/null
+++ b/cookbook/new-zh/sandbox/advanced.md
@@ -0,0 +1,331 @@
+# 工具沙箱高级用法
+
+>本节介绍沙箱的高级用法。我们强烈建议在继续之前先完成上一节的基础教程[沙箱](sandbox.md)。
+
+## 沙箱管理器配置参考
+
+#### ManagerConfig 配置
+
+| Parameter | Type | Description | Default | Notes |
+| ----------------------| ------------ | ---------------------- | -------------------------- | ------------------------------------------------------------ |
+| `defaultSandboxType` | `List` | 默认沙箱类型（可多个） | `SandboxType.BASE` | 可以是单个类型，也可以是多个类型的列表，从而启用多个独立的沙箱预热池。合法取值包括 `BASE`、`BROWSER`、`FILESYSTEM`、`GUI` 等 |
+| `bearerToken` | `String` | 调用远程runtime沙箱的身份验证令牌 | `null` | 如果设置为 `null`，将在连接的时候不会进行身份验证 |
+| `baseUrl` | `String` | 调用远程runtime沙箱的服务器绑定地址 | `null` | 如果设置为 `null`，将默认使用本地沙箱管理 |
+| `containerDeployment` | `BaseClientConfig` | 容器运行时 | `DockerClientConfig` | 目前支持 `Docker`、`K8s` 和 `AgentRun` |
+| `poolSize` | `int` | 预热容器池大小 | `0` | 缓存的容器以实现更快启动。 `poolSize` 参数控制预创建并缓存在就绪状态的容器数量。当用户请求新沙箱时，系统将首先尝试从这个预热池中分配，相比从零开始创建容器显著减少启动时间。例如，使用 `poolSize=10`，系统维护 10 个就绪容器，可以立即分配给新请求 |
+| `fileSystemConfig` | `FileSystemConfig` | 容器文件系统配置 | `LocalFileSystemConfig` | 管理容器文件系统的下载方式，默认使用`本地文件系统`，也可以使用 `oss` |
+| `redisConfig` | `RedisManagerConfig` | redis支持配置 | `null` | 启用 Redis 支持，分布式部署或工作进程数大于 `1` 时必需，默认不启用 |
+
+#### Redis 配置
+
+> **何时使用 Redis：**
+> - **单个工作进程（`WORKERS=1`）**：Redis 是可选的。系统可以使用内存缓存来管理沙箱状态，这更简单且延迟更低。
+> - **多个工作进程（`WORKERS>1`）**：需要 Redis 来在工作进程间共享沙箱状态并确保一致性。
+
+Redis 为沙箱状态和状态管理提供缓存。如果只有一个工作进程，您可以使用内存缓存：
+
+| Parameter | Description | Default | Notes |
+| ----------------------- | ---------------- | ------------------------------------------- | ---------------- |
+| `redisServer` | Redis 服务器地址 | localhost | Redis 主机 |
+| `redisPort` | Redis 端口 | 6379 | 标准 Redis 端口 |
+| `redisDb` | Redis 数据库编号 | `0` | 0-15 |
+| `redisUser` | Redis 用户名 | `null` | 用于 Redis6+ ACL |
+| `redisPassword` | Redis 密码 | `null` | 身份验证 |
+| `redisPortKey` | 端口跟踪键 | `_runtime_sandbox_container_occupied_ports` | 内部使用 |
+| `redisContainerPoolKey` | 容器池键 | `_runtime_sandbox_container_container_pool` | 内部使用 |
+
+#### FileSystemConfig 配置
+
+默认使用 `LocalFileSystemConfig`，本地条件下无需配置，使用 `oss` 情况下需配置
+
+##### OSS 配置
+
+使用[阿里云对象存储服务](https://www.aliyun.com/product/oss)进行分布式文件存储：
+
+| Parameter | Description | Default | Notes |
+| -------------------- | ---------------- | ------- | --------------- |
+| `ossEndpoint` | OSS 端点URL | `null` | 区域端点 |
+| `ossAccessKeyId` | OSS 访问密钥 ID | `null` | 来自 OSS 控制台 |
+| `ossAccessKeySecret` | OSS 访问密钥秘钥 | `null` | 保持安全 |
+| `ossBucketName` | OSS 存储桶名称 | `null` | 预创建的存储桶 |
+
+#### ClientConfig 配置
+
+默认使用本地 `Docker` 作为运行时环境，可以选择如下三种自定义配置方式
+
+##### （可选）Docker 设置
+
+要在沙盒服务器中配置特定 Docker 的设置，请在 `containerDeployment` 中传递 `DockerClientConfig` 参数 。可以考虑调整以下参数：
+
+| Parameter | Description | Default | Notes |
+| ----------------- | ---------------------------- | --------- | ---------------------------------- |
+| `portRange` | 沙箱服务可分配的**动态端口范围**（用于暴露容器内服务 | `(49152, 59152)` | 必须是未被占用的高端口范围；避免与系统服务冲突 |
+| `host` | Docker 守护进程（Docker Daemon）的监听地址 | `localhost` | 若 Docker 运行在远程主机或 Docker Desktop，需设为对应 IP 或 socket 路径 |
+| `port` | Docker 守护进程的 TCP 监听端口 | `2375` | ⚠️ 仅当 Docker 配置了 `tcp://0.0.0.0:2375`时使用；生产环境应禁用（不安全） |
+| `certPath` | **TLS 证书目录路径**（用于安全连接 Docker Daemon） | `null` | 若启用了 TLS（端口通常为 `2376`），需提供包含 `ca.pem`, `cert.pem`, `key.pem` 的目录 |
+
+##### （可选）K8s 设置
+
+要在沙盒服务器中配置特定于 Kubernetes 的设置，请在 `containerDeployment` 中传递 `KubernetesClientConfig` 参数。可以考虑调整以下参数：
+
+| Parameter | Description | Default | Notes |
+| ---------------- | ------------------------------------------------------------ | --------- | ------------------------------------------------------------ |
+| `namespace` | 沙箱 Pod、Service 等资源将被创建到的 **Kubernetes 命名空间** | `default` | 建议使用专用命名空间（如 `agentscope-sandbox`），便于隔离和清理 |
+| `kubeConfigPath` | **kubeconfig 文件的本地路径**，用于认证和连接目标 Kubernetes 集群 | `None` | 若未指定，将尝试使用 `~/.kube/config` |
+
+##### （可选）AgentRun设置
+
+AgentRun是阿里云推出的基于Serverless架构的智能Agent开发框架，提供了一套完整的工具集，帮助开发者快速构建、部署和管理AI Agent应用。您可将沙盒服务器部署到AgentRun上。
+
+要在沙盒服务器中配置特定于 [AgentRun](https://functionai.console.aliyun.com/cn-hangzhou/agent/) 的设置，请在 `containerDeployment` 中传递 `AgentRunClientConfig` 参数。可以考虑调整以下参数：
+
+| Parameter | Description | Default | Notes |
+|-------------------------------| ------------------------ |----------------------------------|-------------------------------------------------------------------------------------------|
+| `agentRunAccountId` | 阿里云账号ID | `null` | 阿里云主账号ID，登录阿里云[RAM控制台](https://ram.console.aliyun.com/profile/access-keys)获取阿里云账号ID和AK、SK |
+| `agentRunAccessKeyId` | 访问密钥ID | `null` | 阿里云AccessKey ID，需要`AliyunAgentRunFullAccess`权限 |
+| `agentRunAccessKeySecret` | 访问密钥Secret | `null` | 阿里云AccessKey Secret |
+| `agentRunRegionId` | 部署区域ID | `cn-hangzhou` | Agentrun部署地域ID |
+| `agentRunCpu` | CPU规格 | `2.0f` | vCPU规格 |
+| `agentRunMemory` | 内存规格 | `2048` | 内存规格 (MB) |
+| `agentRunVpcId` | VPC ID | `null` | VPC网络ID（可选） |
+| `agentRunVswitchIds` | 交换机ID列表 | `null` | VSwitch ID列表（可选） |
+| `agentRunSecurityGroupId` | 安全组ID | `null` | 安全组ID（可选） |
+| `agentRunPrefix` | 资源名称前缀 | `agentscope-sandbox_` | 创建的资源名称前缀 |
+| `agentrunLogProject` | SLS日志项目 | `null` | SLS日志项目名称（可选） |
+| `agentrunLogStore` | SLS日志库 | `null` | SLS日志库名称（可选） |
+
+### 导入自定义沙箱
+
+除了默认提供的基础沙箱类型外，您还可以通过编写扩展模块并使用 `--extension` 参数加载，实现自定义沙箱的功能，例如修改镜像、增加环境变量、定义超时时间等。
+
+#### 编写自定义沙箱扩展（例如 `CustomSandbox.java`）
+
+参考[自定义沙箱类](###创建自定义沙箱类)
+
+> - `@RegisterSandbox` 会将该类注册到沙箱管理器中，启动时可被识别和使用。
+> - `environment` 字段可以向沙箱注入外部 API Key 或其他必要配置。
+> - 类继承自 `Sandbox`，可覆盖其方法来实现更多自定义逻辑。
+
+## 自定义构建沙箱
+
+虽然内置沙箱类型涵盖了常见用例，但您可能会遇到需要专门环境或独特工具组合的场景。创建自定义沙箱允许您根据特定需求定制执行环境。本节演示如何构建和注册您的自定义沙箱类型。
+
+### 从源码安装（自定义沙箱必需）
+
+要创建自定义沙箱，您需要使用Python版本 [AgentScope Runtime](https://github.com/agentscope-ai/agentscope-runtime)。以可编辑模式从源码安装 AgentScope Runtime，这允许您修改代码并立即看到更改：
+
+```bash
+git clone https://github.com/agentscope-ai/agentscope-runtime.git
+cd agentscope-runtime
+git submodule update --init --recursive
+pip install -e .
+```
+
+> 创建自定义沙箱时，`-e`（可编辑）标志是必需的，因为它允许您：
+> - 修改沙箱代码并立即看到更改而无需重新安装
+> - 将您的自定义沙箱类添加到注册表中
+> - 迭代开发和测试自定义工具
+
+### 创建自定义沙箱类
+
+您可以定义自定义沙箱类型并将其注册到系统中以满足特殊需求。只需继承 `Sandbox` 并使用 `SandboxRegistry.register`装饰器，然后将文件放在 `src/agentscope_runtime/sandbox/custom` 中（例如，`src/agentscope_runtime/sandbox/custom/custom_sandbox.py`）:
+
+```python
+import os
+
+from typing import Optional
+
+from agentscope_runtime.sandbox.utils import build_image_uri
+from agentscope_runtime.sandbox.registry import SandboxRegistry
+from agentscope_runtime.sandbox.enums import SandboxType
+from agentscope_runtime.sandbox.box.sandbox import Sandbox
+
+SANDBOXTYPE = "my_custom_sandbox"
+
+
+@SandboxRegistry.register(
+ build_image_uri(f"runtime-sandbox-{SANDBOXTYPE}"),
+ sandbox_type=SANDBOXTYPE,
+ security_level="medium",
+ timeout=60,
+ description="my sandbox",
+ environment={
+ "TAVILY_API_KEY": os.getenv("TAVILY_API_KEY", ""),
+ "AMAP_MAPS_API_KEY": os.getenv("AMAP_MAPS_API_KEY", ""),
+ },
+)
+class MyCustomSandbox(Sandbox):
+ def __init__(
+ self,
+ sandbox_id: Optional[str] = None,
+ timeout: int = 3000,
+ base_url: Optional[str] = None,
+ bearer_token: Optional[str] = None,
+ ):
+ super().__init__(
+ sandbox_id,
+ timeout,
+ base_url,
+ bearer_token,
+ SandboxType(SANDBOXTYPE),
+ )
+```
+
+### 准备Docker镜像
+
+创建自定义沙箱还需要准备相应的 Docker镜像。镜像应包含您特定用例所需的所有依赖项、工具和配置。
+
+**注意：构建镜像操作需要在 Python 代码仓库中进行**
+
+> **配置选项：**
+>
+> - **简单 MCP 服务器更改**：要简单更改沙箱中的初始MCP 服务器，请修改 `mcp_server_configs.json` 文件
+> - **高级定制**：对于更高级的用法和定制，您必须非常熟悉Dockerfile 语法和Docker 最佳实践
+
+这里是一个自定义沙箱的Dockerfile 示例，它在一个沙箱中集成了文件系统、浏览器和一些有用的 MCP 工具：
+
+
+```dockerfile
+FROM node:22-slim
+
+# Set ENV variables
+ENV NODE_ENV=production
+ENV WORKSPACE_DIR=/workspace
+
+ARG DEBIAN_FRONTEND=noninteractive
+
+RUN apt-get update && apt-get install -y --fix-missing \
+ curl \
+ python3 \
+ python3-pip \
+ python3-venv \
+ build-essential \
+ libssl-dev \
+ git \
+ supervisor \
+ vim \
+ nginx \
+ gettext-base
+
+WORKDIR /agentscope_runtime
+RUN python3 -m venv venv
+ENV PATH="/agentscope_runtime/venv/bin:$PATH"
+
+# Copy application files
+COPY src/agentscope_runtime/sandbox/box/shared/app.py ./
+COPY src/agentscope_runtime/sandbox/box/shared/routers/ ./routers/
+COPY src/agentscope_runtime/sandbox/box/shared/dependencies/ ./dependencies/
+COPY src/agentscope_runtime/sandbox/box/shared/artifacts/ ./ext_services/artifacts/
+COPY examples/custom_sandbox/box/third_party/markdownify-mcp/ ./mcp_project/markdownify-mcp/
+COPY examples/custom_sandbox/box/third_party/steel-browser/ ./ext_services/steel-browser/
+COPY examples/custom_sandbox/box/ ./
+
+RUN pip install -r requirements.txt
+
+# Install Google Chrome & fonts
+RUN curl -fsSL https://dl.google.com/linux/linux_signing_key.pub | apt-key add - && \
+ echo "deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main" > /etc/apt/sources.list.d/google-chrome.list && \
+ apt-get update && apt-get install -y --fix-missing google-chrome-stable \
+ google-chrome-stable \
+ fonts-wqy-zenhei \
+ fonts-wqy-microhei
+
+# Install steel browser
+WORKDIR /agentscope_runtime/ext_services/steel-browser
+RUN npm ci --omit=dev \
+ && npm install -g webpack webpack-cli \
+ && npm run build -w api \
+ && rm -rf node_modules/.cache
+
+# Install artifacts backend
+WORKDIR /agentscope_runtime/ext_services/artifacts
+RUN npm install \
+ && rm -rf node_modules/.cache
+
+# Install mcp_project/markdownify-mcp
+WORKDIR /agentscope_runtime/mcp_project/markdownify-mcp
+RUN npm install -g pnpm \
+ && pnpm install \
+ && pnpm run build \
+ && rm -rf node_modules/.cache
+
+WORKDIR ${WORKSPACE_DIR}
+RUN mv /agentscope_runtime/config/supervisord.conf /etc/supervisor/conf.d/supervisord.conf
+RUN mv /agentscope_runtime/config/nginx.conf.template /etc/nginx/nginx.conf.template
+RUN git init \
+ && chmod +x /agentscope_runtime/scripts/start.sh
+
+COPY .gitignore ${WORKSPACE_DIR}
+
+# MCP required environment variables
+ENV TAVILY_API_KEY=123
+ENV AMAP_MAPS_API_KEY=123
+
+# Cleanup to reduce image size
+RUN pip cache purge \
+ && apt-get clean \
+ && rm -rf /var/lib/apt/lists/* \
+ && rm -rf /tmp/* \
+ && rm -rf /var/tmp/* \
+ && npm cache clean --force \
+ && rm -rf ~/.npm/_cacache
+
+CMD ["/bin/sh", "-c", "envsubst '$SECRET_TOKEN' < /etc/nginx/nginx.conf.template > /etc/nginx/nginx.conf && /usr/bin/supervisord -c /etc/supervisor/conf.d/supervisord.conf"]
+```
+
+### 构建您的自定义镜像
+
+准备好Dockerfile 和自定义沙箱类后，使用内置构建器工具构建您的自定义沙箱镜像：
+
+```bash
+runtime-sandbox-builder my_custom_sandbox --dockerfile_path examples/custom_sandbox/Dockerfile --extension PATH_TO_YOUR_SANDBOX_MODULE
+```
+
+**命令参数：**
+
+- `custom_sandbox`: 您的自定义沙箱镜像的名称/标签
+- `--dockerfile_path`: 您的自定义Dockerfile 的路径
+- `--extension`: 自定义沙箱模块的路径
+
+构建完成后，您的自定义沙箱镜像将准备好与您定义的相应沙箱类一起使用。
+
+#### 本地构建内置镜像
+
+您也可以使用构建器在本地构建内置沙箱镜像：
+
+```bash
+# 构建所有内置镜像
+runtime-sandbox-builder all
+
+# 构建基础镜像（约1GB）
+runtime-sandbox-builder base
+
+# 构建GUI镜像（约2GB）
+runtime-sandbox-builder gui
+
+# 构建浏览器镜像（约2GB）
+runtime-sandbox-builder browser
+
+# 构建文件系统镜像（约2GB）
+runtime-sandbox-builder filesystem
+
+# 构建移动端镜像（约3GB）
+runtime-sandbox-builder mobile
+```
+
+上述命令在以下情况下很有用：
+
+- 在本地构建镜像而不是从Docker拉取
+- 在构建自己的镜像之前定制基础镜像
+- 确保您拥有内置镜像的最新版本
+- 在网络隔离的环境中工作
+
+### 更改 Sandbox 镜像相关配置
+
+Sandbox 模块运行所用的 Docker 镜像由以下三个环境变量共同决定，你可以根据需要修改其中任意一个，来改变镜像的来源或版本。
+
+| 环境变量 | 作用 | 默认值 | 修改示例 |
+| --------------------------------- | ------------------------------------------------------- | -------------- | ------------------------------------------------------------ |
+| `RUNTIME_SANDBOX_REGISTRY` | 镜像注册中心地址（Registry）。为空表示使用 Docker Hub。 | `""` | `export RUNTIME_SANDBOX_REGISTRY="agentscope-registry.ap-southeast-1.cr.aliyuncs.com"` |
+| `RUNTIME_SANDBOX_IMAGE_NAMESPACE` | 镜像命名空间（Namespace），类似账号名。 | `"agentscope"` | `export RUNTIME_SANDBOX_IMAGE_NAMESPACE="my_namespace"` |
+| `RUNTIME_SANDBOX_IMAGE_TAG` | 镜像版本标签（Tag）。 | `"latest"` | `export RUNTIME_SANDBOX_IMAGE_TAG="my_custom"` |
diff --git a/cookbook/new-zh/sandbox/sandbox.md b/cookbook/new-zh/sandbox/sandbox.md
new file mode 100644
index 00000000..6ddc6e39
--- /dev/null
+++ b/cookbook/new-zh/sandbox/sandbox.md
@@ -0,0 +1,510 @@
+# 沙箱
+
+AgentScope Runtime Java 的 Sandbox 提供了一个**安全**且**隔离**的环境，用于工具执行、浏览器自动化、文件系统操作、训练评测等功能。在本教程中，您将学习如何设置工具沙箱依赖项并在沙箱环境中运行工具。
+
+## 前提条件
+
+```{note}
+当前的沙箱环境默认使用 Docker 进行隔离。此外，我们还支持 Kubernetes (K8s) 以及阿里云函数计算 AgentRun 作为远程服务后端。未来，我们计划在即将发布的版本中加入更多第三方托管解决方案。
+```
+
+
+>对于使用**苹果芯片**（如M1/M2）的设备，我们建议以下选项来运行**x86** Docker环境以获得最大兼容性：
+> * Docker Desktop：请参阅[Docker Desktop安装指南](https://docs.docker.com/desktop/setup/install/mac-install/)以启用Rosetta2，确保与x86_64镜像的兼容性。
+> * Colima：确保启用Rosetta 2支持。您可以使用以下命令启动[Colima](https://github.com/abiosoft/colima)以实现兼容性：`colima start --vm-type=vz --vz-rosetta --memory 8 --cpu 1`
+
+
+- Docker（默认）
+- Kubernetes
+- 阿里云函数计算 AgentRun
+
+## 安装
+
+### 安装依赖项
+
+首先，安装 AgentScope Runtime：
+
+```bash
+pip install agentscope-runtime
+```
+
+### 准备 Docker 镜像
+
+沙箱为不同功能使用不同的 Docker 镜像。您可以只拉取需要的镜像，或者拉取所有镜像以获得完整功能：
+
+#### 选项1：拉取所有镜像（推荐）
+
+为了确保完整的沙箱体验并启用所有功能，请按照以下步骤从我们的仓库拉取并标记必要的 Docker 镜像：
+
+> **镜像来源：阿里云容器镜像服务**
+>
+> 所有Docker镜像都托管在阿里云容器镜像服务(ACR)上，以在全球范围内实现可获取和可靠性。镜像从ACR拉取后使用标准名称重命名，以与AgentScope Runtime无缝集成。
+
+```bash
+# 基础镜像
+docker pull agentscope-registry.ap-southeast-1.cr.aliyuncs.com/agentscope/runtime-sandbox-base:latest && docker tag agentscope-registry.ap-southeast-1.cr.aliyuncs.com/agentscope/runtime-sandbox-base:latest agentscope/runtime-sandbox-base:latest
+
+# GUI镜像
+docker pull agentscope-registry.ap-southeast-1.cr.aliyuncs.com/agentscope/runtime-sandbox-gui:latest && docker tag agentscope-registry.ap-southeast-1.cr.aliyuncs.com/agentscope/runtime-sandbox-gui:latest agentscope/runtime-sandbox-gui:latest
+
+# 文件系统镜像
+docker pull agentscope-registry.ap-southeast-1.cr.aliyuncs.com/agentscope/runtime-sandbox-filesystem:latest && docker tag agentscope-registry.ap-southeast-1.cr.aliyuncs.com/agentscope/runtime-sandbox-filesystem:latest agentscope/runtime-sandbox-filesystem:latest
+
+# 浏览器镜像
+docker pull agentscope-registry.ap-southeast-1.cr.aliyuncs.com/agentscope/runtime-sandbox-browser:latest && docker tag agentscope-registry.ap-southeast-1.cr.aliyuncs.com/agentscope/runtime-sandbox-browser:latest agentscope/runtime-sandbox-browser:latest
+
+# 移动端镜像
+docker pull agentscope-registry.ap-southeast-1.cr.aliyuncs.com/agentscope/runtime-sandbox-mobile:latest && docker tag agentscope-registry.ap-southeast-1.cr.aliyuncs.com/agentscope/runtime-sandbox-mobile:latest agentscope/runtime-sandbox-mobile:latest
+```
+
+#### 选项2：拉取特定镜像
+
+根据您的具体需求选择镜像：
+
+| Image | Purpose | When to Use |
+| -------------------- | ------------------------- | ------------------------------------------------------------ |
+| **Base Image** | Python代码执行，shell命令 | 基本工具执行必需 |
+| **GUI Image** | 计算机操作 | 当你需要图形操作页面时 |
+| **Filesystem Image** | 文件系统操作 | 当您需要文件读取/写入/管理时 |
+| **Browser Image** | Web浏览器自动化 | 当您需要网络爬取或浏览器控制时 |
+| **Mobile Image** | 移动端操作 | 当您需要操作移动端设备时 |
+| **Training Image** | 训练和评估智能体 | 当你需要在某些基准数据集上训练和评估智能体时 （详情请参考 [训练用沙箱](training_sandbox.md) ） |
+
+### （可选）从头构建Docker镜像
+
+如果您更倾向于在本地自己通过 `Dockerfile` 构建镜像或需要自定义修改，可以从头构建它们。请参阅 [工具沙箱高级用法](sandbox/advanced.md) 了解详细说明。
+
+## 沙箱使用
+
+### 创建沙箱
+
+前面的部分介绍了以工具为中心的使用方法，而本节介绍以沙箱为中心的使用方法。
+
+您可以通过`sandbox` SDK创建不同类型的沙箱。通过 `SandboxService` 管理沙箱生命周期，支持会话管理和沙箱复用。
+
+
+```java
+import io.agentscope.runtime.engine.services.sandbox.SandboxService;
+import io.agentscope.runtime.sandbox.box.BaseSandbox;
+import io.agentscope.runtime.sandbox.box.Sandbox;
+import io.agentscope.runtime.sandbox.manager.SandboxManager;
+import io.agentscope.runtime.sandbox.manager.client.config.BaseClientConfig;
+import io.agentscope.runtime.sandbox.manager.client.config.DockerClientConfig;
+import io.agentscope.runtime.sandbox.manager.model.ManagerConfig;
+
+import com.google.gson.Gson;
+
+public class Main {
+ public static void main(String[] args) {
+// 创建并启动沙箱服务
+ BaseClientConfig clientConfig = DockerClientConfig.builder().build();
+ ManagerConfig managerConfig = ManagerConfig.builder()
+ .containerDeployment(clientConfig)
+ .build();
+ SandboxService sandboxService = new SandboxService(
+ new SandboxManager(managerConfig)
+ );
+ sandboxService.start();
+
+// 连接沙箱（沙箱会在执行后自动删除）
+ try (Sandbox sandbox = sandboxService.connect("sessionId", "userId", BaseSandbox.class)){
+ Gson gson = new Gson();
+ String tools = gson.toJson(sandbox.listTools(""));
+ System.out.println("Available tools: ");
+ System.out.println(tools);
+ }
+ catch (Exception e) {
+ e.printStackTrace();
+ }
+ }
+}
+```
+
+返回的结果如下所示：
+```json
+{
+ "generic": {
+ "run_ipython_cell": {
+ "json_schema": {
+ "function": {
+ "name": "run_ipython_cell",
+ "description": "Run an IPython cell.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "code": {
+ "description": "IPython code to execute",
+ "type": "string"
+ }
+ },
+ "required": [
+ "code"
+ ]
+ }
+ },
+ "type": "function"
+ },
+ "name": "run_ipython_cell"
+ },
+ "run_shell_command": {
+ "json_schema": {
+ "function": {
+ "name": "run_shell_command",
+ "description": "Run a shell command.",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "command": {
+ "description": "Shell command to execute",
+ "type": "string"
+ }
+ },
+ "required": [
+ "command"
+ ]
+ }
+ },
+ "type": "function"
+ },
+ "name": "run_shell_command"
+ }
+ }
+}
+```
+
+可以看到基础沙箱中提供了**运行命令**和**执行python代码**两种工具
+
+
+* **基础沙箱（Base Sandbox）**：用于在隔离环境中运行 **Python 代码** 或 **Shell 命令**。
+
+```java
+try (Sandbox sandbox = sandboxService.connect("sessionId", "userId", BaseSandbox.class)){
+ System.out.println(sandbox.listTools(""));
+ if(sandbox instanceof BaseSandbox baseSandbox) {
+ String pythonResult = baseSandbox.runIpythonCell("print('Hello from the sandbox!')");
+ System.out.println("Sandbox execution result: " + pythonResult);
+ String shellResult = baseSandbox.runShellCommand("echo Hello, World!");
+ System.out.println("Shell command result: " + shellResult);
+ }
+}
+```
+
+* **GUI 沙箱 （GUI Sandbox）**： 提供**可视化桌面环境**，可执行鼠标、键盘以及屏幕相关操作。
+
+ 
+
+```json
+try (Sandbox sandbox = sandboxService.connect("sessionId", "userId", GuiSandbox.class)){
+ Gson gson = new Gson();
+ String tools = gson.toJson(sandbox.listTools(""));
+ System.out.println("Available tools: ");
+ System.out.println(tools);
+
+ if(sandbox instanceof GuiSandbox guiSandbox) {
+ String desktopUrl = guiSandbox.getDesktopUrl();
+ System.out.println("GUI Desktop URL: " + desktopUrl);
+ String cursorPosition = guiSandbox.computerUse("get_cursor_position");
+ System.out.println("Cursor Position: " + cursorPosition);
+ String screenShot = guiSandbox.computerUse("get_screenshot");
+ System.out.println("Screenshot (base64): " + screenShot);
+ }
+}
+```
+
+* **文件系统沙箱 （Filesystem Sandbox）**：基于 GUI 的隔离沙箱，可进行文件系统操作，如创建、读取和删除文件。
+
+ 
+
+```java
+try (Sandbox sandbox = sandboxService.connect("sessionId", "userId", FilesystemSandbox.class)){
+ Gson gson = new Gson();
+ String tools = gson.toJson(sandbox.listTools(""));
+ System.out.println("Available tools: ");
+ System.out.println(tools);
+
+ if(sandbox instanceof FilesystemSandbox filesystemSandbox) {
+ String desktopUrl = filesystemSandbox.getDesktopUrl();
+ System.out.println("GUI Desktop URL: " + desktopUrl);
+ String cursorPosition = filesystemSandbox.createDirectory("test");
+ System.out.println("Created directory 'test' at: " + cursorPosition);
+ }
+}
+```
+
+* **浏览器沙箱（Browser Sandbox）**: 基于 GUI 的沙箱，可进行浏览器操作。
+
+ 
+
+```java
+try (Sandbox sandbox = sandboxService.connect("sessionId", "userId", BrowserSandbox.class)){
+ Gson gson = new Gson();
+ String tools = gson.toJson(sandbox.listTools(""));
+ System.out.println("Available tools: ");
+ System.out.println(tools);
+
+ if(sandbox instanceof BrowserSandbox browserSandbox) {
+ String desktopUrl = browserSandbox.getDesktopUrl();
+ System.out.println("GUI Desktop URL: " + desktopUrl);
+ String navigateResult = browserSandbox.navigate("https://cn.bing.com");
+ System.out.println("Navigate Result: " + navigateResult);
+ }
+}
+```
+
+* **TrainingSandbox**：训练评估沙箱，详情请参考：[训练用沙箱](training_sandbox.md)。
+
+```java
+try (Sandbox sandbox = sandboxService.connect("sessionId", "userId", APPWorldSandbox.class)){
+ if(sandbox instanceof APPWorldSandbox appWorldSandbox){
+ String profileList = appWorldSandbox.getEnvProfile("appworld","train",null);
+ System.out.println("Profile List: " + profileList);
+ } else {
+ System.err.println("Failed to connect to TrainingSandbox.");
+ }
+}
+```
+
+> 更多沙箱类型正在开发中，敬请期待！
+
+### 向沙箱添加MCP服务器
+
+MCP（模型上下文协议）是一个标准化协议，使AI应用程序能够安全地连接到外部数据源和工具。通过将MCP服务器集成到您的沙箱中，您可以在不影响安全性的情况下使用专门的工具和服务扩展沙箱的功能。
+
+沙箱支持通过`add_mcp_servers`方法集成MCP服务器。添加后，您可以使用`list_tools`发现可用工具并使用`call_tool`执行它们。
+
+```java
+try {
+ String mcpServerConfig = """
+ {
+ "mcpServers": {
+ "time": {
+ "command": "uvx",
+ "args": [
+ "mcp-server-time",
+ "--local-timezone=America/New_York"
+ ]
+ }
+ }
+ }
+ """;
+ List mcpTools = ToolkitInit.getMcpTools(
+ mcpServerConfig,
+ SandboxType.BASE,
+ sandboxService.getManagerApi());
+
+ System.out.println("MCP Tools: " + mcpTools);
+}
+```
+
+### 连接到远程沙箱
+
+> 沙箱远程部署特别适用于：
+> * 将计算密集型任务分离到专用服务器
+> * 多个客户端共享同一沙箱环境
+> * 在资源受限的本地机器上开发，同时在高性能服务器上执行
+> * K8s 集群部署沙盒服务
+>
+> 有关sandbox-server的更高级用法，请参阅[工具沙箱高级用法](sandbox_advanced.md)了解详细说明。
+
+您可以在本地机器或不同机器上启动沙箱服务器，以便于远程访问。您可以先启动一个runtime，作为远程沙箱管理器
+
+要连接到远程沙箱服务，只需要在构建managerConfig的时候添加远程runtime的实际启动地址，其余操作和本地沙箱相同，在进行沙箱管理和工具调用的时候会自动将操作转发到远程runtime处理：
+
+```java
+ManagerConfig managerConfig = ManagerConfig.builder()
+ .baseUrl("http://remote-host:port")
+ .build();
+```
+
+## 沙箱服务
+
+### 使用沙箱服务管理沙箱
+
+`SandboxService` 提供了统一的沙箱管理接口，支持通过 `session_id` 和 `user_id` 来管理不同用户会话的沙箱环境。使用 `SandboxService` 可以让您更好地控制沙箱的生命周期，并实现沙箱的复用。
+
+```java
+import io.agentscope.runtime.engine.services.sandbox.SandboxService;
+import io.agentscope.runtime.sandbox.box.BaseSandbox;
+import io.agentscope.runtime.sandbox.box.Sandbox;
+import io.agentscope.runtime.sandbox.manager.SandboxManager;
+import io.agentscope.runtime.sandbox.manager.client.config.BaseClientConfig;
+import io.agentscope.runtime.sandbox.manager.client.config.DockerClientConfig;
+import io.agentscope.runtime.sandbox.manager.model.ManagerConfig;
+
+public class Main {
+ public static void main(String[] args) {
+// 创建并启动沙箱服务
+ BaseClientConfig clientConfig = DockerClientConfig.builder().build();
+ ManagerConfig managerConfig = ManagerConfig.builder()
+ .containerDeployment(clientConfig)
+ .build();
+ SandboxService sandboxService = new SandboxService(
+ new SandboxManager(managerConfig)
+ );
+ sandboxService.start();
+
+ try {
+// 连接到沙箱，指定需要的沙箱类型
+ Sandbox sandbox = sandboxService.connect("sessionId", "userId", BaseSandbox.class);
+ if(sandbox instanceof BaseSandbox baseSandbox) {
+// 直接在沙箱实例上调用工具方法
+ String pythonResult = baseSandbox.runIpythonCell("a=1");
+ System.out.println("Sandbox execution result: " + pythonResult);
+ }
+// 使用相同的 session_id 和 user_id 会复用同一个沙箱实例
+ sandbox = sandboxService.connect("sessionId", "userId", BaseSandbox.class);
+ if(sandbox instanceof BaseSandbox baseSandbox) {
+// 变量 a 仍然存在，因为复用了同一个沙箱
+ String pythonResult = baseSandbox.runIpythonCell("print(a)");
+ System.out.println("Sandbox execution result: " + pythonResult);
+ }
+// 停止沙箱服务
+ sandbox.close();
+ }
+ catch (Exception e) {
+ e.printStackTrace();
+ }
+ }
+}
+```
+
+### 使用沙箱服务添加MCP服务器
+
+```{code-cell}
+from agentscope_runtime.engine.services.sandbox import SandboxService
+
+async def main():
+ sandbox_service = SandboxService()
+ await sandbox_service.start()
+
+ session_id = "session_mcp"
+ user_id = "user_mcp"
+
+ sandboxes = sandbox_service.connect(
+ session_id=session_id,
+ user_id=user_id,
+ sandbox_types=["base"],
+ )
+
+ sandbox = sandboxes[0]
+
+ mcp_server_configs = {
+ "mcpServers": {
+ "time": {
+ "command": "uvx",
+ "args": [
+ "mcp-server-time",
+ "--local-timezone=America/New_York",
+ ],
+ },
+ },
+ }
+
+ # 将MCP服务器添加到沙箱
+ sandbox.add_mcp_servers(server_configs=mcp_server_configs)
+
+ # 列出所有可用工具（现在包括MCP工具）
+ print(sandbox.list_tools())
+
+ # 使用MCP服务器提供的时间工具
+ print(
+ sandbox.call_tool(
+ "get_current_time",
+ arguments={
+ "timezone": "America/New_York",
+ },
+ ),
+ )
+
+ await sandbox_service.stop()
+
+await main()
+```
+
+### 使用沙箱服务连接远程沙箱
+
+```java
+import io.agentscope.runtime.engine.services.sandbox.SandboxService;
+import io.agentscope.runtime.sandbox.box.BaseSandbox;
+import io.agentscope.runtime.sandbox.box.Sandbox;
+import io.agentscope.runtime.sandbox.manager.SandboxManager;
+import io.agentscope.runtime.sandbox.manager.client.config.BaseClientConfig;
+import io.agentscope.runtime.sandbox.manager.client.config.DockerClientConfig;
+import io.agentscope.runtime.sandbox.manager.model.ManagerConfig;
+
+public class Main {
+ public static void main(String[] args) {
+// 创建并启动沙箱服务
+ ManagerConfig managerConfig = ManagerConfig.builder()
+ .baseUrl("http://remote-host:port")
+ .build();
+ SandboxService sandboxService = new SandboxService(
+ new SandboxManager(managerConfig)
+ );
+ sandboxService.start();
+
+ try {
+// 连接到沙箱，指定需要的沙箱类型
+ Sandbox sandbox = sandboxService.connect("sessionId", "userId", BaseSandbox.class);
+ if(sandbox instanceof BaseSandbox baseSandbox) {
+// 直接在沙箱实例上调用工具方法
+ String pythonResult = baseSandbox.runIpythonCell("a=1");
+ System.out.println("Sandbox execution result: " + pythonResult);
+ }
+// 停止沙箱服务
+ sandbox.close();
+ }
+ catch (Exception e) {
+ e.printStackTrace();
+ }
+ }
+}
+```
+
+## 工具列表
+
+* 基础工具（在所有沙箱类型中可用）
+* 计算机操作工具（在`GuiSandbox`中可用）
+* 文件系统工具（在`FilesystemSandbox`中可用）
+* 浏览器工具（在`BrowserSandbox`中可用）
+
+
+| 分类 | 工具名称 | 描述 |
+| -------------------------------------- | ------------------------------------------- | ------------------------------------------------------------ |
+| **基础工具** | `runIpythonCell(code: String)` | 在IPython环境中执行Python代码 |
+| | `runShellCommand(command: String)` | 在沙箱中执行shell命令 |
+| **文件系统工具** | `readFile(path: String)` | 读取文件的完整内容 |
+| | `readMultipleFiles(paths: List)` | 同时读取多个文件 |
+| | `writeFile(path: String, content: String)` | 创建或覆盖文件内容 |
+| | `editFile(path: String, edits: Object[], dryRun: boolean)` | 对文本文件进行基于行的编辑 |
+| | `createDirectory(path: String)` | 创建新目录 |
+| | `listDirectory(path: String)` | 列出路径中的所有文件和目录 |
+| | `directoryTree(path: String)` | 获取目录结构的递归树视图 |
+| | `moveFile(source: String, destination: String)` | 移动或重命名文件和目录 |
+| | `searchFiles(path: String, pattern: String, excludePatterns: String[])` | 搜索匹配模式的文件 |
+| | `getFileInfo(path: String)` | 获取文件或目录的详细元数据 |
+| | `listAllowedDirectories()` | 列出服务器可以访问的目录 |
+| **浏览器工具** | `navigate(url: String)` | 导航到特定URL |
+| | `navigateBack()` | 返回到上一页 |
+| | `navigateForward()` | 前进到下一页 |
+| | `closeBrowser()` | 关闭当前浏览器页面 |
+| | `resize(width: Double, height: Double)` | 调整浏览器窗口大小 |
+| | `click(element: String, ref: String)` | 点击Web元素 |
+| | `type(element: String, ref: String, text: String)` | 在输入框中输入文本 |
+| | `hover(element: String, ref: String)` | 悬停在Web元素上 |
+| | `drag(startElement: String, startRef: String, endElement: String, endRef: String)` | 在元素之间拖拽 |
+| | `selectOption(element: String, ref: String, values: String[])` | 在下拉菜单中选择选项 |
+| | `pressKey(key: String)` | 按键盘按键 |
+| | `fileUpload(paths: String[])` | 上传文件到页面 |
+| | `snapshot()` | 捕获当前页面的可访问性快照 |
+| | `takeScreenshot(raw: Boolean, filename: String, element: String, ref: String)` | 截取页面或元素的屏幕快照 |
+| | `pdfSave(filename: String)` | 将当前页面保存为PDF |
+| | `tabList()` | 列出所有打开的浏览器标签页 |
+| | `tabNew(url: String)` | 打开新标签页 |
+| | `tabSelect(index: Integer)` | 切换到特定标签页 |
+| | `tabClose(index: Integer)` | 关闭标签页（如果未指定索引则关闭当前标签页） |
+| | `waitFor(time: Double, text: String, textGone: String)` | 等待条件或时间流逝 |
+| | `consoleMessages()` | 获取页面的所有控制台消息 |
+| | `networkRequests()` | 获取页面加载以来的所有网络请求 |
+| | `handleDialog(accept: Boolean, promptText: String)` | 处理浏览器对话框（警告、确认、提示） |
+| **计算机操作工具** | `computerUse(action: String, coordinate: List, text: String)` | 使用鼠标和键盘与桌面 GUI 互动，支持以下操作：移动光标、点击、输入文字以及截图 |
diff --git a/cookbook/new-zh/sandbox/training_sandbox.md b/cookbook/new-zh/sandbox/training_sandbox.md
new file mode 100644
index 00000000..38024dae
--- /dev/null
+++ b/cookbook/new-zh/sandbox/training_sandbox.md
@@ -0,0 +1,271 @@
+# 训练用沙箱
+
+> 本节介绍训练沙箱的用法，我们强烈建议在继续之前先完成上一节的基础教程（[沙箱](sandbox.md)） 中的 Docker 安装和注意事项。
+
+## 背景介绍
+
+AgentScope Runtime Java 的 Training Sandbox 主要用于训练评测的功能。训练沙箱的数据主要基于公开数据集（如 Appworld、 Webshop、 BFCL 等），提供用于 Agent 训练的数据供给、 Agent 使用数据集内供给的工具调用、实时的 Reward 验证。
+
+训练用沙箱内主要通过 Ray 实现高并发的数据调用，在创建沙箱后，支持外部 Agent 高并发对不同样本的实例创建、执行、评测。
+
++ [APPWorld](https://github.com/StonyBrookNLP/appworld)：APPWorld 是一个高效的测试环境，用于测试和评估 AI Agent 在执行复杂多步骤任务的能力。
++ [BFCL](https://github.com/ShishirPatil/gorilla)：BFCL 是首个专门评估大语言模型（LLMs）函数调用能力的全面且可执行的评测平台。与以往的评测不同，BFCL涵盖了多种形式的函数调用、丰富的场景，并关注函数调用的可执行性。
+
+## 安装
+
+### Appworld 案例
+#### 拉取所需的镜像
+
+请按照以下步骤从我们的仓库拉取并标记必要的训练用沙盒Docker镜像：
+
+> **镜像来源：阿里云容器镜像服务**
+>
+> 所有 Docker 镜像都托管在阿里云容器镜像服务(ACR)上，以在全球范围内实现可获取和可靠性。镜像从ACR拉取后使用标准名称重命名，以与 AgentScope Runtime Java 无缝集成。
+
+```bash
+# 从 DockerHub 拉取 Appworld 镜像
+docker pull agentscope/runtime-sandbox-appworld:latest
+
+# 从 ACR 拉取 Appworld 镜像并打标签
+docker pull agentscope-registry.ap-southeast-1.cr.aliyuncs.com/agentscope/runtime-sandbox-appworld:latest && docker tag agentscope-registry.ap-southeast-1.cr.aliyuncs.com/agentscope/runtime-sandbox-appworld:latest agentscope/runtime-sandbox-appworld:latest
+```
+
+#### 验证安装
+
+您可以通过调用`getEnvProfile`来验证一切设置是否正确，如果正确将返回数据集ID：
+
+```python
+import io.agentscope.runtime.engine.services.sandbox.SandboxService;
+import io.agentscope.runtime.sandbox.box.BaseSandbox;
+import io.agentscope.runtime.sandbox.box.Sandbox;
+import io.agentscope.runtime.sandbox.manager.SandboxManager;
+import io.agentscope.runtime.sandbox.manager.client.config.BaseClientConfig;
+import io.agentscope.runtime.sandbox.manager.client.config.DockerClientConfig;
+import io.agentscope.runtime.sandbox.manager.model.ManagerConfig;
+
+import com.google.gson.Gson;
+
+public class Main {
+ public static void main(String[] args) {
+// 创建并启动沙箱服务
+ BaseClientConfig clientConfig = DockerClientConfig.builder().build();
+ ManagerConfig managerConfig = ManagerConfig.builder()
+ .containerDeployment(clientConfig)
+ .build();
+ SandboxService sandboxService = new SandboxService(
+ new SandboxManager(managerConfig)
+ );
+ sandboxService.start();
+
+// 连接沙箱（沙箱会在执行后自动删除）
+ try (Sandbox sandbox = sandboxService.connect("sessionId", "userId", APPWorldSandbox.class)){
+ if(sandbox instanceof APPWorldSandbox appWorldSandbox){
+ String profileList = appWorldSandbox.getEnvProfile("appworld","train", null);
+ System.out.println("Profile List: " + profileList);
+ } else {
+ System.err.println("Failed to connect to TrainingSandbox.");
+ }
+ }
+ catch (Exception e) {
+ e.printStackTrace();
+ }
+ }
+}
+```
+
+#### （可选）从头构建Docker镜像
+
+如果您更倾向于在本地自己通过`Dockerfile`构建镜像或需要自定义修改，可以从头构建它们。请参阅[工具沙箱高级用法](advanced.md)了解详细说明。
+
+对于训练用沙箱，不同数据集使用不同的DockerFile，其路径在 Python 版本 [AgentScope Runtime](https://github.com/agentscope-ai/agentscope-runtime) 仓库`src/agentscope_runtime/sandbox/box/training_box/environments/{dataset_name}` 目录下
+
+以appworld为例：
+
+```bash
+docker build -f src/agentscope_runtime/sandbox/box/training_box/environments/appworld/Dockerfile -t agentscope/runtime-sandbox-appworld:latest .
+```
+
+#### 训练样本使用
+
+您可以创建某一个具体的训练用沙箱（默认为 `Appworld` ），随后可以并行创建多个不同的训练样本，并且分别执行、评测。
+
+#### 查看数据集样本
+
+构建 Docker 镜像后，我们可以首先查看数据集样本。
+
+例如，我们可以使用 `getEnvProfile` 方法获取训练ID列表。
+
+```java
+try (Sandbox sandbox = sandboxService.connect("sessionId", "userId", APPWorldSandbox.class)){
+ if(sandbox instanceof APPWorldSandbox appWorldSandbox){
+ String profileList = appWorldSandbox.getEnvProfile("appworld","train", null);
+ System.out.println("Profile List: " + profileList);
+ } else {
+ System.err.println("Failed to connect to TrainingSandbox.");
+ }
+}
+```
+
+#### 创建训练样本
+
+以取训练集中的第1个query为例，可以通过`createInstance`创建1个训练实例（Instance)，并分配了一个实例ID（Instance ID）。
+一个Query可以创建多个实例，一个实例唯一对应一个训练样本（基于您创建时，指定的样本ID）
+其中，训练集提供的prompt (`system prompt`) 和 实际问题 (`user prompt`) 均会以`Message List`返回，具体位置于返回值的`state`
+中
+
+```java
+try (Sandbox sandbox = sandboxService.connect("sessionId", "userId", APPWorldSandbox.class)){
+ if(sandbox instanceof APPWorldSandbox appWorldSandbox){
+ String profileList = appWorldSandbox.getEnvProfile("appworld","train", null);
+ System.out.println("Profile List: " + profileList);
+
+ Gson gson = new Gson();
+ Type listType = new TypeToken>(){}.getType();
+ List list = gson.fromJson(profileList, listType);
+ String initResponse = appWorldSandbox.createInstance("appworld", list.get(0));
+ Type instanceType = new TypeToken>(){}.getType();
+ Map instance = gson.fromJson(initResponse, instanceType);
+ String instanceInfo = instance.get("info").toString();
+ Type infoType = new TypeToken>(){}.getType();
+ Map infoMap = gson.fromJson(instanceInfo, infoType);
+ String instanceId = (String) infoMap.get("instance_id");
+ String query = instance.get("state").toString();
+ System.out.println("Created instance " + instanceId + " with query: " + query);
+ } else {
+ System.err.println("Failed to connect to TrainingSandbox.");
+ }
+}
+```
+
+#### 使用训练样本
+
+使用`step`方法，并指定具体的`instanceId`和`action`，可以得到环境内反馈结果。
+该方法目前仅支持输入Message格式，建议以` "role": "assistant"` 方式输入。
+
+```java
+Map action = Map.of(
+ "role", "assistant",
+ "content", "```python\\nprint('hello appworld!!')\\n```"
+);
+String result = appWorldSandbox.step(instanceId, action, null);
+System.out.println("Step Result: " + result);
+```
+
+#### 评测训练样本
+
+使用`evaluate`方法，并评测某个实例的状态，并获取`Reward`。不同的数据集可能含有额外的测评参数，通过`params`传入。
+
+```python
+String score = appWorldSandbox.evaluate(instanceId, Map.of(), Map.of("sparse", true));
+System.out.println("Evaluation Score: " + score);
+```
+
+#### 释放训练样本
+
+为了减少内存开销，建议在使用完样本后使用`releaseInstance`方法。
+同时，在训练用沙箱运行期间，每5分钟亦会定期清除非活跃实例。
+
+```java
+String success = appWorldSandbox.releaseInstance(instanceId);
+System.out.println("Instance released: " + success);
+```
+
+### BFCL案例
+
+#### 拉取所需的镜像
+请按照以下步骤从我们的仓库拉取并标记必要的训练用沙盒Docker镜像：
+
+> **镜像来源：阿里云容器镜像服务**
+>
+> 所有 Docker 镜像都托管在阿里云容器镜像服务(ACR)上，以在全球范围内实现可获取和可靠性。镜像从 ACR 拉取后使用标准名称重命名，以与 AgentScope Runtime Java 无缝集成。
+
+```bash
+# 从 DockerHub 拉取 BFCL 镜像
+docker pull agentscope/runtime-sandbox-bfcl:latest
+
+# 从 ACR 拉取 BFCL 镜像并打标签
+docker pull agentscope-registry.ap-southeast-1.cr.aliyuncs.com/agentscope/runtime-sandbox-bfcl:latest && docker tag agentscope-registry.ap-southeast-1.cr.aliyuncs.com/agentscope/runtime-sandbox-bfcl:latest agentscope/runtime-sandbox-bfcl:latest
+```
+
+
+ (可选) 建立自己的Docker镜像
+ 在 AgentScope Runtime Python 根目录运行以下代码：
+
+
+
+```bash
+docker build -f src/agentscope_runtime/sandbox/box/training_box/environments/bfcl/Dockerfile -t agentscope/runtime-sandbox-bfcl:latest .
+```
+
+
+
+#### 初始化
+BFCL 有多个子数据库 *all, all_scoring, multi_turn, single_turn, live, non_live, non_python, python*.在初始化沙盒前请选择一个数据库，然后填上自己的openai_api_key。
+
+**注意：这里需要设置 OPENAI_API_KEY 以及 DATASET_SUB_TYPE 环境变量，二者默认分别为 "" 和 "multi_turn"**
+
+
+```java
+try (Sandbox sandbox = sandboxService.connect("sessionId", "userId", BFCLSandbox.class)){
+ if(sandbox instanceof BFCLSandbox bfclSandbox){
+ String profileList = bfclSandbox.getEnvProfile("bfcl");
+ System.out.println("Connected to BFCLSandbox. Profile List: " + profileList);
+
+ Gson gson = new Gson();
+ Type listType = new TypeToken>(){}.getType();
+ List list = gson.fromJson(profileList, listType);
+ String initResponse = bfclSandbox.createInstance("bfcl", list.get(0));
+ Type instanceType = new TypeToken>(){}.getType();
+ Map instance = gson.fromJson(initResponse, instanceType);
+ String instanceInfo = instance.get("info").toString();
+ Type infoType = new TypeToken>(){}.getType();
+ Map infoMap = gson.fromJson(instanceInfo, infoType);
+ String instanceId = (String) infoMap.get("instance_id");
+ String query = instance.get("state").toString();
+ System.out.println("Created instance " + instanceId + " with query: " + query);
+ } else {
+ System.err.println("Failed to connect to TrainingSandbox.");
+ }
+}
+```
+
+#### 使用训练样本
+参考以下模拟的对话：
+模拟对话
+
+```java
+List> assistantMessages = List.of(
+ Map.of("role", "assistant", "content", "'\\n{\"name\": \"cd\", \"arguments\": {\"folder\": \"document\"}}\\n\\n\\n{\"name\": \"mkdir\", \"arguments\": {\"dir_name\": \"temp\"}}\\n\\n\\n{\"name\": \"mv\", \"arguments\": {\"source\": \"final_report.pdf\", \"destination\": \"temp\"}}\\n'"),
+ Map.of("role", "assistant", "content", "'ok.1'"),
+ Map.of("role", "assistant", "content", "'\\n{\"name\": \"cd\", \"arguments\": {\"folder\": \"temp\"}}\\n\\n\\n{\"name\": \"grep\", \"arguments\": {\"file_name\": \"final_report.pdf\", \"pattern\": \"budget analysis\"}}\\n'"),
+ Map.of("role", "assistant", "content", "'ok.2'"),
+ Map.of("role", "assistant", "content", "'\\n{\"name\": \"sort\", \"arguments\": {\"file_name\": \"final_report.pdf\"}}\\n'"),
+ Map.of("role", "assistant", "content", "'ok.2'"),
+ Map.of("role", "assistant", "content", "'\\n{\"name\": \"cd\", \"arguments\": {\"folder\": \"..\"}}\\n\\n\\n{\"name\": \"mv\", \"arguments\": {\"source\": \"previous_report.pdf\", \"destination\": \"temp\"}}\\n\\n\\n{\"name\": \"cd\", \"arguments\": {\"folder\": \"temp\"}}\\n\\n\\n{\"name\": \"diff\", \"arguments\": {\"file_name1\": \"final_report.pdf\", \"file_name2\": \"previous_report.pdf\"}}\\n'"),
+ Map.of("role", "assistant", "content", "'ok.2'")
+);
+```
+
+