## 项目概述

AgentScope Java 2.0 是一个用于构建分布式、生产级、长期运行智能体的 Java 框架。它提供了必要的抽象，以支持不断增长的模型能力，并内置了对长期运行、安全可控的智能体执行的支持。该项目由 agentscope-ai 组织维护，采用 Apache License 2.0 许可证，要求 JDK 17 或更高版本。

## 核心功能

- **事件系统**：统一的事件流，包含 28 种类型化事件，用于实时前端渲染和人在环路（HITL）。
- **权限系统**：工具调用门控，支持允许、需要用户批准、拒绝三种状态。
- **中间件**：AOP 风格的钩子拦截，用于灵活扩展推理-行动循环。
- **工作区与沙箱**：在隔离环境中运行工具，支持本地、Docker、Kubernetes 或 AgentRun 云沙箱。
- **多智能体编排**：通过 `agent_spawn` / `agent_send` 定义多种子智能体模式，并支持实时事件转发。
- **分布式部署**：真正的分布式会话和内存管理（支持 Redis / MySQL / PostgreSQL / OSS / COS），支持跨副本会话恢复。
- **智能体进化**：提供智能体可观测性和审计、智能体评估和实验、智能体资产管理和持续优化。

## 适用与不适用场景

**适用场景：**

- 需要长期运行、状态可恢复的智能体应用。
- 企业级多租户环境，需要隔离和权限控制。
- 需要分布式部署和横向扩展的生产系统。
- 需要多智能体协作和任务编排的复杂工作流。
- 需要沙箱隔离执行不可信代码或命令的场景。

**不适用场景：**

- 简单的单轮问答应用，无需复杂状态管理。
- 对延迟极度敏感、不能容忍额外框架开销的场景。
- 需要轻量级、无依赖的智能体实现。

## 技术架构与依赖

AgentScope Java 2.0 采用双层架构：核心层（`agentscope-core`）提供基础的消息、事件和扩展模型；Harness 层（`agentscope-harness`）在核心之上构建生产级运行时基础设施，通过钩子（Hooks）和工具包（Toolkits）扩展。主要依赖包括：

- JDK 17+。
- Maven 中央仓库中的 `io.agentscope:agentscope-harness` 和 `io.agentscope:agentscope-core`。
- 模型提供方扩展模块，如 `agentscope-extensions-model-dashscope`、`agentscope-extensions-model-openai` 等。
- 可选依赖：Redis、MySQL、PostgreSQL、OSS、COS 等用于分布式状态存储。

## 安装与快速开始

**安装：**

在 Maven 项目中添加依赖：

```xml
<dependency>
    <groupId>io.agentscope</groupId>
    <artifactId>agentscope-harness</artifactId>
    <version>2.0.1</version>
</dependency>
```

根据使用的模型提供商，添加相应的扩展模块，例如 DashScope：

```xml
<dependency>
    <groupId>io.agentscope</groupId>
    <artifactId>agentscope-extensions-model-dashscope</artifactId>
    <version>2.0.1</version>
</dependency>
```

**快速开始：**

以下代码创建一个简单的 HarnessAgent 并调用：

```java
import io.agentscope.core.agent.RuntimeContext;
import io.agentscope.core.message.UserMessage;
import io.agentscope.harness.agent.HarnessAgent;
import java.nio.file.Paths;

public class FirstAgent {
    public static void main(String[] args) {
        HarnessAgent agent = HarnessAgent.builder()
                .name("assistant")
                .sysPrompt("You are a helpful AI assistant.")
                .model("dashscope:qwen-plus")
                .workspace(Paths.get(".agentscope/workspace"))
                .build();

        RuntimeContext ctx = RuntimeContext.builder()
                .sessionId("demo").userId("alice").build();

        agent.call(new UserMessage("Hello!"), ctx).block();
    }
}
```

## 典型使用方法

**流式事件处理：**

```java
agent.streamEvents(new UserMessage("Summarize today in three bullets."), ctx)
        .doOnNext(event -> {
            switch (event.getType()) {
                case TEXT_BLOCK_DELTA -> System.out.print(
                        ((io.agentscope.core.event.TextBlockDeltaEvent) event).getDelta());
                case TOOL_CALL_START -> System.out.println(
                        "\n[tool] " + ((io.agentscope.core.event.ToolCallStartEvent) event).getToolCallName());
                default -> { }
            }
        })
        .blockLast();
```

**多智能体辩论模式：**

使用 `MsgHub` 实现多智能体辩论，参与者通过消息广播进行讨论，并由主持人评估。

**子智能体编排：**

通过 `agent_spawn` 和 `agent_send` 工具创建和通信子智能体，支持同步和异步任务。

## 配置与部署要点

- **模型配置**：通过 `ModelRegistry` 解析模型字符串，并自动读取对应的 API 密钥环境变量（如 `OPENAI_API_KEY`）。
- **工作区配置**：工作区目录存放智能体的身份、记忆、技能和子智能体定义，可通过 `workspace` 方法指定。
- **沙箱配置**：通过 `filesystem(SandboxFilesystemSpec)` 启用沙箱模式，支持 Docker、Kubernetes 等后端。
- **分布式部署**：使用 `sandboxDistributed` 和分布式会话（如 RedisSession）实现跨副本状态共享。
- **权限控制**：配置权限系统以控制工具调用的批准流程。
- **内存管理**：配置压缩策略（`CompactionConfig`）和工具结果驱逐（`ToolResultEvictionConfig`）以管理上下文长度。

## 限制、风险与许可证

- **许可证**：Apache License 2.0。
- **限制**：需要 JDK 17+；沙箱模式可能需要 Docker 或 Kubernetes 环境；分布式部署需要额外的存储服务。
- **风险**：沙箱执行可能带来安全风险，需谨慎配置；长期运行可能产生大量状态数据，需合理管理。

## 官方链接

- GitHub 仓库：https://github.com/agentscope-ai/agentscope-java
- 文档：https://java.agentscope.io/
- 最新版本：v2.0.1（2026-08-06 发布）

## 信息来源和分析时间

- 信息来源：GitHub 仓库 README、文档目录、发布说明。
- 分析时间：2026-08-06（基于最新发布版本）。