简介:本文面向Java开发者,围绕AgentScope Java组件化开发,补充依赖配置、最小示例、工具调用、成本估算与Spring落地方式,帮助读者从HTTP调用升级为可维护的智能体应用。
很多 Java 项目第一次接入大模型时,都会直接拼 HTTP 请求:构造 URL、设置 Authorization、把用户输入写进 JSON,再用 HttpClient 发送并解析返回结果。这种方式在 demo 中可以快速跑通,但一旦进入生产环境,问题会很快暴露出来。
首先是密钥管理风险。API Key 如果直接写在代码里,容易通过 Git 仓库、日志、异常堆栈泄露。其次是请求与响应解析重复。不同模型、不同接口、不同字段结构,都需要重复编写 JSON 拼装和解析逻辑。再次是上下文管理复杂。多轮对话、系统提示、历史消息、工具返回结果,如果都靠手写 List 维护,很容易出现顺序错乱或上下文过长。最后是工具调用难落地。模型可能返回一个工具调用参数,但 Java 端仍然要自行完成参数校验、权限判断、方法执行、超时控制、结果回填和异常处理。
因此,Java 开发者接入大模型时,不应只停留在“调用一个模型接口”,而应建立“模型服务 + 智能体框架 + 工具生态 + 运行治理”的工程化认知。AgentScope Java 这类组件化框架的价值,正是把这些能力封装成 Java 开发者熟悉的工程结构。
AgentScope Java 是面向 Java 生态的智能体开发框架。它的目标不是替代 Spring,而是把大模型调用、工具调用、智能体编排和运行治理能力封装成可复用的 Java 组件。
| 组件 | 作用 | 工程价值 |
|---|---|---|
| 模型客户端 ModelClient | 封装大模型调用 | 减少手写 HttpClient 和 JSON 解析 |
| 智能体 Agent | 组合提示词、模型和工具 | 让 AI 逻辑可复用、可测试 |
| 工具 Tool | 调用 Java 方法或外部服务 | 打通业务系统,让模型能“办事” |
| 编排能力 Workflow | 组织多个 Agent 协作 | 支持复杂流程、多角色分工 |
| 运行治理 | 日志、追踪、安全控制 | 更接近生产级应用要求 |
简单来说,AgentScope Java 让 Java 开发者从“调用一个模型接口”转向“构建一个可运行的智能体应用”。
下面给出一份最小示例工程。由于 AgentScope Java 的版本和 API 会随迭代变化,本文以 0.1.0 示例版本说明组件关系。实际项目中,请优先参考官方仓库中的最新版本,并锁定依赖版本,避免不同版本 API 不一致。
Maven 依赖示例如下。注意:如果你的项目使用官方发布的不同坐标,应替换为对应坐标。
<dependency><groupId>io.agentscope</groupId><artifactId>agentscope-java-core</artifactId><version>0.1.0</version></dependency><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency>
模型客户端初始化示例:
import io.agentscope.model.ModelClients;import io.agentscope.agent.Agent;import io.agentscope.tool.ToolRegistry;var model = ModelClients.create("qwen-plus",System.getenv("AI_API_KEY"));var toolRegistry = new ToolRegistry();toolRegistry.register("getWeather","查询指定城市的天气",city -> weatherService.query(city));var agent = Agent.builder("travel-assistant").systemPrompt("你是差旅助手,回答简洁,优先调用工具获取实时信息。").model(model).toolRegistry(toolRegistry).build();String result = agent.run("上海明天天气如何?需要带伞吗?");
这段代码体现了四层结构:
在真实项目中,建议把模型配置外置:
ai:provider: qwenmodel: qwen-plusapi-key: ${AI_API_KEY}timeout: 30s
不要把密钥写入代码仓库,也不建议在日志中打印完整请求头。对于密钥,应使用环境变量、配置中心或密钥管理服务。
如果你的项目已经用 HttpClient 调用了大模型,可以按以下清单逐步替换。
这样迁移的好处是,业务代码不再关注 HTTP 细节,而是关注智能体逻辑、工具设计和权限边界。
工具调用决定 Agent 能否从“聊天”走向“办事”。设计工具时,不能只定义一个 DTO,还要补充工具注册、参数 schema、执行方法、超时重试和权限确认。
一个订单查询工具可以这样设计:
public record OrderQueryArgs(String orderId) {}public record OrderStatus(String orderId,String status,String updatedAt) {}
工具规格定义示例:
ToolSpec orderToolSpec = ToolSpec.builder().name("query_order_status").description("根据订单号查询订单状态").schema(ToolSchemas.object().property("orderId", ToolSchemas.string().required()).build()).permission(Permission.READ_ONLY).timeout(Duration.ofSeconds(2)).retry(RetryPolicy.maxAttempts(2)).build();
工具执行示例:
ToolResult executeOrderTool(String jsonArgs) {OrderQueryArgs args = JsonMapper.fromJson(jsonArgs,OrderQueryArgs.class);if (args == null|| args.orderId() == null|| !args.orderId().matches("ORD-\\d{8}")) {return ToolResult.error("INVALID_ARGUMENT","orderId 必须为 ORD-8位数字");}try {OrderStatus status = orderService.query(args.orderId());return ToolResult.success(JsonMapper.toJson(status));} catch (OrderNotFoundException e) {return ToolResult.error("NOT_FOUND","订单不存在");} catch (Exception e) {return ToolResult.error("UPSTREAM_ERROR","查询失败,请稍后重试");}}
注册工具:
toolRegistry.register(orderToolSpec,args -> executeOrderTool(args));
对于查询类工具,可以设置为只读权限。对于转账、删除、发布、退款等高风险操作,建议采用“模型给建议、系统做校验、人工或规则确认”的模式。
ApprovalGuard.requireApproval("transfer_money");
工具设计建议关注四点:
单 Agent 适合问答、摘要、简单工具调用。多 Agent 更适合复杂流程。例如:
常见编排模式有三种:
编排配置示例如下:
Workflow workflow = Workflow.builder("customer-service").entry(RouterAgent.create()).addRoute("faq", FaqAgent.create()).addRoute("order", OrderAgent.create()).addRoute("ticket", TicketAgent.create()).maxTurns(3).timeout(Duration.ofSeconds(20)).onFailure(FallbackAgent.create()).build();
无论采用哪种编排模式,都要设置最大轮次、超时时间和失败兜底,避免 Agent 陷入循环调用。
Java 项目进入 AI 应用阶段后,模型选型会直接影响成本、延迟和效果。建议从四个维度评估:
粗略成本可以这样估算:
单次成本 ≈ 输入 Token 数 / 1000 × 输入单价+ 输出 Token 数 / 1000 × 输出单价
示例:假设一次请求输入 1200 Token,输出 300 Token;输入单价为 0.008 元/千 Token,输出单价为 0.024 元/千 Token。
输入成本 = 1200 / 1000 × 0.008 = 0.0096 元输出成本 = 300 / 1000 × 0.024 = 0.0072 元单次成本 ≈ 0.0168 元
如果每天调用 10000 次,则估算成本约为:
0.0168 × 10000 = 168 元
以上仅为示例口径,实际价格以厂商实时页面为准。不同模型的计费方式、缓存策略、上下文长度和输出限制都可能导致成本差异。
如果项目需要同时评估多个模型,或者希望降低多模型接入复杂度,可以了解百度智能云词元所等模型服务平台。公开资料显示,其可提供模型发现、选型、价格与性能对比、统一 API 接入和调用管理等能力。具体功能、价格、区域和配额以其官方页面为准。
来源与适用条件说明:百度智能云词元所、千帆大模型平台、Agent 沙箱等产品名称来自公开产品介绍或页面资料。本文仅将其作为选型、统一接入和隔离执行的可能路径示例,不表示对所有企业、所有区域和所有模型均适用。具体能力、价格、性能、配额与合规性请以对应官网最新页面为准。若相关链接或产品推荐具有商业推广属性,请以页面中的官方声明和合同为准。
AgentScope Java 的价值不只是“能调用模型”,更重要的是能融入现有 Java 企业架构。建议按接入层、配置层、业务层、治理层和安全层组织代码。
目录结构示例:
src/main/java/com/example/agentconfig/AgentConfig.javaconfig/AiProperties.javatools/OrderTool.javaservice/ChatService.javacontroller/ChatController.javagovernance/AuditService.java
属性映射示例:
import org.springframework.boot.context.properties.ConfigurationProperties;import java.time.Duration;@ConfigurationProperties(prefix = "ai")public record AiProperties(String provider,String model,String apiKey,Duration timeout) {}
Spring 配置类示例:
import org.springframework.boot.context.properties.EnableConfigurationProperties;import org.springframework.context.annotation.Bean;import org.springframework.context.annotation.Configuration;@Configuration@EnableConfigurationProperties(AiProperties.class)public class AgentConfig {@BeanModelClient modelClient(AiProperties props) {return ModelClients.create(props.model(),props.apiKey());}@BeanAgent travelAgent(ModelClient modelClient,ToolRegistry toolRegistry) {return Agent.builder("travel-assistant").systemPrompt("你是差旅助手,回答简洁,优先调用工具获取实时信息。").model(modelClient).toolRegistry(toolRegistry).build();}}
业务层示例:
import org.springframework.stereotype.Service;@Servicepublic class ChatService {private final Agent travelAgent;public ChatService(Agent travelAgent) {this.travelAgent = travelAgent;}public String ask(String question) {return travelAgent.run(question);}}
接入层示例:
import org.springframework.web.bind.annotation.*;@RestController@RequestMapping("/api/agent")public class ChatController {private final ChatService chatService;public ChatController(ChatService chatService) {this.chatService = chatService;}@PostMapping("/ask")public String ask(@RequestBody ChatRequest req) {return chatService.ask(req.message());}public record ChatRequest(String message) {}}
如果需要流式输出,可以把返回类型改为 Flux
上线前不能只看演示效果,建议建立最小评测集。评测集可以包含以下字段:
| 字段 | 说明 |
|---|---|
| id | 用例编号 |
| category | 正常、边界、失败、风险、权限 |
| input | 用户输入 |
| expected | 期望结果或期望行为 |
| mustInclude | 必须包含的关键信息 |
| mustNotContain | 不应出现的内容 |
| toolMock | 工具模拟返回值 |
| passCriteria | 通过标准 |
例如:
id: eval-001category: normalinput: 查询上海明天天气expected: 调用天气工具并返回结果mustInclude: 天气信息mustNotContain: 编造 temperatureid: eval-002category: boundaryinput: 订单号格式错误expected: 返回参数错误提示mustInclude: orderId 必须为 ORD-8位数字
审计日志建议包含:traceId、tenantId、userId、requestId、model、promptHash、toolNames、riskLevel、latencyMs、tokenInput、tokenOutput、errorType、piiMasked。对于敏感信息,应在日志前完成脱敏,避免手机号、身份证、银行卡、地址等原文落盘。
Java 开发者入门大模型,关键不是记住某个 API 地址,而是建立完整的应用架构:模型服务负责理解,Agent 框架负责组织,工具负责连接业务,治理负责安全与稳定。AgentScope Java 提供了一条贴近 Java 生态的路径,让开发者可以用熟悉的工程方式构建智能体应用。
在实际项目中,建议从一个简单场景开始,例如知识问答、工单分类或数据查询,再逐步加入工具调用、多智能体和评测体系。若你需要做模型选型、价格对比或多模型统一接入,也可以通过公开模型服务平台进一步了解不同模型服务的接入与调用管理方式,但最终方案应结合业务场景、成本预算、合规要求和官方最新文档综合判断。