启动 Session

Session 是 Qoder Cloud Agents 中实际执行任务的单元。它将 Agent（配置）和 Environment（基础设施）组合在一起，形成一个有状态的工作会话。你向 Session 发送消息，它处理后返回事件流。

Session 生命周期

创建 → idle

新 Session 进入 idle，等待输入。

idle → processing

发送 user.message 事件后，状态切换到 processing。

processing → idle

本轮完成后回到 idle，可继续下一轮。

cancelled / archived（终态）

取消和归档都是终态，Session 不再可恢复。

Session 是一个状态机，核心状态如下：

状态	说明	可流转到
`idle`	空闲，等待用户消息	`processing`, `cancelled`
`processing`	正在处理，Agent 执行中	`idle`, `cancelled`
`cancelled`	已取消，终止执行	— (终态)

字段说明

字段	类型	说明
`id`	string	系统生成，`ses_` 前缀
`agent_id`	string	绑定的 Agent ID
`environment_id`	string	绑定的 Environment ID
`status`	string	当前状态：`idle` / `processing` / `cancelled`
`title`	string/null	会话标题，可为空
`metadata`	object	自定义键值对
`usage`	object	Token 用量统计
`usage.input_tokens`	integer	累计输入 token 数
`usage.output_tokens`	integer	累计输出 token 数
`created_at`	string	创建时间
`updated_at`	string	最后更新时间

创建 Session

创建 Session 时需要指定 agent 和 environment_id：

方式一：使用 Agent ID（字符串）

绑定该 Agent 的最新版本：

# 使用 Agent ID 创建 Session
curl -s -X POST https://openapi.qoder.sh/api/v1/cloud/sessions \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "ag_r4nD0mId123",
    "environment_id": "env_default"
  }' | jq .

方式二：使用 Agent 对象（指定版本）

绑定 Agent 的特定版本，确保行为一致性：

# 指定 Agent 版本创建 Session
curl -s -X POST https://openapi.qoder.sh/api/v1/cloud/sessions \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": {
      "id": "ag_r4nD0mId123",
      "version": 2
    },
    "environment_id": "env_default"
  }' | jq .

成功返回 201 Created：

{
  "id": "ses_newSession456",
  "agent_id": "ag_r4nD0mId123",
  "environment_id": "env_default",
  "status": "idle",
  "title": null,
  "metadata": {},
  "usage": {
    "input_tokens": 0,
    "output_tokens": 0
  },
  "created_at": "2026-05-18T12:00:00Z",
  "updated_at": "2026-05-18T12:00:00Z"
}

在生产环境中建议使用方式二（指定版本），避免因 Agent 更新导致行为变化。

agent 字段格式

格式	示例	行为
字符串	`"ag_r4nD0mId123"`	使用该 Agent 最新版本
对象	`{"id": "ag_r4nD0mId123", "version": 2}`	锁定到指定版本

状态流转

事件请求体格式

POST /sessions/{id}/events 的请求体必须使用 events 数组包装，content 是内容块数组：

字段	类型	必填	说明
`events`	array	是	事件数组，单次请求可包含一个或多个事件
`events[].type`	string	是	事件类型，如 `user.message`
`events[].content`	array	是	内容块数组
`events[].content[].type`	string	是	内容块类型，如 `text`
`events[].content[].text`	string	是	文本内容

idle → processing

当你向 Session 发送 user.message 事件时，状态从 idle 变为 processing：

# 发送消息触发处理
curl -s -X POST "https://openapi.qoder.sh/api/v1/cloud/sessions/ses_newSession456/events" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [{
      "type": "user.message",
      "content": [{"type": "text", "text": "分析当前目录下所有 Python 文件的代码复杂度。"}]
    }]
  }' | jq .

processing → idle

Agent 完成处理后自动回到 idle，通过事件流会收到 session.status_idle 事件。

取消 Session

强制终止正在执行的 Session：

# 取消 Session
curl -s -X POST "https://openapi.qoder.sh/api/v1/cloud/sessions/ses_newSession456/cancel" \
  -H "Authorization: Bearer $QODER_PAT"

取消是终态操作。被取消的 Session 无法恢复，需要创建新 Session。

查询 Session

# 获取单个 Session 详情
curl -s "https://openapi.qoder.sh/api/v1/cloud/sessions/ses_newSession456" \
  -H "Authorization: Bearer $QODER_PAT"

# 列出所有 Session（支持分页）
curl -s "https://openapi.qoder.sh/api/v1/cloud/sessions?limit=10" \
  -H "Authorization: Bearer $QODER_PAT"

分页响应：

{
  "data": [
    {
      "id": "ses_newSession456",
      "agent_id": "ag_r4nD0mId123",
      "environment_id": "env_default",
      "status": "idle",
      "usage": {
        "input_tokens": 1520,
        "output_tokens": 834
      }
    }
  ],
  "first_id": "ses_newSession456",
  "last_id": "ses_newSession456",
  "has_more": false
}

Usage 统计

每个 Session 维护累计的 token 用量：

