AgentScope Java 项目入门 & Builder 深度解读

第一部分：AgentScope Java 项目入门

一、项目定位

AgentScope Java 是阿里巴巴开源的 AI 智能体编程框架（Apache-2.0，JDK 17+），用于构建基于大语言模型（LLM）的生产级应用。可以类比为 Java 版的 LangChain + CrewAI，但更面向企业级生产环境。

Maven 坐标：io.agentscope:agentscope:2.0.0-SNAPSHOT

二、模块全景

项目是多模块 Maven 工程，共 6 个顶层模块：

顶层模块	定位
agentscope-java/	父工程
├─ agentscope-core/	核心框架（Agent、Model、Tool、Memory、Hook 等）
├─ agentscope-harness/	生产运行时（沙箱、Workspace、消息总线、分布式存储）
├─ agentscope-extensions/	16 个扩展模块（MCP、A2A、RAG、长期记忆、渠道接入等）
├─ agentscope-examples/	示例应用（CodingAgent、DataAgent、Builder 等）
├─ agentscope-dependencies-bom/	BOM 版本管理
└─ agentscope-distribution/	发布打包

模块	定位
agentscope-core	框架内核：Agent、Model、Tool、Memory、Hook/Middleware、消息、状态、技能、RAG 抽象、权限、追踪
agentscope-harness	生产运行层：沙箱文件系统、Workspace 管理、消息总线、分布式存储、Agent 隔离
agentscope-extensions	16 个扩展模块，提供集成能力
agentscope-examples	示例应用和文档片段
agentscope-dependencies-bom	BOM（物料清单）统一依赖版本
agentscope-distribution	发布打包（agentscope-all uber-jar、agentscope-bom）

三、核心概念（5 个关键抽象）

理解这 5 个抽象就掌握了框架骨架：

概念	核心类	作用
Agent	ReActAgent	智能体，执行 "推理→行动" 循环
Model	DashScopeChatModel/ OpenAIChatModel/ AnthropicChatModel等	LLM 模型层，统一流式接口
Tool	@Tool+ @ToolParam+ Toolkit	工具系统，注解驱动，自动 JSON Schema 生成
Msg	Msg+ ContentBlock	消息模型，支持文本 / 图片 / 音频 / 工具调用等多模态
Memory/State	AgentState+ AgentStateStore	会话上下文持久化状态（2.0 版本替代了旧 Memory）

四、ReAct 循环 ------Agent 的核心工作方式

1. 用户输入 → Agent 推理（LLM 决定用什么工具）→ 执行工具 → 观察结果 → 再推理 → ... → 最终回复

ReActAgent 是这个循环的核心实现，关键参数：

• maxIters --- 最大推理轮数（防止无限循环）
• toolkit --- 注册的工具集
• middleware --- 中间件链（2.0 新特性，替代 Hook）

五、最小可运行示例

ReActAgent agent = ReActAgent.builder()
    .name("Assistant")
    .sysPrompt("你是一个有帮助的 AI 助手。")
    .model(DashScopeChatModel.builder()
        .apiKey(System.getenv("DASHSCOPE_API_KEY"))
        .modelName("qwen-max")
        .build())
    .build();

// 同步调用
Msg response = agent.call(Msg.builder()
    .textContent("你好！")
    .build()).block();

System.out.println(response.getTextContent());

六、工具定义（最常用功能）

用注解定义工具，框架自动生成 JSON Schema 给 LLM：

public class MyTools {
    @Tool(description = "查询天气信息")
    public String getWeather(
        @ToolParam(name = "city", description = "城市名称") String city
    ) {
        return city + "今天晴, 25℃";
    }
}

// 注册到 Agent
Toolkit toolkit = new Toolkit();
toolkit.registerTool(new MyTools());

ReActAgent agent = ReActAgent.builder()
    .name("WeatherAgent")
    .toolkit(toolkit)
    .model(model)
    .build();

七、关键设计特点

特点	说明
全异步响应式	基于 Project Reactor，所有 I/O 非阻塞，call() 返回 Mono, stream() 返回 Flux
中间件系统（2.0）	5 个拦截点：Agent/Reasoning/Acting/ModelCall/SystemPrompt，洋葱模型
多模型支持	DashScope、OpenAI、Anthropic、Gemini、Ollama，统一接口
MCP 协议	一行代码接入 MCP 工具生态
A2A 协议	分布式多 Agent 协作，注册到 Nacos 即可互相发现和调用
人机协同（HITL）	PermissionEngine 支持 ASK 模式，关键操作需人类确认
安全沙箱	4 种沙箱环境（AgentRun/Daytona/E2B/K8s Pod）

八、核心架构（agentscope-core 包结构）

基础路径：agentscope-core/src/main/java/io/agentscope/core/

