会话管理（Session）集中保存 Agent 应用的交互记录和业务状态。应用按用户管理会话，读取历史记录和状态，继续处理后续请求。
能力概述
会话管理：创建、查询和删除会话，修改标题及元数据。会话按空间和用户组织。
事件读写：逐条写入或更新用户输入、Agent 回复、工具调用等交互记录，按时间或作者查询历史事件。
状态持久化：将任务进度、用户选择等业务数据保存在会话中，下次交互时直接读取。
元数据筛选：用键值对标记会话的业务分类或关联资源，查询时按元数据或标题精确过滤。
权限管理：通过 CAM 策略控制子账号对指定会话空间的操作权限。
适用场景
为便于水平扩容和故障切换，Agent 应用通常采用无状态的多实例部署，将需要持久保存的会话数据存储在实例之外。云端 Session 集中保存交互记录和业务状态，同一 Agent 的不同实例可以按会话标识读取数据、重建上下文，后续请求无需依赖原实例本地保存的会话数据。
无状态多实例部署：将会话记录和状态保存在云端，供同一 Agent 的不同实例读取，支持请求在实例间切换。
实例切换后继续对话：应用重启或请求转交其他实例时，读取已保存的数据，继续处理后续请求。
历史会话管理：按业务用户查询会话及事件，展示历史记录并继续已有对话。
接入示例
Session Cookbook 以 DeepSeek Harness（DSH）为例，演示如何在 Agent 框架中接入 Session，并将应用部署到 弹性部署（Deployment）。弹性部署提供稳定的服务入口，负责应用实例的按需启动和弹性伸缩。
教程通过 SessionPersistence 插件保存对话事件和资源关联信息，并部署 Agent 服务与工作区服务。完成一次工具调用后，读取 Session 中保存的 Deployment 和 Affinity 信息，再次访问原工作区中的文件。
示例包含资源创建、框架接入、部署、结果验证和资源清理，提供接入插件及验证脚本。插件的适用范围和一致性限制见教程说明。
工作方式
核心概念
概念 | 说明 |
会话空间（SessionSpace） | 账号和地域内管理会话的逻辑资源，用于区分业务或环境。每个空间有唯一的 SpaceId（服务端生成），以及用户可编辑的名称和描述。CAM 权限按会话空间配置。 |
用户标识（UserId） | 应用定义的业务用户标识，用于组织该用户的会话，例如应用中的用户编号。它不代表腾讯云主账号或子账号。 |
会话（Session） | 一段持续交互的数据集合。创建时由调用方指定 SessionId，在同一空间和用户下唯一。包含标题、状态、元数据及关联事件。 |
事件（Event） | 会话中的一条交互记录，例如一次用户输入、Agent 回复或工具调用结果。事件可以携带状态增量，在追加事件时更新相应的业务状态。 |
状态（State） | 与会话关联的 JSON 对象，保存任务进度、用户选择等业务数据。事件写入时通过状态增量（StateDelta）更新。 |
元数据（Metadata） | 描述会话属性的键值信息，例如业务分类、工单编号或关联的 Deployment 标识，用于管理和筛选会话。 |
在指定账号和地域下，应用通过
SpaceId、UserId 和 SessionId 定位会话。会话处理流程
创建会话空间后，应用按以下流程保存和使用会话数据：
1. 用户发起新对话时，由应用生成会话标识并创建会话；继续已有对话时，使用原会话标识。
2. 查询该会话的历史事件和状态，与当前用户输入一起构建上下文。
3. Agent 根据上下文调用模型或工具，生成回复。
4. 将用户输入、Agent 回复、工具调用及其结果逐条写入会话事件，并通过状态增量更新需要保留的业务数据。
后续请求重复上述流程。例如，旅行规划应用可以读取上一轮保存的目的地和预算，继续处理用户新增的行程要求。
应用负责选择历史记录和组装模型上下文。事件可随交互过程逐条写入，无需等待整轮对话结束。
为弹性部署上的 Agent 接入 Session
将 Agent 应用部署到弹性部署前，需要先在所用框架中接入 Session，保存交互记录和业务状态，并在后续请求中读取这些数据。以 DSH 为例，可参考 Cookbook 中的 SessionPersistence 插件。
1. 接入会话存储：创建会话空间，在框架的会话创建、事件保存和历史读取环节接入 Session。
2. 部署 Agent 应用：将集成后的应用打包为镜像，创建自定义沙箱工具和 Deployment，并配置会话空间及访问凭证。
3. 处理会话请求：客户端访问 Deployment 的服务入口，应用根据会话标识读取历史事件和状态，构建上下文并处理请求，将新增记录保存到 Session。
4. 在实例切换后读取会话：后续请求由其他实例处理时，应用使用同一组会话标识读取已保存的数据。需要访问原工作区时，再按 Deployment 的亲和配置携带 Affinity ID。
Session 通过可选的预定义元数据记录与 Deployment 的关联关系：
元数据名称 | 说明 |
ags.tencentcloud.com/deployment-id | 主要关联的 Deployment 标识。 |
ags.tencentcloud.com/affinity-id | 该 Deployment 对应的可选 Affinity 标识。 |
元数据用于保存关联信息。访问 Deployment 时，应用需携带访问凭证；使用会话亲和时，还需按配置携带 Affinity ID。填写 Affinity 时必须同时填写非空 Deployment 标识；更换 Deployment 时应同时移除或替换 Affinity。Session 不校验目标资源是否存在。
ags.tencentcloud.com/ 为保留命名空间，自定义元数据应使用其他命名空间，例如 example.com/。权限管理
主账号或管理员通过访问管理（CAM）策略，控制子账号对指定会话空间的操作权限。例如，只允许某个子账号查询会话和事件，不允许写入或删除。
CAM 权限按会话空间配置。会话和事件使用所属空间的权限，不单独授权。资源描述方式请参见 CAM 资源描述方式。
同一空间内的业务用户隔离由应用负责。
UserId 用于标识业务用户，本身不代表访问权限——应用需要自行校验当前用户是否有权访问目标会话。数据生命周期
会话数据独立于应用运行实例保存。模型调用结束、应用退出或沙箱实例释放不会触发会话删除。
删除会话时，该会话的关联事件一并删除。删除 Session 与删除 Deployment 互不影响。
使用限制
一个 Session 仅供同一 Agent 使用，可由其不同实例接续处理；并发处理需由应用协调，避免状态冲突。
会话恢复以应用成功保存的数据为基础，不包括运行进程、沙箱内存和文件系统的恢复。
SessionId 支持自定义，长度不超过 128 个字符。同一账号、会话空间和用户下，不同会话应使用不同的 ID；使用已有 ID 重复创建时，会返回原会话。建议使用 UUID，避免不同会话意外复用同一 ID。
