前提条件
当前身份具备创建、查询、修改和删除会话空间的权限。子账号需由主账号通过 CAM 授予对应会话空间的权限，授权粒度见 会话管理概述 的权限管理部分。
使用命令行时，需安装 v0.7.0 或更高版本的 agr CLI 并完成凭证初始化，安装和初始化方法见 AGR CLI 说明。
agr session 命令从 v0.7.0 起提供。初始化后运行 agr status 确认可用。确定会话空间所在地域。应用、控制台和命令行必须使用同一地域，否则看不到对方创建的空间和会话。
管理会话空间
创建会话空间
通过控制台创建
1. 登录 Agent Runtime 会话管理控制台，确认并选择会话空间所在地域。
2. 在会话管理页面，单击创建 Session Space。
3. 填写名称（必填，最多 128 个字符）和描述（可选，最多 512 个字符），单击确定。
4. 在列表的 Session Space 名称 / ID 列中，单击 ID 旁的复制图标，获取 SpaceId。
通过命令行创建
agr 使用全局配置中的地域，可通过
agr status 查看。命令中的 --region 参数可单次覆盖该配置。后文命令统一通过 --region 引用 shell 变量，避免地域与空间不一致。以上海地域为例：export AGR_REGION=ap-shanghai
然后创建会话空间：
agr session space create \\--region "${AGR_REGION}" \\--name customer-support \\--description "Customer support sessions" \\--output json \\--jq '.Data.SessionSpace.SpaceId'
命令输出的是由 Session 服务生成的 SpaceId。将以下占位值替换为实际返回的 ID，再执行：
export SESSION_SPACE_ID="实际返回的 SpaceId"
如果通过控制台创建空间，使用命令行前请先设置地域，并填入从列表中复制的 SpaceId：
export AGR_REGION=ap-shanghaiexport SESSION_SPACE_ID="从控制台复制的 SpaceId"
说明
SpaceId 由 Session 服务生成，不能自定义。名称和描述可以后续修改。
创建多少个空间、何时拆分，请参见 会话管理概述 的“规划会话空间”。
查看会话空间
通过控制台查看
在会话管理页面查看空间名称 / ID、状态、描述及创建时间。搜索框支持按名称、Space ID、描述筛选。单击空间名称进入该空间的会话列表。
通过命令行查看
# 列出当前地域的所有空间agr session space list --region "${AGR_REGION}" --output text# 查看指定空间agr session space get --region "${AGR_REGION}" --space-id "${SESSION_SPACE_ID}" --output text
已有可用空间时，直接复用，无需重复创建。
修改会话空间
可修改空间的名称和描述，SpaceId 不可修改。
通过控制台修改
在目标空间的操作列单击编辑，在“编辑 Session Space”对话框中修改名称和描述，单击确定。
通过命令行修改
agr session space update \\--region "${AGR_REGION}" \\--space-id "${SESSION_SPACE_ID}" \\--name customer-support-prod \\--description "Production"
多个 Agent 共用空间时区分会话
多个 Agent 共用同一个空间和
UserId 时，Session 不会自动区分各 Agent 的会话。需要独立管理或授权时，为 Agent 使用不同空间；希望集中管理时，可共用空间，并用元数据区分：1. 创建会话时，将业务自定义的 Agent 标识写入元数据，例如
example.com/agent-id。同一 Agent 的所有实例必须使用相同的标识。2. 查询会话时，在查询条件中按该元数据过滤。
3. 修改会话元数据是整体替换，更新时需保留原有的 Agent 标识，否则该会话将无法再按此标识查询到。
Agent 标识由业务自行定义，与腾讯云账号和资源 ID 无关，只需在同一空间内唯一且保持不变。自定义元数据命名空间不得使用保留的
ags.tencentcloud.com/。元数据过滤仅用于区分查询结果，不提供访问授权。应用还需在读取、修改和删除指定会话及其事件前校验用户和 Agent 归属。独立空间也需配置对应的 CAM 权限；具备多个空间权限的凭证仍可访问这些空间。
在应用中使用会话空间
应用读写会话时，需要告诉 Session 操作哪个空间里的哪个会话。这些信息分两类：创建空间后写入应用配置的，和应用在运行时按请求确定的。
信息 | 来源 | 说明 |
地域 | 写入应用配置 | 会话空间所在地域。 |
SpaceId | 写入应用配置 | 创建空间时返回的 SpaceId。 |
访问凭证 | 写入应用配置 | 应用调用 Session 所用的凭证，需要具备该空间的权限。可以定期轮换。 |
UserId | 运行时确定 | 当前用户在业务系统中的标识，由应用在用户登录后确定。 |
SessionId | 运行时确定 | 新对话时创建，继续已有对话时使用原值。 |
同一个会话，每次访问都要使用相同的腾讯云账号、地域、SpaceId、UserId 和 SessionId。这样，应用重启或请求转交给其他实例后，仍能读到之前保存的会话。
例如，用户
user-001 的会话 session-001 保存在上海地域的某个空间中。应用重启后，只要仍使用同一账号、地域、SpaceId、user-001 和 session-001，就可以恢复这个会话。写入配置的方式取决于所用框架。DSH 示例通过环境变量配置地域、SpaceId 和访问凭证，见 DSH 会话持久化示例。该示例为了演示，同一 DSH 实例内的所有会话使用同一个固定的 UserId；多用户应用应在用户登录后，使用可信的用户身份作为 UserId。
结果验证
完成创建和修改操作后，在空间列表或查询命令的结果中，确认 SpaceId 与应用配置一致，修改后的名称和描述正确。
上述检查只验证空间的管理操作，不代表应用已完成接入。验证应用接入时，请按 DSH 会话持久化示例 完成一次对话，再使用应用实际写入的 UserId 和 SessionId 查询事件，并验证重新加载历史。
清理资源
以下删除操作仅在完成验证后执行。只删除为本次测试新建且不再使用的空间，复用的已有空间不要删除。
删除会话空间
注意：
空间内仍有会话等数据时无法删除，需要先删除全部会话。可在控制台的会话列表中删除，或由应用通过 SDK 删除。
默认空间受保护，不能删除。
删除前确认该空间没有被应用使用。
通过控制台删除
在目标空间的操作列单击删除，核对空间名称及“删除后无法恢复”的提示，确认不再使用后单击删除。
通过命令行删除
agr session space delete --region "${AGR_REGION}" --space-id "${SESSION_SPACE_ID}"
