前言Java开发者如何快速构建企业级AI Agent应用最近这段时间AI Agent智能体这个概念火得一塌糊涂。从OpenClaw到Claude Code从Manus到各种Agent框架仿佛一夜之间“让AI自己干活”成了技术圈最热门的话题。但很多Java开发者在尝试入局的时候发现了一个尴尬的问题——市面上主流的Agent框架绝大多数是Python生态的。LangChainPython的。AutoGenPython的。CrewAI还是Python的。“三哥我们团队都是Java技术栈难道要为了做Agent专门去学Python吗”当然不用。阿里巴巴开源的AgentScope-Java就是专为Java开发者打造的智能体开发框架。今天这篇文章就专门跟大家一起聊聊AgentScope-Java希望对你会有所帮助。一、AgentScope-Java到底是什么1.1 一句话说清AgentScope-Java是阿里巴巴开源的一个面向智能体Agent编程的Java框架用于构建基于大语言模型LLM的智能体应用。它的核心目标很明确——让Java开发者用自己熟悉的语言和工具链快速构建生产级的AI Agent应用。1.2 AgentScope-Java解决了什么问题在AgentScope出现之前Java开发者想做Agent应用基本只有两条路第一条路用Python框架。学新语言、搭新环境、维护两套技术栈团队分裂。第二条路自己从零造轮子。写ReAct循环、做工具调用、管理对话记忆、处理多Agent协作……每一项都是大工程。AgentScope做的事情就是把Agent开发需要的所有基础设施——ReAct推理循环、工具调用、记忆管理、多智能体协作、分布式部署——全部封装成一个Java框架开箱即用。1.3 和Spring AI Alibaba有什么区别很多小伙伴可能会问“三哥阿里巴巴不是有Spring AI Alibaba吗跟这个有什么区别”这是一个非常好的问题。两者定位完全不同Spring AI Alibaba偏重“AI能力接入”——让Java应用方便地调用各种大模型API适合做RAG、聊天机器人等场景AgentScope-Java偏重“Agent工程化”——让开发者构建具有自主推理、工具调用、多Agent协作能力的智能体系统两者不是竞争关系而是可以配合使用的关系。AgentScope负责Agent的“大脑”推理、决策、行动Spring AI Alibaba负责“感官”接入各种AI能力。二、核心概念AgentScope-Java 2.0的核心设计思路非常清晰——提供两种Agent覆盖从简单到复杂的所有场景。2.1 ReActAgent最轻量的推理核心ReActAgent是AgentScope最基础的Agent实现它实现了完整的ReActReasoning Acting推理循环。所谓ReAct就是让LLM在“思考→行动→观察→再思考”的循环中自主完成任务ReActAgent适合轻量级、单次对话、不需要持久化状态的场景。2.2 HarnessAgent生产级的工程化封装HarnessAgent是AgentScope 2.0推荐的生产级入口。它在ReActAgent的基础上额外封装了一套工程化能力工程能力说明工作区WorkspaceAgent的人格、知识、技能、记忆统一沉淀在结构化工作区中长期记忆Memory跨会话的记忆持久化和语义检索会话持久化Session对话状态自动保存重启后无缝恢复子Agent编排主Agent可以委派任务给多个子Agent沙箱隔离Sandbox工具执行在隔离环境中运行保证安全上下文压缩Compaction长对话自动压缩防止上下文溢出核心区别ReActAgent解决的是“这一次对话怎么跑”HarnessAgent解决的是“长期运行的Agent怎么稳定、安全、可扩展”。图片我的建议大部分场景直接用HarnessAgent。虽然看起来多了一些配置但这些工程能力在生产环境中几乎是必需的。三、5分钟跑通第一个Agent3.1 前置要求AgentScope-Java 2.0需要JDK 17或更高版本推荐使用Maven 3.9。检查你的Java版本java -version # 需要输出 17 或更高3.2 添加Maven依赖AgentScope的依赖设计很清晰——核心模块和模型扩展分离。第一步添加核心依赖dependency groupIdio.agentscope/groupId artifactIdagentscope-harness/artifactId version2.0.0/version /dependencyagentscope-harness会自动引入agentscope-core包含了ReActAgent和HarnessAgent的核心实现。第二步添加模型扩展根据你要用的模型添加对应的扩展依赖。以通义千问DashScope为例dependency groupIdio.agentscope/groupId artifactIdagentscope-extensions-model-dashscope/artifactId version2.0.0/version /dependency3.3 配置API KeyAgentScope通过环境变量读取API Key。以DashScope为例export DASHSCOPE_API_KEYsk-你的API密钥如果你用的是DeepSeek或OpenAI兼容的服务export OPENAI_API_KEYsk-你的API密钥3.4 第一个Agent最简示例下面这段代码是AgentScope-Java的“Hello World”——创建一个能对话的Agent。package com.example; import io.agentscope.core.ReActAgent; import io.agentscope.core.agent.RuntimeContext; import io.agentscope.core.formatter.openai.OpenAIChatFormatter; import io.agentscope.core.message.UserMessage; import io.agentscope.core.model.GenerateOptions; import io.agentscope.core.model.OpenAIChatModel; import io.agentscope.core.tool.Toolkit; import io.agentscope.harness.HarnessAgent; import java.nio.file.Path; public class FirstAgent { public static void main(String[] args) { // 1. 创建Model以DeepSeek为例 String apiKey System.getenv(DEEPSEEK_API_KEY); OpenAIChatModel model OpenAIChatModel.builder() .apiKey(apiKey) .modelName(deepseek-chat) .baseUrl(https://api.deepseek.com) .stream(true) // 启用流式输出 .enableThinking(true) // 启用思考模式 .formatter(new OpenAIChatFormatter()) .defaultOptions(GenerateOptions.builder() .thinkingBudget(1024) // 思考token预算 .build()) .build(); // 2. 创建Agent HarnessAgent agent HarnessAgent.builder() .name(Assistant) .sysPrompt(你是一个乐于助人的AI助手请友好简洁地回答问题。) .model(model) .workspace(Path.of(./workspace)) .build(); // 3. 发送消息并获取回复 UserMessage userMsg new UserMessage(你好请介绍一下自己); String reply agent.call(userMsg, RuntimeContext.empty()) .block() .getTextContent(); System.out.println(reply); } }代码拆解第1步创建OpenAIChatModel配置API地址、模型名称、是否流式输出、是否启用思考模式第2步用HarnessAgent.builder()创建Agent指定名称、系统提示词、模型和工作区目录第3步构造UserMessage调用agent.call()获取回复运行后你会看到Agent的回复。整个过程不到10行核心代码一个能对话的AI Agent就跑起来了。四、工具系统让Agent“长出手脚”有些小伙伴可能会说“Agent光会聊天有什么用我要的是它能调用工具、执行操作”别急。AgentScope的工具系统就是干这个的。没有工具的Agent只能“纸上谈兵”。AgentScope通过Tool注解让开发者可以把任意Java方法注册为Agent可调用的工具。4.1 定义工具用Tool和ToolParam注解定义工具import io.agentscope.core.tool.Tool; import io.agentscope.core.tool.ToolParam; public class WeatherTools { Tool(name get_weather, description 获取指定城市的当前天气) public String getWeather( ToolParam(name city, description 城市名称例如北京) String city ) { // 这里可以调用真实的天气API return city 今天晴温度25°C; } Tool(name calculate, description 执行数学计算) public double calculate( ToolParam(name expression, description 数学表达式) String expression ) { // 这里可以集成表达式计算引擎 return 42.0; } }关键点Tool的name是工具的唯一标识Agent调用时使用此名称Tool的description描述工具功能Agent根据此描述决定何时调用ToolParam标注在方法参数上描述参数的含义4.2 注册工具创建Toolkit实例将工具注册进去// 创建工具集 Toolkit toolkit new Toolkit(); toolkit.registerTool(new WeatherTools()); // 将工具集传给Agent HarnessAgent agent HarnessAgent.builder() .name(Assistant) .sysPrompt(你是一个可以使用工具的助手。) .model(model) .toolkit(toolkit) // 注册工具 .workspace(Path.of(./workspace)) .build();4.3 带工具的Agentpublic class ToolCallingExample { public static void main(String[] args) { // 创建Model OpenAIChatModel model ...; // 创建工具集 Toolkit toolkit new Toolkit(); toolkit.registerTool(new WeatherTools()); // 创建Agent并注册工具 HarnessAgent agent HarnessAgent.builder() .name(Assistant) .sysPrompt(你是一个可以使用工具的助手。当用户问天气时调用get_weather工具。) .model(model) .toolkit(toolkit) .build(); // 用户提问Agent会自动决定是否调用工具 UserMessage userMsg new UserMessage(北京今天天气怎么样); String reply agent.call(userMsg, RuntimeContext.empty()) .block() .getTextContent(); System.out.println(reply); // 输出北京今天晴温度25°C } }关键理解Agent在ReAct循环中会自主决定是否调用工具、调用哪个工具、何时调用。开发者只需要定义工具Agent自己会判断“什么时候该用”。五、多Agent协作有些小伙伴可能会问“一个Agent不够用怎么办复杂任务需要多个Agent协作怎么搞”AgentScope 2.0提供了orchestrator workers模式来实现多Agent协作。5.1 核心模式2.0版本的核心理念是主Agent扮演“主持人”子Agent扮演“参与者”。主Agent负责接收用户任务、拆解任务、委派给子Agent、汇总结果。5.2 定义子Agent子Agent可以通过文件驱动的方式定义——在workspace/subagents/目录下创建.md文件workspace/subagents/weather.mdid: weather description: 查城市天气。输入城市名 日期。输出温度区间、是否下雨。 sysPrompt: | 你是一个气象助理。用户给你一个城市和日期你返回 - 温度高/低 - 是否下雨 - 是否需要带伞 严格三行不超过60字。workspace/subagents/flight.mdid: flight description: 查航班信息。输入出发城市 到达城市 日期。 sysPrompt: | 你是一个航班查询助理。根据用户输入给出一个mock航班号和起降时间。5.3 Java端补强如果子Agent需要调用Java端的工具比如真实的天气API可以在Java端再注册一份import io.agentscope.harness.agent.subagent.SubagentDeclaration; // Java端补强weather子Agent SubagentDeclaration weather SubagentDeclaration.builder() .name(weather) .description(查城市天气输入城市日期返回温度区间和是否带伞) .inlineAgentsBody(你是一个气象助理会调用工具查询真实天气) .build(); // 在HarnessAgent中注册子Agent HarnessAgent agent HarnessAgent.builder() .name(TravelAssistant) .model(model) .subagent(weather) // 注册子Agent .workspace(Path.of(./workspace)) .build();主Agent会自己决定是否需要调用子Agent、调用哪些子Agent、调用顺序是什么。六、底层原理6.1 分层架构AgentScope-Java采用经典的分层架构设计图片AgentScope的整体架构可以清晰分为四层模型适配层负责与不同LLM提供商通信支持OpenAI协议、DashScope通义千问、Anthropic Claude、Google Gemini等ReAct推理层实现ReAct推理循环思考→行动→观察→再思考是整个Agent的“大脑”Harness工程化层在ReAct之上封装了工作区、记忆、会话、子Agent、沙箱等工程能力应用层你的业务代码6.2 ReAct推理循环的执行流程当一个用户消息进入Agent时ReAct循环的执行流程如下图片HarnessAgent在ReAct循环的关键时机插入了Hook实现了工作区加载、记忆读写、会话持久化等功能。6.3 分布式部署架构AgentScope 2.0最核心的升级之一就是原生支持分布式部署。在单机开发阶段状态默认落到本地workspace目录。进入生产部署后只需把状态后端切换为分布式存储图片同一份业务代码只需切换存储后端就能从单机模式切换到分布式模式。任意副本都能恢复任意用户的完整上下文。七、实战案例多Agent天气助手有些小伙伴可能会说“单个Agent我跑通了但真实业务需要多个Agent协作怎么办”AgentScope 2.0提供了文件驱动的Subagent机制。你只需要在workspace/subagents/目录下放几个.md文件主Agent就会自己决定“什么时候该叫谁”。我们来看一个完整的实战——旅行助手。用户问“我明天从北京飞杭州落地后去西湖要带伞吗”1.x时代你需要写代码串三个Agent天气→航班→景点。2.0时代主Agent自己决定先查天气还是航班三个Subagent并行启动。7.1 工程结构travel-assistant/ ├── pom.xml └── workspace/ ├── MEMORY.md ├── subagents/ │ ├── weather.md │ ├── flight.md │ └── attraction.md └── state/ └── session-*.json # JsonFileAgentStateStore自动生成7.2 三个Subagent文件workspace/subagents/weather.mdid: weather description: | 查城市天气。 输入城市名 日期YYYY-MM-DD。 输出温度区间、是否下雨、是否需要带伞。 sysPrompt: | 你是一个气象助理。 用户给你一个城市和日期你返回 - 温度高/低摄氏度 - 是否下雨 - 是否需要带伞 严格三行不超过60字。workspace/subagents/flight.mdid: flight description: | 查航班信息mock。 输入出发城市 到达城市 日期。 输出航班号、起飞时间、到达时间。 sysPrompt: | 你是一个航班查询助理。 根据用户输入给出一个mock航班号和起降时间。 注意测试环境无需真查询给出合理mock即可。workspace/subagents/attraction.mdid: attraction description: | 景点信息助理mock。 输入城市 景点名。 输出开放时间、是否需要预约、周边交通。 sysPrompt: | 你是一个导游助理。 根据用户输入给出景点的实用信息。这三份描述对主Agent来说是路由表——主Agent全靠description决定要不要spawn它们。7.3 Java端补强Subagent如果某个Subagent需要调用Java端的真实工具比如weather.md背后要接真的天气API可以在Java端再注册一份——HarnessAgent会把文件Java声明合并import io.agentscope.core.model.DashScopeChatModel; import io.agentscope.core.tool.Toolkit; import io.agentscope.harness.HarnessAgent; import io.agentscope.harness.agent.subagent.SubagentDeclaration; import java.nio.file.Path; public class TravelAssistant { public static void main(String[] args) { // 1. 创建Model DashScopeChatModel model DashScopeChatModel.builder() .apiKey(System.getenv(DASHSCOPE_API_KEY)) .modelName(qwen-plus) .build(); // 2. 创建Toolkit并注册天气查询工具 Toolkit toolkit new Toolkit(); toolkit.registerTool(new WeatherLookupTool()); // 真实的天气API工具 // 3. Java端补强weather subagent——tools白名单过滤继承自父agent的工具 SubagentDeclaration weather SubagentDeclaration.builder() .name(weather) .description(查城市天气输入城市日期返回温度区间和是否带伞) .inlineAgentsBody(你是一个气象助理会调用工具查询真实天气) .build(); // 4. 创建HarnessAgent注册subagent HarnessAgent agent HarnessAgent.builder() .name(TravelAssistant) .model(model) .toolkit(toolkit) .workspace(Path.of(./workspace)) .subagent(weather) // Java端补强的subagent .build(); // 5. 运行 UserMessage userMsg new UserMessage( 我明天从北京飞杭州落地后去西湖要带伞吗 ); String reply agent.call(userMsg, RuntimeContext.empty()) .block() .getTextContent(); System.out.println(reply); } }关键理解主Agent在推理过程中会自主决定是否需要调用Subagent、调用哪些Subagent、调用的顺序是什么。整个“编排”过程由LLM完成不需要你写死Pipeline。八、实战案例MCP协议工具有些小伙伴可能会说“工具调用要自己写Java类如果要接入GitHub、数据库、Slack这些外部服务难道每个都要自己封装”不用。AgentScope 2.0支持MCPModel Context Protocol协议你只需要在workspace/tools.json里一行声明一个MCP serverAgent启动时自动发现并注册工具。8.1 什么是MCPMCP是Anthropic在2024年推出的开放协议让LLM应用以统一方式发现并调用外部工具。AgentScope 2.0把MCP server作为Agent工具的一种“来源”——你在tools.json里声明一个MCP serverAgent启动时通过stdio或sse协议连上它自动把server暴露的工具当作Agent自己的tool。8.2 第一个MCP集成workspace/tools.json{ mcpServers: { github: { command: npx, args: [-y, modelcontextprotocol/server-github], env: { GITHUB_PERSONAL_ACCESS_TOKEN: ${env:GITHUB_TOKEN} } } } }HarnessAgent.builder().workspace(path)启动时会自动扫描workspace/tools.json的mcpServers段、连接每个server、把工具注册到Agent——不需要额外开关HarnessAgent agent HarnessAgent.builder() .name(GitHubAssistant) .model(model) .workspace(Path.of(./workspace)) // 自动加载tools.json .build();跑起来后Agent就能调用GitHub MCP server暴露的create_issue、list_repos、search_code等工具了。8.3 三种连接方式MCP支持三种传输协议协议适用场景声明方式stdio本地进程最常见commandargssse远程HTTP SSE serverurlheadersws双向WebSocketurlheadersstdio示例接入本地文件系统{ mcpServers: { filesystem: { command: npx, args: [-y, modelcontextprotocol/server-filesystem, ./data] } } }sse示例接入远程知识库{ mcpServers: { remote-knowledge: { url: https://mcp.example.com/sse, headers: { Authorization: Bearer ${env:MCP_TOKEN} } } } }8.4 不想写JSONJava代码直接配有时候你想在代码里动态拼参数——比如token从环境变量读、超时按环境切换。这时候可以直接在Java代码里配import io.agentscope.harness.agent.tools.McpServerConfig; import io.agentscope.harness.agent.tools.ToolsConfig; ToolsConfig cfg new ToolsConfig(); MapString, McpServerConfig servers new LinkedHashMap(); McpServerConfig github new McpServerConfig(); github.setTransport(stdio); github.setCommand(npx); github.setArgs(List.of(-y, modelcontextprotocol/server-github)); github.setEnv(Map.of(GITHUB_PERSONAL_ACCESS_TOKEN, System.getenv(GITHUB_TOKEN))); servers.put(github, github); cfg.setMcpServers(servers); // 然后通过HarnessAgent的toolsConfig()方法传入效果和tools.json完全一样。8.5 常见的MCP ServerMCP Server用途安装命令server-githubGitHub操作创建Issue、搜索代码等npx -y modelcontextprotocol/server-githubserver-filesystem本地文件系统读写npx -y modelcontextprotocol/server-filesystemserver-postgresPostgreSQL数据库查询npx -y modelcontextprotocol/server-postgresserver-slackSlack消息发送npx -y modelcontextprotocol/server-slackserver-puppeteer浏览器自动化网页抓取、截图npx -y modelcontextprotocol/server-puppeteer接入MCP生态后AgentScope的Agent能力边界被极大地扩展了——只要能通过MCP暴露的工具Agent都能调用。九、优缺点优点1. Java生态无缝集成AgentScope完美兼容Spring Boot、Spring Cloud、Maven等Java主流技术栈。对于Java团队来说学习曲线非常平缓。2. 双Agent架构覆盖全场景ReActAgent满足轻量级需求HarnessAgent覆盖生产级工程需求。从原型到生产一套框架全搞定。3. 完善的工具系统通过Tool注解即可将任意Java方法注册为Agent工具Agent在ReAct循环中自主决定调用时机。4. 原生多Agent协作内置orchestrator workers模式主Agent可以委派任务给多个子Agent支持同步和异步两种模式。5. 生产级工程能力工作区、长期记忆、会话持久化、上下文压缩、沙箱隔离——HarnessAgent把企业级Agent需要的工程能力全部打包。6. 分布式部署原生支持支持Redis、MySQL、PostgreSQL等多种状态存储后端支持Kubernetes水平扩展。7. 多模型支持内置OpenAI协议DeepSeek、GLM、Ollama等、DashScope通义千问、Anthropic Claude、Google Gemini。8. MCP/A2A协议支持支持Model Context Protocol和Agent-to-Agent协议可以接入MCP生态的工具和服务。缺点1. 相对较新AgentScope-Java 1.0于2025年12月发布2.0于2026年7月GA。相比Spring AI等成熟框架社区积累较少。2. 学习曲线HarnessAgent的工程化概念工作区、记忆、子Agent等需要一定的学习成本。3. 生态不如Spring AI丰富目前第三方集成和扩展的数量不如Spring AI Alibaba。4. 文档偏英文虽然官方提供了中文文档但部分深度内容仍以英文为主。十、适用场景场景推荐程度理由智能客服系统强烈推荐多Agent协作知识库RAG运维诊断Agent强烈推荐自主推理工具调用日志分析金融分析Agent强烈推荐结构化输出多步推理代码辅助Agent推荐工具调用代码执行沙箱企业内部知识助手推荐RAG长期记忆简单聊天机器人可能过度设计用Spring AI Alibaba即可已有Spring AI生态需评估两者可以配合使用总结回到最初的问题Java开发者怎么做AI AgentAgentScope-Java给出了一个非常完整的答案。它不是“把Python框架翻译成Java”的简单移植而是从Java生态的实际情况出发专门为Java开发者设计的Agent框架。ReActAgent让你快速跑通Agent原型HarnessAgent让你把原型变成生产级应用。Tool注解让工具定义像写普通Java方法一样自然子Agent系统让多Agent协作变得清晰可控。最关键的是——它让Java开发者不需要为了做Agent去学Python。学习资源推荐如果你想更深入地学习大模型以下是一些非常有价值的学习资源这些资源将帮助你从不同角度学习大模型提升你的实践能力。一、全套AGI大模型学习路线AI大模型时代的学习之旅从基础到前沿掌握人工智能的核心技能因篇幅有限仅展示部分资料需要点击文章最下方名片即可前往获取二、640套AI大模型报告合集这套包含640份报告的合集涵盖了AI大模型的理论研究、技术实现、行业应用等多个方面。无论您是科研人员、工程师还是对AI大模型感兴趣的爱好者这套报告合集都将为您提供宝贵的信息和启示因篇幅有限仅展示部分资料需要点击文章最下方名片即可前往获取三、AI大模型经典PDF籍随着人工智能技术的飞速发展AI大模型已经成为了当今科技领域的一大热点。这些大型预训练模型如GPT-3、BERT、XLNet等以其强大的语言理解和生成能力正在改变我们对人工智能的认识。 那以下这些PDF籍就是非常不错的学习资源。因篇幅有限仅展示部分资料需要点击文章最下方名片即可前往获取四、AI大模型商业化落地方案作为普通人入局大模型时代需要持续学习和实践不断提高自己的技能和认知水平同时也需要有责任感和伦理意识为人工智能的健康发展贡献力量。
AgentScope入门指南
前言Java开发者如何快速构建企业级AI Agent应用最近这段时间AI Agent智能体这个概念火得一塌糊涂。从OpenClaw到Claude Code从Manus到各种Agent框架仿佛一夜之间“让AI自己干活”成了技术圈最热门的话题。但很多Java开发者在尝试入局的时候发现了一个尴尬的问题——市面上主流的Agent框架绝大多数是Python生态的。LangChainPython的。AutoGenPython的。CrewAI还是Python的。“三哥我们团队都是Java技术栈难道要为了做Agent专门去学Python吗”当然不用。阿里巴巴开源的AgentScope-Java就是专为Java开发者打造的智能体开发框架。今天这篇文章就专门跟大家一起聊聊AgentScope-Java希望对你会有所帮助。一、AgentScope-Java到底是什么1.1 一句话说清AgentScope-Java是阿里巴巴开源的一个面向智能体Agent编程的Java框架用于构建基于大语言模型LLM的智能体应用。它的核心目标很明确——让Java开发者用自己熟悉的语言和工具链快速构建生产级的AI Agent应用。1.2 AgentScope-Java解决了什么问题在AgentScope出现之前Java开发者想做Agent应用基本只有两条路第一条路用Python框架。学新语言、搭新环境、维护两套技术栈团队分裂。第二条路自己从零造轮子。写ReAct循环、做工具调用、管理对话记忆、处理多Agent协作……每一项都是大工程。AgentScope做的事情就是把Agent开发需要的所有基础设施——ReAct推理循环、工具调用、记忆管理、多智能体协作、分布式部署——全部封装成一个Java框架开箱即用。1.3 和Spring AI Alibaba有什么区别很多小伙伴可能会问“三哥阿里巴巴不是有Spring AI Alibaba吗跟这个有什么区别”这是一个非常好的问题。两者定位完全不同Spring AI Alibaba偏重“AI能力接入”——让Java应用方便地调用各种大模型API适合做RAG、聊天机器人等场景AgentScope-Java偏重“Agent工程化”——让开发者构建具有自主推理、工具调用、多Agent协作能力的智能体系统两者不是竞争关系而是可以配合使用的关系。AgentScope负责Agent的“大脑”推理、决策、行动Spring AI Alibaba负责“感官”接入各种AI能力。二、核心概念AgentScope-Java 2.0的核心设计思路非常清晰——提供两种Agent覆盖从简单到复杂的所有场景。2.1 ReActAgent最轻量的推理核心ReActAgent是AgentScope最基础的Agent实现它实现了完整的ReActReasoning Acting推理循环。所谓ReAct就是让LLM在“思考→行动→观察→再思考”的循环中自主完成任务ReActAgent适合轻量级、单次对话、不需要持久化状态的场景。2.2 HarnessAgent生产级的工程化封装HarnessAgent是AgentScope 2.0推荐的生产级入口。它在ReActAgent的基础上额外封装了一套工程化能力工程能力说明工作区WorkspaceAgent的人格、知识、技能、记忆统一沉淀在结构化工作区中长期记忆Memory跨会话的记忆持久化和语义检索会话持久化Session对话状态自动保存重启后无缝恢复子Agent编排主Agent可以委派任务给多个子Agent沙箱隔离Sandbox工具执行在隔离环境中运行保证安全上下文压缩Compaction长对话自动压缩防止上下文溢出核心区别ReActAgent解决的是“这一次对话怎么跑”HarnessAgent解决的是“长期运行的Agent怎么稳定、安全、可扩展”。图片我的建议大部分场景直接用HarnessAgent。虽然看起来多了一些配置但这些工程能力在生产环境中几乎是必需的。三、5分钟跑通第一个Agent3.1 前置要求AgentScope-Java 2.0需要JDK 17或更高版本推荐使用Maven 3.9。检查你的Java版本java -version # 需要输出 17 或更高3.2 添加Maven依赖AgentScope的依赖设计很清晰——核心模块和模型扩展分离。第一步添加核心依赖dependency groupIdio.agentscope/groupId artifactIdagentscope-harness/artifactId version2.0.0/version /dependencyagentscope-harness会自动引入agentscope-core包含了ReActAgent和HarnessAgent的核心实现。第二步添加模型扩展根据你要用的模型添加对应的扩展依赖。以通义千问DashScope为例dependency groupIdio.agentscope/groupId artifactIdagentscope-extensions-model-dashscope/artifactId version2.0.0/version /dependency3.3 配置API KeyAgentScope通过环境变量读取API Key。以DashScope为例export DASHSCOPE_API_KEYsk-你的API密钥如果你用的是DeepSeek或OpenAI兼容的服务export OPENAI_API_KEYsk-你的API密钥3.4 第一个Agent最简示例下面这段代码是AgentScope-Java的“Hello World”——创建一个能对话的Agent。package com.example; import io.agentscope.core.ReActAgent; import io.agentscope.core.agent.RuntimeContext; import io.agentscope.core.formatter.openai.OpenAIChatFormatter; import io.agentscope.core.message.UserMessage; import io.agentscope.core.model.GenerateOptions; import io.agentscope.core.model.OpenAIChatModel; import io.agentscope.core.tool.Toolkit; import io.agentscope.harness.HarnessAgent; import java.nio.file.Path; public class FirstAgent { public static void main(String[] args) { // 1. 创建Model以DeepSeek为例 String apiKey System.getenv(DEEPSEEK_API_KEY); OpenAIChatModel model OpenAIChatModel.builder() .apiKey(apiKey) .modelName(deepseek-chat) .baseUrl(https://api.deepseek.com) .stream(true) // 启用流式输出 .enableThinking(true) // 启用思考模式 .formatter(new OpenAIChatFormatter()) .defaultOptions(GenerateOptions.builder() .thinkingBudget(1024) // 思考token预算 .build()) .build(); // 2. 创建Agent HarnessAgent agent HarnessAgent.builder() .name(Assistant) .sysPrompt(你是一个乐于助人的AI助手请友好简洁地回答问题。) .model(model) .workspace(Path.of(./workspace)) .build(); // 3. 发送消息并获取回复 UserMessage userMsg new UserMessage(你好请介绍一下自己); String reply agent.call(userMsg, RuntimeContext.empty()) .block() .getTextContent(); System.out.println(reply); } }代码拆解第1步创建OpenAIChatModel配置API地址、模型名称、是否流式输出、是否启用思考模式第2步用HarnessAgent.builder()创建Agent指定名称、系统提示词、模型和工作区目录第3步构造UserMessage调用agent.call()获取回复运行后你会看到Agent的回复。整个过程不到10行核心代码一个能对话的AI Agent就跑起来了。四、工具系统让Agent“长出手脚”有些小伙伴可能会说“Agent光会聊天有什么用我要的是它能调用工具、执行操作”别急。AgentScope的工具系统就是干这个的。没有工具的Agent只能“纸上谈兵”。AgentScope通过Tool注解让开发者可以把任意Java方法注册为Agent可调用的工具。4.1 定义工具用Tool和ToolParam注解定义工具import io.agentscope.core.tool.Tool; import io.agentscope.core.tool.ToolParam; public class WeatherTools { Tool(name get_weather, description 获取指定城市的当前天气) public String getWeather( ToolParam(name city, description 城市名称例如北京) String city ) { // 这里可以调用真实的天气API return city 今天晴温度25°C; } Tool(name calculate, description 执行数学计算) public double calculate( ToolParam(name expression, description 数学表达式) String expression ) { // 这里可以集成表达式计算引擎 return 42.0; } }关键点Tool的name是工具的唯一标识Agent调用时使用此名称Tool的description描述工具功能Agent根据此描述决定何时调用ToolParam标注在方法参数上描述参数的含义4.2 注册工具创建Toolkit实例将工具注册进去// 创建工具集 Toolkit toolkit new Toolkit(); toolkit.registerTool(new WeatherTools()); // 将工具集传给Agent HarnessAgent agent HarnessAgent.builder() .name(Assistant) .sysPrompt(你是一个可以使用工具的助手。) .model(model) .toolkit(toolkit) // 注册工具 .workspace(Path.of(./workspace)) .build();4.3 带工具的Agentpublic class ToolCallingExample { public static void main(String[] args) { // 创建Model OpenAIChatModel model ...; // 创建工具集 Toolkit toolkit new Toolkit(); toolkit.registerTool(new WeatherTools()); // 创建Agent并注册工具 HarnessAgent agent HarnessAgent.builder() .name(Assistant) .sysPrompt(你是一个可以使用工具的助手。当用户问天气时调用get_weather工具。) .model(model) .toolkit(toolkit) .build(); // 用户提问Agent会自动决定是否调用工具 UserMessage userMsg new UserMessage(北京今天天气怎么样); String reply agent.call(userMsg, RuntimeContext.empty()) .block() .getTextContent(); System.out.println(reply); // 输出北京今天晴温度25°C } }关键理解Agent在ReAct循环中会自主决定是否调用工具、调用哪个工具、何时调用。开发者只需要定义工具Agent自己会判断“什么时候该用”。五、多Agent协作有些小伙伴可能会问“一个Agent不够用怎么办复杂任务需要多个Agent协作怎么搞”AgentScope 2.0提供了orchestrator workers模式来实现多Agent协作。5.1 核心模式2.0版本的核心理念是主Agent扮演“主持人”子Agent扮演“参与者”。主Agent负责接收用户任务、拆解任务、委派给子Agent、汇总结果。5.2 定义子Agent子Agent可以通过文件驱动的方式定义——在workspace/subagents/目录下创建.md文件workspace/subagents/weather.mdid: weather description: 查城市天气。输入城市名 日期。输出温度区间、是否下雨。 sysPrompt: | 你是一个气象助理。用户给你一个城市和日期你返回 - 温度高/低 - 是否下雨 - 是否需要带伞 严格三行不超过60字。workspace/subagents/flight.mdid: flight description: 查航班信息。输入出发城市 到达城市 日期。 sysPrompt: | 你是一个航班查询助理。根据用户输入给出一个mock航班号和起降时间。5.3 Java端补强如果子Agent需要调用Java端的工具比如真实的天气API可以在Java端再注册一份import io.agentscope.harness.agent.subagent.SubagentDeclaration; // Java端补强weather子Agent SubagentDeclaration weather SubagentDeclaration.builder() .name(weather) .description(查城市天气输入城市日期返回温度区间和是否带伞) .inlineAgentsBody(你是一个气象助理会调用工具查询真实天气) .build(); // 在HarnessAgent中注册子Agent HarnessAgent agent HarnessAgent.builder() .name(TravelAssistant) .model(model) .subagent(weather) // 注册子Agent .workspace(Path.of(./workspace)) .build();主Agent会自己决定是否需要调用子Agent、调用哪些子Agent、调用顺序是什么。六、底层原理6.1 分层架构AgentScope-Java采用经典的分层架构设计图片AgentScope的整体架构可以清晰分为四层模型适配层负责与不同LLM提供商通信支持OpenAI协议、DashScope通义千问、Anthropic Claude、Google Gemini等ReAct推理层实现ReAct推理循环思考→行动→观察→再思考是整个Agent的“大脑”Harness工程化层在ReAct之上封装了工作区、记忆、会话、子Agent、沙箱等工程能力应用层你的业务代码6.2 ReAct推理循环的执行流程当一个用户消息进入Agent时ReAct循环的执行流程如下图片HarnessAgent在ReAct循环的关键时机插入了Hook实现了工作区加载、记忆读写、会话持久化等功能。6.3 分布式部署架构AgentScope 2.0最核心的升级之一就是原生支持分布式部署。在单机开发阶段状态默认落到本地workspace目录。进入生产部署后只需把状态后端切换为分布式存储图片同一份业务代码只需切换存储后端就能从单机模式切换到分布式模式。任意副本都能恢复任意用户的完整上下文。七、实战案例多Agent天气助手有些小伙伴可能会说“单个Agent我跑通了但真实业务需要多个Agent协作怎么办”AgentScope 2.0提供了文件驱动的Subagent机制。你只需要在workspace/subagents/目录下放几个.md文件主Agent就会自己决定“什么时候该叫谁”。我们来看一个完整的实战——旅行助手。用户问“我明天从北京飞杭州落地后去西湖要带伞吗”1.x时代你需要写代码串三个Agent天气→航班→景点。2.0时代主Agent自己决定先查天气还是航班三个Subagent并行启动。7.1 工程结构travel-assistant/ ├── pom.xml └── workspace/ ├── MEMORY.md ├── subagents/ │ ├── weather.md │ ├── flight.md │ └── attraction.md └── state/ └── session-*.json # JsonFileAgentStateStore自动生成7.2 三个Subagent文件workspace/subagents/weather.mdid: weather description: | 查城市天气。 输入城市名 日期YYYY-MM-DD。 输出温度区间、是否下雨、是否需要带伞。 sysPrompt: | 你是一个气象助理。 用户给你一个城市和日期你返回 - 温度高/低摄氏度 - 是否下雨 - 是否需要带伞 严格三行不超过60字。workspace/subagents/flight.mdid: flight description: | 查航班信息mock。 输入出发城市 到达城市 日期。 输出航班号、起飞时间、到达时间。 sysPrompt: | 你是一个航班查询助理。 根据用户输入给出一个mock航班号和起降时间。 注意测试环境无需真查询给出合理mock即可。workspace/subagents/attraction.mdid: attraction description: | 景点信息助理mock。 输入城市 景点名。 输出开放时间、是否需要预约、周边交通。 sysPrompt: | 你是一个导游助理。 根据用户输入给出景点的实用信息。这三份描述对主Agent来说是路由表——主Agent全靠description决定要不要spawn它们。7.3 Java端补强Subagent如果某个Subagent需要调用Java端的真实工具比如weather.md背后要接真的天气API可以在Java端再注册一份——HarnessAgent会把文件Java声明合并import io.agentscope.core.model.DashScopeChatModel; import io.agentscope.core.tool.Toolkit; import io.agentscope.harness.HarnessAgent; import io.agentscope.harness.agent.subagent.SubagentDeclaration; import java.nio.file.Path; public class TravelAssistant { public static void main(String[] args) { // 1. 创建Model DashScopeChatModel model DashScopeChatModel.builder() .apiKey(System.getenv(DASHSCOPE_API_KEY)) .modelName(qwen-plus) .build(); // 2. 创建Toolkit并注册天气查询工具 Toolkit toolkit new Toolkit(); toolkit.registerTool(new WeatherLookupTool()); // 真实的天气API工具 // 3. Java端补强weather subagent——tools白名单过滤继承自父agent的工具 SubagentDeclaration weather SubagentDeclaration.builder() .name(weather) .description(查城市天气输入城市日期返回温度区间和是否带伞) .inlineAgentsBody(你是一个气象助理会调用工具查询真实天气) .build(); // 4. 创建HarnessAgent注册subagent HarnessAgent agent HarnessAgent.builder() .name(TravelAssistant) .model(model) .toolkit(toolkit) .workspace(Path.of(./workspace)) .subagent(weather) // Java端补强的subagent .build(); // 5. 运行 UserMessage userMsg new UserMessage( 我明天从北京飞杭州落地后去西湖要带伞吗 ); String reply agent.call(userMsg, RuntimeContext.empty()) .block() .getTextContent(); System.out.println(reply); } }关键理解主Agent在推理过程中会自主决定是否需要调用Subagent、调用哪些Subagent、调用的顺序是什么。整个“编排”过程由LLM完成不需要你写死Pipeline。八、实战案例MCP协议工具有些小伙伴可能会说“工具调用要自己写Java类如果要接入GitHub、数据库、Slack这些外部服务难道每个都要自己封装”不用。AgentScope 2.0支持MCPModel Context Protocol协议你只需要在workspace/tools.json里一行声明一个MCP serverAgent启动时自动发现并注册工具。8.1 什么是MCPMCP是Anthropic在2024年推出的开放协议让LLM应用以统一方式发现并调用外部工具。AgentScope 2.0把MCP server作为Agent工具的一种“来源”——你在tools.json里声明一个MCP serverAgent启动时通过stdio或sse协议连上它自动把server暴露的工具当作Agent自己的tool。8.2 第一个MCP集成workspace/tools.json{ mcpServers: { github: { command: npx, args: [-y, modelcontextprotocol/server-github], env: { GITHUB_PERSONAL_ACCESS_TOKEN: ${env:GITHUB_TOKEN} } } } }HarnessAgent.builder().workspace(path)启动时会自动扫描workspace/tools.json的mcpServers段、连接每个server、把工具注册到Agent——不需要额外开关HarnessAgent agent HarnessAgent.builder() .name(GitHubAssistant) .model(model) .workspace(Path.of(./workspace)) // 自动加载tools.json .build();跑起来后Agent就能调用GitHub MCP server暴露的create_issue、list_repos、search_code等工具了。8.3 三种连接方式MCP支持三种传输协议协议适用场景声明方式stdio本地进程最常见commandargssse远程HTTP SSE serverurlheadersws双向WebSocketurlheadersstdio示例接入本地文件系统{ mcpServers: { filesystem: { command: npx, args: [-y, modelcontextprotocol/server-filesystem, ./data] } } }sse示例接入远程知识库{ mcpServers: { remote-knowledge: { url: https://mcp.example.com/sse, headers: { Authorization: Bearer ${env:MCP_TOKEN} } } } }8.4 不想写JSONJava代码直接配有时候你想在代码里动态拼参数——比如token从环境变量读、超时按环境切换。这时候可以直接在Java代码里配import io.agentscope.harness.agent.tools.McpServerConfig; import io.agentscope.harness.agent.tools.ToolsConfig; ToolsConfig cfg new ToolsConfig(); MapString, McpServerConfig servers new LinkedHashMap(); McpServerConfig github new McpServerConfig(); github.setTransport(stdio); github.setCommand(npx); github.setArgs(List.of(-y, modelcontextprotocol/server-github)); github.setEnv(Map.of(GITHUB_PERSONAL_ACCESS_TOKEN, System.getenv(GITHUB_TOKEN))); servers.put(github, github); cfg.setMcpServers(servers); // 然后通过HarnessAgent的toolsConfig()方法传入效果和tools.json完全一样。8.5 常见的MCP ServerMCP Server用途安装命令server-githubGitHub操作创建Issue、搜索代码等npx -y modelcontextprotocol/server-githubserver-filesystem本地文件系统读写npx -y modelcontextprotocol/server-filesystemserver-postgresPostgreSQL数据库查询npx -y modelcontextprotocol/server-postgresserver-slackSlack消息发送npx -y modelcontextprotocol/server-slackserver-puppeteer浏览器自动化网页抓取、截图npx -y modelcontextprotocol/server-puppeteer接入MCP生态后AgentScope的Agent能力边界被极大地扩展了——只要能通过MCP暴露的工具Agent都能调用。九、优缺点优点1. Java生态无缝集成AgentScope完美兼容Spring Boot、Spring Cloud、Maven等Java主流技术栈。对于Java团队来说学习曲线非常平缓。2. 双Agent架构覆盖全场景ReActAgent满足轻量级需求HarnessAgent覆盖生产级工程需求。从原型到生产一套框架全搞定。3. 完善的工具系统通过Tool注解即可将任意Java方法注册为Agent工具Agent在ReAct循环中自主决定调用时机。4. 原生多Agent协作内置orchestrator workers模式主Agent可以委派任务给多个子Agent支持同步和异步两种模式。5. 生产级工程能力工作区、长期记忆、会话持久化、上下文压缩、沙箱隔离——HarnessAgent把企业级Agent需要的工程能力全部打包。6. 分布式部署原生支持支持Redis、MySQL、PostgreSQL等多种状态存储后端支持Kubernetes水平扩展。7. 多模型支持内置OpenAI协议DeepSeek、GLM、Ollama等、DashScope通义千问、Anthropic Claude、Google Gemini。8. MCP/A2A协议支持支持Model Context Protocol和Agent-to-Agent协议可以接入MCP生态的工具和服务。缺点1. 相对较新AgentScope-Java 1.0于2025年12月发布2.0于2026年7月GA。相比Spring AI等成熟框架社区积累较少。2. 学习曲线HarnessAgent的工程化概念工作区、记忆、子Agent等需要一定的学习成本。3. 生态不如Spring AI丰富目前第三方集成和扩展的数量不如Spring AI Alibaba。4. 文档偏英文虽然官方提供了中文文档但部分深度内容仍以英文为主。十、适用场景场景推荐程度理由智能客服系统强烈推荐多Agent协作知识库RAG运维诊断Agent强烈推荐自主推理工具调用日志分析金融分析Agent强烈推荐结构化输出多步推理代码辅助Agent推荐工具调用代码执行沙箱企业内部知识助手推荐RAG长期记忆简单聊天机器人可能过度设计用Spring AI Alibaba即可已有Spring AI生态需评估两者可以配合使用总结回到最初的问题Java开发者怎么做AI AgentAgentScope-Java给出了一个非常完整的答案。它不是“把Python框架翻译成Java”的简单移植而是从Java生态的实际情况出发专门为Java开发者设计的Agent框架。ReActAgent让你快速跑通Agent原型HarnessAgent让你把原型变成生产级应用。Tool注解让工具定义像写普通Java方法一样自然子Agent系统让多Agent协作变得清晰可控。最关键的是——它让Java开发者不需要为了做Agent去学Python。学习资源推荐如果你想更深入地学习大模型以下是一些非常有价值的学习资源这些资源将帮助你从不同角度学习大模型提升你的实践能力。一、全套AGI大模型学习路线AI大模型时代的学习之旅从基础到前沿掌握人工智能的核心技能因篇幅有限仅展示部分资料需要点击文章最下方名片即可前往获取二、640套AI大模型报告合集这套包含640份报告的合集涵盖了AI大模型的理论研究、技术实现、行业应用等多个方面。无论您是科研人员、工程师还是对AI大模型感兴趣的爱好者这套报告合集都将为您提供宝贵的信息和启示因篇幅有限仅展示部分资料需要点击文章最下方名片即可前往获取三、AI大模型经典PDF籍随着人工智能技术的飞速发展AI大模型已经成为了当今科技领域的一大热点。这些大型预训练模型如GPT-3、BERT、XLNet等以其强大的语言理解和生成能力正在改变我们对人工智能的认识。 那以下这些PDF籍就是非常不错的学习资源。因篇幅有限仅展示部分资料需要点击文章最下方名片即可前往获取四、AI大模型商业化落地方案作为普通人入局大模型时代需要持续学习和实践不断提高自己的技能和认知水平同时也需要有责任感和伦理意识为人工智能的健康发展贡献力量。
