会话存储保存模型续聊状态、展示历史和工作区数据。默认 JSON 可直接使用，Redis 和 MySQL 需要额外模块。

选择存储方式

Session 存储负责保存续聊状态和聊天历史，也承担工作区的持久化。按部署方式选择即可：

存储	适用场景	数据在哪里
JSON，默认	本地开发、单实例应用	本机磁盘目录
Redis	多实例共享会话，已有 Redis	Redis
MySQL	多实例共享会话，希望使用数据库管理数据	MySQL

存储与 Docker 可以自由组合。 例如 Redis 保存会话，命令可以在本机执行，也可以在 Docker 中执行。Docker 本身不替代会话存储。

JSON：不需要额外依赖

快速开始已经使用 JSON。默认保存到 ./data/agent-state，需要改目录时配置：

liteflow.agent.session-store.type=JSON
liteflow.agent.session-store.json-root=/srv/liteflow/state

相对路径以 Java 进程工作目录 为基准。正式部署建议固定为绝对路径，并持久保留目录；应用本身装在容器中时，应给该目录挂载持久卷。

文件工具生成的文件默认保存在 <json-root>/workspace。需要独立保存时，再设置 session-store.json-workspace-root。使用 Docker 执行还需保存容器文件快照，见 Docker 沙箱。

JSON 默认只协调同一 JVM 内的调用。多个应用实例同时使用同一会话时，选择 Redis 或 MySQL。

Redis：添加依赖和连接配置

添加模块，版本与快速开始一致：

<dependency>
    <groupId>com.yomahub</groupId>
    <artifactId>liteflow-agent-redis</artifactId>
    <version>${liteflow.version}</version>
</dependency>

将存储配置改为：

liteflow.agent.session-store.type=REDIS
liteflow.agent.session-store.redis.uri=${AGENT_REDIS_URI}

AGENT_REDIS_URI 例如 redis://localhost:6379/0。Redis 会保存会话、历史、工作区及 Docker 快照，多个应用实例使用同一连接配置和应用名即可共享。

已有 Redis 客户端 Bean 时，用下面的属性替换 uri：

liteflow.agent.session-store.redis.client-bean-name=agentRedisClient

支持 Jedis UnifiedJedis、Lettuce RedisClient／RedisClusterClient、Redisson RedissonClient；不能直接填 RedisTemplate 的 Bean 名。uri 与 client-bean-name 二选一。

默认不会让会话自动过期。Redis 服务重启后的数据保留取决于 Redis 的持久化配置。使用 Cluster 时，给 key-prefix 设置共同 hash tag，例如 agent:{prod}:，使状态更新涉及的键落在同一 slot。

MySQL：添加依赖和连接配置

添加模块：

<dependency>
    <groupId>com.yomahub</groupId>
    <artifactId>liteflow-agent-mysql</artifactId>
    <version>${liteflow.version}</version>
</dependency>

开发环境可让框架首次创建库表：

liteflow.agent.session-store.type=MYSQL
liteflow.agent.session-store.mysql.jdbc-url=jdbc:mysql://localhost:3306/
liteflow.agent.session-store.mysql.username=${AGENT_DB_USERNAME}
liteflow.agent.session-store.mysql.password=${AGENT_DB_PASSWORD}
liteflow.agent.session-store.mysql.database-name=liteflow_agent
liteflow.agent.session-store.mysql.table-name=agent_sessions
liteflow.agent.session-store.mysql.create-if-not-exist=true

账号需有建库建表权限。准备好结构后，可将 create-if-not-exist 改为 false。MySQL 保存会话、历史、工作区及 Docker 快照。

已有连接池时，用下面的属性替换 jdbc-url、username 和 password，保留数据库名等其他配置：

liteflow.agent.session-store.mysql.data-source-bean-name=dataSource

data-source-bean-name 与 jdbc-url 二选一。请显式设置 database-name；未设置时使用 agentscope，不会自动采用 JDBC URL 中的库名。

下面的库表名与上面的配置对应。先由部署流程执行，再设置 create-if-not-exist=false：

CREATE DATABASE IF NOT EXISTS liteflow_agent
  DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

CREATE TABLE IF NOT EXISTS liteflow_agent.agent_sessions (
  session_id VARCHAR(255) NOT NULL,
  state_key VARCHAR(255) NOT NULL,
  item_index INT NOT NULL DEFAULT 0,
  state_data LONGTEXT NOT NULL,
  version BIGINT NOT NULL DEFAULT 0,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  PRIMARY KEY (session_id, state_key, item_index)
) DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

CREATE TABLE IF NOT EXISTS liteflow_agent.agent_sessions_workspace (
  namespace_path VARCHAR(512) NOT NULL,
  item_key VARCHAR(255) NOT NULL,
  value_json LONGTEXT NOT NULL,
  version BIGINT NOT NULL,
  updated_at BIGINT NOT NULL,
  PRIMARY KEY (namespace_path, item_key)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

第二张表的名字是 table-name 加 _workspace。旧状态表缺少 version 列时，应先补齐；底层存储也会尝试补列。表名使用字母、数字和下划线，以字母或下划线开头，并为后缀预留长度。

部署时保持这几个设置一致

同一会话的各个应用实例应使用相同的应用名、存储地址和库表／前缀配置。默认 invocation-guard.mode=AUTO 会随 Redis／MySQL 选择分布式协调方式，通常不需要修改。同一会话的请求会排队，不同会话可以并发。

修改 session-store.type 只会切换后端，不会自动迁移旧会话和文件。切换前备份原数据，完成迁移并验证续聊后再使用新配置。正常保存完成后可恢复的数据，不包括进程强杀时尚未保存的内容。