第一部分AgentScope Java 项目入门一、项目定位AgentScope Java 是阿里巴巴开源的 AI 智能体编程框架Apache-2.0JDK 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-extensions16 个扩展模块提供集成能力agentscope-examples示例应用和文档片段agentscope-dependencies-bomBOM物料清单统一依赖版本agentscope-distribution发布打包agentscope-all uber-jar、agentscope-bom三、核心概念5 个关键抽象理解这 5 个抽象就掌握了框架骨架概念核心类作用AgentReActAgent智能体执行 “推理→行动” 循环ModelDashScopeChatModel/ OpenAIChatModel/ AnthropicChatModel等LLM 模型层统一流式接口ToolToolToolParam Toolkit工具系统注解驱动自动 JSON Schema 生成MsgMsg ContentBlock消息模型支持文本 / 图片 / 音频 / 工具调用等多模态Memory/StateAgentState AgentStateStore会话上下文持久化状态2.0 版本替代了旧 Memory四、ReAct 循环 ——Agent 的核心工作方式用户输入 → 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 给 LLMpublic 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.05 个拦截点Agent/Reasoning/Acting/ModelCall/SystemPrompt洋葱模型多模型支持DashScope、OpenAI、Anthropic、Gemini、Ollama统一接口MCP 协议一行代码接入 MCP 工具生态A2A 协议分布式多 Agent 协作注册到 Nacos 即可互相发现和调用人机协同HITLPermissionEngine 支持 ASK 模式关键操作需人类确认安全沙箱4 种沙箱环境AgentRun/Daytona/E2B/K8s Pod八、核心架构agentscope-core 包结构基础路径agentscope-core/src/main/java/io/agentscope/core/包职责agent/Agent 接口和基类Agent、AgentBase、CallableAgent、StreamableAgent、RuntimeContextagent/accumulator/流式内容累加器TextAccumulator、ThinkingAccumulator、ToolCallsAccumulatoragent/config/配置记录ModelConfig、ReactConfigcredential/凭证管理event/流式事件类型约 35 个事件类AgentStartEvent、TextBlockDeltaEvent、ToolCallStartEvent等exception/框架异常formatter/模型消息格式化器openai/、anthropic/、dashscope/、gemini/、ollama/hook/旧版 Hook 系统2.0 已废弃被 middleware 替代interruption/协作中断InterruptControl、InterruptContextmemory/记忆接口Memory已废弃、InMemoryMemory、LongTermMemory、StateBackedMemorymessage/消息模型Msg、MsgRole、ContentBlock、TextBlock、ThinkingBlock、ToolUseBlock等middleware/2.0 新中间件系统MiddlewareBase、MiddlewareChain、AgentInput、ReasoningInput等model/LLM 模型层Model接口、ChatModelBase、各厂商实现、传输层OkHttp/JDK HTTP/WebSocketpermission/权限引擎PermissionEngine、PermissionRule、HITL 确认流程rag/RAG 抽象Knowledge接口、genericRAGHook、KnowledgeRetrievalToolsshutdown/优雅关闭GracefulShutdownManager、GracefulShutdownMiddlewareskill/技能系统SkillBox、AgentSkill、SkillRegistry、DynamicSkillMiddlewarestate/Agent 状态持久化AgentState、AgentStateStore、JsonFileAgentStateStoretool/工具框架Toolkit、AgentTool、Tool、ToolParam、ReflectiveFunctionTool、MCP 集成、内置工具tracing/可观测性Tracer、NoopTracer、OtelTracingMiddleware九、扩展模块一览agentscope-extensions扩展子模块用途extensions-channelchannel-dingtalk、channel-feishu、channel-github、channel-gitlab、channel-wecomIM 平台集成钉钉、飞书、GitHub、GitLab、企微extensions-higress—Higress API 网关集成extensions-memmem0、memory-bailian、reme长期记忆后端Mem0、阿里百炼、ReMeextensions-mysql—MySQL 状态持久化extensions-nacos—Nacos 服务发现 / 配置extensions-oss—阿里云 OSS 存储extensions-protocola2a客户端 服务端、agent-protocol、agui、chat-completions-web协议适配器A2A、Agent Protocol、AG-UI、OpenAI 兼容 APIextensions-ragrag-bailian、rag-dify、rag-haystack、rag-ragflow、rag-simpleRAG 后端百炼、Dify、Haystack、RAGFlow、简单 Embeddingextensions-redis—Redis 状态持久化extensions-sandboxsandbox-agentrun、sandbox-daytona、sandbox-e2b、sandbox-kubernetes沙箱代码执行环境extensions-schedulerscheduler-quartz、scheduler-xxl-job定时 Agent 执行Quartz、XXL-JOBextensions-studio—AgentScope Studio可视化调试 UI、WebSocket、OpenTelemetryspring-boot-startersagentscope、a2a、admin、agui、chat-completions-web、nacosSpring Boot 自动配置十、关键类速查表你在找的文件路径Agent 接口core/agent/Agent.javaReActAgent主 Agent 实现core/ReActAgent.javaModel 接口core/model/Model.javaDashScope 模型core/model/DashScopeChatModel.javaOpenAI 模型core/model/OpenAIChatModel.javaAnthropic 模型core/model/AnthropicChatModel.javaMsg消息core/message/Msg.javaContentBlock 系列core/message/TextBlock.java、ThinkingBlock.java、ToolUseBlock.java等Toolkitcore/tool/Toolkit.javaTool注解core/tool/Tool.javaToolParam注解core/tool/ToolParam.javaMemory 接口core/memory/Memory.javaLongTermMemorycore/memory/LongTermMemory.javaMiddleware (2.0)core/middleware/MiddlewareBase.javaHook旧版core/hook/Hook.javaAgentStatecore/state/AgentState.javaPermission 引擎core/permission/PermissionEngine.javaMCP 客户端core/tool/mcp/McpClientBuilder.javaSkill 系统core/skill/SkillBox.javaRAG Knowledgecore/rag/Knowledge.javaHarnessAgentharness/agent/HarnessAgent.java十一、重要编码禁忌禁止正确做法在 Agent 逻辑中调用.block()只在main()或测试中.block()使用Thread.sleep()使用Mono.delay()使用ThreadLocal使用 Reactor ContextMono.deferContextual()硬编码 API Key使用System.getenv()toolkit.registerObject()使用toolkit.registerTool()十二、推荐的入门路径先读SKILL.md项目根目录— 官方编码指南1053 行包含完整 API 用法和避坑规则跑示例agentscope-examples/下的示例应用特别是agentscope-codingagent带技能的编码 Agent理解核心读ReActAgent.java源码理解 ReAct 循环的实现尝试扩展看agentscope-extensions/中感兴趣的扩展如 MCP、RAG、长期记忆