Skip to main content
Sessions

创建 Session

基于 Identity 和 Template 创建 Forward Session。

POST /api/v1/forward/sessions Forward 会先编译 Template 基线与 Identity Config 覆盖层，再创建运行时 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 配置覆盖，只接受白名单字段。
config.environment_variablesobject否Session 环境变量，key-value 形式；在 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 编译结果。

示例请求

curl -s -X POST 'https://api.qoder.com/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": {
    "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": {
    "environment_variables": {
      "API_KEY": "sk-xxx"
    }
  },
  "stats": {
    "active_seconds": 0,
    "duration_seconds": 0
  },
  "usage": {
    "total_credits": 0
  },
  "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。

错误

HTTPTypeCode触发条件
400invalid_request_errorinvalid_request_body请求体不合法。
403permission_errortemplate_access_deniedIdentity 无权使用该 Template。
404not_found_erroridentity_not_foundIdentity 不存在或已删除。
404not_found_errortemplate_not_foundTemplate 不存在。
409conflict_erroridentity_disabledIdentity 已停用。
422invalid_request_errorruntime_config_invalidEffective 运行时配置不合法。
401authentication_errorauthentication_requiredPAT 或 SAT 无效或已过期。

备注

  • source_type 由 Forward 设置，创建请求不接受该字段。
  • incremental_streaming_enabled 是兼容保留的旧版流式开关，不推荐新接入使用，且创建后不能修改。新接入如需流式输出，请在订阅 Session Event Stream 时使用 event_deltas[]；若该字段设为 true，event_deltas[] 不会生效。
  • resources 中的文件必须已通过 Files API 上传。

相关

发送 Session Events

订阅 Session Events

快速入门
构建 Agent
配置 Agent 环境
委派任务给 Agent
集成 Agent
管理 Agent 上下文
账户
最佳实践
公告
API 参考
创建 Session - Qoder