> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 创建 Session

> 基于 Identity 和 Template 创建 Forward Session。

`POST /api/v1/forward/sessions`

Forward 会先编译 Template 基线与 Identity Config 覆盖层，再创建运行时 Session。

## 请求头

| Header          | 是否必填 | 说明                 |
| --------------- | ---- | ------------------ |
| Authorization   | 是    | `Bearer <PAT>`     |
| Content-Type    | 是    | `application/json` |
| Idempotency-Key | 否    | 有副作用请求可选的幂等键。      |

## 请求体参数

| 参数                              | 类型      | 是否必填 | 说明                                  |
| ------------------------------- | ------- | ---- | ----------------------------------- |
| identity\_id                    | string  | 是    | Forward Identity ID。                |
| template\_id                    | string  | 是    | Forward Template ID。                |
| title                           | string  | 否    | Session 标题。                         |
| incremental\_streaming\_enabled | boolean | 否    | 是否开启 assistant 增量流式事件，默认 `false`。   |
| metadata                        | object  | 否    | 业务元数据。                              |
| config                          | object  | 否    | 单次 Session 配置覆盖，只接受白名单字段。           |
| config.environment\_variables   | object  | 否    | Session 环境变量 key-value。             |
| resources                       | array   | 否    | Session 级资源，当前用于挂载文件。               |
| resources\[].type               | string  | 条件必填 | 资源类型，当前为 `file`。                    |
| resources\[].file\_id           | string  | 条件必填 | Files API 返回的 File ID。              |
| resources\[].mount\_path        | string  | 否    | Agent 容器内挂载路径；省略时由 Forward 根据文件名生成。 |

## 示例请求

```bash theme={null}
curl -s -X POST 'https://api.qoder.com/api/v1/forward/sessions' \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
  "identity_id": "idn_xxx",
  "template_id": "tmpl_support",
  "title": "Customer support session",
  "incremental_streaming_enabled": true,
  "metadata": {
    "source": "web",
    "biz_id": "ticket_123"
  },
  "config": {
    "environment_variables": {
      "API_KEY": "sk-xxx",
      "REGION": "cn-hangzhou"
    }
  },
  "resources": [
    {
      "type": "file",
      "file_id": "file_019e6a18dc09abcd",
      "mount_path": "/data/input.py"
    }
  ]
}'
```

## 示例响应

**HTTP 200 OK**

```json theme={null}
{
  "id": "sess_xxx",
  "type": "session",
  "identity_id": "idn_xxx",
  "template": {
    "id": "tmpl_support",
    "type": "template",
    "name": "Support assistant",
    "model": "ultimate",
    "version": 3
  },
  "source_type": "api",
  "status": "idle",
  "title": "Customer support session",
  "incremental_streaming_enabled": true,
  "metadata": {
    "source": "web"
  },
  "config": {
    "environment_variables": {
      "API_KEY": "sk-xxx"
    }
  },
  "stats": {
    "active_seconds": 0,
    "duration_seconds": 0
  },
  "created_at": "2026-06-22T10:00:00Z",
  "updated_at": "2026-06-22T10:00:00Z"
}
```

## 响应字段

| 字段                              | 类型      | 说明                                                          |
| ------------------------------- | ------- | ----------------------------------------------------------- |
| id                              | string  | Session ID。                                                 |
| type                            | string  | 固定为 `session`。                                              |
| identity\_id                    | string  | Forward Identity ID。                                        |
| template                        | object  | Template 摘要。                                                |
| source\_type                    | string  | Session 来源，直接 API 创建为 `api`。                                |
| status                          | string  | `idle`、`running`、`rescheduling`、`canceling` 或 `terminated`。 |
| incremental\_streaming\_enabled | boolean | 是否开启增量流式事件。                                                 |

## 错误

| HTTP | Type                    | Code                      | 触发条件                     |
| ---- | ----------------------- | ------------------------- | ------------------------ |
| 400  | `invalid_request_error` | `invalid_request_body`    | 请求体不合法。                  |
| 403  | `permission_error`      | `template_access_denied`  | Identity 无权使用该 Template。 |
| 404  | `not_found_error`       | `identity_not_found`      | Identity 不存在或已删除。        |
| 404  | `not_found_error`       | `template_not_found`      | Template 不存在。            |
| 409  | `conflict_error`        | `identity_disabled`       | Identity 已停用。            |
| 422  | `invalid_request_error` | `runtime_config_invalid`  | Effective 运行时配置不合法。      |
| 401  | `authentication_error`  | `authentication_required` | PAT 无效或已过期。              |

## 注意事项

* `source_type` 由 Forward 设置，创建请求不接受该字段。
* `incremental_streaming_enabled` 创建后持久化在 Session 上，之后不能修改。
* `resources` 中的文件必须已通过 Files API 上传。

## 相关

<CardGroup cols={2}>
  <Card title="发送 Session Events" icon="paper-plane" href="/cloud-agents/api/forward/sessions/send-events" />

  <Card title="订阅 Session Events" icon="radio" href="/cloud-agents/api/forward/sessions/stream-events" />
</CardGroup>