会话管理（Session）集中保存 Agent 应用的交互记录和业务状态。应用按用户管理会话，读取历史记录和状态，继续处理后续请求。
能力概述
会话管理：创建、查询和删除会话，修改标题及元数据。会话按空间和用户组织。
事件读写：逐条写入或更新用户输入、Agent 回复、工具调用等交互记录，按时间或作者查询历史事件。
状态持久化：将任务进度、用户选择等业务数据保存在会话中，下次交互时直接读取。
元数据筛选：用键值对标记会话的业务分类或关联资源，查询时按元数据或标题精确过滤。
权限管理：通过 CAM 策略控制子账号对指定会话空间的操作权限。
适用场景
为便于水平扩容和故障切换，Agent 应用通常采用无状态的多实例部署，将需要持久保存的会话数据存储在实例之外。云端 Session 集中保存交互记录和业务状态，同一 Agent 的不同实例可以按会话标识读取数据、重建上下文，后续请求无需依赖原实例本地保存的会话数据。
无状态多实例部署：将会话记录和状态保存在云端，供同一 Agent 的不同实例读取，支持请求在实例间切换。
实例切换后继续对话：应用重启或请求转交其他实例时，读取已保存的数据，继续处理后续请求。
历史会话管理：按业务用户查询会话及事件，展示历史记录并继续已有对话。
接入示例
Agent Runtime 提供两个接入示例，分别对应不同的需求。
示例 | 适用需求 | 内容 |
只需要保存和恢复会话历史 | 以 DeepSeek Harness（DSH）为例，将会话持久化到云端 Session。删除容器后，在新容器中加载同一会话并继续对话。不要求独立工作区服务，支持本地运行，并提供可选的沙箱和 Deployment 部署步骤。 | |
除会话历史外，还需要回到原工作区 | Brain 负责模型调用与工具执行流程，Hands 承载工作区文件操作，两者均部署在弹性部署（Deployment）上。Session 保存对话事件以及 Deployment 和 Affinity 信息，后续请求据此回到原工作区。 |
弹性部署提供稳定的服务入口，负责应用实例的按需启动和弹性伸缩。
两个示例都提供 SessionPersistence 插件和验证脚本，并覆盖资源创建、框架接入、结果验证和资源清理。DSH 示例提供可选的云端运行方式；Brain/Hands 示例演示两个 Deployment 与 Session 的组合使用。
使用限制见教程中的“限制与边界”。
工作方式
核心概念
概念 | 说明 |
会话空间（SessionSpace） | 账号和地域内管理会话的逻辑资源，用于区分业务或环境。每个空间有唯一的 SpaceId（服务端生成），以及用户可编辑的名称和描述。CAM 权限按会话空间配置。 |
用户标识（UserId） | 应用定义的业务用户标识，用于组织该用户的会话，例如应用中的用户编号。它不代表腾讯云主账号或子账号。 |
会话（Session） | 一段持续交互的数据集合。创建时由调用方指定 SessionId，在同一空间和用户下唯一。包含标题、状态、元数据及关联事件。 |
事件（Event） | 会话中的一条交互记录，例如一次用户输入、Agent 回复或工具调用结果。事件可以携带状态增量，在追加事件时更新相应的业务状态。 |
状态（State） | 与会话关联的 JSON 对象，保存任务进度、用户选择等业务数据。事件写入时通过状态增量（StateDelta）更新。 |
元数据（Metadata） | 描述会话属性的键值信息，例如业务分类、工单编号或关联的 Deployment 标识，用于管理和筛选会话。 |
在指定账号和地域下，应用通过
SpaceId、UserId 和 SessionId 定位会话。规划会话空间
与 Agent、实例的关系
Session 不要求会话空间与 Agent 或运行实例一一对应，也不限制它们的数量关系。同一 Agent 的多个实例可以共用一个空间，多个不同 Agent 也可以共用一个空间。
如何决定空间数量
是否创建多个空间，取决于是否需要独立管理或授权，而不取决于 Agent 或实例的数量。需要独立管理或授权时使用不同空间；希望集中管理时，可共用空间并按 Agent 标识筛选。例如：
测试和生产环境需要独立管理时，分别创建空间。
需要给不同子账号授予不同权限时，分别创建空间。CAM 权限按空间配置，同一空间内的会话和事件使用相同的权限。
与工作区的关系
会话空间只保存会话数据，不是执行工作区，不会在实例之间共享本地文件。
恢复会话的条件
多个 Agent 共用空间
多个 Agent 共用同一个空间和同一个
UserId 时，Session 不会自动区分各 Agent 的会话。如果查询时没有按 Agent 筛选，结果会包含所有 Agent 的会话。可按以下方式组织数据：方式 | 做法 | 适用场景 |
使用独立空间 | 为需要独立管理的 Agent 分别创建空间，并配置各自的 SpaceId。 | 需要独立管理，或为不同 Agent 授予不同的空间级访问权限。 |
共用空间，用元数据区分 | 创建会话时，将业务自定义的 Agent 标识写入元数据，例如 example.com/agent-id；查询会话时按该元数据过滤。 | 希望将会话数据集中在一个空间管理。 |
会话处理流程
创建会话空间后，应用按以下流程保存和使用会话数据：
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。
