# 创建空会话

`POST` `/api/session/create`

预先生成一个空会话并返回sessionId。适用于需要在发起对话前获取sessionId的场景，如前端需要sessionId来建立SSE连接。传入 projectId 时创建项目会话并使用该项目目录；不传时创建临时会话。可通过 environmentId 绑定沙箱环境，后续该会话的运行均在此环境中执行，环境必须归属当前租户/应用，否则返回无权访问错误。可通过 vaultIds 绑定当前应用空间的密钥；不传或空列表时不绑定密钥，列表中任一密钥不归属当前租户/应用时返回无权访问错误。身份说明：当您通过API访问本系统时，请求头中必须传递 X-Principal-Id 以标识操作主体；当您通过页面访问本系统时，无需传递。

## 请求参数

### 请求头参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| X-Principal-Id | integer | 否 | 身份主体ID（Long类型）。通过API访问时必须传递以标识操作主体；通过页面访问时无需传递。可通过「身份主体」模块的创建接口获取。 |

### 请求体（JSON）

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| projectId | integer | 否 | 项目ID。传入时创建项目会话并使用该项目目录；不传时创建临时会话 |
| agentId | integer | 是 | 智能体ID |
| title | string | 是 | 会话标题，不超过100个字符 |
| environmentId | integer | 否 | 沙箱环境ID，传入后创建的会话将绑定该沙箱环境，后续该会话的运行均在此环境中执行。环境必须归属当前租户/应用，否则返回无权访问错误。不传时不绑定沙箱环境，保持原有行为。 |
| vaultIds | array | 否 | 本次新建会话绑定的应用空间密钥ID列表。密钥必须归属当前租户/应用，否则返回无权访问错误；不传或空列表时不绑定密钥。重复ID按首次出现顺序去重。 |

## 响应

### 200

| 参数名 | 类型 | 说明 |
|--------|------|------|
| httpStatusCode | integer | HTTP状态码 |
| message | string | 响应消息 |
| data | SessionCreateResponse | 响应数据 |
|     sessionId | integer | 生成的会话ID |
|     principalId | integer | 主体ID |
|     projectId | integer | 项目ID；临时会话为空 |
|     agentId | integer | 智能体ID |
|     title | string | 会话标题 |
| success | boolean | 是否成功 |
| requestId | string | 上游请求ID，用于跨系统链路追踪排查问题 |
| errCode | string | 上游错误码，前端可据此做特殊UI处理 |

### 400

| 参数名 | 类型 | 说明 |
|--------|------|------|
| httpStatusCode | integer | HTTP状态码 |
| message | string | 响应消息 |
| data | object | 响应数据 |
| success | boolean | 是否成功 |
| requestId | string | 上游请求ID，用于跨系统链路追踪排查问题 |
| errCode | string | 上游错误码，前端可据此做特殊UI处理 |

### 500

| 参数名 | 类型 | 说明 |
|--------|------|------|
| httpStatusCode | integer | HTTP状态码 |
| message | string | 响应消息 |
| data | object | 响应数据 |
| success | boolean | 是否成功 |
| requestId | string | 上游请求ID，用于跨系统链路追踪排查问题 |
| errCode | string | 上游错误码，前端可据此做特殊UI处理 |