Skip to main content
Sessions

创建 Session

基于 Identity 和 Template 创建 Forward Session。

POST /api/v1/forward/sessions Forward 会先编译 Template 基线与 Identity Config 覆盖层，再应用本次 Session 配置并创建运行时 Session。

请求头

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

请求体参数

参数类型是否必填说明
identity_idstring是Forward Identity ID。
template_idstring是Forward Template ID。
titlestring否Session 标题。
metadataobject否业务元数据。
configobject否单次 Session 配置覆盖，允许 environment_variables 和 model；必须为非 null 对象，省略或 {} 均合法。
config.environment_variablesobject<string, string>（推荐）否Session 环境变量；新接入请将每个 value 都作为字符串传入。在 Template + Identity Config 编译结果基础上追加合并，同名变量覆盖基础层的值。
config.modelstring | object否Session 级模型覆盖，详见 config.model；省略时继承 Template 与 Identity Config 的有效模型。
resourcesarray否Session 级资源，当前用于挂载文件。
resources[].typestring条件必填资源类型，当前为 file。
resources[].file_idstring条件必填Files API 返回的 File ID。
resources[].mount_pathstring否Agent 容器内挂载路径；省略时由 Forward 根据文件名生成。
config.environment_variables 合并语义：
  • Forward 先编译 Template environment_variables 基线与 Identity Config 覆盖层，得到基础环境变量。
  • 请求中传入的 key-value 在基础环境变量上做追加：新 key 追加，同名 key 以 Session 级传入的值覆盖基础层的值。
  • 未传入的变量继续保留 Template + Identity Config 编译结果。
  • 可省略或传入空 object {}。value 请使用字符串。
  • 字段本身显式传 null、非 object 类型（历史兼容的字符串格式除外），以及 object 中嵌套 object 或 array，均返回 400 invalid_request_body。

config.model

config.model 支持非空模型 ID 字符串（例如 "ultimate"），或包含模型 ID 和可选调优参数的对象，与 Template / Identity Config 的模型格式一致。可用模型和支持的选项请查询列出模型。
对象字段类型是否必填说明
idstring是非空模型 ID，取自列出模型返回的 id。
effortstring否Reasoning effort 等级：none、low、medium、high、xhigh、max；实际支持的等级以模型的 efforts 为准，省略时使用模型默认值。
speedstring否推理速度：standard、high；省略时使用 standard。实际支持的速度以模型的 speed 数组为准。
context_windowinteger否上下文窗口的 token 数，必须为正整数；请从模型的 available_context_windows 中选择，省略时使用模型默认窗口。
模型与选项组合是否可用，以列出模型的能力和运行时校验结果为准。
  • 省略 config.model：继承 Template / Identity Config 的有效模型。
  • 传入 string / object：整体覆盖本 Session 的模型，省略的调优参数使用所选模型默认值。
  • 传入 null 或 {}：返回 400；创建时使用继承模型请省略字段，模型对象必须包含非空 id。
template.model 是模板摘要；Session 模型覆盖值请查看响应中的 config.model。

示例请求

curl -s -X POST 'https://api.qoder.com.cn/api/v1/forward/sessions' \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "identity_id": "idn_xxx",
  "template_id": "tmpl_support",
  "title": "Customer support session",
  "metadata": {
    "source": "web",
    "biz_id": "ticket_123"
  },
  "config": {
    "model": {
      "id": "ultimate",
      "effort": "high",
      "context_window": 200000
    },
    "environment_variables": {
      "API_KEY": "sk-xxx",
      "REGION": "cn-hangzhou"
    }
  },
  "resources": [
    {
      "type": "file",
      "file_id": "file_019e6a18dc09abcd",
      "mount_path": "/data/input.py"
    }
  ]
}'

示例响应

HTTP 200 OK 
{
  "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",
  "metadata": {
    "source": "web"
  },
  "config": {
    "model": {
      "id": "ultimate",
      "effort": "high",
      "context_window": 200000
    },
    "environment_variables": {
      "API_KEY": "sk-xxx"
    }
  },
  "stats": {
    "active_seconds": 0,
    "duration_seconds": 0
  },
  "usage": {
    "total_credits": 0
  },
  "outcome_evaluations": [],
  "archived_at": null,
  "created_at": "2026-06-22T10:00:00Z",
  "updated_at": "2026-06-22T10:00:00Z"
}

响应字段

字段类型说明
idstringSession ID。
typestring固定为 session。
identity_idstringForward Identity ID。
templateobjectTemplate 摘要。
source_typestringSession 来源，直接 API 创建为 api。
statusstringidle、running、rescheduling、canceling 或 terminated。
config.modelstring | object已保存的 Session 模型覆盖值，保留 string / object 形态；未设置覆盖时省略。

错误

HTTPTypeCode触发条件
400invalid_request_errorinvalid_request_body请求体不合法，包括 config.environment_variables 不合法。
400invalid_request_errorinvalid_requestconfig.model 不合法（包括 null、{}、空 ID 或非法参数），或包含不支持的配置字段。
403permission_errortemplate_access_deniedIdentity 无权使用该 Template。
404not_found_erroridentity_not_foundIdentity 不存在或已删除。
404not_found_errortemplate_not_foundTemplate 不存在。
409conflict_erroridentity_disabledIdentity 已停用。
401authentication_error-PAT 或 SAT 无效或已过期。

备注

  • source_type 由 Forward 设置，创建请求不接受该字段。
  • incremental_streaming_enabled 是兼容保留的旧版流式开关，不推荐新接入使用，且创建后不能修改。新接入如需流式输出，请在订阅 Session Event Stream 时使用 event_deltas[]；若该字段设为 true，event_deltas[] 不会生效。
  • resources 中的文件必须已通过 Files API 上传。
  • 仅为兼容既有调用，非字符串标量 value 会规范化为字符串（null 为空字符串）；旧版 APP_ID=demo-app;DEBUG=true 或换行分隔的字符串输入仍可使用。新接入请使用字符串 value 的对象格式。

相关

发送 Session Events

订阅 Session Events