跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://docs.qoder.com/llms.txt

Use this file to discover all available pages before exploring further.

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

​
请求头

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

​
请求体

字段类型必选说明
agentstring是Agent ID（agent_ 前缀）
environment_idstring是Environment ID（env_ 前缀）
titlestring否会话标题
metadataobject否自定义元数据键值对
delta_flush_interval_msinteger否增量刷新间隔，范围 50-5000，默认 100
memory_store_idsarray否关联的 Memory Store ID 列表
resourcesarray否文件资源列表（M3 门控）
vault_idsarray否Vault ID 列表（M3 门控）

​
示例请求

curl -X POST "https://openapi.qoder.sh/api/v1/cloud/sessions" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "agent_019e390add9f7bac9b6cc806db46fcbd",
    "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": "test-agent-e2e",
    "description": "E2E 测试用 Agent",
    "model": "ultimate",
    "instructions": "你是一个测试助手",
    "system": "你是一个测试助手",
    "tools": [],
    "mcp_servers": [],
    "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"
}

​
响应字段

字段类型说明
idstringSession 唯一标识（sess_ 前缀）
typestring固定值 "session"
agent_idstring关联的 Agent ID
agentobjectAgent 完整对象（含 name、model、tools 等）
environment_idstring关联的 Environment ID
titlestring会话标题
statusstring会话状态：idle、processing、cancelled
resourcesarray关联的文件资源
vault_idsarray关联的 Vault ID 列表
memory_store_idsarray关联的 Memory Store ID 列表
usageobjectToken 用量统计
created_atstring创建时间（ISO 8601）
updated_atstring最后更新时间（ISO 8601）

​
错误码

HTTPtype触发条件
400invalid_request_error请求体格式错误或缺少必填字段
401authentication_errorPAT 无效或过期
404not_found_errorAgent 或 Environment 不存在
完整错误信封说明详见 错误参考。