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