Java AgentScope智能体入门

作者:半吊子全栈工匠2026.11.17 03:37浏览量:0

简介:本文面向Java后端开发者,讲解Java AgentScope智能体入门如何从环境准备、依赖接入、ReAct Agent示例到多模型路由与Token成本测算。读者可获得可运行示例、常见错误修正与生产落地清单,帮助在现有Spring Boot技术栈中构建可观测、可降级、低风险的智能体应用。

如果你正在用 Java 调用大模型 API,可能已经写过“拼 JSON、设置 Authorization、解析响应”的代码。这类写法能完成单次问答,但一旦进入工具调用、多轮上下文和复杂任务编排,就会暴露维护成本高、循环不可控、日志不足等问题。本文围绕 Java AgentScope 智能体怎么接入、AgentScope Java 怎么选模型、Java Agent 成本怎么算等问题,给出一套可逐步落地的入门路径。

agent">一、为什么原始 HttpClient 写法撑不起 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 能力可以像数据源、缓存、消息队列一样,被纳入现有分层架构和测试体系。

一个最小消息流可以理解为:

  1. User: order-service 现在正常吗?最近有没有发布过?
  2. Assistant: 需要查询 order-service 的实时状态。
  3. Tool: query_service_status(service="order-service")
  4. Tool Result: {"service":"order-service","status":"UP","lastRelease":"示例时间"}
  5. Assistant: order-service 当前状态正常,最近一次发布信息如下。

在多轮 Agent 中,User、Assistant、Tool Message 会不断进入上下文。框架需要负责消息序列化、工具结果回填、轮次控制和异常终止,而开发者重点维护工具实现、业务校验、权限边界和可观测日志。

三、环境准备:先跑通一个最小工程

为了避免“示例代码复制后无法运行”,建议先准备一个最小 Spring Boot 工程。

环境建议:

  • JDK 17 或更高版本。
  • Spring Boot 3.x。
  • Maven 或 Gradle。
  • 一个可用的模型服务与 API Key,例如 DashScope。
  • API Key 通过环境变量注入,例如 DASHSCOPE_API_KEY。

需要特别说明的是,AgentScope Java 的依赖坐标和版本可能会随官方发布调整。为了避免读者拉到不存在或已过期的坐标,本文不写死未经核验的版本号,而是给出官方坐标核验方式:请先打开官方仓库、官方文档或 Maven Central 搜索页,确认当前官方提供的 groupId、artifactId 和 version;如果官方提供的是核心 SDK 而非 Spring Boot Starter,也应使用官方对应坐标。

Maven 依赖可以使用占位符形式表达:

  1. <dependency>
  2. <groupId>${agentscope.groupId}</groupId>
  3. <artifactId>${agentscope.artifactId}</artifactId>
  4. <version>${agentscope.version}</version>
  5. </dependency>

Gradle 依赖同样建议从官方发布页复制:

  1. implementation("${agentscope.groupId}:${agentscope.artifactId}:${agentscope.version}")

接入后,可以在本地执行依赖解析和依赖树检查,确认坐标可用:

  1. mvn dependency:resolve
  2. mvn dependency:tree

如果官方文档给出了具体坐标,也可以使用官方提供的安装命令进行验证。核心原则是:groupId、artifactId、version 必须来自当前官方发布页、官方 README 或 Maven Central 搜索结果,而不是来自网络转载中的固定版本号。

启动类可以保持 Spring Boot 标准写法:

  1. @SpringBootApplication
  2. public class AgentApplication {
  3. public static void main(String[] args) {
  4. SpringApplication.run(AgentApplication.class, args);
  5. }
  6. }

运行方式可以是 IDE 启动,也可以命令行运行:

  1. mvn spring-boot:run

或使用 Gradle:

  1. ./gradlew bootRun

需要提醒:不同版本 API 命名可能存在微调。本文代码用于说明 AgentScope Java 的组件结构,正式落地前请对照官方文档逐项核对 ChatModel、ReActAgent、Toolkit、Msg、Memory 等 builder 和方法名。

四、第一个可运行示例:运维问答助手

假设我们要做一个“运维问答助手”,它能查服务状态、能查日志、能用自然语言回答问题。下面给出一个相对完整的示例,包括配置类、工具类、状态客户端和启动调用。

首先,配置文件可以只保留必要项:

  1. server:
  2. port: 8080
  3. agentscope:
  4. dashscope:
  5. model: qwen-plus

真实环境中,API Key 不要写入配置文件,而是通过环境变量注入:

  1. export DASHSCOPE_API_KEY=your-api-key

