AgentScope Demo

基于 AgentScope 的 Java AI Agent 演示项目，支持多种 Agent 类型、工具调用、文档解析、多模态交互、RAG 知识库和多智能体协作。

特性

🤖 多种 Agent 类型

• Basic Chat: 纯对话 AI 助手
• Tool Calling: 带工具调用的 AI 助手（时间、计算器、天气）
• Task Agent: 支持文档解析的智能助手（.docx/.pdf/.xlsx）
• Bank Invoice: 银行发票自动生成
• Vision Analyzer: 图片理解和 OCR 文字识别
• Voice Assistant: 语音交互助手
• Search Assistant: 网络搜索和实时信息查询
• Project Planner: 项目规划和任务分解

🎨 多模态支持

• 文本: 自然语言对话
• 图片: OCR 文字识别、图表分析、场景理解
• 语音: 语音转文字、语音交互

🔍 RAG 知识库（Generic 模式）

• 本地自动索引: 启动时自动扫描 src/main/resources/knowledge/ 目录
• 上传文档: 支持 PDF、DOCX、TXT、MD 格式
• 向量相似度搜索: 基于 DashScope text-embedding-v3
• 智能问答: Generic RAG 模式，高效检索增强
• 状态追踪: Agent 配置面板实时显示索引状态cs-strategy-kb

🗂️ 会话管理

• 持久化会话历史
• 会话隔离
• 多会话管理

🤝 多智能体协作

• Sequential Pipeline: 串行执行多个子智能体
• Intelligent Routing: 自动路由到专家智能体
• Agent Handoffs: 智能体交接

📊 实时调试面板

• Agent 生命周期追踪
• LLM 调用详情（Token 使用量）
• 工具执行状态和耗时
• 思考过程可视化

界面展示

🎨 赛博朋克风格 UI

系统采用赛博朋克风格的深色主题界面，提供沉浸式的 AI 交互体验。

核心功能区域：

• 左侧边栏：Agent 选择器、会话管理、知识库管理
• 中间聊天区：流式对话、Markdown 渲染、代码高亮
• 右侧调试面板：实时显示 Agent 运行时信息
  • 🔍 Timeline: Agent 执行时间线
  • 📊 Metrics: Token 统计、调用耗时
  • 🧠 Thinking: AI 思考过程可视化
  • 🛠️ Tools: 工具调用详情和结果
  • 🤖 Multi-Agent: 多智能体协作事件

快速开始

环境要求

• Java 17+
• Maven 3.9+
• DashScope API Key (获取地址)

运行项目

# 克隆仓库
git clone https://github.com/ataskite/agentscope-demo.git
cd agentscope-demo

# 配置 API Key
export DASHSCOPE_API_KEY=your_api_key_here

# 启动应用
mvn spring-boot:run

启动后访问 http://localhost:8081（端口配置见 src/main/resources/application.yml）

可选依赖（缺失不影响启动，仅对应功能降级）：

• Node.js/npx：MCP 演示服务器（supergateway 桥，占用 9090/9091 端口）需要；未安装时自动跳过
• Docker：仅 sandbox-artifact-demo 这一个 agent（DOCKER 沙箱模式）需要；其余 agent 均为本地执行

使用示例

Basic Chat

你：你好，请介绍一下自己
Assistant：你好！我是一个 AI 助手，很高兴为您服务...

Tool Calling

你：现在几点了？帮我算一下 123 + 456
ToolAgent：[调用 get_current_time] [调用 calculate_sum]
现在是北京时间 2024-04-10 14:30:00，123 + 456 = 579

Task Agent - 文档解析

1. 点击上传按钮（+）
2. 选择 .docx、.pdf 或 .xlsx 文件
3. 输入指令："请总结这个文档的核心内容"
4. TaskAgent 自动调用对应解析工具

Vision Analyzer - 图片分析

1. 点击上传按钮（+）
2. 选择图片文件（.jpg, .png, .gif, .webp）
3. 自动切换到视觉分析智能体
4. 输入问题："图片中有什么文字？"

RAG Chat - 知识库问答

方式一：本地目录自动索引

1. 将文档放入 src/main/resources/knowledge/ 目录
2. 重启应用（或等待后台索引完成）
3. 切换到 "RAG Chat" 智能体
4. 提问与文档相关的问题

方式二：上传文档

1. 点击知识库图标
2. 上传文档（PDF、DOCX、TXT）
3. 切换到 "RAG Chat" 智能体
4. 提问与文档相关的问题

Bank Invoice - 发票生成

