AgentScope 入门：用 Java 快速搭一个可用的 Agent

摘要

很多人第一次接触 Agent 框架，容易把它理解成"更复杂一点的模型 SDK"。但真正进入业务场景后，你会发现问题根本不在"怎么调模型"，而在"怎么让模型稳定地参与业务流程"。这篇文章从 Java 开发者视角出发，介绍 AgentScope 是什么、适合解决什么问题，以及如何用 AgentScope + DashScope 快速跑通一个最小可用 Agent，同时补充流式输出的基本接法，适合作为 AgentScope 入门文章。

---

---

最近在做企业内部 AI 助手时，我系统体验了一下 AgentScope Java。如果只是简单调一下模型，直接用 OpenAI SDK 或 DashScope SDK 就够了；但如果你想做一个真正的 Agent，比如带工具调用、记忆、流程编排、状态管理，那就需要一个更像"运行时"的框架。

这篇文章不讲太虚的概念，重点回答 3 个问题：

• AgentScope 是什么
• 它适合解决什么问题
• 如何用 Java 快速跑通一个最小可用 Agent

---

一、为什么需要 Agent 框架

很多 AI 应用一开始的代码都很简单：

1. 拼 prompt
2. 调 LLM
3. 返回结果

做 demo 没问题，但一旦进入真实业务，很快就会碰到这些问题：

• 需要调用工具，比如查数据库、调内部 API、发工单
• 需要多轮对话，而不是一次问答
• 需要保留上下文和记忆
• 需要让模型输出变成"动作"，而不是一段文本
• 需要可中断、可恢复、可观测

这时就不能只把 LLM 当成一个"字符串输入输出函数"，而是要把它放进一个 Agent runtime 里。

AgentScope 的价值就在这里：它不是单纯封装模型调用，而是把 Agent 常见的运行机制一起抽象出来。

---

二、AgentScope 是什么

AgentScope Java 可以理解成：

一个面向 Java 生态的 Agent 运行时框架

它主要解决的是这类问题：

• 如何统一消息结构
• 如何接入不同模型
• 如何支持工具调用
• 如何维护记忆
• 如何进行 ReAct 式推理循环
• 如何做多智能体协作和状态恢复

如果只看最核心的组成，大概有 4 个：

• Msg：统一消息对象
• Model：底层大模型
• Tool / Toolkit：工具能力
• Memory：上下文记忆

你可以把它理解成一套 Java 版的 Agent 基础设施。

---

三、AgentScope 适合哪些场景

我觉得它特别适合以下场景：

• 企业内部 AI 助手
• 带工具调用的问答系统
• 有审批、查询、执行动作的智能体
• 多轮对话型业务系统
• 希望用 Java / Spring Boot 落地 Agent 的团队

如果只是做一个简单聊天页，其实没必要上 AgentScope；但如果已经进入"让模型参与业务执行"的阶段，它就很有价值。

---

四、最小 Demo：用 AgentScope + DashScope 跑一个 Agent

下面给一个最小例子，用 DashScope 接 qwen-plus。

1. Maven 依赖

<dependencies>
    <dependency>
        <groupId>io.agentscope</groupId>
        <artifactId>agentscope</artifactId>
        <version>1.0.9</version>
    </dependency>
</dependencies>

2. 创建模型

import io.agentscope.core.model.DashScopeChatModel;

public class ModelFactory {

    public static DashScopeChatModel createQwenModel() {
        String apiKey = System.getenv("DASHSCOPE_API_KEY");
        if (apiKey == null || apiKey.isBlank()) {
            throw new IllegalStateException("DASHSCOPE_API_KEY is required");
        }

        return DashScopeChatModel.builder()
                .apiKey(apiKey)
                .modelName("qwen-plus")
                .build();
    }
}

3. 创建一个 ReActAgent

import io.agentscope.core.ReActAgent;
import io.agentscope.core.message.Msg;
import io.agentscope.core.model.DashScopeChatModel;

public class SimpleAgentDemo {

