AgentScope Java Day 8: Full Knowledge Map and High‑Frequency Q&A Self‑Test

Full Knowledge Map

AgentScope Java（JVM Agent 框架 · JDK 17+ · 阿里开源 · 基于 Reactor）
│
├─ Message 消息（Day2）
│   ├─ role：USER / ASSISTANT / SYSTEM / TOOL
│   └─ content 块：TextBlock / ImageBlock / ToolUseBlock / ToolResultBlock
│
├─ ReActAgent 智能体（Day1 / Day3）
│   ├─ ReAct 循环：Reason → Act → Observe（maxIters 默认 10）
│   ├─ 调用：call() → Mono<Msg>  ｜  stream()/streamEvents() → Flux<Event>
│   └─ Model：「provider:model」简写 + Formatter 多厂商适配
│
├─ Tool 工具（Day4）
│   ├─ @Tool + @ToolParam（registerTool）/ ToolBase（registerAgentTool，权限三态）
│   └─ MCP：McpClientBuilder + registerMcpClient 接外部工具生态
│
├─ Memory & State 记忆（Day5）
│   ├─ AgentState（getContext）→ AgentStateStore（持久化）
│   └─ Compaction 压缩 + MEMORY.md 长期记忆
│
├─ Harness 工程化（Day6）
│   ├─ Middleware：onAgent / onReasoning / onActing / onModelCall / onSystemPrompt 洋葱钩子
│   ├─ Workspace + 沙箱：DockerFilesystemSpec 一行切容器隔离
│   ├─ 上下文工程：Compaction + ToolResultEviction 大结果落盘
│   └─ 模型容错：modelExecutionConfig 超时重试 + 备用模型
│
└─ 多智能体（Day7）
    ├─ 路由委派：Agent 即 @Tool
    └─ Subagent：HarnessAgent + Channel

Core API Quick Reference

创建 Agent : ReActAgent.builder().name().model().toolkit().build() 选模型 : .model("dashscope:qwen-plus") 同步调用 : agent.call(msg).block().getTextContent() 流式调用 : agent.streamEvents(msg) / agent.stream(msgs, opts, ctx) 定义工具 : @Tool(name, description) + @ToolParam(name) 注册工具 : toolkit.registerTool() / registerAgentTool() 持久化 :

.stateStore(new JsonFileAgentStateStore(path)).defaultSessionId(id)

取历史 : agent.getAgentState().getContext() 长期记忆 : HarnessAgent + .workspace() + .compaction() 多智能体 : @Tool 包成专家 Agent，或 HarnessAgent Subagent 挂中间件 : .middleware(new XxxMiddleware()) （实现 MiddlewareBase 钩子）

沙箱隔离 :

.filesystem(new DockerFilesystemSpec().image(...).isolationScope(...))

接 MCP : McpClientBuilder.create(...).stdioTransport(...) + toolkit.registerMcpClient() 模型容错 :

.modelExecutionConfig(ExecutionConfig.builder().timeout(...).maxAttempts(...))

Dependency Quick Reference

io.agentscope:agentscope:2.0.0-RC3

– All‑in‑One, ready to use io.agentscope:agentscope-core – Minimal core, extend as needed io.agentscope:agentscope-harness – Core + engineering capabilities

High‑Frequency Q&A Self‑Test

Q1: What is ReAct and why should an Agent use it? Reasoning + Acting alternating loop—model reasoning decides the next step, action invokes a tool, observation feeds back into reasoning, repeating until an answer is produced. It lets an Agent decompose tasks, call tools, and dynamically adjust based on intermediate results instead of a simple question‑answer flow.

Q2: Difference between ReActAgent and HarnessAgent? ReActAgent provides the core "reason‑tool‑reply" loop; HarnessAgent layers engineering capabilities (workspace persona, long‑term memory, context compaction, sandbox, sub‑Agent) on top, targeting stable production use. Both share the same reasoning core.

Q3: When to choose call() vs. stream()? call() returns Mono<Msg>, blocks for a complete reply—suitable for backend or batch processing. stream() / streamEvents() return Flux<Event>, emitting tokens in real time—ideal for chat UI or Web SSE. Use stream for human‑facing output, call for programmatic consumption.

Q4: Why must @ToolParam explicitly specify parameter names? Java compilation discards method parameter names by default, so the model cannot infer semantics. The @ToolParam name + description is merged into the tool definition, enabling the model to call the tool correctly.

Q5: What does ToolBase add over @Tool? It introduces three‑state permission checking (allow/deny/passthrough), asynchronous execution via callAsync returning Mono, safety flags ( readOnly / concurrencySafe), and a customizable inputSchema. These are useful for risky operations or those requiring concurrency control.

Q6: How is memory organized in version 2.0? Three layers: (1) In‑call state via AgentState + RuntimeContext; (2) Cross‑call persistence via AgentStateStore (JsonFile/MySQL/Redis) with automatic session handling; (3) Long‑term memory where HarnessAgent persists valuable facts to MEMORY.md with compaction to limit context length.

Q7: How to switch to a larger model and what mechanism powers it? Change the string in .model("provider:model"). ModelRegistry parses the provider, reads the corresponding environment variable key, and Formatter translates the unified message into the provider’s API format. Built‑in providers include DashScope, OpenAI, Anthropic, Gemini, Ollama, DeepSeek, GLM.

Q8: How does AgentScope 2.0 implement multi‑agent orchestration compared to a Pipeline framework? There is no fixed Pipeline DSL. The paradigm is "Agent as Tool"—wrap expert Agents with @Tool for dynamic routing, or use HarnessAgent Subagent (spawn child Agent + Channel streaming) for complex scenarios. Orchestration decisions are made by a large model at runtime, not by a static flowchart.

Q9: Why is the framework built on Project Reactor? Agents spend most of their time waiting on I/O (model calls, tool calls, external APIs). The non‑blocking Mono / Flux model efficiently handles concurrent requests and streaming output, and stream() token‑by‑token pushing aligns naturally with reactive programming.

Q10: Can a single Agent instance be concurrently reused? No. An Agent holds internal state; concurrent access leads to interference. Either create a new instance per request or use sessionId with AgentStateStore for session isolation.

Q11: What can HarnessAgent’s Middleware do? MiddlewareBase provides hooks such as onAgent, onReasoning, onActing, onModelCall, onSystemPrompt. These onion‑style hooks let you inject logic (logging, tracing, permission checks, rate limiting, context injection) before or after each stage of the reasoning loop while keeping the core loop unchanged. Assemble with .middleware(...), which runs before any custom middleware.

Q12: How to safely execute file operations or shell commands? Use HarnessAgent’s sandbox:

.filesystem(new DockerFilesystemSpec().image("ubuntu:24.04").isolationScope(IsolationScope.USER))

isolates execution in a Docker container, protecting the host. IsolationScope controls granularity (per user or per session). For multi‑instance deployments, share sandbox state via DistributedStore.

Related Links

AgentScope Java official documentation: https://java.agentscope.io/v2/zh/intro.html

Quick start guide: https://java.agentscope.io/v2/zh/docs/quickstart.html

GitHub repository: https://github.com/agentscope-ai/agentscope-java

DashScope Open Platform: https://dashscope.aliyun.com/