# 第十一章 中断与恢复：用 AgentStateStore 持久化会话，sessionId 实现断点续聊

> "用户问了 3 轮突然关掉浏览器；20 分钟后用同一个会话 ID 回来——上一轮的上下文、todo、subagent 状态怎么全在？这是 2.0 的 `AgentStateStore` 后端（`JsonFileAgentStateStore` / `RedisAgentStateStore` / `MysqlAgentStateStore`）干的事，比 1.x 自己把 `Memory` 序列化 JSON 简单很多。"
>
> 本章你将学到：如何让 `HarnessAgent` 在中断后秒级恢复、如何在前端用 `sessionId` 做'断点续聊'、以及如何配合 `Plan Mode` 让用户的待办清单也跟着恢复。

## 11.1 中断与恢复的本质

1.x 时代，"中断恢复" 要自己做：

1. 写一个 `Memory` 的 JSON 序列化器
2. 启动时检查 session 目录，有旧 JSON 就 load 进 `Memory`
3. 手动管理 session ID 与 cookie / token 的对应

2.0 把这件事**下沉到 `AgentStateStore` 后端**——`HarnessAgent` 调用时根据 `RuntimeContext.sessionId()` 去后端查状态；查到就 load 进 `AgentState`，查不到就当新会话。**业务代码不需要写任何序列化逻辑**。

## 11.2 第一个可恢复会话

```java
import io.agentscope.core.agent.RuntimeContext;
import io.agentscope.core.message.UserMessage;
import io.agentscope.core.model.DashScopeChatModel;
import io.agentscope.core.state.JsonFileAgentStateStore;
import io.agentscope.harness.HarnessAgent;

import java.nio.file.Path;
import java.util.List;

public class Chapter11_Resume {

    public static void main(String[] args) {
        // 用同一个 sessionId 模拟"用户先问一通，再回来问"
        String sessionId = "demo-user-9527-2026-06-07";

        HarnessAgent agent = HarnessAgent.builder()
                .name("assistant")
                .sysPrompt("你是一个中文助理，简洁回答。")
                .model(DashScopeChatModel.builder()
                        .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                        .modelName("qwen-plus")
                        .build())
                .workspace(Path.of("./workspace"))
                .stateStore(new JsonFileAgentStateStore(Path.of("./workspace")))  // 文件版 AgentStateStore
                .build();

        RuntimeContext ctx = RuntimeContext.builder()
                .sessionId(sessionId)
                .userId("9527")
                .build();

        // ---- 第一通对话 ----
        agent.call(List.of(new UserMessage("user", "我叫小李，在杭州做程序员。")), ctx).block();
        agent.call(List.of(new UserMessage("user", "我用什么语言开发？")), ctx).block();

        // 假装用户关掉浏览器。20 分钟后 JVM 重新跑 main() —— 实际生产里这是另一个进程。

        // ---- 20 分钟后：用同一 sessionId 接着问 ----
        agent.call(List.of(new UserMessage("user", "我叫什么？在哪个城市？")), ctx).block();
        // 输出会包含："你叫小李，在杭州做程序员。"
    }
}
```

第一次跑：

```text
[reply] 你好小李，很高兴认识你。
[reply] 根据你刚才提供的信息，你在杭州做程序员。
```

关掉进程，删掉进程内变量；第二次跑（同一个 `workspace`、同一个 `sessionId`）：

```text
[reply] 早上好小李。有什么可以帮你？
[reply] 你叫小李，在杭州做程序员。
```

——**完整恢复**。

## 11.3 三个常见的"断点续聊"场景

### 11.3.1 浏览器刷新

最简单：前端把 `sessionId` 存 `localStorage`，刷新后从 `localStorage` 取出、塞回请求参数。后端完全无感。

```javascript
let sessionId = localStorage.getItem("sessionId");
if (!sessionId) {
  sessionId = crypto.randomUUID();
  localStorage.setItem("sessionId", sessionId);
}

fetch(`/api/agent/chat?sessionId=${sessionId}`, {
  method: "POST",
  body: JSON.stringify({ text: "我叫什么？" }),
});
```

### 11.3.2 用户切换设备

用户在手机问了一通，到电脑上想接着聊。把手机端的 `sessionId` 暴露成"会话恢复码"，让用户在电脑端输入；后端用同一个 `sessionId` 调 agent。

> **注意**：`AgentStateStore` 不感知设备。要加一层 user_id → session_id 的映射（自己做或者用 Spring Session）。

### 11.3.3 用户主动重置

提供"清空对话"按钮——后端开新 `sessionId`：

```java
@PostMapping("/session/reset")
public Map<String, String> reset(@RequestParam String userId) {
    String newId = "user-" + userId + "-" + System.currentTimeMillis();
    return Map.of("sessionId", newId);
}
```

老会话状态会自然过期（按 `AgentStateStore` 后端的 TTL 清理）。

## 11.4 Plan Mode 与 todo 的恢复

如果开了 Plan Mode（`HarnessAgent.enablePlanMode()`），`todo_write` 写下的待办也会被 `AgentStateStore` 持久化。例：

```java
HarnessAgent agent = HarnessAgent.builder()
        ...
        .enablePlanMode(true)
        .build();
```

