AgentScope Java 2.0 源码学习手册 v2

AgentScope Java 2.0 的定位是：面向分布式、企业级、长时间运行、安全可控 Agent 的生产级 Java 框架。README 明确列出 Event System、Permission System、Middleware、Workspace & Sandbox、Multi-Agent Orchestration、Distributed Deployment 等能力。

第一次学习不要直接陷入全部源码。先按这条路径建立“能跑、能看、能断点”的感觉。

生产学习优先从 HarnessAgent 开始，因为它是用户侧工程入口；只做底层实验时再直接使用 ReActAgent。

Maven 依赖

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

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

最小 HarnessAgent

复制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()
    .userId("alice")
    .sessionId("demo-session")
    .build();

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

AgentBase 是所有 Agent 的生命周期底座。它不负责具体 ReAct 逻辑，而负责执行框架共性问题：Reactor Context、call scope、pre/post hook、tracing、shutdown、错误处理、同 key 串行化。

ReActAgent 是 AgentScope Java 的核心 Agent 实现。它在 reasoning 与 acting 之间循环：模型先思考并生成文本或工具调用；如果有工具调用，则进入 acting 执行工具；工具结果写回上下文，再继续 reasoning。

模型层是一个很薄的抽象：Model.stream(List<Msg>, List<ToolSchema>, GenerateOptions) 返回 Flux<ChatResponse>。这让 OpenAI、DashScope、Anthropic、Gemini、Ollama 等 provider 可以被统一接入。

复制public interface Model {
    Flux<ChatResponse> stream(
        List<Msg> messages,
        List<ToolSchema> tools,
        GenerateOptions options
    );

    String getModelName();

    default boolean supportsNativeStructuredOutput() { return false; }
    default boolean supportsNativeStructuredOutputWithTools() {
        return supportsNativeStructuredOutput();
    }
}

这个接口的关键不是复杂，而是边界清楚：Agent Runtime 负责流程、状态、工具和事件；模型实现负责把 AgentScope 的消息和工具 schema 转成具体 provider 请求。

AgentScope Java 2.0 使用细粒度 AgentEvent，可以把模型流式输出、工具调用、工具结果、用户确认、外部执行等过程直接推给前端。

Toolkit 可以扫描带 @Tool 注解的方法，生成工具 schema，并在模型返回工具调用时反射执行。

复制public class WeatherTools {
    @Tool(name = "get_weather", description = "Get weather by city name")
    public String getWeather(String city) {
        return city + " today is sunny";
    }
}

Toolkit toolkit = new Toolkit();
toolkit.registerTool(new WeatherTools());

ReActAgent agent = ReActAgent.builder()
    .name("assistant")
    .model(model)
    .toolkit(toolkit)
    .maxIters(8)
    .build();

Toolkit 是工具系统 facade，内部委托多个 manager：ToolRegistry、ToolGroupManager、ToolSchemaProvider、McpClientManager、MetaToolFactory、ToolExecutor。

call() 只拿最终结果；streamEvents() 可以观察完整运行过程。学习源码时，优先用 streamEvents()。

复制agent.streamEvents(new UserMessage("帮我查天气"), ctx)
    .doOnNext(event -> {
        switch (event.getType()) {
            case MODEL_CALL_START -> System.out.println("模型开始调用");
            case TEXT_BLOCK_DELTA -> System.out.print(event);
            case TOOL_CALL_START -> System.out.println("工具开始调用");
            case TOOL_RESULT_END -> System.out.println("工具执行完成");
            case REQUIRE_USER_CONFIRM -> System.out.println("需要用户确认");
            default -> {}
        }
    })
    .blockLast();

如果你要做 Web UI，建议直接围绕 AgentEvent 设计前端协议，而不是只返回最终文本。

PermissionEngine 是工具安全控制的核心。源码注释明确给出权限评估顺序：deny 最高，其次 ask，再 tool-specific checks，再 allow，再 BYPASS，最后 default ASK 或 DONT_ASK 下转 DENY。