状态查询客户端可以先用接口和模拟实现表达结构:

  1. public interface OpsStatusClient {
  2. ServiceStatus query(String service);
  3. }
  4. public record ServiceStatus(
  5. String service,
  6. String status,
  7. String lastRelease
  8. ) {}

示例实现如下:

  1. @Component
  2. public class DemoOpsStatusClient implements OpsStatusClient {
  3. @Override
  4. public ServiceStatus query(String service) {
  5. return new ServiceStatus(
  6. service,
  7. "UP",
  8. "示例发布时间为 2026-06-01 10:00"
  9. );
  10. }
  11. }

工具类需要由 Spring 管理,并注入状态客户端:

  1. @Component
  2. public class OpsToolbox {
  3. private final OpsStatusClient statusClient;
  4. private final ObjectMapper objectMapper = new ObjectMapper();
  5. public OpsToolbox(OpsStatusClient statusClient) {
  6. this.statusClient = statusClient;
  7. }
  8. @Tool(
  9. name = "query_service_status",
  10. description = "查询指定服务当前的运行状态与最近一次发布时间"
  11. )
  12. public String queryStatus(
  13. @ToolParam(
  14. name = "service",
  15. description = "服务名,例如 order-service"
  16. )
  17. String service
  18. ) {
  19. if (service == null || service.isBlank()) {
  20. return "{\"ok\":false,\"error\":\"service 不能为空\"}";
  21. }
  22. try {
  23. ServiceStatus status = statusClient.query(service);
  24. return objectMapper.writeValueAsString(
  25. new ToolResult(true, status)
  26. );
  27. } catch (Exception e) {
  28. return "{\"ok\":false,\"error\":\"查询服务状态失败\"}";
  29. }
  30. }
  31. public Toolkit toToolkit() {
  32. return Toolkit.builder()
  33. .register(this)
  34. .build();
  35. }
  36. record ToolResult(boolean ok, ServiceStatus data) {}
  37. }

Agent 配置如下:

  1. @Configuration
  2. public class AgentConfig {
  3. @Bean
  4. public ChatModel chatModel() {
  5. return DashScopeChatModel.builder()
  6. .apiKey(System.getenv("DASHSCOPE_API_KEY"))
  7. .modelName("qwen-plus")
  8. .build();
  9. }
  10. @Bean
  11. public ReActAgent opsAgent(ChatModel model, OpsToolbox toolbox) {
  12. return ReActAgent.builder()
  13. .name("ops-agent")
  14. .sysPrompt("你是运维助手。需要实时数据时必须调用工具,"
  15. + "不要凭记忆编造服务状态。回答控制在 200 字内。")
  16. .model(model)
  17. .toolkit(toolbox.toToolkit())
  18. .maxIters(8)
  19. .build();
  20. }
  21. }

为了让示例可以直接启动并观察结果,可以增加一个 CommandLineRunner:

  1. @Component
  2. public class AgentDemoRunner implements CommandLineRunner {
  3. private final ReActAgent opsAgent;
  4. public AgentDemoRunner(ReActAgent opsAgent) {
  5. this.opsAgent = opsAgent;
  6. }
  7. @Override
  8. public void run(String... args) {
  9. Msg reply = opsAgent.reply(
  10. Msg.user("order-service 现在正常吗?最近有没有发布过?")
  11. );
  12. System.out.println(reply.getTextContent());
  13. }
  14. }

启动方式:

  1. mvn spring-boot:run

如果配置正确,预期输出类似:

  1. order-service 当前状态为 UP,最近一次发布时间为示例发布时间为 2026-06-01 10:00。

这一行调用背后,框架通常会完成:拼装 system prompt 与工具定义、请求模型、解析 tool_calls、反射调用 Java 工具方法、把结果回填进上下文、再次请求模型,直到模型给出最终答复或达到 maxIters。开发者真正需要重点维护的,是工具方法本身、权限校验、返回格式和异常处理。

如果需要多轮记忆,可以在 Agent 配置中接入 Memory 组件。短期记忆用于保存最近几轮对话,摘要压缩则用于把早期对话压缩成摘要,避免上下文无限增长。

五、多模型接入:不要只用一个模型

生产系统几乎一定会遇到“这个任务该用哪个模型”的问题。Agent 场景尤其明显:意图识别、参数抽取、简单分类这类子任务可以用小模型;最终答复生成、复杂推理才更适合旗舰模型。

示例:

  1. ChatModel fast = DashScopeChatModel.builder()
  2. .apiKey(System.getenv("DASHSCOPE_API_KEY"))
  3. .modelName("qwen-turbo")
  4. .build();
  5. ChatModel strong = DashScopeChatModel.builder()
  6. .apiKey(System.getenv("DASHSCOPE_API_KEY"))
  7. .modelName("qwen-max")
  8. .build();