用户在第一通对话里让 agent 计划"调研 5 件事"——`agent_todo` 会被持久化；用户回来时：

```text
"上次我让你调研的 5 件事，现在做到哪了？"
```

agent 会读 `AgentStateStore` 里的 todo 列表，把状态念给用户听。

## 11.5 用 RedisAgentStateStore 做生产级恢复

`JsonFileAgentStateStore` 适合开发与单机部署；多实例 / 多机部署要用 `RedisAgentStateStore`（见第 5 章）：

```java
HarnessAgent agent = HarnessAgent.builder()
        .stateStore(RedisAgentStateStore.builder()
                .jedisClient(new UnifiedJedis("redis://127.0.0.1:6379"))
                .build())
        .build();
```

恢复流程一模一样，区别只在"状态存在 Redis 而非本地 JSON"。

## 11.6 主动重连 vs 自动重连

| 场景 | 推荐策略 |
|------|----------|
| 用户离开 5 分钟 | 不主动重连——`AgentStateStore` 一直保留；用户回来直接续 |
| 30 分钟未活动 | 由前端弹"是否继续"按钮，避免 token 浪费 |
| 1 小时未活动 | 后端 cron 清理 Redis 里的旧 session |
| 24 小时未活动 | 强制清空（保留 `MEMORY.md` 长期记忆） |

`RedisAgentStateStore` 可以设 TTL；`JsonFileAgentStateStore` 可以用 `Files.deleteIfExists` 自己写清理脚本。

## 11.7 完整可运行示例

```java
import io.agentscope.core.agent.RuntimeContext;
import io.agentscope.core.message.UserMessage;
import io.agentscope.core.model.DashScopeChatModel;
import io.agentscope.core.state.JsonFileAgentStateStore;
import io.agentscope.harness.HarnessAgent;

import java.nio.file.Path;
import java.util.List;
import java.util.concurrent.TimeUnit;

public class Chapter11_Interrupted {

    public static void main(String[] args) throws InterruptedException {
        String sessionId = "u-9527-2026-06-07";

        HarnessAgent agent = HarnessAgent.builder()
                .name("assistant")
                .sysPrompt("你是一个中文助理。")
                .model(DashScopeChatModel.builder()
                        .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                        .modelName("qwen-plus")
                        .build())
                .workspace(Path.of("./workspace"))
                .stateStore(new JsonFileAgentStateStore(Path.of("./workspace")))
                .build();

        RuntimeContext ctx = RuntimeContext.builder()
                .sessionId(sessionId).userId("9527").build();

        // ---- Round 1 ----
        agent.call(List.of(new UserMessage("user", "我养了一只橘猫，叫'小年'。")), ctx).block();
        agent.call(List.of(new UserMessage("user", "它叫什么？")), ctx).block();

        System.out.println("=== 模拟用户关闭浏览器 5 秒 ===");
        TimeUnit.SECONDS.sleep(5);

        // ---- Round 2：模拟"再回来" ----
        agent.call(List.of(new UserMessage("user", "我养了什么宠物？")), ctx).block();
    }
}
```

## 11.8 本章小结

- `AgentStateStore` 是 2.0 中断恢复的核心，业务代码无需写序列化。
- 同一 `sessionId` + 同一 `AgentStateStore` 后端 = 上下文自动恢复。
- `Plan Mode` 的 todo 也会被 `AgentStateStore` 持久化。
- 生产用 `RedisAgentStateStore`，开发用 `JsonFileAgentStateStore`。
- RC2 中 Agent 完全无状态化——同一实例可安全并发服务多 `(userId, sessionId)` 组合。


"用户问了 3 轮突然关掉浏览器；20 分钟后用同一个会话 ID 回来——上一轮的上下文、todo、subagent 状态怎么全在？这是 2.0 的 AgentStateStore 后端（JsonFileAgentStateStore  RedisAgentStateStore  MysqlAgentStateStore）干的事，比 1.x 自己把 Memory 序列化 JSON 简单很多。"

【AgentScope Java新手村系列】（11）中断与恢复

中断与恢复 — AgentStateStore 按 sessionId 持久化上下文，浏览器关闭后秒级恢复对话与 todo 状态。

架构设计

AgentStateStore实现会话持久化，支持断点续聊。通过sessionId恢复上下文、待办事项和子代理状态，无需手动序列化。支持浏览器刷新、设备切换和主动重置场景，PlanMode自动恢复待办事项。开发推荐JsonFileAgentStateStore，生产环境使用RedisAgentStateStore，实现秒级恢复和无状态并发。

Redis

Agent

JSON

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

AgentStateStore实现会话持久化，支持断点续聊。通过sessionId恢复上下文、待办事项和子代理状态，无需手动序列化。支持浏览器刷新、设备切换和主动重置场景，PlanMode自动恢复待办事项。开发推荐JsonFileAgentStateStore，生产环境使用RedisAgentStateStore，实现...

【AgentScope Java新手村系列】（11）中断与恢复-腾讯云开发者社区-腾讯云

【AgentScope Java新手村系列】（11）中断与恢复

【AgentScope Java新手村系列】（11）中断与恢复

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