HITL 的本质是：模型已经提出工具调用，但运行时不立即执行，而是把工具调用标为 ASKING，返回确认事件；用户确认后，下一次 agent.call() 带上 ConfirmResult，Agent 再继续执行。

这套设计让用户确认成为 Agent Runtime 的一等公民，而不是业务层临时加弹窗。

AgentStateStore 按 (userId, sessionId) 保存状态。状态项包括会话上下文、权限状态、工具状态、Plan Mode 状态等。版本化 backend 可以通过 getVersioned() 和 saveIfVersion() 做乐观并发控制。

状态恢复最容易被误解。AgentStateStore 可以恢复会话上下文和工具状态，但不能天然保证外部副作用 exactly-once。

复制// 自研工具幂等建议：每次工具调用生成稳定业务幂等键
String idempotencyKey = sessionId + ":" + toolCallId + ":" + toolName;

// 业务数据库先写入 pending，再执行外部副作用
// 若重试发现 idempotencyKey 已成功，直接返回历史结果
// 若 pending 超时，走查询/补偿逻辑，而不是盲目再次执行

结构化输出有两条路径：模型支持原生 response_format/json_schema 时走 Native；否则注入一个 per-call 合成工具 generate_response，让模型通过工具调用返回结构化结果。

HarnessAgent 是用户侧生产入口。它包装内部 ReActAgent，并在上层增加 workspace、filesystem、sandbox、subagent、skill、plan-mode、MCP orchestration、context compaction 等能力。

官方生产文档强调：从单机到多副本，核心变化是多个 replica 必须共享 session、隔离用户、沙箱执行不可信代码，并能在 pod 重启后恢复会话。

复制DistributedStore store = RedisDistributedStore.fromJedis(jedis);

HarnessAgent agent = HarnessAgent.builder()
    .name("prod-agent")
    .model(model)
    .distributedStore(store)
    .filesystem(new RemoteFilesystemSpec()
        .isolationScope(IsolationScope.USER))
    .build();

1. README.md：先确认项目定位、模块、快速开始、2.0 能力。
2. agentscope-core/.../AgentBase.java：理解生命周期、Reactor Context、同 key 串行化。
3. agentscope-core/.../ReActAgent.java：理解 reasoning、acting、structured output、HITL、state save。
4. agentscope-core/.../model/Model.java：理解模型 provider 如何被抽象。
5. agentscope-core/.../tool/Toolkit.java：理解工具注册、工具组、MCP、ToolExecutor。
6. agentscope-core/.../permission/PermissionEngine.java：理解权限优先级。
7. agentscope-core/.../state/AgentStateStore.java：理解状态保存、恢复和 CAS。
8. agentscope-harness/.../HarnessAgent.java：理解 Workspace、Sandbox、Memory、Skill、Subagent 的工程入口。
9. docs/v2/en/docs/others/going-to-production.md：理解生产部署替换哪些组件。

1. AgentScope Java 为什么不能只理解成 ReAct Demo？
2. AgentBase.runLifecycle() 解决了哪些通用运行时问题？
3. 为什么 RuntimeContext 要通过 Reactor Context 传递？
4. 同一个 userId/sessionId 的调用为什么需要串行化？
5. 模型输出的 ToolUseBlock 如何变成真正工具执行？
6. Toolkit 为什么设计成 facade，而不是一个简单工具列表？
7. PermissionEngine 的优先级是什么？为什么 deny 要最高？
8. HITL 暂停后，下一次 call() 如何恢复？
9. AgentStateStore.saveIfVersion() 解决什么问题？
10. 为什么 AgentStateStore 不能保证支付、发邮件等外部副作用 exactly-once？
11. 结构化输出为什么需要 Native 与 synthetic tool 两条路径？
12. HarnessAgent 相比裸 ReActAgent 增加了哪些生产能力？
13. 分布式部署中为什么需要 SandboxExecutionGuard？
14. 如果用 Java 自研 Agent Runtime，你会复用哪些设计？