字段	说明
`usage.input_tokens`	所有请求的输入 token 总数
`usage.output_tokens`	所有响应的输出 token 总数

# 查看 Session 用量
curl -s "https://openapi.qoder.sh/api/v1/cloud/sessions/ses_newSession456" \
  -H "Authorization: Bearer $QODER_PAT"

{
  "input_tokens": 3840,
  "output_tokens": 2156
}

Session 与 Agent 版本绑定

Session 创建时会快照 Agent 的配置：

使用字符串形式 "agent": "ag_xxx" 绑定创建时刻的最新版本
使用对象形式 "agent": {"id": "ag_xxx", "version": N} 绑定精确版本
Session 创建后，修改 Agent 不会影响已存在的 Session
想要使用新版 Agent，需要创建新的 Session

Session A — 绑定 Agent v1

在更新前创建。即使 Agent 后续更新到 v2，Session A 仍然继续使用 v1 配置。

Session B — 绑定 Agent v2

在更新后创建，使用新的 v2 配置。

多轮对话

Session 支持多轮对话。每次发送消息后等待 session.status_idle，然后继续发送：

#!/bin/bash
# 多轮对话示例
BASE_URL="https://openapi.qoder.sh/api/v1/cloud"
SESSION_ID="ses_newSession456"
HEADERS=(
  -H "Authorization: Bearer $QODER_PAT"
)

# 第一轮：提出需求
curl -s -X POST "$BASE_URL/sessions/$SESSION_ID/events" \
  "${HEADERS[@]}" \
  -H "Content-Type: application/json" \
  -d '{"events": [{"type": "user.message", "content": [{"type": "text", "text": "创建一个 Python Flask 项目脚手架。"}]}]}'

# 等待处理完成...（轮询或监听 SSE）
sleep 30

# 第二轮：追加要求
curl -s -X POST "$BASE_URL/sessions/$SESSION_ID/events" \
  "${HEADERS[@]}" \
  -H "Content-Type: application/json" \
  -d '{"events": [{"type": "user.message", "content": [{"type": "text", "text": "给项目添加单元测试和 CI 配置。"}]}]}'

最佳实践

版本锁定 — 生产环境始终使用 {"id": ..., "version": ...} 形式创建 Session
及时取消 — 不再需要的 Session 及时 cancel，释放资源
监控用量 — 定期检查 usage 字段，避免意外消耗
元数据标记 — 用 metadata 记录业务上下文（任务 ID、触发来源等）

常见问题

Q: Session 有超时机制吗？ A: Session 在 idle 状态下会保持一段时间。长时间不活跃的 Session 可能被系统自动归档。建议按需创建，任务完成后主动 cancel。 Q: 向 processing 状态的 Session 发消息会怎样？ A: 会返回错误。必须等待 Session 回到 idle 状态后才能发送新消息。 Q: 一个 Session 最多支持多少轮对话？ A: 没有硬性轮次限制，但受模型上下文窗口大小约束。随着对话增长，早期内容可能被截断。 Q: 如何获取 Session 的完整对话历史？ A: 通过 GET /sessions/{id}/events 获取该 Session 的所有事件，包括用户消息和 Agent 响应。 Q: cancelled 状态可以恢复吗？ A: 不能。cancelled 是终态，需要创建新的 Session 继续工作。如需保留上下文，可在新 Session 的首条消息中携带必要的背景信息。

下一步

概览 — 回顾 Cloud Agents 整体架构
快速开始 — 完整的端到端示例
定义 Agent — 深入 Agent 配置
云端环境 — 自定义运行环境

快速入门

用户指南

SDK

Cloud Agents

启动 Session

Session 生命周期

字段说明

创建 Session

方式一：使用 Agent ID（字符串）

方式二：使用 Agent 对象（指定版本）

agent 字段格式

状态流转

事件请求体格式

idle → processing

processing → idle

取消 Session

查询 Session

Usage 统计

Session 与 Agent 版本绑定

Session A — 绑定 Agent v1

Session B — 绑定 Agent v2

多轮对话

最佳实践

常见问题

下一步

快速入门

用户指南

SDK

Cloud Agents

Documentation Index

​Session 生命周期

​字段说明

​创建 Session

​方式一：使用 Agent ID（字符串）

​方式二：使用 Agent 对象（指定版本）

​agent 字段格式

​状态流转

​事件请求体格式

​idle → processing

​processing → idle

​取消 Session

​查询 Session

​Usage 统计

​Session 与 Agent 版本绑定

Session A — 绑定 Agent v1

Session B — 绑定 Agent v2

​多轮对话

​最佳实践

​常见问题

​下一步

Session 生命周期

字段说明

创建 Session

方式一：使用 Agent ID（字符串）

方式二：使用 Agent 对象（指定版本）

agent 字段格式

状态流转

事件请求体格式

idle → processing

processing → idle

取消 Session

查询 Session

Usage 统计

Session 与 Agent 版本绑定

多轮对话

最佳实践

常见问题

下一步