请帮我生成银行发票。
客户姓名：张三丰
身份证号：110101199003072316
手机：13802213478
邮箱：[email protected]
合同号：HT20240410001
借据号：JD20240410001
放款日期：2024-04-10
贷款总额：100000
银行放款金额：80000
费用类型：服务费
发票金额：5000
流水号：001

自动生成：

• Excel: XX银行_张某某_240410_001.xlsx
• Word: XX银行_张某某_240410_001.docx

项目结构

src/main/java/com/skloda/agentscope/
├── controller/
│   ├── ChatController.java         # 响应式 SSE 聊天 + 文件上传
│   └── KnowledgeController.java    # 知识库管理 API
├── service/
│   ├── AgentService.java           # Agent 路由，实例缓存
│   ├── SessionManagerService.java  # 会话管理
│   ├── KnowledgeService.java       # RAG 知识库（含本地索引）
│   └── KnowledgeProperties.java    # 知识库配置属性
├── agent/
│   ├── AgentConfig.java            # Agent 配置实体
│   ├── AgentConfigService.java     # 配置加载服务
│   └── AgentFactory.java           # Agent 创建工厂
├── runtime/
│   ├── AgentRuntime.java           # 运行时容器
│   └── AgentRuntimeFactory.java    # 运行时工厂
├── hook/
│   └── ObservabilityHook.java      # 可观测性 Hook
├── model/
│   ├── ChatRequest.java            # 请求模型
│   ├── ChatEvent.java              # 事件模型
│   ├── SessionInfo.java            # 会话信息
│   ├── MultiModalMessage.java      # 多模态消息
│   ├── KnowledgeFileStatus.java    # 知识文件状态
│   └── KnowledgeIndexStatus.java   # 知识索引状态
└── tool/
    ├── ToolRegistry.java           # 工具注册表
    ├── SimpleTools.java            # 演示工具集
    ├── DocxParserTool.java         # DOCX 解析
    ├── PdfParserTool.java          # PDF 解析
    ├── XlsxParserTool.java         # XLSX 解析
    ├── BankInvoiceTool.java        # 银行发票生成
    └── WebSearchTool.java          # 网络搜索工具

src/main/resources/
├── skills/                         # 技能定义
│   ├── docx/SKILL.md
│   ├── pdf/SKILL.md
│   ├── xlsx/SKILL.md
│   ├── docx-template/SKILL.md
│   └── bank_invoice_java/
│       ├── SKILL.md
│       └── assets/                 # 模板文件
├── config/
│   └── agents.yml                  # Agent 配置（YAML）
├── templates/
│   └── chat.html                   # 单页聊天 UI
├── static/
│   ├── scripts/                    # 前端模块化 JS
│   │   ├── chat.js
│   │   ├── api.js
│   │   ├── state.js
│   │   └── modules/
│   │       ├── agents.js
│   │       ├── session.js
│   │       ├── knowledge.js
│   │       ├── upload.js
│   │       ├── debug.js
│   │       ├── ui.js
│   │       └── utils.js
│   └── styles/                     # 模块化 CSS
│       ├── chat.css
│       └── modules/
│           ├── header.css
│           ├── sidebar.css
│           ├── chat.css
│           ├── debug.css
│           ├── modal.css
│           └── upload.css
└── application.yml                 # 配置文件

配置

主要配置在 application.yml：

agentscope:
  model:
    dashscope:
      api-key: ${DASHSCOPE_API_KEY}    # 通过环境变量设置
  session:
    storage-path: ${user.home}/.agentscope/demo-sessions
  knowledge:
    enabled: true                      # 启用知识库
    path: src/main/resources/knowledge # 本地知识目录
    embedding-model: text-embedding-v3 # 嵌入模型
    dimensions: 1024                   # 向量维度
    chunk-size: 512                    # 分块大小
    overlap-size: 50                   # 重叠大小
    split-strategy: PARAGRAPH          # 分块策略
    auto-index-on-startup: true        # 启动时自动索引

spring:
  servlet:
    multipart:
      max-file-size: 50MB              # 文件上传限制

技术栈

可观测性

调试面板实时显示完整的 Agent 执行过程：

内置 Agent

单功能 Agent

专家 Agent（用于多智能体协作）

多智能体协作

API 端点

添加新 Agent

1. 在 src/main/resources/config/agents.yml 中添加配置
2. 如果使用新工具类，在 tool/ 目录创建带 @Tool 注解的方法
3. 在 ToolRegistry 构造函数中注册工具
4. 如果使用技能，创建 skills//SKILL.md
5. 重启应用 — Agent 自动出现在 UI 中

开发

# 编译
mvn clean compile

# 测试
mvn test

# 打包
mvn package

License

Apache License 2.0

Links

• AgentScope 官方文档
• DashScope 控制台
• 项目开发指南