    public static void main(String[] args) {
        DashScopeChatModel model = ModelFactory.createQwenModel();

        ReActAgent agent = ReActAgent.builder()
                .name("Nexus")
                .sysPrompt("You are a helpful enterprise assistant.")
                .model(model)
                .build();

        Msg response = agent.call(
                Msg.builder()
                        .textContent("你好，请介绍一下 AgentScope 是什么")
                        .build()
        ).block();

        if (response != null) {
            System.out.println(response.getTextContent());
        }
    }
}

这个例子已经能跑通最基础的 Agent 调用。

---

五、如果想做流式输出怎么办

做聊天产品时，很多人都会想要"打字机效果"。

这里要区分两种完全不同的实现。

1. 假流式

先一次性拿到完整回答，再按字符拆开吐给前端。

优点：

• 简单
• 前端效果也像流式

缺点：

• 本质上不是 LLM 真流式
• 用户得等完整结果出来后才开始显示

2. 真流式

直接走模型的流式接口，边生成边输出。

在 AgentScope 里，底层 Model 接口本身就有：

Flux<ChatResponse> stream(...)

这意味着你可以直接把 DashScope 的增量输出转成 SSE 推给前端。

比如：

import io.agentscope.core.message.Msg;
import io.agentscope.core.message.TextBlock;
import io.agentscope.core.model.DashScopeChatModel;
import io.agentscope.core.model.GenerateOptions;
import reactor.core.publisher.Flux;

import java.util.List;

public class StreamDemo {

    public Flux<String> stream(String prompt) {
        DashScopeChatModel model = ModelFactory.createQwenModel();

        GenerateOptions options = GenerateOptions.builder()
                .stream(Boolean.TRUE)
                .build();

        return model.stream(
                        List.of(Msg.builder().textContent(prompt).build()),
                        List.of(),
                        options)
                .map(chatResponse -> chatResponse.getContent().stream()
                        .filter(TextBlock.class::isInstance)
                        .map(TextBlock.class::cast)
                        .map(TextBlock::getText)
                        .reduce("", String::concat))
                .filter(text -> text != null && !text.isBlank());
    }
}

这才是真正意义上的"边生成边显示"。

---

六、在 Spring Boot 里怎么接

如果是 Web 项目，通常会拆成这几层：

• Controller：暴露 REST 或 SSE 接口
• Service：封装 AgentScope 调用
• Configuration：声明模型 Bean
• Tool：定义业务工具

比如一个 SSE 接口：

@GetMapping(value = "/test", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
public Flux<String> test(@RequestParam String message) {
    return qwenResponseComposer.composeTypewriter(message);
}

这样前端就能实时接收模型输出。

---

七、我对 AgentScope 的几个判断

1. 它不是"更方便调用模型的 SDK"

它更像一个 Agent runtime。

2. 它更适合往业务里走

如果你在做企业内部助手、审批助手、查询执行一体化系统，AgentScope 的抽象会比较顺手。

3. Java 团队会比较舒服

很多 Agent 框架偏 Python 生态，而 AgentScope Java 对 Spring Boot / Java 团队更友好。

4. 真正难的不是"跑起来"，而是"约束住"

做 Agent 项目，后期更关键的是：

• 权限边界
• 工具治理
• 审计日志
• 错误处理
• 会话记忆
• 知识引用

框架能帮你起步，但真实项目最后拼的是工程化能力。

---

八、总结

如果只想做一个"能聊天"的 AI 页面，AgentScope 可能有点重。

但如果你已经开始考虑下面这些问题：

• 模型怎么接业务系统
• 工具怎么调
• 多轮对话怎么管
• 状态怎么保存
• 流式怎么做
• 后续怎么往生产级演进

那 AgentScope 值得试一试。

一句话总结：

AgentScope 适合的不是"模型调用 demo"，而是"真正要进入业务流程的 Agent 应用"。

---

参考

• AgentScope Java 官方文档：java.agentscope.io/zh/intro.ht...

---

如果你最近也在做下面这些事：

• 企业内部 AI 助手
• 带工具调用的问答系统
• 多轮对话型业务系统
• Spring Boot 落地 Agent 应用

那 AgentScope 值得你认真看一遍。

如果这篇对你有帮助，欢迎点赞、收藏，我后面把工具调用、流式输出、企业项目落地这几块继续展开写。