创建 Session

创建一个新的会话。Session 是 Agent 与用户之间的对话容器。

POST /v1/sessions

创建一个新的会话。Session 是 Agent 与用户之间的对话容器，创建后状态为 idle，可通过 Events API 发送消息触发 Agent 处理。

​

请求头

头部	必选	说明
Authorization	是	Bearer <PAT>
Content-Type	是	application/json

​

请求体

字段	类型	必选	说明
agent	string 或 object	是	Agent 引用。传字符串 Agent ID 表示使用最新 active 版本；也可传对象，包含 id、可选 type、可选 version。
environment_id	string	条件必选	已存在的 Environment ID（env_ 前缀）。未提供 environment 时必选；如果同时提供 environment_id 和 environment，优先使用 environment_id。
environment	string 或 object	条件必选	已存在的 Environment ID 字符串，或内联 Environment 对象。未提供 environment_id 时必选。
title	string	否	会话标题
metadata	object	否	自定义元数据键值对
delta_flush_interval_ms	integer	否	增量刷新间隔，范围 50-5000，默认 100
memory_store_ids	array	否	唯一且非空的 Memory Store ID 数组，默认 []。
resources	array	否	文件或 GitHub 仓库资源列表，默认 []。
vault_ids	array	否	唯一且非空的 Vault ID 数组，默认 []。
vaults	array	否	vault_ids 的别名，仅当 vault_ids 为空或未提供时使用。
environment_variables	string	否	Session 级环境变量，格式为用分号或换行分隔的 KEY=VALUE 字符串；默认不注入自定义变量。self-hosted Environment 不支持该字段。

​

agent 对象

字段	类型	必选	说明
id	string	是	Agent ID（agent_ 前缀）
type	string	否	可选类型标记，服务端不要求固定值。
version	integer	否	用于本 Session 的 Agent 版本。不传或传 0 表示使用最新 active Agent。

​

内联 environment 对象

字段	类型	必选	说明
name	string	否	Environment 名称。为空或省略时默认为 "Session Environment"。
description	string	否	Environment 描述
config	object	是	Environment 配置，结构与创建 Environment一致。
metadata	object	否	内联 Environment 的自定义元数据

​

environment_variables 格式

environment_variables 必须是一个字符串，不支持 JSON object。多个变量可用分号或换行分隔：

{
  "environment_variables": "NODE_ENV=production; FEATURE_FLAG=1\nEMPTY_VALUE="
}

每一项必须使用 KEY=VALUE 格式。变量名必须匹配 [A-Za-z_][A-Za-z0-9_]*；重复变量名会被拒绝；允许空值。服务端最多接受 64 个变量、单个值最大 8 KiB、所有变量名和值合计最大 64 KiB。SERVER_ENDPOINT、USER_ID、WORK_DIR 以及 CAW_、QODER_ 前缀为保留名称。

​

resources 数组元素

resources 数组中的每个元素通过 type 字段区分类型：

文件资源 (type: "file")：

字段	类型	必填	说明
type	string	否	"file"；省略时默认 "file"。
file_id	string	是	文件 ID（通过 Files API 上传后获得）。文件状态必须为 ready。
path	string	否	挂载路径，默认 /data/{file_id}。相对路径会自动加上 /data/ 前缀；归一化后必须位于 /data/ 下，最长 512 字符。
mount_path	string	否	path 的别名。若同时提供 path 和 mount_path，两者必须一致；响应中统一返回归一化后的 path。

GitHub 仓库资源 (type: "github_repository")：

字段	类型	必填	说明
type	string	是	"github_repository"
url	string	是	仓库 URL
mount_path	string	否	克隆到容器中的路径
authorization_token	string	否	访问私有仓库时使用的授权 token。提供后会保存在 Session resource 对象中。

​

示例请求

curl -X POST "https://api.qoder.com/api/v1/cloud/sessions" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": {"id": "agent_019e390add9f7bac9b6cc806db46fcbd", "version": 2},
    "environment_id": "env_019e2590d33f711fabf42f2857cecd8a",
    "title": "我的会话",
    "metadata": {"purpose": "customer-support"},
    "environment_variables": "NODE_ENV=production; FEATURE_FLAG=1",
    "delta_flush_interval_ms": 100
  }'

