创建 Session

创建绑定 Agent 和 Environment 的新 Session。

POST /api/v1/cloud/sessions

创建 Session。新 Session 初始状态为 idle，发送事件后开始执行。

​

请求头

头部	必选	说明
Authorization	是	Bearer $QODER_PAT
Content-Type	是	application/json

​

请求体

字段	类型	必填	说明
agent	string 或 object	是	Agent ID，或包含 id、必填 type: "agent"、可选 version 的对象。详见 Agent 引用
environment_id	string	是	env_ 前缀的已有 Environment ID
title	string | null	否	Session 标题
metadata	object	否	Session 元数据
environment_variables	string	否	注入到 agent 运行时的 Session 级环境变量。请求侧使用单字符串，KEY=VALUE 之间用 ;（也接受换行或全角 ；）分隔；响应侧返回 JSON 对象，详见 校验规则。Self-hosted Environment 不支持
resources	array	否	创建时挂载的 file、GitHub repository 或 Memory Store 资源
vault_ids	array	否	Session 可使用的 Vault ID

旧请求字段 environment、delta_flush_interval_ms、vaults 和 memory_store_ids 不支持。挂载 Memory Store 请使用 resources[] 中的 type: "memory_store"。

​

environment_variables 校验

变量名必须匹配 [A-Za-z_][A-Za-z0-9_]*；保留名 SERVER_ENDPOINT、USER_ID、WORK_DIR，以及任何带 CAW_、QODER_ 前缀的名称都会被拒绝。单个 value 不超过 8 KiB；总条目不超过 64 条且总字节不超过 64 KiB。重复键、格式错误或在 self-hosted Environment 上使用会返回 400 invalid_request_error。

​

资源参数

资源类型	必填字段	可选字段
file	type, file_id	mount_path
github_repository	type, url, authorization_token	mount_path, checkout
memory_store	type, memory_store_id	access, instructions

Self-hosted Environment 当前不支持 Session resources。

​

示例请求

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", "type": "agent", "version": 2},
    "environment_id": "env_019e2590d33f711fabf42f2857cecd8a",
    "title": "Code review session",
    "metadata": {"purpose": "review"},
    "environment_variables": "FEATURE_FLAG=on;LOG_LEVEL=debug",
    "resources": [
      {
        "type": "github_repository",
        "url": "https://github.com/your-org/your-repo",
        "mount_path": "/data/workspace/your-repo",
        "authorization_token": "ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      },
      {
        "type": "memory_store",
        "memory_store_id": "memstore_019eed05b61e78cea61bfd366e072878",
        "access": "read_write",
        "instructions": "Use this memory for long-lived project context."
      }
    ],
    "vault_ids": ["vault_019eed0519807975983d0ffc4b4b4c79"]
  }'

​

示例响应

HTTP 200 OK

返回 Session 对象。

{
  "id": "sess_019e3bb1e8c171fd9abbb1477ffb84cc",
  "type": "session",
  "agent": {
    "id": "agent_019e390add9f7bac9b6cc806db46fcbd",
    "type": "agent",
    "name": "doc-test-agent",
    "description": "Documentation example Agent",
    "model": {
      "id": "ultimate",
      "effective_context_window": 200000
    },
    "system": "You are a test assistant.",
    "tools": [],
    "skills": [],
    "mcp_servers": [],
    "version": 2
  },
  "environment_id": "env_019e2590d33f711fabf42f2857cecd8a",
  "title": "Code review session",
  "status": "idle",
  "metadata": {"purpose": "review"},
  "environment_variables": {"FEATURE_FLAG": "on", "LOG_LEVEL": "debug"},
  "resources": [],
  "vault_ids": ["vault_019eed0519807975983d0ffc4b4b4c79"],
  "deployment_id": null,
  "outcome_evaluations": [],
  "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"
}

​

错误码

HTTP	类型	触发条件
400	invalid_request_error	请求体错误、缺少必填字段、使用不支持的旧字段或资源非法
401	authentication_error	PAT 无效或过期
404	not_found_error	Agent、Environment、File、Memory Store 或 Vault 不存在
409	invalid_request_error	引用的文件未 ready，或资源路径/ID 冲突

HTTP 400 Bad Request

{
  "type": "error",
  "request_id": "cb80235f-76a2-4ff3-9e28-5aa2da12dc14",
  "error": {
    "type": "invalid_request_error",
    "message": "Field 'agent' is required."
  }
}

HTTP 404 Not Found

{
  "type": "error",
  "request_id": "cb80235f-76a2-4ff3-9e28-5aa2da12dc14",
  "error": {
    "type": "not_found_error",
    "message": "Agent 'agent_does_not_exist_0000000000000000000000000000' was not found."
  }
}

注意：agent 缺少 agent_ 前缀（或 environment_id 缺少 env_ 前缀）时同样会被解析为 404 not_found_error，而不是 400。

详见 Errors。

​

相关

启动 Session

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