# 会话管理
会话（Session）是智能体运行时中隔离执行和状态管理的核心单元。每个会话运行在独立的安全沙箱中，支持会话级状态持久化，使智能体能够在多次调用间保持上下文。通过会话管理，可实现多轮对话、命令执行、文件传输等高级交互能力。
#### 约束与限制
- 会话ID由调用方自行生成，由英文、数字、中划线（-）、下划线（_）组成，不超过 64 个字符。
- 配置会话存储后，不支持取消（关闭），仅支持修改挂载路径。
- 会话存储仅支持配置 1 个。
- 会话存储底层基于OBS 对象存储，通过FUSE挂载到沙箱容器。配置umask后，文件权限由挂载时的umask、uid、gid参数决定，运行时执行chmod/chown命令不会生效。
- 配置会话存储后，请谨慎使用同一会话ID进行跨访问方式访问，版本不一致会导致调用超时。
- 空闲会话超时和最大存活时间取值范围为60 - 604800 秒（1 分钟 \~ 7 天）。
 
#### 原理介绍
#### 会话隔离机制
每个会话运行在独立的安全沙箱（microVM）实例中，实现进程级、文件系统级和网络级的隔离。同一会话ID的多次调用会被路由到同一个沙箱实例（会话亲和性），不同会话ID的调用彼此隔离。
#### 会话生命周期
会话从创建到销毁经历以下阶段：
表1会话生命周期 
| 阶段      | API 接口                                        | 平台动作     | 说明                           |
|:---|:---|:---|:---|
| 创建会话   | POST /runtimes/{runtime_name}/sessions-start | 创建沙箱和会话 | 创建独立沙箱实例并生成会话。             |
| 会话活跃期 | POST /runtimes/{runtime_name}/invocations    | 调用沙箱    | 通过会话ID路由到同一沙箱，支持命令执行和文件传输。 |
| 停止会话     | POST /runtimes/{runtime_name}/sessions-stop   | 销毁沙箱     | 销毁沙箱实例，释放计算资源。会话内临时文件自动清除。  |
   
