简介:本文从Java开发者最熟悉的HttpClient调用痛点出发,拆解AgentScope Java的核心组件(Model、Memory、Tool、ReActAgent、Pipeline),给出可跑通的最小代码示例、工具调用与多智能体编排写法,并附Spring Boot集成、模型选型与Token成本控制建议。如果你还在纠结接哪家模型、单价多少,可以先看[百度智能云词元所](https://cloud.baidu.com/product-s/token_exchange.html?from=article),它提供模型能力查询、价格对比与统一API接入,能在选型阶段省掉大量试错。
AgentScope Java 是阿里巴巴开源的智能体开发框架的 Java 版本,定位是把「大模型调用 + 工具调用 + 多步推理 + 多智能体协作」封装成 Java 开发者熟悉的对象模型。它不是 SDK 的简单包装,而是一套抽象层:你写 Agent、Tool、Memory,框架负责拼 Prompt、解析模型返回的 tool_call、调度执行、把结果回填进上下文。
对 Java 后端来说,价值集中在三点: 统一模型接入接口 (换模型不改业务代码)、 声明式工具注册 (一个注解就是一个 Function Calling 能力)、 可编排的多 Agent 流水线 (对应你熟悉的 Pipeline / Chain 模式)。
先看这段几乎每个 Java 项目都出现过的代码:
HttpClient client = HttpClient.newHttpClient();String requestBody = """{ "model": "qwen-plus","messages": [{"role": "user", "content": "你好"}] }""";HttpRequest request = HttpRequest.newBuilder().uri(URI.create("https://dashscope.aliyuncs.com/api/v1/services/aigc/text-generation/generation")).header("Authorization", "Bearer " + apiKey).header("Content-Type", "application/json").POST(HttpRequest.BodyPublishers.ofString(requestBody)).build();HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());JSONObject json = new JSONObject(response.body());String answer = json.getJSONObject("output").getString("text");
问题不在”能不能跑”,而在”能不能维护”:
| 痛点 | 具体表现 |
|---|---|
| 手写 JSON 拼装 | 多轮 messages、system prompt、tool schema 全靠字符串拼接,转义极易出错 |
| 无智能体抽象 | 只有”请求-响应”,多步推理、工具调用循环、失败重试都要自己写状态机 |
| 模型强耦合 | URL、字段路径(output.text vs choices.message.content)写死在代码里,换供应商等于重写 |
| 与 Java 生态割裂 | 密钥、超时、限流、埋点散落在业务层,无法统一治理 |
| 缺可观测性 | 不知道每轮消耗多少 Token、哪一步工具调用失败 |
AgentScope Java 的组件划分,正是逐条对应这些痛点。
| 组件 | 作用 | Java 类比 |
|---|---|---|
Model / ChatModel |
统一的大模型调用接口,屏蔽不同厂商协议差异 | JDBC 的 DataSource |
Message / Msg |
统一的消息结构,承载 role、content、tool_calls | DTO |
Memory |
对话历史管理,支持截断、摘要、外部存储 | Session / Cache |
Toolkit + @Tool |
工具注册与 Function Calling schema 自动生成 | Spring Bean + 注解扫描 |
ReActAgent |
推理-行动循环的执行器,自动处理多轮工具调用 | 任务调度器 |
Pipeline / MsgHub |
多 Agent 编排与消息广播 | 责任链 / 工作流引擎 |
理解这张表,后面的代码就都是”填参数”。
在 pom.xml 中加入核心包(具体 groupId、artifactId 与最新版本号请以官方仓库和 Maven Central 为准,框架迭代较快):
<dependency><groupId>io.agentscope</groupId><artifactId>agentscope-core</artifactId><version>${agentscope.version}</version></dependency>
@Configurationpublic class AgentConfig {@Beanpublic ChatModel chatModel(@Value("${llm.api-key}") String apiKey) {return DashScopeChatModel.builder().apiKey(apiKey).modelName("qwen-plus").build();// 换 OpenAI / 其他兼容 OpenAI 协议的服务,只需替换这一处实现}}
这一步是框架化最大的收益: 模型是可替换的 Bean 。业务代码只依赖 ChatModel 接口,做 A/B 测试或多供应商容灾时,改配置即可。
@Servicepublic class ChatService {private final ReActAgent agent;public ChatService(ChatModel model) {this.agent = ReActAgent.builder().name("assistant").sysPrompt("你是一名严谨的技术支持工程师,回答控制在 200 字内。").model(model).memory(new InMemoryMemory()).maxIters(10) // 推理-行动最大轮数,防止死循环.build();}public String ask(String query) {return agent.reply(query).getTextContent();}}
maxIters 是必须显式设置的参数。不设上限时,一旦模型陷入”反复调用同一个工具”的循环,Token 会持续燃烧,这是新手最常见的一笔意外账单。
工具能力是 Agent 与”聊天机器人”的分水岭。AgentScope Java 用注解声明工具,框架自动生成 JSON Schema 并处理调用回填:
public class OrderTools {@Tool(name = "query_order_status",description = "根据订单号查询订单当前状态与物流信息")public String queryOrderStatus(@ToolParam(name = "orderId", description = "订单编号") String orderId) {return orderService.getStatus(orderId); // 调用你已有的业务 Service}}
注册到 Agent:
Toolkit toolkit = new Toolkit();toolkit.registerTools(new OrderTools());ReActAgent agent = ReActAgent.builder().name("support").model(chatModel).toolkit(toolkit).sysPrompt("你是订单客服,涉及订单状态必须调用工具查询,禁止编造。").maxIters(8).build();
三个实践要点:
description 就是 Prompt 。模型靠它判断该不该调用工具,写得含糊会直接导致”该调不调”或”乱调”。orderId 必须校验归属当前登录用户,否则就是越权漏洞。单 Agent 塞太多工具会显著降低选择准确率。更稳的做法是按职责拆分,用 Pipeline 编排:
ReActAgent retriever = ReActAgent.builder().name("retriever").model(chatModel).toolkit(ragToolkit).sysPrompt("你负责检索内部知识库并给出原文依据。").build();ReActAgent writer = ReActAgent.builder().name("writer").model(chatModel).sysPrompt("你负责基于给定资料撰写正式答复,不得引入资料外信息。").build();Msg result = new SequentialPipeline(retriever, writer).run("如何申请发票?");
工程上要注意 上下文一致性 :多 Agent 之间通过共享状态(文件或结构化上下文对象)传递中间结果,比让模型自己在对话里”复述”更可靠,也更能压住 Token 消耗。这一点在复杂应用生成场景里已经是共识做法。
api-key、base-url、model、temperature、max-tokens 全部走 application.yml + 环境变量,禁止硬编码。InMemoryMemory 只适合单机验证,生产环境换成 Redis 或数据库实现,并按会话设置 TTL。Agent 场景的 Token 消耗远高于普通对话——一次带 3 次工具调用的任务,实际输入 Token 往往是用户提问长度的十几倍(历史消息 + 工具 schema 每轮都要重发)。成本估算公式:
单次任务费用 = Σ(每轮输入Token × 输入单价 + 每轮输出Token × 输出单价)
优化方向有四个: 精简工具数量 (工具 schema 每轮都进上下文)、 压缩 Memory (摘要替代全量历史)、 分级路由 (简单意图用小模型,复杂推理用旗舰模型)、 开启上下文缓存 (命中部分通常单价更低)。
选型阶段最耗时的其实是横向对比:不同模型在中文理解、Function Calling 稳定性、长上下文、单价上差异明显。可以在词元所模型服务上按能力维度和价格做对比,再通过统一 API 接入做小规模实测,用你自己的业务样本集决定,而不是只看榜单。对需要覆盖数据管理、模型训练到部署全链路的团队,也可以结合百度智能云千帆这类一站式平台做统一纳管。
本篇解决的是”从 0 到 1 跑通”:组件职责、最小 Agent、工具注册、多 Agent 编排、生产化清单。下一篇将进入实战部分——RAG 检索增强在 AgentScope Java 中的落地(文档解析、切片、向量召回与重排)、自定义组件开发,以及基于真实业务语料的精调与效果评估路径。
建议你现在就做一件事:把项目里那段手写 HttpClient 的模型调用,替换成 ChatModel Bean + ReActAgent,跑通一个带单工具的 Demo。改造完成后,再回到百度智能云词元所对比几家模型的实测成本与效果,为下一步上生产做决策。