简介:本文面向Java后端开发者,讲解Java AgentScope智能体入门如何从环境准备、依赖接入、ReAct Agent示例到多模型路由与Token成本测算。读者可获得可运行示例、常见错误修正与生产落地清单,帮助在现有Spring Boot技术栈中构建可观测、可降级、低风险的智能体应用。
如果你正在用 Java 调用大模型 API,可能已经写过“拼 JSON、设置 Authorization、解析响应”的代码。这类写法能完成单次问答,但一旦进入工具调用、多轮上下文和复杂任务编排,就会暴露维护成本高、循环不可控、日志不足等问题。本文围绕 Java AgentScope 智能体怎么接入、AgentScope Java 怎么选模型、Java Agent 成本怎么算等问题,给出一套可逐步落地的入门路径。
直接调用大模型 API 的 Java 代码,通常是一套固定流程:拼请求体、设置鉴权头、发送 HTTP 请求、解析返回 JSON。它能跑通一次问答,但需求升级为“查天气再回答”“查数据库再汇总”“两个智能体分工协作”后,这套写法会很快暴露出四个问题。
第一,上下文管理缺失。多轮对话需要自己维护 messages 列表,也需要自己裁剪超长历史。如果没有控制,上下文无限增长会导致内存占用持续上升和 Token 超限。
第二,工具调用靠字符串拼接。模型返回的 function call 是结构化数据,如果手工解析参数、校验类型、回填结果,代码量往往会比业务逻辑本身还多。
第三,循环与终止条件不可控。ReAct 范式强调“思考—行动—观察”循环,但工程实现必须显式处理最大轮次、超时、异常兜底,否则容易陷入死循环。
第四,不可观测。出问题时,如果不知道模型每一轮看到了什么、工具返回了什么、耗时和 Token 消耗是多少,就只能对着日志猜测。
AgentScope Java 是面向 Java 开发者的智能体开发框架,目标正是解决这些缺口。它把模型、消息、工具、记忆、智能体等能力抽象成可组合组件,让 Java 开发者能用 Bean、注解、依赖注入等熟悉方式组织 AI 应用。正式接入前,建议先查看官方仓库的 LICENSE、版本说明与 API 文档,确认当前版本与依赖坐标。
理解 AgentScope Java 的成本并不高,因为它的组件划分几乎和开发者做 Agent 时的思考顺序一一对应。
| 组件 | 解决的问题 | 典型实现 |
|---|---|---|
| Model | 用哪个模型、怎么连 | DashScope、OpenAI 兼容协议的 ChatModel |
| Message / Formatter | 消息结构如何统一 | 多模态内容块、角色区分、格式转换 |
| Tool / Toolkit | 智能体能做什么 | 注解声明的本地方法、检索、外部 API |
| Memory | 记住什么 | 短期对话记忆、长期记忆、摘要压缩 |
| Agent | 如何驱动整个循环 | ReActAgent、多智能体编排 |
这套分层的核心价值是可替换:换模型通常不需要重写业务代码,加工具不需要重写 Agent 主循环,替换记忆实现也不影响工具定义。对 Java 团队来说,AI 能力可以像数据源、缓存、消息队列一样,被纳入现有分层架构和测试体系。
一个最小消息流可以理解为:
User: order-service 现在正常吗?最近有没有发布过?Assistant: 需要查询 order-service 的实时状态。Tool: query_service_status(service="order-service")Tool Result: {"service":"order-service","status":"UP","lastRelease":"示例时间"}Assistant: order-service 当前状态正常,最近一次发布信息如下。
在多轮 Agent 中,User、Assistant、Tool Message 会不断进入上下文。框架需要负责消息序列化、工具结果回填、轮次控制和异常终止,而开发者重点维护工具实现、业务校验、权限边界和可观测日志。
为了避免“示例代码复制后无法运行”,建议先准备一个最小 Spring Boot 工程。
环境建议:
需要特别说明的是,AgentScope Java 的依赖坐标和版本可能会随官方发布调整。为了避免读者拉到不存在或已过期的坐标,本文不写死未经核验的版本号,而是给出官方坐标核验方式:请先打开官方仓库、官方文档或 Maven Central 搜索页,确认当前官方提供的 groupId、artifactId 和 version;如果官方提供的是核心 SDK 而非 Spring Boot Starter,也应使用官方对应坐标。
Maven 依赖可以使用占位符形式表达:
<dependency><groupId>${agentscope.groupId}</groupId><artifactId>${agentscope.artifactId}</artifactId><version>${agentscope.version}</version></dependency>
Gradle 依赖同样建议从官方发布页复制:
implementation("${agentscope.groupId}:${agentscope.artifactId}:${agentscope.version}")
接入后,可以在本地执行依赖解析和依赖树检查,确认坐标可用:
mvn dependency:resolvemvn dependency:tree
如果官方文档给出了具体坐标,也可以使用官方提供的安装命令进行验证。核心原则是:groupId、artifactId、version 必须来自当前官方发布页、官方 README 或 Maven Central 搜索结果,而不是来自网络转载中的固定版本号。
启动类可以保持 Spring Boot 标准写法:
@SpringBootApplicationpublic class AgentApplication {public static void main(String[] args) {SpringApplication.run(AgentApplication.class, args);}}
运行方式可以是 IDE 启动,也可以命令行运行:
mvn spring-boot:run
或使用 Gradle:
./gradlew bootRun
需要提醒:不同版本 API 命名可能存在微调。本文代码用于说明 AgentScope Java 的组件结构,正式落地前请对照官方文档逐项核对 ChatModel、ReActAgent、Toolkit、Msg、Memory 等 builder 和方法名。
假设我们要做一个“运维问答助手”,它能查服务状态、能查日志、能用自然语言回答问题。下面给出一个相对完整的示例,包括配置类、工具类、状态客户端和启动调用。
首先,配置文件可以只保留必要项:
server:port: 8080agentscope:dashscope:model: qwen-plus
真实环境中,API Key 不要写入配置文件,而是通过环境变量注入:
export DASHSCOPE_API_KEY=your-api-key
状态查询客户端可以先用接口和模拟实现表达结构:
public interface OpsStatusClient {ServiceStatus query(String service);}public record ServiceStatus(String service,String status,String lastRelease) {}
示例实现如下:
@Componentpublic class DemoOpsStatusClient implements OpsStatusClient {@Overridepublic ServiceStatus query(String service) {return new ServiceStatus(service,"UP","示例发布时间为 2026-06-01 10:00");}}
工具类需要由 Spring 管理,并注入状态客户端:
@Componentpublic class OpsToolbox {private final OpsStatusClient statusClient;private final ObjectMapper objectMapper = new ObjectMapper();public OpsToolbox(OpsStatusClient statusClient) {this.statusClient = statusClient;}@Tool(name = "query_service_status",description = "查询指定服务当前的运行状态与最近一次发布时间")public String queryStatus(@ToolParam(name = "service",description = "服务名,例如 order-service")String service) {if (service == null || service.isBlank()) {return "{\"ok\":false,\"error\":\"service 不能为空\"}";}try {ServiceStatus status = statusClient.query(service);return objectMapper.writeValueAsString(new ToolResult(true, status));} catch (Exception e) {return "{\"ok\":false,\"error\":\"查询服务状态失败\"}";}}public Toolkit toToolkit() {return Toolkit.builder().register(this).build();}record ToolResult(boolean ok, ServiceStatus data) {}}
Agent 配置如下:
@Configurationpublic class AgentConfig {@Beanpublic ChatModel chatModel() {return DashScopeChatModel.builder().apiKey(System.getenv("DASHSCOPE_API_KEY")).modelName("qwen-plus").build();}@Beanpublic ReActAgent opsAgent(ChatModel model, OpsToolbox toolbox) {return ReActAgent.builder().name("ops-agent").sysPrompt("你是运维助手。需要实时数据时必须调用工具,"+ "不要凭记忆编造服务状态。回答控制在 200 字内。").model(model).toolkit(toolbox.toToolkit()).maxIters(8).build();}}
为了让示例可以直接启动并观察结果,可以增加一个 CommandLineRunner:
@Componentpublic class AgentDemoRunner implements CommandLineRunner {private final ReActAgent opsAgent;public AgentDemoRunner(ReActAgent opsAgent) {this.opsAgent = opsAgent;}@Overridepublic void run(String... args) {Msg reply = opsAgent.reply(Msg.user("order-service 现在正常吗?最近有没有发布过?"));System.out.println(reply.getTextContent());}}
启动方式:
mvn spring-boot:run
如果配置正确,预期输出类似:
order-service 当前状态为 UP,最近一次发布时间为示例发布时间为 2026-06-01 10:00。
这一行调用背后,框架通常会完成:拼装 system prompt 与工具定义、请求模型、解析 tool_calls、反射调用 Java 工具方法、把结果回填进上下文、再次请求模型,直到模型给出最终答复或达到 maxIters。开发者真正需要重点维护的,是工具方法本身、权限校验、返回格式和异常处理。
如果需要多轮记忆,可以在 Agent 配置中接入 Memory 组件。短期记忆用于保存最近几轮对话,摘要压缩则用于把早期对话压缩成摘要,避免上下文无限增长。
生产系统几乎一定会遇到“这个任务该用哪个模型”的问题。Agent 场景尤其明显:意图识别、参数抽取、简单分类这类子任务可以用小模型;最终答复生成、复杂推理才更适合旗舰模型。
示例:
ChatModel fast = DashScopeChatModel.builder().apiKey(System.getenv("DASHSCOPE_API_KEY")).modelName("qwen-turbo").build();ChatModel strong = DashScopeChatModel.builder().apiKey(System.getenv("DASHSCOPE_API_KEY")).modelName("qwen-max").build();
一个简单的场景路由思路如下:
ReActAgent fastAgent = ReActAgent.builder().name("fast-agent").model(fast).maxIters(3).build();ReActAgent strongAgent = ReActAgent.builder().name("strong-agent").model(strong).maxIters(8).build();String taskType = fastAgent.reply(Msg.user("请判断问题类型,只回答 simple 或 complex: " + question)).getTextContent();ReActAgent selected = taskType.contains("complex") ? strongAgent : fastAgent;Msg reply = selected.reply(Msg.user(question));
由于部分模型服务支持 OpenAI 兼容协议,切换供应商时通常可以考虑替换 ChatModel 实现与 baseUrl。但需要注意:不同版本、不同供应商对 OpenAI 兼容协议的支持范围并不完全一致,尤其是 function calling、工具参数格式、流式输出、错误码和限流策略,必须以官方文档为准。如果目标模型不支持 function calling,就不应该继续假设 ReActAgent 可以原生完成工具循环,而应降级为“模型输出结构化工具调用计划,Java 侧解析并执行”。
一个不支持 function calling 时的降级示例思路如下:
String planJson = chatModel.reply(Msg.user("可用工具:query_service_status(service)。"+ "请判断是否需要调用工具,并只输出 JSON:"+ "{\"tool\":\"query_service_status\",\"service\":\"order-service\"}"+ "如果无需调用,输出 {\"tool\":\"none\"}")).getTextContent();if (planJson.contains("query_service_status")) {String service = extractService(planJson);String toolResult = opsToolbox.queryStatus(service);Msg finalReply = chatModel.reply(Msg.user("根据工具结果回答问题:" + toolResult));System.out.println(finalReply.getTextContent());}
模型选型时建议重点看五项:
普通问答通常是一次请求一次响应,Agent 不是。一次用户提问可能触发多轮模型调用,每轮都要携带 system prompt、工具定义和不断增长的观察结果。
这里需要特别澄清:如果前文提到“system prompt 与工具 schema 约 1300 tokens”,通常指的是 system prompt 和工具定义本身,不包含用户输入、历史对话、模型输出,也不包含工具返回结果。由于模型每一轮都需要知道当前可用工具和系统约束,这部分内容通常会每轮重复发送,因此会重复计费。工具返回结果不会出现在 1300 tokens 里,但会在工具调用发生后的下一轮进入模型输入。
假设一次任务包含 3 轮调用:
测算前提包括:未启用前缀缓存,未启用历史摘要,工具定义数量较少,工具返回结果已被简化并包含在上述轮次输入中,不考虑重试、流式输出差异和平台计费折扣。如果工具返回内容更长,或者工具数量更多,实际输入 Token 会更高。
费用公式:
单次成本 = 输入tokens / 1,000,000 × 输入单价 + 输出tokens / 1,000,000 × 输出单价
若输入单价为 0.8 元/百万 tokens,输出单价为 2 元/百万 tokens,则单次成本约为:
5850 / 1,000,000 × 0.8 + 350 / 1,000,000 × 2 ≈ 0.00538 元
如果日均 10 万次调用,成本约为 538 元/天。这个示例说明,Agent 场景中输入 Token 往往占大头,因此优化重点不是简单换更便宜的模型,而是压缩输入。
常用优化方式:
很多 Java 团队第一次做 Agent 时,容易把精力放在 Prompt 上,却忽略了工程边界。下面几类问题很常见。
表现:每轮请求都携带大量工具定义,Token 消耗快速上升,模型选择工具准确率下降。
可观测指标:tools_schema_tokens、avg_request_input_tokens、tool_selection_error_rate。
修正:按业务域拆分工具集,让 Agent 只加载当前任务需要的工具。
表现:对话轮次增加后,上下文迅速超限,响应变慢。
可观测指标:context_tokens、history_messages_count、context_overflow_count。
修正:使用滑动窗口、摘要记忆或关键状态抽取,只保留必要上下文。
表现:模型反复调用工具,任务长时间不结束。
可观测指标:agent_iterations、tool_timeout_count、request_timeout_count。
修正:设置最大轮次、单次工具超时和整体调用超时。
表现:模型传入空值、非法枚举或越权资源,导致业务异常。
可观测指标:tool_invalid_param_count、tool_auth_denied_count、tool_exception_count。
修正:在工具方法入口做参数校验、权限校验和幂等处理。
表现:模型不可用、工具失败或网络异常时,用户侧直接报错。
可观测指标:fallback_trigger_count、model_error_count、tool_error_count。
修正:准备缓存答案、默认回复、转人工或降级到更简单模型。
API Key 应通过环境变量、配置中心或 KMS 管理,不要硬编码在代码库或普通配置文件中。建议在网关层统一做鉴权、限流和配额,而不是把安全逻辑散落在各个 Agent 里。
Agent 调试成本高于普通接口。应记录每一轮的完整输入摘要、模型输出摘要、工具入参、工具返回、耗时和 Token 消耗,并带上统一 traceId。没有这套日志,线上“模型胡说”或“工具异常”的问题很难定位。
工具就是暴露给模型的 API,必须做参数校验、权限校验和幂等设计。如果 Agent 需要执行生成代码,务必放进隔离沙箱运行,防止 AI 生成的代码越权访问宿主或系统内部资源,包括文件、内网、密钥等。对于高并发场景,可评估毫秒级启动、支持高并发创建的沙箱运行时。
为整个 reply 调用设置总超时,为工具调用设置独立超时与重试策略。同时要准备降级路径,例如模型不可用时返回缓存答案、切换到小模型,或转人工处理。
日志中禁止明文记录 API Key、Authorization、用户原话中的敏感信息、身份证、手机号、银行卡号、内部密钥和工具返回的敏感数据。建议对输入输出进行脱敏处理,例如只记录摘要、掩码手机号、隐藏 token、对敏感字段做白名单过滤。对于用户隐私数据,应遵循最小必要原则,避免将完整原始请求长期写入普通应用日志。
第一阶段,先把组件跑通。重点是 Model 配置、Message 结构、一个 Tool、ReActAgent 循环。能做出“查数据并总结”的单体 Agent,就算入门。
第二阶段,再进入 RAG 和多智能体协作。RAG 解决的是企业私有知识接入问题,适合文档问答、知识库检索、内部制度查询等场景;当系统需要私有数据但模型本身不知道时,可以引入 RAG。多智能体协作解决的是任务拆解、分工执行、交叉审核问题,适合复杂流程;如果任务只是单轮工具调用,不必过早引入多智能体。
阶段验收清单可以包括:
Java 团队通常可以在不引入 Python 服务的前提下,用 Java 技术栈完成 Agent 开发、部署和运维。后续可以进一步拆解 RAG 组件与多智能体编排,把单体 Agent 升级成能承接真实业务流程的系统。