![](https://support.huaweicloud.com/highcode-agentarts/public_sys-resources/note_3.0-zh-cn.png)
停止会话（销毁沙箱）和删除会话状态（清除持久化存储）是两个独立操作。允许您在沙箱销毁后仍保留会话数据，或按需单独清理存储状态，避免操作失败导致资源泄漏。
可通过控制台配置会话生命周期，详细操作请参见[通过控制台部署](https://support.huaweicloud.com/highcode-agentarts/agentarts_10_031.html)中"生命周期配置"。
表2生命周期参数 
| 参数（控制台） | 参数（API/JSON）                          | 描述                                      | 取值范围          | 默认值             |
|:---|:---|:---|:---|:---|
| 空闲会话超时  | lifecycleConfig.idleSessionTimeoutSec | 会话在设置的空闲时间内没有交互或活动，系统自动结束该会话。          | 60 - 604800 秒 | 900 秒（15 分钟）    |
| 最大存活时间 | lifecycleConfig.maxAliveTimeSec        | 会话持续调用时自动终止前的最大存活时间。达到此时间后无论是否活跃都会被强制终止。 | 60 - 604800 秒  | 86400 秒（24 小时） |
   
![](https://support.huaweicloud.com/highcode-agentarts/public_sys-resources/note_3.0-zh-cn.png)
当空闲会话超时或最大存活时间满足任一条件时，运行时会话将自动终止。支持以秒、分钟、小时或天为单位进行配置。
#### 会话路由机制
平台通过 HTTP 请求头中的会话 ID 标识和路由会话。默认请求头为 X-Hw-Agentarts-Session-Id，会话 ID 从请求头（header）中提取。
不同运行时类型的会话 ID 请求头如下：
表3各运行时类型的会话 ID 请求头 
| 运行时类型          | 会话 ID 请求头                                  |
|:---|:---|
| Agent（默认）       | X-Hw-Agentarts-Session-Id                |
| Code Interpreter | X-Hw-Agentarts-Code-Interpreter-Session-Id |
| Browser         | X-Hw-Agentarts-Browser-Session-Id           |
| Gateway（MCP）      | X-Hw-Agentarts-Session-Id                  |
   
#### 跨访问方式的会话路由
在智能体运行时中，是否配置会话存储会影响跨访问方式（Endpoint）的会话路由行为：
- **未配置会话存储**：新请求根据指定的访问方式路由，同一会话ID可在不同版本中独立使用。
- **已配置会话存储**：新请求根据当前是否存在已激活的同一会话ID沙箱进行判断。不存在已激活沙箱时，按指定访问方式路由；存在已激活沙箱且版本一致时，调用同一沙箱；版本不一致时，调用超时。
![](https://support.huaweicloud.com/highcode-agentarts/public_sys-resources/note_3.0-zh-cn.png)
请谨慎使用同一会话 ID 进行跨访问方式访问。配置会话存储后，版本不一致会导致调用超时。建议在灰度发布验证时使用新的会话 ID。
#### 会话示例
**场景一：基础多轮对话**
通过会话 ID 实现多轮对话，无需创建独立会话。在请求头中携带X-Hw-Agentarts-Session-Id，同一会话 ID 的多次调用共享沙箱上下文。
```
# 第一轮（会话 ID = session-001）
POST /runtimes/{runtime_name}/invocations
Headers: X-Hw-Agentarts-Session-Id: session-001
Body: {"message": "我叫张三"}
→ {"reply": "你好，张三！有什么可以帮助你的？"}
# 第二轮（相同会话 ID）
POST /runtimes/{runtime_name}/invocations
Headers: X-Hw-Agentarts-Session-Id: session-001
Body: {"message": "你还记得我叫什么吗？"}
→ {"reply": "你叫张三。"}
# 第三轮（新会话 ID → 上下文清空）
POST /runtimes/{runtime_name}/invocations
Headers: X-Hw-Agentarts-Session-Id: session-002
Body: {"message": "你还记得我叫什么吗？"}
→ {"reply": "抱歉，我不清楚你的名字。"}
```
![](https://support.huaweicloud.com/highcode-agentarts/public_sys-resources/note_3.0-zh-cn.png)
X-Hw-Agentarts-Session-Id提供的是会话标识，用于平台将多次请求路由到同一沙箱。但上下文是否能保持（即Agent能否记住之前的对话），取决于Agent代码是否实现了对话记忆逻辑。
**场景二：涉及文件处理**
当需要让智能体处理本地文件时，需先创建会话获取沙箱环境：
1. **创建会话**：调用 POST /runtimes/{runtime_name}/sessions-start，获取沙箱环境。
2. **上传文件**：调用 POST /runtimes/{runtime_name}/upload-files，将本地文件上传至沙箱。单文件限制 100MB，多文件总大小限制 500MB。
3. **调用智能体**：调用 POST /runtimes/{runtime_name}/invocations，Agent 读取并处理文件。
4. **下载文件**：调用 GET /runtimes/{runtime_name}/download-files，取回处理结果。
5. **停止会话**：调用 POST /runtimes/{runtime_name}/sessions-stop，释放资源。
**场景三：涉及命令执行**
当需要在智能体沙箱中执行Shell命令时：
1. **创建会话**：获取沙箱环境。
2. **调用智能体**：Agent推理决策，决定需要执行的命令。
3. **执行命令**：调用POST /runtimes/{runtime_name}/commands，在沙箱内执行 Shell 命令，返回标准输出和错误输出。
4. **再次调用智能体**：Agent 基于命令结果继续推理。
5. **停止会话** ：释放资源。
   ![](https://support.huaweicloud.com/highcode-agentarts/public_sys-resources/note_3.0-zh-cn.png)
   步骤②③④可多次循环，形成"推理 → 执行 → 再推理"的闭环。