一个简单的场景路由思路如下:

  1. ReActAgent fastAgent = ReActAgent.builder()
  2. .name("fast-agent")
  3. .model(fast)
  4. .maxIters(3)
  5. .build();
  6. ReActAgent strongAgent = ReActAgent.builder()
  7. .name("strong-agent")
  8. .model(strong)
  9. .maxIters(8)
  10. .build();
  11. String taskType = fastAgent.reply(
  12. Msg.user("请判断问题类型,只回答 simple 或 complex: " + question)
  13. ).getTextContent();
  14. ReActAgent selected = taskType.contains("complex") ? strongAgent : fastAgent;
  15. Msg reply = selected.reply(Msg.user(question));

由于部分模型服务支持 OpenAI 兼容协议,切换供应商时通常可以考虑替换 ChatModel 实现与 baseUrl。但需要注意:不同版本、不同供应商对 OpenAI 兼容协议的支持范围并不完全一致,尤其是 function calling、工具参数格式、流式输出、错误码和限流策略,必须以官方文档为准。如果目标模型不支持 function calling,就不应该继续假设 ReActAgent 可以原生完成工具循环,而应降级为“模型输出结构化工具调用计划,Java 侧解析并执行”。

一个不支持 function calling 时的降级示例思路如下:

  1. String planJson = chatModel.reply(
  2. Msg.user("可用工具:query_service_status(service)。"
  3. + "请判断是否需要调用工具,并只输出 JSON:"
  4. + "{\"tool\":\"query_service_status\",\"service\":\"order-service\"}"
  5. + "如果无需调用,输出 {\"tool\":\"none\"}")
  6. ).getTextContent();
  7. if (planJson.contains("query_service_status")) {
  8. String service = extractService(planJson);
  9. String toolResult = opsToolbox.queryStatus(service);
  10. Msg finalReply = chatModel.reply(
  11. Msg.user("根据工具结果回答问题:" + toolResult)
  12. );
  13. System.out.println(finalReply.getTextContent());
  14. }

模型选型时建议重点看五项:

  1. 是否稳定支持工具调用。
  2. 上下文长度是否满足 Agent 多轮观察结果。
  3. 单价是否匹配业务调用量。
  4. 限流、并发和 SLA 是否满足生产要求。
  5. 是否兼容 OpenAI 协议,以及兼容范围是否覆盖 function calling。

六、算清 Token 账:Agent 成本会被放大

普通问答通常是一次请求一次响应,Agent 不是。一次用户提问可能触发多轮模型调用,每轮都要携带 system prompt、工具定义和不断增长的观察结果。

这里需要特别澄清:如果前文提到“system prompt 与工具 schema 约 1300 tokens”,通常指的是 system prompt 和工具定义本身,不包含用户输入、历史对话、模型输出,也不包含工具返回结果。由于模型每一轮都需要知道当前可用工具和系统约束,这部分内容通常会每轮重复发送,因此会重复计费。工具返回结果不会出现在 1300 tokens 里,但会在工具调用发生后的下一轮进入模型输入。

假设一次任务包含 3 轮调用:

  • system prompt 与工具 schema:约 1300 tokens,且每轮重复发送。
  • 第 1 轮输入约 1500,输出约 150。
  • 第 2 轮输入约 1950,输出约 120。
  • 第 3 轮输入约 2400,输出约 80。
  • 合计输入约 5850 tokens,输出约 350 tokens。

测算前提包括:未启用前缀缓存,未启用历史摘要,工具定义数量较少,工具返回结果已被简化并包含在上述轮次输入中,不考虑重试、流式输出差异和平台计费折扣。如果工具返回内容更长,或者工具数量更多,实际输入 Token 会更高。

费用公式:

  1. 单次成本 = 输入tokens / 1,000,000 × 输入单价 + 输出tokens / 1,000,000 × 输出单价

若输入单价为 0.8 元/百万 tokens,输出单价为 2 元/百万 tokens,则单次成本约为:

  1. 5850 / 1,000,000 × 0.8 + 350 / 1,000,000 × 2 ≈ 0.00538 元

如果日均 10 万次调用,成本约为 538 元/天。这个示例说明,Agent 场景中输入 Token 往往占大头,因此优化重点不是简单换更便宜的模型,而是压缩输入。

常用优化方式:

  1. 精简工具数量。工具定义每轮都可能进入上下文,过多工具会显著增加输入成本。可以按业务域拆成多个 Agent,按需加载工具集。
  2. 历史摘要化。把早期对话压缩成摘要写入 Memory,而不是全量回填。
  3. Prompt 前缀稳定。保持 system prompt 与工具定义顺序不变,有助于命中平台提供的前缀缓存;是否支持以及计费方式,以平台公示为准。
  4. 分级路由。意图识别、参数抽取交给小模型,只有最终生成使用大模型。