包	职责
agent/	Agent 接口和基类（Agent、AgentBase、CallableAgent、StreamableAgent、RuntimeContext）
agent/accumulator/	流式内容累加器（TextAccumulator、ThinkingAccumulator、ToolCallsAccumulator）
agent/config/	配置记录（ModelConfig、ReactConfig）
credential/	凭证管理
event/	流式事件类型（约 35 个事件类）：AgentStartEvent、TextBlockDeltaEvent、ToolCallStartEvent等
exception/	框架异常
formatter/	模型消息格式化器：openai/、anthropic/、dashscope/、gemini/、ollama/
hook/	旧版 Hook 系统（2.0 已废弃，被 middleware 替代）
interruption/	协作中断（InterruptControl、InterruptContext）
memory/	记忆接口：Memory（已废弃）、InMemoryMemory、LongTermMemory、StateBackedMemory
message/	消息模型：Msg、MsgRole、ContentBlock、TextBlock、ThinkingBlock、ToolUseBlock等
middleware/	2.0 新中间件系统：MiddlewareBase、MiddlewareChain、AgentInput、ReasoningInput等
model/	LLM 模型层：Model接口、ChatModelBase、各厂商实现、传输层（OkHttp/JDK HTTP/WebSocket）
permission/	权限引擎：PermissionEngine、PermissionRule、HITL 确认流程
rag/	RAG 抽象：Knowledge接口、genericRAGHook、KnowledgeRetrievalTools
shutdown/	优雅关闭：GracefulShutdownManager、GracefulShutdownMiddleware
skill/	技能系统：SkillBox、AgentSkill、SkillRegistry、DynamicSkillMiddleware
state/	Agent 状态持久化：AgentState、AgentStateStore、JsonFileAgentStateStore
tool/	工具框架：Toolkit、AgentTool、@Tool、@ToolParam、ReflectiveFunctionTool、MCP 集成、内置工具
tracing/	可观测性：Tracer、NoopTracer、OtelTracingMiddleware

九、扩展模块一览（agentscope-extensions）

扩展	子模块	用途
extensions-channel	channel-dingtalk、channel-feishu、channel-github、channel-gitlab、channel-wecom	IM 平台集成（钉钉、飞书、GitHub、GitLab、企微）
extensions-higress	---	Higress API 网关集成
extensions-mem	mem0、memory-bailian、reme	长期记忆后端（Mem0、阿里百炼、ReMe）
extensions-mysql	---	MySQL 状态持久化
extensions-nacos	---	Nacos 服务发现 / 配置
extensions-oss	---	阿里云 OSS 存储
extensions-protocol	a2a（客户端 + 服务端）、agent-protocol、agui、chat-completions-web	协议适配器：A2A、Agent Protocol、AG-UI、OpenAI 兼容 API
extensions-rag	rag-bailian、rag-dify、rag-haystack、rag-ragflow、rag-simple	RAG 后端（百炼、Dify、Haystack、RAGFlow、简单 Embedding）
extensions-redis	---	Redis 状态持久化
extensions-sandbox	sandbox-agentrun、sandbox-daytona、sandbox-e2b、sandbox-kubernetes	沙箱代码执行环境
extensions-scheduler	scheduler-quartz、scheduler-xxl-job	定时 Agent 执行（Quartz、XXL-JOB）
extensions-studio	---	AgentScope Studio（可视化调试 UI、WebSocket、OpenTelemetry）
spring-boot-starters	agentscope、a2a、admin、agui、chat-completions-web、nacos	Spring Boot 自动配置

十、关键类速查表

你在找的	文件路径
Agent 接口	core/agent/Agent.java
ReActAgent（主 Agent 实现）	core/ReActAgent.java
Model 接口	core/model/Model.java
DashScope 模型	core/model/DashScopeChatModel.java
OpenAI 模型	core/model/OpenAIChatModel.java
Anthropic 模型	core/model/AnthropicChatModel.java
Msg（消息）	core/message/Msg.java
ContentBlock 系列	core/message/TextBlock.java、ThinkingBlock.java、ToolUseBlock.java等
Toolkit	core/tool/Toolkit.java
@Tool 注解	core/tool/Tool.java
@ToolParam 注解	core/tool/ToolParam.java
Memory 接口	core/memory/Memory.java
LongTermMemory	core/memory/LongTermMemory.java
Middleware (2.0)	core/middleware/MiddlewareBase.java
Hook（旧版）	core/hook/Hook.java
AgentState	core/state/AgentState.java
Permission 引擎	core/permission/PermissionEngine.java
MCP 客户端	core/tool/mcp/McpClientBuilder.java
Skill 系统	core/skill/SkillBox.java
RAG Knowledge	core/rag/Knowledge.java
HarnessAgent	harness/agent/HarnessAgent.java

十一、重要编码禁忌

禁止	正确做法
在 Agent 逻辑中调用 .block()	只在 main() 或测试中 .block()
使用 Thread.sleep()	使用 Mono.delay()
使用 ThreadLocal	使用 Reactor Context（Mono.deferContextual()）
硬编码 API Key	使用 System.getenv()
toolkit.registerObject()	使用 toolkit.registerTool()

十二、推荐的入门路径

1. 先读 SKILL.md（项目根目录）--- 官方编码指南，1053 行，包含完整 API 用法和避坑规则
2. 跑示例 agentscope-examples/ 下的示例应用，特别是 agentscope-codingagent（带技能的编码 Agent）
3. 理解核心：读 ReActAgent.java 源码，理解 ReAct 循环的实现
4. 尝试扩展：看 agentscope-extensions/ 中感兴趣的扩展（如 MCP、RAG、长期记忆）