会话操作
什么是会话
会话是AgentArts运行时中的一个逻辑单元，它背后对应着一个独立的安全沙箱环境。
| 概念 | 说明 |
|---|---|
| 会话 ID | 一个字符串标识符，用于在请求中指明使用哪个会话。 |
| 沙箱 | 实际的资源容器，包含独立的文件系统、内存空间和进程环境。 |
| 创建会话 | 分配一个沙箱实例，并将其与会话 ID 绑定，完成环境预热。 |
AgentArts运行时提供了显式的会话生命周期管理，通过StartRuntimeSession创建会话，通过StopRuntimeSession停止会话。理解会话的两种创建方式：
- 隐式创建：调用ExecuteRuntime（即/invocations）接口时，在请求头中携带自定义的X-Hw-Agentarts-Session-Id，平台会在该会话不存在时自动创建。这是大多数场景推荐的方式。
- 显式创建：调用StartRuntimeSession接口，由平台分配并返回session_id。适用于需要精细控制会话生命周期的场景。
调用StartRuntimeSession的本质是：提前向平台申请一个沙箱实例，完成环境预热，然后绑定到您指定的会话ID上。这样后续的第一次实际请求可以立即执行，无需等待沙箱拉起。
什么场景需要显式的创建会话
并非所有场景都需要显式调用StartRuntimeSession接口：
| 场景 | 是否需要调用会话接口 | 原因 |
|---|---|---|
| 基础对话（仅调用ExecuteRuntime） | 否 | 直接在请求头中传入自定义的X-Hw-Agentarts-Session-Id（会话ID），平台会自动创建会话。 |
| 执行命令（ExecuteRuntimeCommands） | 否 | 也可以直接在请求头中传入自定义会话ID进行隐式创建。但如果需要在执行命令前确保沙箱资源就绪，建议先显式创建。 |
| 上传/下载文件 | 否 | 同样支持隐式创建。但如果需要上传大文件或批量文件，建议先显式创建会话，确保沙箱资源已分配。 |
| 精细控制会话生命周期（如预先分配资源、主动管理会话状态） | 是 | 需要调用 StartRuntimeSession 获取平台分配的会话ID，后续所有操作使用此ID。 |
如果只是进行对话交互，您完全不需要阅读本章节。直接参考调用智能体章节即可。仅当您需要执行命令或传输文件，或者需要精细控制会话生命周期时，才需要关注本章节的内容。
创建会话
如果需要显式创建会话，调用StartRuntimeSession接口：
POST https://{域名}/runtimes/{runtime_name}/sessions-start 参数说明：
- 域名：在AgentArts控制台运行时详情页的“基本信息”区域获取。
- runtime_name：运行时名称，在控制台运行时列表中获取。
请求示例
以下示例使用API Key鉴权方式进行演示。
curl -X POST "https://{域名}/runtimes/{runtime_name}/sessions-start" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {api_key}" 成功响应
接口调用成功后，会返回一个会话ID。
"session_id": "abc123-def456-..."
创建成功后，后续的命令执行、文件上传下载等操作，都需要在请求头X-Hw-Agentarts-Session-Id中携带此session_id：
curl -X POST "https://{域名}/runtimes/{runtime_name}/commands" \
-H "Authorization: Bearer {api_key}" \
-H "X-Hw-Agentarts-Session-Id: abc123-def456-ghi789" \
-d '{"command": ["ls", "-la"]}' 停止会话
使用完毕后，调用StopRuntimeSession释放沙箱资源：
- 请求示例：
POST https://{域名}/runtimes/{runtime_name}/sessions-stop Headers: Authorization: Bearer {api_key} X-Hw-Agentarts-Session-Id: {session_id} - 成功响应：
成功响应后接口会返回200状态码。
- 停止会话后，沙箱实例被销毁，沙箱临时目录中的文件会被自动清除且无法恢复。请在停止前通过DownloadFiles接口下载所有需要保留的结果文件。
- 如果创建运行时过程中，已配置会话存储功能，存储目录中的文件不受影响，会被持久化保留。
