第1章 AgentScope-Java 简介

本章目标：了解 AgentScope-Java 是什么、能做什么、为什么选择它

---

1.1 什么是 AgentScope-Java

1.1.1 框架定位

AgentScope-Java 是一个面向智能体的编程框架，专门用于构建基于大语言模型（LLM）的 AI 应用程序。

┌─────────────────────────────────────────────────────────────┐
│                      你的业务应用                            │
├─────────────────────────────────────────────────────────────┤
│                   AgentScope-Java 框架                       │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐        │
│  │  Agent  │  │  Tool   │  │ Memory  │  │  Model  │        │
│  │  智能体  │  │  工具   │  │  记忆   │  │  模型   │        │
│  └─────────┘  └─────────┘  └─────────┘  └─────────┘        │
├─────────────────────────────────────────────────────────────┤
│                  LLM 服务 (DashScope/OpenAI/...)            │
└─────────────────────────────────────────────────────────────┘

简单来说，AgentScope-Java 为你提供了创建智能体所需的一切核心能力：

能力	说明	类比
ReAct 推理	让智能体能够"思考"并"行动"	就像人类思考后再做事
工具调用	让智能体能够执行外部操作	就像人使用计算器、搜索引擎
记忆管理	让智能体能够记住对话历史	就像人的短期和长期记忆
多智能体协作	让多个智能体能够协同工作	就像团队协作完成任务

1.1.2 AgentScope 家族

AgentScope 最初由阿里巴巴达摩院开发，是一个开源的多智能体开发平台。目前有两个版本：

版本	语言	特点	适用场景
AgentScope-Python	Python	灵活、生态丰富	研究、原型开发
AgentScope-Java	Java	类型安全、企业级	生产环境、企业应用

两个版本共享相同的设计理念，但 Java 版本专门针对企业级应用进行了优化：

• 类型安全：编译时检查，减少运行时错误
• 响应式架构：基于 Project Reactor，高性能非阻塞
• Spring 集成：无缝融入 Java 企业级生态
• GraalVM 支持：原生镜像，快速启动

1.1.3 什么是"智能体"

在深入框架之前，让我们明确"智能体"的概念：

传统程序：                    智能体程序：
输入 → 固定逻辑 → 输出        输入 → LLM思考 → 决策 → 行动 → 结果
                                      ↑__________________|
                                          循环执行

智能体（Agent） 是一个能够：

1. 感知环境：接收用户输入、读取数据
2. 自主决策：基于 LLM 推理，决定下一步行动
3. 执行行动：调用工具、生成回复
4. 学习记忆：记住历史交互，持续改进

与传统的"问答式" LLM 应用不同，智能体具有自主性和持续性：

// 传统 LLM 调用：一问一答
String response = llm.chat("今天天气怎么样？");

// 智能体调用：自主完成复杂任务
Msg response = agent.call(
    Msg.builder().textContent("帮我订一张明天去上海的机票").build()
).block();
// 智能体会自动：
// 1. 理解意图
// 2. 查询航班信息（调用工具）
// 3. 比较价格（多次推理）
// 4. 完成预订（执行操作）
// 5. 返回结果

---

1.2 核心亮点

1.2.1 自主且可控

AgentScope 采用 ReAct（Reasoning + Acting） 范式，这是当前最流行的智能体设计模式。

ReAct 循环：
┌────────────────────────────────────────────────────┐
│                                                    │
│   ┌─────────┐         ┌─────────┐                 │
│   │ 推理    │ ──────→ │ 需要工具? │                │
│   │Reasoning│         └────┬────┘                 │
│   └─────────┘              │                      │
│        ↑                   │ 是                   │
│        │                   ↓                      │
│        │            ┌─────────┐                   │
│        │            │  行动   │                   │
│        └─────────── │ Acting  │                   │
│       结果返回       └─────────┘                   │
│                           │                       │
│                           │ 否                    │
│                           ↓                       │
│                     ┌─────────┐                   │
│                     │ 返回结果 │                   │
│                     └─────────┘                   │
└────────────────────────────────────────────────────┘

自主性：

• 智能体可以动态决定使用哪些工具
• 根据任务复杂度自动调整执行步骤
• 处理未预见的情况和错误

可控性： 在生产环境中，没有控制的自主性是一种隐患。AgentScope 提供了完整的运行时介入机制：

// ========================================
// 【运行时控制示例】
// ========================================

// 1. 安全中断：在任意时刻暂停执行
agent.interrupt();

