创建 Session-Qoder CN 系列(Lingma)-阿里云帮助中心

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

请求头

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

请求体

字段	类型	必选	说明
`agent`	object	是	Agent 引用对象：`{"id": "", "version": }`。兼容纯字符串 `"agent_xxx"`（使用最新版本），但不推荐。
`environment_id`	string	是	Environment ID（`env_` 前缀）
`title`	string	否	会话标题
`metadata`	object	否	自定义元数据键值对
`delta_flush_interval_ms`	integer	否	增量刷新间隔，范围 50-5000，默认 100
`memory_store_ids`	array	否	关联的 Memory Store ID 列表
`resources`	array	否	文件资源列表（M3 门控）
`vault_ids`	array	否	Vault ID 列表（M3 门控）

示例请求

curl -X POST "https://api.qoder.com.cn/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"}
  }'

示例响应

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",
    "instructions": "你是一个测试助手",
    "system": "你是一个测试助手",
    "tools": [
      {
        "type": "agent_toolset_20260401",
        "enabled_tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "WebFetch", "WebSearch"]
      }
    ],
    "mcp_servers": [
      {
        "type": "url",
        "name": "weather-service",
        "url": "https://mcp.example.com/sse"
      }
    ],
    "default_environment": "",
    "version": 2,
    "created_at": "2026-05-18T03:04:33.952256Z",
    "updated_at": "2026-05-18T03:05:28.023697Z"
  },
  "environment_id": "env_019e2590d33f711fabf42f2857cecd8a",
  "title": "我的会话",
  "status": "idle",
  "resources": [],
  "vault_ids": [],
  "memory_store_ids": [],
  "usage": {
    "input_tokens": 0,
    "output_tokens": 0,
    "cache_read_input_tokens": 0,
    "cache_creation": {
      "ephemeral_5m_input_tokens": 0,
      "ephemeral_1h_input_tokens": 0
    }
  },
  "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	Agent 完整对象（含 `name`、`model`、`tools` 等）
`environment_id`	string	关联的 Environment ID
`title`	string	会话标题
`status`	string	会话状态：`idle`、`processing`、`canceling`
`resources`	array	关联的文件资源
`vault_ids`	array	关联的 Vault ID 列表
`memory_store_ids`	array	关联的 Memory Store ID 列表
`usage`	object	Token 用量统计
`created_at`	string	创建时间（ISO 8601）
`updated_at`	string	最后更新时间（ISO 8601）

错误码

HTTP	type	触发条件
400	`invalid_request_error`	请求体格式错误或缺少必填字段
401	`authentication_error`	PAT 无效或过期
404	`not_found_error`	Agent 或 Environment 不存在

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