​

附带 GitHub 仓库的示例

curl -X POST "https://api.qoder.com/api/v1/cloud/sessions" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": {"id": "agent_019e390add9f7bac9b6cc806db46fcbd", "version": 2},
    "environment_id": "env_019e2590d33f711fabf42f2857cecd8a",
    "title": "代码审查会话",
    "resources": [
      {
        "type": "github_repository",
        "url": "https://github.com/your-org/your-repo"
      }
    ]
  }'

​

示例响应

HTTP 201 Created

{
  "id": "sess_019e3bb1e8c171fd9abbb1477ffb84cc",
  "type": "session",
  "agent_id": "agent_019e390add9f7bac9b6cc806db46fcbd",
  "agent": {
    "id": "agent_019e390add9f7bac9b6cc806db46fcbd",
    "type": "agent",
    "name": "doc-test-agent",
    "description": "文档示例用 Agent",
    "model": "ultimate",
    "system": "你是一个测试助手",
    "tools": [
      {
        "type": "agent_toolset_20260401",
        "enabled_tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "WebFetch", "WebSearch"]
      }
    ],
    "skills": [],
    "metadata": {},
    "mcp_servers": [
      {
        "type": "http",
        "name": "weather-service",
        "url": "https://mcp.example.com/mcp"
      }
    ],
    "version": 2,
    "archived_at": null,
    "created_at": "2026-05-18T03:04:33.952256Z",
    "updated_at": "2026-05-18T03:05:28.023697Z"
  },
  "environment_id": "env_019e2590d33f711fabf42f2857cecd8a",
  "title": "我的会话",
  "status": "idle",
  "turn_status": "idle",
  "metadata": {"purpose": "customer-support"},
  "resources": [],
  "vault_ids": [],
  "memory_store_ids": [],
  "environment_variables": {
    "NODE_ENV": "production",
    "FEATURE_FLAG": "1"
  },
  "stats": {
    "active_seconds": 0,
    "duration_seconds": 0
  },
  "archived_at": null,
  "created_at": "2026-05-18T15:26:15.747298Z",
  "updated_at": "2026-05-18T15:26:15.747298Z"
}

​

响应字段

字段	类型	说明
id	string	Session 唯一标识（sess_ 前缀）
type	string	固定值 "session"
agent_id	string	关联的 Agent ID
agent	object	本 Session 使用的 Agent 快照，字段包括 id、type、name、description、model、system、tools、mcp_servers、skills、metadata、version、可为空的 archived_at、created_at、updated_at。不会返回旧字段 instructions 或 default_environment。
environment_id	string	关联的 Environment ID
title	string	会话标题
status	string	Session 生命周期状态。新建时为 "idle"；正在处理时通常为 "running"。
turn_status	string	当前 turn 状态，例如 "idle"、"processing"、"cancelling"。
metadata	object	Session 元数据
resources	array	归一化后的资源对象。文件资源包含 type、file_id、path；GitHub 仓库资源包含 type、url、可选 mount_path、可选 authorization_token。
vault_ids	array	关联的 Vault ID 列表
memory_store_ids	array	关联的 Memory Store ID 列表
environment_variables	object	归一化后的 Session 级环境变量；未提供自定义变量时为空对象。
stats	object	Session 统计信息。新建 Session 包含 active_seconds 和 duration_seconds，初始值均为 0。
archived_at	string 或 null	归档时间；未归档时为 null。
created_at	string	创建时间（ISO 8601）
updated_at	string	最后更新时间（ISO 8601）

​

错误码

HTTP	type	触发条件
400	invalid_request_error	请求体格式错误、缺少必填字段，或 environment_variables 格式非法
401	authentication_error	PAT 无效或过期
404	not_found_error	Agent 或 Environment 不存在
409	conflict_error	引用的 Environment 已归档、文件资源未 ready，或资源路径/ID 冲突

完整错误信封说明详见 错误参考。

​

相关

启动 Session

让 Agent 在环境中以有状态对话的方式运行。