# AgentScope-Java-DeepResearch **Repository Path**: wii95/AgentScope-Java-DeepResearch ## Basic Information - **Project Name**: AgentScope-Java-DeepResearch - **Description**: No description available - **Primary Language**: Unknown - **License**: Apache-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-08-23 - **Last Updated**: 2026-08-23 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README [English](README-en-US.md) | [中文](README.md) # 🔍 AgentScope 深度研究助手 ![Java 21](https://img.shields.io/badge/Java-21-orange) ![Spring Boot 3.5](https://img.shields.io/badge/Spring%20Boot-3.5-6DB33F) ![AgentScope](https://img.shields.io/badge/AgentScope-1.0.12-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-blue) 基于 **AgentScope Java** 的多智能体**深度研究**应用。输入一个研究问题 → 五个智能体协作完成「**规划 → 联网搜索 → 阅读提炼 → 事实核查 → 撰写**」→ 产出一份**带可点击引用的结构化研究报告**，全过程通过 SSE 实时流式呈现。 > 同时是一个端到端的 **AgentScope Java 教学样本**（ReAct、Function Calling、Memory、多智能体编排、流式），也是一个可自部署的调研工具。

输入问题 → 看着智能体实时工作 → 报告边写边出 → 完成。

## ✨ 特性 - **5 个智能体协作**：Planner 规划 · Researcher 检索 · Reader 阅读 · FactChecker 核查 · Writer 撰写 - **联网搜索（Tavily）+ 网页抓取（Jsoup）**，通过 `@Tool` Function Calling 暴露 - **事实核查回环**：发现信息缺口时自动补搜，最多 2 轮 - **带可点击 `[n]` 引用的报告** + 来源列表（含 URL） - **实时 SSE**：逐个 Agent 步骤实时可见；报告边生成边推送 - **Last-Event-ID 断线重连**（事件走共享 Redis Stream，断连不丢） - **分布式预留**：Agent/工具接口化、状态全外置（MySQL + Redis） - Docker Compose 一键起：client(:9090) + 5 个角色 server + Nacos + MySQL + Redis ## 🏗 架构（v2 分布式） ``` [用户浏览器] ──HTTP + SSE──► [orchestrator-client :9090] WebFlux · REST + SSE · 编排 · MySQL/Redis │ │ A2A JSON-RPC（经 Nacos 发现 agent card） │ namespace=research ┌────────────┬────────────┬──────┴─────┬────────────┬────────────┐ ▼ ▼ ▼ ▼ ▼ [planner] [researcher] [reader] [factchecker] [writer] :8081 :8082 :8083 :8084 :8085 │ │ │ │ │ └────────────┴───────┬────┴────────────┘ ▼ Nacos（注册中心 + 配置中心，namespace=research）＋ MySQL ＋ Redis ``` 5 个 Agent 各运行在独立 server 进程，client 经 **A2A 远程调用**（Nacos 发现 agent card）；业务配置（含 `application.name`/`autoconfigure.exclude`/`server.port`）全在 **Nacos 配置中心**（namespace `research`）。设计文档：[`docs/design/07-v2-distributed.md`](docs/design/07-v2-distributed.md)；单模块时期（M0–M5）见 [`docs/code-architecture.md`](docs/code-architecture.md)。 ## 🤖 工作原理 ``` 1. Planner → 把问题拆成 3–5 个可搜索子问题 2. Researcher→ 对每个子问题并行搜索 + 抓取来源 3. Reader → 把来源提炼成结构化研究笔记 4. FactChecker → 核查笔记、找缺口；必要时回到 Researcher 补搜（≤2 轮） 5. Writer → 流式产出带引用的 Markdown 报告（REPORT_CHUNK 事件） ``` 5 个 Agent 各自运行在独立 server 进程，由 client 编排（A2A 远程调用）；每个阶段的事件发到 **Redis Stream**，SSE 端点实时推给浏览器。状态存 **Redis**（研究上下文）+ **MySQL**（任务/笔记/来源/报告）。 ## 🚀 快速开始 ### 方式 A —— Docker（推荐） ```bash export DASHSCOPE_API_KEY=xxx # 必须（LLM） export TAVILY_API_KEY=xxx # 必须（联网搜索） docker compose up --build # v2 分布式：client(:9090) + 5 个 role server + nacos + mysql + redis # 首次启动 nacos-config-init 会自动把 nacos-config/*.yaml 推送到 Nacos 配置中心（group=RESEARCH_GROUP） # 浏览器打开 http://localhost:9090/ ``` ### 方式 B —— 本地逐模块运行（开发调试；v2 为分布式，推荐方式 A） **选项 1：Nacos 模式（默认，与方式 A 同架构，配置全在 Nacos）** ```bash docker compose up -d mysql redis nacos # 起依赖（含 nacos） ./scripts/init-nacos-config.sh # 首次/改配置后把 nacos-config/*.yaml 推送到 Nacos（命名空间 research） export DASHSCOPE_API_KEY=xxx export TAVILY_API_KEY=xxx # 依次在 planner/researcher/reader/factchecker/writer-server、orchestrator-client 目录 ./mvnw spring-boot:run # （默认 profile=nacos → application-nacos.yaml → 从 Nacos 拉全部业务配置） ``` **选项 2：本地模式（无 Nacos，`SPRING_PROFILES_ACTIVE=local`）** ```bash docker compose up -d mysql redis # 只需 mysql/redis（无需 nacos） export DASHSCOPE_API_KEY=xxx export TAVILY_API_KEY=xxx # 依次在 5 个 server、orchestrator-client 目录 SPRING_PROFILES_ACTIVE=local ./mvnw spring-boot:run # （走 application-local.yaml，A2A 用 wellknown 直连，client 自动指向各 server 的 localhost:8081-8085） ``` 接口冒烟： ```bash # 完整研究（异步） curl -XPOST http://localhost:9090/api/research -H 'Content-Type: application/json' -d '{"query":"向量数据库如何选型"}' # 然后 GET http://localhost:9090/api/research/{taskId}（状态/报告） # 或订阅过程：curl -N http://localhost:9090/api/research/{taskId}/stream ``` ## ⚙️ 配置（环境变量） | 变量 | 必需 | 说明 | |---|---|---| | `DASHSCOPE_API_KEY` | ✅ | 阿里通义 DashScope key —— [获取](https://dashscope.console.aliyun.com/apiKey) | | `TAVILY_API_KEY` | ✅ | Tavily 搜索 key —— [获取](https://tavily.com/) | | `DB_HOST` / `DB_PORT` / `DB_NAME` / `DB_USER` / `DB_PASSWORD` | — | MySQL（默认 localhost:3306/research，root/rootpass） | | `REDIS_HOST` / `REDIS_PORT` | — | Redis（默认 localhost:6379） | | `NACOS_SERVER_ADDR` / `NACOS_USERNAME` / `NACOS_PASSWORD` | — | Nacos 注册 + 配置中心（默认 127.0.0.1:8848，nacos/nacos） | | `NACOS_NAMESPACE` | — | 项目专属命名空间（配置 + A2A 注册/发现统一，默认 `research`，seed 自动创建） | > 密钥**绝不入库**——`application.yaml` 里只有 `${ENV_VAR}` 占位。把 [`.env.example`](.env.example) 复制为 `.env`。 > > **Nacos 配置中心**：各模块业务配置几乎全在 Nacos（数据源 `nacos-config/*.yaml`，**namespace=`research`**（`NACOS_NAMESPACE` 可配）、group=`RESEARCH_GROUP`，密钥仍是 `${ENV_VAR}` 占位）——`application.yaml` 只留 Nacos 自举 + 默认 `profile=nacos`（走 `application-nacos.yaml` 拉配置，含 `application.name`/`autoconfigure.exclude`/`server.port` 等）；`application-local.yaml` 是完整自包含配置（`SPRING_PROFILES_ACTIVE=local` 即可**无 Nacos 运行**，A2A 走 wellknown 直连）。`docker compose up` 自动 seed（**seed 自动创建命名空间**）；本地 Nacos 模式需先 `./scripts/init-nacos-config.sh`；改配置后 `docker compose run --rm nacos-config-init` 重推；server 侧 `@RefreshScope` 热更新无需重启。控制台按命名空间 `research` 筛选即可看到本项目全部配置。 ## 🧱 技术栈 | | | |---|---| | **运行时** | Java 21 · Spring Boot 3.5 · WebFlux（响应式，Netty） | | **Agent** | AgentScope Java `agentscope-spring-boot-starter:1.0.12`（含 DashScope） | | **LLM** | 通义 Qwen（qwen-plus），经 DashScope | | **存储** | MySQL 8（MyBatis-Plus）· Redis 7（上下文 + Redis Stream） | | **注册/配置中心** | Nacos（服务发现 + 配置中心，SCA nacos-config） | | **工具** | Tavily（搜索）· Jsoup（抓取） | | **前端** | 原生 HTML/JS + marked.js（零构建，打进 jar） | ## 📁 项目结构 ``` AgentScope-Java-DeepResearch ├── common/common-core/ 契约：5 个 role 接口 + DTO + 枚举 + 工具（WebSearcher/Jsoup…） ├── orchestrator-client/ 编排 + Web（REST/SSE）+ 5 个 A2A 远程 Client + MySQL/Redis 仓储 ├── planner-server/ 角色 server：Planner（A2A + Nacos 注册） ├── researcher-server/ 角色 server：Researcher（web_search/web_fetch 工具） ├── reader-server/ 角色 server：Reader ├── factchecker-server/ 角色 server：FactChecker ├── writer-server/ 角色 server：Writer ├── nacos-config/ 进 git 的配置数据源（seed 推送 Nacos 的唯一事实源，namespace=research） └── scripts/init-nacos-config.sh 推配置到 Nacos（自动创建命名空间，幂等） ``` 文档：[`docs/`](docs/) —— 设计、编码规范、代码架构、路线图。 ## 🚀 效果图 项目启动完毕之后，访问 http://localhost:9090 端口即可 ![](docs/img/v1版本-开始.png) ![](docs/img/v1版本-完成1.png) ![](docs/img/v1版本-完成2.png) ## 🗺 路线图 - ✅ M0 基础设施 · ✅ M1 工具+单 Agent · ✅ M2 多 Agent 编排 - ✅ M3 响应式 SSE · ✅ M4 前端 Demo · ✅ M5 开源化 - ✅ v2 分布式：A2A 远程化 + 多模块 + Nacos 注册/配置中心（[`docs/design/07-v2-distributed.md`](docs/design/07-v2-distributed.md)） 后续可选：报告历史、多模型路由。 ## 📄 许可证 [Apache License 2.0](LICENSE) —— 与 AgentScope 一致。 ## 🙏 致谢 - [AgentScope](https://github.com/agentscope-ai) —— 本项目所基于的多智能体框架。 - [Spring AI Alibaba](https://github.com/alibaba/spring-ai-alibaba) 生态。 - [Tavily](https://tavily.com/) · [marked.js](https://marked.js.org/)。