agentscope-ai · chickenlj · Dec 15, 2025 · Dec 11, 2025 · Dec 11, 2025 · Dec 11, 2025
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,103 @@
+# How to Contribute
+
+Thanks for your interest in the AgentScope Runtime Java project.
+
+AgentScope Runtime is an open-source project focused on agent deployment and secure tool execution with a friendly community of developers eager to help new contributors. We welcome contributions of all types, from code improvements to documentation.
+
+## Community
+
+A good first step to getting involved in the AgentScope Runtime Java project is to participate in our discussions and join us in our different communication channels. Here are several ways to connect with us:
+
+- **GitHub Discussions**: Ask questions and share experiences (use **English**)
+- **Discord**: Join our [Discord channel](https://discord.gg/eYMpfnkG8h) for real-time discussions
+- **DingTalk**: Chinese users can join our [DingTalk Group](https://qr.dingtalk.com/action/joingroup?code=v1,k1,OmDlBXpjW+I2vWjKDsjvI9dhcXjGZi3bQiojOq3dlDw=&_dt_no_comment=1&origin=11)
+
+
+## Reporting Issues
+
+### Bugs
+
+If you find a bug in AgentScope Runtime Java, first test against the latest version to ensure your issue hasn't already been fixed. If not, search our issues list on GitHub to see if a similar issue has already been opened.
+
+If you confirm that the bug hasn't already been reported, file a bug issue before writing any code. When submitting an issue, please include:
+
+- Clear problem description
+- Steps to reproduce
+- Code/error messages
+- Environment details (OS, Python version)
+- Affected components (Engine, Sandbox, or both)
+
+### Security Issues
+
+If you discover a security issue in AgentScope Runtime, please report it to us through the [Alibaba Security Response Center (ASRC)](https://security.alibaba.com/).
+
+## Requesting Features
+
+If you find yourself wishing for a feature that doesn't exist in AgentScope Runtime, please open a feature request issue on GitHub to describe:
+
+- The feature and its purpose
+- How it should work
+- Security considerations (if applicable)
+
+## Contributing Code
+
+If you would like to contribute a new feature or a bug fix to AgentScope Runtime Java, please first discuss your idea on a GitHub issue. If there isn't an issue for it, create one. There may be someone already working on it, or it may have particular complexities (especially security considerations for sandbox features) that you should be aware of before starting to code.
+
+### Fork and Create a Branch
+
+Fork the main AgentScope Runtime Java code and clone it to your local machine. See the GitHub help page for help.
+
+```shell
+git clone https://github.com/agentscope-ai/agentscope-runtime-java.git
+```
+
+Create a branch with a descriptive name.
+
+```bash
+git checkout -b feature/your-feature-name
+```
+
+### Make Your Changes
+
+- Write clear, well-commented code
+- Follow existing code style
+- Add tests for new features/fixes
+- Update documentation as needed
+
+### Test Your Changes
+
+Run the test suite to ensure your changes don't break existing functionality:
+
+```bash
+mvn clean test
+```
+
+### Submit Your Changes
+
+0. Format code before submitting:
+
+```shell
+mvn spotless:apply
+```
+
+1. Commit your changes with a clear message:
+
+```bash
+git commit -m "Add: brief description of your changes"
+```
+
+2. Push to your fork:
+
+```bash
+git push origin feature/your-feature-name
+```
+
+3. Create a Pull Request (PR) from your branch to the main repository with a **clear description**
+
+### Code Review Process
+
+- All PRs require review from maintainers
+- Address any feedback or requested changes
+- Once approved, your PR will be merged
+
+Thank you for contributing to AgentScope Runtime!
diff --git a/README.md b/README.md
@@ -8,7 +8,9 @@
 [![Maven Central](https://maven-badges.herokuapp.com/maven-central/io.agentscope/agentscope-runtime/badge.svg)](https://maven-badges.herokuapp.com/maven-central/io.agentscope/agentscope-runtime)
 [![DingTalk](https://img.shields.io/badge/DingTalk-Join_Us-orange.svg)](https://qr.dingtalk.com/action/joingroup?code=v1,k1,OmDlBXpjW+I2vWjKDsjvI9dhcXjGZi3bQiojOq3dlDw=&_dt_no_comment=1&origin=11)
 
-[Cookbook](./cookbook/zh)
+[[Cookbook]](./cookbook/zh)
+[[中文README]](./README_zh.md)
+[[Examples]](./examples)
 
 **AgentScope Runtime Java**
 
@@ -25,7 +27,7 @@ This is the Java implementation of [AgentScope Runtime](https://github.com/agent
 - **Sandboxed Tool Execution**: Isolated sandboxes ensure safe tool execution without system compromise
 - **Developer Friendly**: Simple deployment with powerful customization options
 - **Framework Agnostic**: Not tied to any specific framework. Works seamlessly with popular open-source agent frameworks and custom implementations
-- 🚧 **Observability**: Trace and visualize agent operations comprehensively
+- 🚧 **Observability**: Trace and visualize agent operations comprehensively (under development)
 
 ---
 
@@ -42,8 +44,6 @@ Join our community on DingTalk:
 ## 📋 Table of Contents
 
 - [Quick Start](#-quick-start)
-- [Agent Framework Integration](#-agent-framework-integration)
-- [Deployment](#️-deployment)
 - [Contributing](#-contributing)
 - [License](#-license)
 

diff --git a/README_zh.md b/README_zh.md
@@ -0,0 +1,185 @@
+<div align="center">
+
+# AgentScope Runtime for Java
+
+[![License](https://img.shields.io/badge/license-Apache%202.0-red.svg?logo=apache&label=License)](LICENSE)
+[![GitHub Stars](https://img.shields.io/github/stars/agentscope-ai/agentscope-runtime-java?style=flat&logo=github&color=yellow&label=Stars)](https://github.com/agentscope-ai/agentscope-runtime-java/stargazers)
+[![GitHub Forks](https://img.shields.io/github/forks/agentscope-ai/agentscope-runtime-java?style=flat&logo=github&color=purple&label=Forks)](https://github.com/agentscope-ai/agentscope-runtime-java/network)
+[![Maven Central](https://maven-badges.herokuapp.com/maven-central/io.agentscope/agentscope-runtime/badge.svg)](https://maven-badges.herokuapp.com/maven-central/io.agentscope/agentscope-runtime)
+[![DingTalk](https://img.shields.io/badge/DingTalk-Join_Us-orange.svg)](https://qr.dingtalk.com/action/joingroup?code=v1,k1,OmDlBXpjW+I2vWjKDsjvI9dhcXjGZi3bQiojOq3dlDw=&_dt_no_comment=1&origin=11)
+
+[[Cookbook]](./cookbook/zh)
+[[English README]](./README.md)
+[[Examples]](./examples)
+
+**AgentScope Runtime Java**
+
+这是 [AgentScope Runtime](https://github.com/agentscope-ai/agentscope-runtime/) 的 Java 实现。
+
+
+</div>
+
+---
+
+## ✨ 核心特性
+
+- **部署基础设施**：内置会话管理、内存和沙箱环境控制服务
+- **沙箱化工具执行**：隔离的沙箱确保工具执行安全，不会危及系统
+- **开发者友好**：简单部署，强大的自定义选项
+- **框架无关**：不绑定任何特定框架。可与流行的开源 Agent 框架和自定义实现无缝协作
+- 🚧 **可观测性**：全面追踪和可视化 Agent 操作（开发中）
+
+---
+
+## 💬 社区
+
+加入我们的钉钉社区：
+
+| DingTalk                                                     |
+| ------------------------------------------------------------ |
+| <img src="https://img.alicdn.com/imgextra/i1/O1CN01LxzZha1thpIN2cc2E_!!6000000005934-2-tps-497-477.png" width="100" height="100"> |
+
+---
+
+## 📋 目录
+
+- [快速开始](#-快速开始)
+- [贡献](#-贡献)
+- [许可证](#-许可证)
+
+---
+
+## 🚀 快速开始
+
+### 前置要求
+
+- Java 17 或更高版本
+- Maven 3.6+
+
+### 添加依赖
+
+在您的 `pom.xml` 中添加以下依赖：
+<!-- Add runtime starter dependency -->
+```xml
+<dependency>
+    <groupId>io.agentscope</groupId>
+    <artifactId>spring-boot-starter-runtime-a2a</artifactId>
+    <version>1.0.0-BETA1</version>
+</dependency>
+
+<!-- Add AgentScope Agent adapter dependency -->
+<dependency>
+    <groupId>io.agentscope</groupId>
+    <artifactId>agentscope-runtime-agentscope</artifactId>
+    <version>1.0.0-BETA1</version>
+</dependency>
+```
+
+### 基础 Agent 使用示例
+
+以下示例演示如何使用 AgentScope Runtime 委托一个 AgentScope ReactAgent。完整源代码可在 [examples](./examples) 目录中找到。
+
+1. 创建 Agent Handler
+
+通过扩展 `AgentScopeAgentHandler` 创建自定义 agent handler：
+
+```java
+public class MyAgentScopeAgentHandler extends AgentScopeAgentHandler {
+
+    @Override
+    public Flux<io.agentscope.core.agent.Event> streamQuery(AgentRequest request, Object messages) {
+        // Create Toolkit and register tools
+        Toolkit toolkit = new Toolkit();
+        if (sandboxService != null) {
+            Sandbox sandbox = sandboxService.connect(
+                request.getUserId(), 
+                request.getSessionId(), 
+                BaseSandbox.class
+            );
+            toolkit.registerTool(ToolkitInit.RunPythonCodeTool(sandbox));
+        }
+
+        // Create ReActAgent with tools
+        ReActAgent agent = ReActAgent.builder()
+            .name("Friday")
+            .toolkit(toolkit)
+            .model(DashScopeChatModel.builder()
+                .apiKey(System.getenv("AI_DASHSCOPE_API_KEY"))
+                .modelName("qwen-max")
+                .stream(true)
+                .formatter(new DashScopeChatFormatter())
+                .build())
+            .build();
+
+        // Convert messages and stream agent responses
+        // See examples/README.md for complete implementation
+        return agent.stream(queryMessage, streamOptions);
+    }
+}
+```
+
+2. 初始化服务并部署
+
+使用所需服务配置 agent handler，并使用 `AgentApp` 进行部署：
+
+```java
+// Create and configure the agent handler
+MyAgentScopeAgentHandler agentHandler = new MyAgentScopeAgentHandler();
+agentHandler.setStateService(new InMemoryStateService());
+agentHandler.setSessionHistoryService(new InMemorySessionHistoryService());
+agentHandler.setMemoryService(new InMemoryMemoryService());
+agentHandler.setSandboxService(new SandboxService(
+    new SandboxManager(ManagerConfig.builder().build())
+));
+
+// Deploy using AgentApp
+AgentApp agentApp = new AgentApp(agentHandler);
+agentApp.run(8090); // Server will listen on port 8090
+```
+
+> [!NOTE]
+> 您也可以使用 **Kubernetes** 或阿里云 FC 平台的 **AgentRun** 来执行沙箱工具。更多详情请参考 [examples](./examples) 目录。
+---
+
+## 🔌 Agent 框架集成
+
+AgentScope Runtime Java 实现可以轻松集成任何用 Java 开发的 Agent 框架。目前支持的框架包括：
+
+- **AgentScope Java**
+- **Spring AI Alibaba, Langchain4j 以及更多即将推出...**
+
+---
+
+## 🤝 贡献
+
+我们欢迎社区贡献！以下是如何提供帮助：
+
+### 🐛 错误报告
+
+- 使用 [GitHub Issues](https://github.com/agentscope-ai/agentscope-runtime-java/issues) 报告错误
+- 包含详细的复现步骤
+- 提供系统信息和相关日志
+
+### 💡 功能请求
+
+- 在 [GitHub Discussions](https://github.com/agentscope-ai/agentscope-runtime-java/discussions) 中讨论新想法
+- 遵循功能请求模板
+- 考虑实现可行性
+
+### 🔧 代码贡献
+
+1. Fork 仓库
+2. 创建功能分支 (`git checkout -b feature/amazing-feature`)
+3. 提交更改 (`git commit -m 'Add amazing feature'`)
+4. 推送到分支 (`git push origin feature/amazing-feature`)
+5. 打开 Pull Request
+
+详细的贡献指南，请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。
+
+---
+
+## 📄 许可证
+
+本项目采用 Apache License 2.0 许可证。详情请参阅 [LICENSE](LICENSE) 文件。
+
+---
diff --git a/cookbook/new-zh/CHANGELOG.md b/cookbook/new-zh/CHANGELOG.md