// 2. Hook 系统：在任意阶段注入逻辑
Hook safetyHook = new Hook() {
    @Override
    public <T extends HookEvent> Mono<T> onEvent(T event) {
        if (event instanceof PreActingEvent e) {
            // 检查即将执行的工具是否安全
            String toolName = e.getToolUse().getName();
            if (isDangerousTool(toolName)) {
                e.stopAgent();  // 暂停执行，等待人工确认
            }
        }
        return Mono.just(event);
    }
};

// 3. 人机协同：敏感操作需要人工确认
// 详见第17章 Human-in-the-Loop

1.2.2 内置工具

AgentScope 内置了生产就绪的工具，解决智能体开发中的常见挑战：

PlanNotebook - 任务规划

// ========================================
// 【任务规划示例】
// 复杂任务自动分解为可追踪的子步骤
// ========================================

ReActAgent agent = ReActAgent.builder()
        .name("ProjectManager")
        .sysPrompt("你是项目经理，善于将复杂任务分解为可执行的步骤。")
        .model(model)
        .enablePlan()  // 一行代码启用计划功能
        .build();

// 智能体会自动：
// 1. 分析任务复杂度
// 2. 创建结构化计划
// 3. 逐步执行子任务
// 4. 更新完成状态

结构化输出 - 类型安全的响应

// ========================================
// 【结构化输出示例】
// 从自然语言中提取结构化数据
// ========================================

// 定义输出结构
public class OrderInfo {
    public String productName;
    public int quantity;
    public String deliveryAddress;
}

// 请求结构化输出
Msg response = agent.call(
    Msg.builder().textContent("我要买3个苹果，送到北京市朝阳区...").build(),
    OrderInfo.class  // 指定输出类型
).block();

// 类型安全地获取结果
OrderInfo order = response.getStructuredData(OrderInfo.class);
System.out.println("产品: " + order.productName);    // "苹果"
System.out.println("数量: " + order.quantity);       // 3

长期记忆 - 跨会话的记忆

// ========================================
// 【长期记忆示例】
// 记住用户偏好，提供个性化服务
// ========================================

// 第一次对话
user: "我喜欢喝拿铁咖啡，少糖"
assistant: "好的，我记住了您的偏好。"

// 一周后的对话（新会话）
user: "给我来杯咖啡"
assistant: "好的，为您准备一杯少糖拿铁，还是您上次的口味。"
// ↑ 智能体通过长期记忆记住了用户偏好

RAG - 知识增强

// ========================================
// 【RAG 示例】
// 让智能体能够检索企业知识库
// ========================================

// 配置知识库
Knowledge knowledge = SimpleKnowledge.builder()
        .embeddingModel(embeddingModel)
        .build();

// 加载文档
knowledge.addDocuments(
    reader.read(ReaderInput.fromFile("company_policy.pdf")).block()
).block();

// 智能体自动检索相关知识回答问题
ReActAgent agent = ReActAgent.builder()
        .name("HRAssistant")
        .knowledge(knowledge)
        .ragMode(RAGMode.GENERIC)  // 自动检索模式
        .build();

// 用户提问
agent.call(Msg.builder()
    .textContent("公司的年假政策是什么？")
    .build());
// 智能体会先从知识库检索相关内容，再生成回答

1.2.3 无缝集成

MCP 协议

MCP（Model Context Protocol）是连接 AI 应用与外部工具服务的标准协议。AgentScope 原生支持 MCP：

// ========================================
// 【MCP 集成示例】
// 连接外部 MCP 工具服务器
// ========================================

// 连接到文件系统 MCP 服务器
McpClientWrapper mcpClient = McpClientBuilder.create("filesystem")
        .stdioTransport("npx", "-y", 
                "@modelcontextprotocol/server-filesystem", "/workspace")
        .buildAsync()
        .block();

// 注册到工具包
toolkit.registerMcpClient(mcpClient).block();

// 智能体现在可以读写文件了！
agent.call(Msg.builder()
    .textContent("读取 /workspace/config.json 的内容")
    .build());

A2A 协议

A2A（Agent-to-Agent）协议用于分布式多智能体协作：

// ========================================
// 【A2A 集成示例】
// 调用远程智能体服务
// ========================================

// 创建远程智能体客户端
A2aAgent remoteExpert = A2aAgent.builder()
        .name("LegalExpert")
        .agentCardResolver(new WellKnownAgentCardResolver(
                "https://legal-agent.example.com",
                "/.well-known/agent-card.json",
                Map.of()))
        .build();

// 像调用本地智能体一样调用远程智能体
Msg response = remoteExpert.call(
    Msg.builder().textContent("这份合同有什么风险？").build()
).block();

1.2.4 生产就绪

