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