example/java/rocketmq-multiagent-session-consistency/README.md

# Quick Start

本案例展示了基于 [Apache RocketMQ](http://rocketmq.apache.org/) 的LiteTopic为分布式 Web 应用的长连接会话管理提供的一种高效解决方案。(实现了跨节点会话状态的一致性)

## 整体架构图
<img src="docs/img.png" alt="Architecture Diagram" width="1200" />

## 基本的前期准备工作

### 1. 部署 Apache RocketMQ

部署 [Apache RocketMQ](http://rocketmq.apache.org/) 的 LiteTopic 版本(关于开源版本，预计在2月发布)，或购买支持 LiteTopic 的 RocketMQ 商业版实例，并创建以下资源：

- **1.1** 创建接收响应请求的轻量级Topic：`WorkerAgentResponse`(web-gateway用于接收响应结果)
- **1.2** 创建与`WorkerAgentResponse` 绑定的轻量级消费者CID：`CID_HOST_AGENT_LITE`(web-gateway中用于订阅`WorkerAgentResponse`)
- **1.3** 创建普通Topic：`LLM_TOPIC`(llm-agent用于接收任务请求)
- **1.4** 创建普通消费者CID：`LLM_CID`(llm-agent中用于订阅`LLM_TOPIC`)

### 2. 以下示例以阿里云百炼平台提供的Qwen大模型调用服务为例。欢迎社区开发者贡献来自其他厂商的更多集成案例。

1. 进入阿里云百炼平台
2. 获取对应调用服务的apiKey

## 运行环境

- JDK 17 及以上
- [Maven](http://maven.apache.org/) 3.9 及以上

## 代码打包与示例运行

### 1. 编译打包

```shell
mvn clean install -Dmaven.test.skip=true -Dcheckstyle.skip=true
```
以下4个进程建议分别在不同的窗口中运行

### 2. 基本参数介绍

| 参数名称  | 基本介绍                              | 是否必填 |
|-------|-----------------------------------|------|
| rocketMQEndpoint | rocketmq服务接入点                     | 是    |
| rocketMQNamespace | rocketmq命名空间                      | 否    |
| bizTopic | 普通Topic，llm-agent用于接收任务请求的Topic   | 是    |
| bizConsumerGroup | 普通消费者CID，llm-agent用于订阅普通Topic     | 是    |
| rocketMQAK | rocketmq账号                        | 否    |
| rocketMQSK | rocketmq密码                        | 否    |
| apiKey | 百炼平台调用apiKey                      | 是    |
| workAgentResponseTopic | 轻量Topic，web-gateway用于接收响应结果的Topic | 是    |
| workAgentResponseGroupID | 轻量消费者ID，web-gateway用于订阅轻量Topic    | 是    |
| agentTopic | 普通Topic，llm-agent接收请求的Topic        | 是    |

### 3.运行llm-agent
```shell
cd llm-agent/target
```
```shell
java -DrocketMQEndpoint= -DrocketMQNamespace= -DrocketMQAK= -DrocketMQSK= -DbizTopic=LLM_TOPIC -DbizConsumerGroup=LLM_CID -DapiKey= -jar llm-agent-2.1.1-SNAPSHOT.jar
```

### 4.运行web-gateway (监听9090端口)
```shell
cd web-gateway/target
```
```shell
java -DrocketMQEndpoint= -DrocketMQNamespace= -DworkAgentResponseTopic=WorkerAgentResponse -DworkAgentResponseGroupID=CID_HOST_AGENT_LITE -DrocketMQAK= -DrocketMQSK= -DagentTopic=LLM_TOPIC -jar web-gateway-2.1.1-SNAPSHOT.jar --server.port=9090
```

### 5.运行web-gateway (监听9191端口)
```shell
cd web-gateway/target
```
```shell
java -DrocketMQEndpoint= -DrocketMQNamespace= -DworkAgentResponseTopic=WorkerAgentResponse -DworkAgentResponseGroupID=CID_HOST_AGENT_LITE -DrocketMQAK= -DrocketMQSK= -DagentTopic=LLM_TOPIC -jar web-gateway-2.1.1-SNAPSHOT.jar --server.port=9191
```

### 6.运行web-gateway (监听9292端口)
```shell
cd web-gateway/target
```
```shell
java -DrocketMQEndpoint= -DrocketMQNamespace= -DworkAgentResponseTopic=WorkerAgentResponse -DworkAgentResponseGroupID=CID_HOST_AGENT_LITE -DrocketMQAK= -DrocketMQSK= -DagentTopic=LLM_TOPIC -jar web-gateway-2.1.1-SNAPSHOT.jar --server.port=9292
```
### 7.开始体验
- 打开浏览器，访问 http://localhost:9090
- 点击“重连会话”按钮，即可在节点切换过程中实现无缝会话恢复与数据续传

<img src="docs/img1.png" alt="Architecture Diagram" width="1200" />