特性	说明	技术实现
高性能	非阻塞、高并发	Project Reactor 响应式架构
快速启动	200ms 冷启动	GraalVM 原生镜像支持
可观测性	分布式追踪	OpenTelemetry 原生集成
类型安全	编译时检查	Java 强类型系统

---

1.3 技术栈概览

1.3.1 核心依赖

<!-- AgentScope 核心依赖 -->
<dependency>
    <groupId>io.agentscope</groupId>
    <artifactId>agentscope</artifactId>
    <version>1.0.7</version>
</dependency>

框架基于以下技术栈构建：

技术	用途	版本要求
JDK	运行时环境	17+
Project Reactor	响应式编程	3.5+
Jackson	JSON 序列化	2.15+
SLF4J	日志抽象	2.0+

1.3.2 支持的 LLM 提供商

提供商	模型类	流式	工具	视觉	推理
DashScope	DashScopeChatModel	✅	✅	✅	✅
OpenAI	OpenAIChatModel	✅	✅	✅	-
Anthropic	AnthropicChatModel	✅	✅	✅	✅
Google Gemini	GeminiChatModel	✅	✅	✅	✅
Ollama	OllamaChatModel	✅	✅	✅	✅
DeepSeek	OpenAIChatModel	✅	✅	-	✅

1.3.3 框架集成

// ========================================
// 【Spring Boot 集成】
// ========================================

// 添加 Starter 依赖
// <artifactId>agentscope-spring-boot-starter</artifactId>

// application.yml 配置
// agentscope:
//   dashscope:
//     api-key: ${DASHSCOPE_API_KEY}
//   agent:
//     name: assistant
//     sys-prompt: 你是一个有帮助的助手

// 自动注入使用
@RestController
public class ChatController {
    @Autowired
    private ReActAgent agent;  // 自动配置的智能体
    
    @PostMapping("/chat")
    public Mono<String> chat(@RequestBody String message) {
        return agent.call(Msg.builder().textContent(message).build())
                    .map(Msg::getTextContent);
    }
}

---

1.4 与其他框架的对比

1.4.1 主流框架对比

特性	AgentScope-Java	LangChain4j	Spring AI
ReAct 智能体	✅ 内置完整实现	⚠️ 需要自行组装	⚠️ 有限支持
多智能体协作	✅ Pipeline/MsgHub/A2A	⚠️ 基础支持	❌ 不支持
MCP 协议	✅ 原生支持	❌ 不支持	❌ 不支持
人机协同	✅ Hook 系统完整支持	⚠️ 有限支持	❌ 不支持
状态持久化	✅ Session 系统	⚠️ 需要自行实现	⚠️ 有限支持
响应式编程	✅ 原生 Reactor	⚠️ 部分支持	⚠️ 部分支持
结构化输出	✅ 自纠错解析器	⚠️ 基础支持	✅ 良好支持
中文文档	✅ 完善	⚠️ 较少	⚠️ 较少

1.4.2 何时选择 AgentScope-Java

适合使用 AgentScope-Java 的场景：

1. 复杂智能体应用

- 需要多轮推理和工具调用 - 需要多智能体协作 - 需要任务规划和执行

1. 企业级生产环境

- 需要高可靠性和可观测性 - 需要状态持久化 - 需要与现有 Java 系统集成

1. 需要人机协同

- 敏感操作需要人工确认 - 需要实时监控和干预

可能不适合的场景：

1. 简单的问答应用

- 只需要基础的 LLM 调用 - 不需要工具和记忆 - → 考虑使用 Spring AI 或直接调用 API

1. 快速原型开发

- 需要快速验证想法 - 不关心生产环境 - → 考虑使用 Python 版 AgentScope

---

1.5 本章小结

本章我们了解了：

1. AgentScope-Java 是什么

- 面向智能体的 Java 编程框架 - 阿里巴巴达摩院开源项目的 Java 版本 - 专为企业级应用设计

1. 核心亮点

- 自主且可控：ReAct 范式 + 运行时介入 - 内置工具：计划、结构化输出、长期记忆、RAG - 无缝集成：MCP 协议、A2A 协议 - 生产就绪：响应式、快速启动、可观测

1. 技术栈

- JDK 17+、Project Reactor - 支持多种 LLM 提供商 - Spring Boot 集成

1. 框架选型

- 适合复杂智能体应用和企业级场景 - 相比其他框架有更完整的智能体支持

---

练习

1. 访问 AgentScope-Java GitHub 仓库，浏览项目结构
2. 阅读官方文档的快速开始部分
3. 思考：你的项目中有哪些场景适合使用智能体？

---

下一章 → 第2章 环境搭建与第一个智能体