七、Agent 常见错误与修正方式

很多 Java 团队第一次做 Agent 时,容易把精力放在 Prompt 上,却忽略了工程边界。下面几类问题很常见。

  1. 工具 schema 过大

表现:每轮请求都携带大量工具定义,Token 消耗快速上升,模型选择工具准确率下降。

可观测指标:tools_schema_tokens、avg_request_input_tokens、tool_selection_error_rate。

修正:按业务域拆分工具集,让 Agent 只加载当前任务需要的工具。

  1. 历史全量回填

表现:对话轮次增加后,上下文迅速超限,响应变慢。

可观测指标:context_tokens、history_messages_count、context_overflow_count。

修正:使用滑动窗口、摘要记忆或关键状态抽取,只保留必要上下文。

  1. 未设置 maxIters 或超时

表现:模型反复调用工具,任务长时间不结束。

可观测指标:agent_iterations、tool_timeout_count、request_timeout_count。

修正:设置最大轮次、单次工具超时和整体调用超时。

  1. 工具方法缺少参数校验

表现:模型传入空值、非法枚举或越权资源,导致业务异常。

可观测指标:tool_invalid_param_count、tool_auth_denied_count、tool_exception_count。

修正:在工具方法入口做参数校验、权限校验和幂等处理。

  1. 没有降级路径

表现:模型不可用、工具失败或网络异常时,用户侧直接报错。

可观测指标:fallback_trigger_count、model_error_count、tool_error_count。

修正:准备缓存答案、默认回复、转人工或降级到更简单模型。

八、生产落地的必做项

  1. 密钥与配置

API Key 应通过环境变量、配置中心或 KMS 管理,不要硬编码在代码库或普通配置文件中。建议在网关层统一做鉴权、限流和配额,而不是把安全逻辑散落在各个 Agent 里。

  1. 可观测性

Agent 调试成本高于普通接口。应记录每一轮的完整输入摘要、模型输出摘要、工具入参、工具返回、耗时和 Token 消耗,并带上统一 traceId。没有这套日志,线上“模型胡说”或“工具异常”的问题很难定位。

  1. 工具的安全边界

工具就是暴露给模型的 API,必须做参数校验、权限校验和幂等设计。如果 Agent 需要执行生成代码,务必放进隔离沙箱运行,防止 AI 生成的代码越权访问宿主或系统内部资源,包括文件、内网、密钥等。对于高并发场景,可评估毫秒级启动、支持高并发创建的沙箱运行时。

  1. 超时与降级

为整个 reply 调用设置总超时,为工具调用设置独立超时与重试策略。同时要准备降级路径,例如模型不可用时返回缓存答案、切换到小模型,或转人工处理。

  1. 日志脱敏与用户隐私保护

日志中禁止明文记录 API Key、Authorization、用户原话中的敏感信息、身份证、手机号、银行卡号、内部密钥和工具返回的敏感数据。建议对输入输出进行脱敏处理,例如只记录摘要、掩码手机号、隐藏 token、对敏感字段做白名单过滤。对于用户隐私数据,应遵循最小必要原则,避免将完整原始请求长期写入普通应用日志。

九、建议的学习顺序与阶段验收清单

第一阶段,先把组件跑通。重点是 Model 配置、Message 结构、一个 Tool、ReActAgent 循环。能做出“查数据并总结”的单体 Agent,就算入门。

第二阶段,再进入 RAG 和多智能体协作。RAG 解决的是企业私有知识接入问题,适合文档问答、知识库检索、内部制度查询等场景;当系统需要私有数据但模型本身不知道时,可以引入 RAG。多智能体协作解决的是任务拆解、分工执行、交叉审核问题,适合复杂流程;如果任务只是单轮工具调用,不必过早引入多智能体。

阶段验收清单可以包括:

  • 能否通过官方坐标成功拉取依赖并启动 Spring Boot 工程。
  • 能否给 Agent 设置 maxIters、超时和降级路径。
  • 能否记录 traceId、模型耗时、工具耗时、Token 用量。
  • 能否根据输入输出 Token 估算单次调用成本。
  • 能否在模型不支持 function calling 时切换到结构化输出降级方案。

Java 团队通常可以在不引入 Python 服务的前提下,用 Java 技术栈完成 Agent 开发、部署和运维。后续可以进一步拆解 RAG 组件与多智能体编排,把单体 Agent 升级成能承接真实业务流程的系统。