GitShelf — GitHub 项目目录

项目概述

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 项目中添加依赖：

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

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

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

快速开始：

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

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();
    }
}

典型使用方法

流式事件处理：

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（基于最新发布版本）。