Session 数据结构

Session、资源、事件和统计信息的复用结构。

​

Session 对象

创建、查询、列表、更新和归档接口都会返回该结构。

字段	类型	说明
id	string	Session ID，前缀为 sess_
type	string	固定值 "session"
agent	Agent 对象	创建 Session 时捕获的 Agent 快照
agent_id	string	本 Session 使用的 Agent ID
environment_id	string	本 Session 使用的 Environment ID
status	string	Session 生命周期状态，如 idle、running、terminated
turn_status	string	当前 turn 状态；为空时返回 idle
title	string	Session 标题
metadata	object	Metadata 对象
resources	Session resource 数组	挂载到 Session 的文件或仓库，默认 []
vault_ids	string 数组	挂载到 Session 的 Vault ID，默认 []
memory_store_ids	string 数组	挂载到 Session 的 Memory Store ID，默认 []
environment_variables	object	归一化后的 Session 级环境变量，默认 {}
stats	Session stats	Session 统计信息
archived_at	string | null	归档时间；未归档时为 null
created_at	string	创建时间
updated_at	string	最后更新时间

​

Agent 引用

创建请求中的 agent 可以是 Agent ID 字符串，也可以是以下对象。

字段	类型	必填	说明
id	string	是	Agent ID，前缀为 agent_
type	string	否	可选标记
version	integer	否	要捕获的 Agent 版本；省略或传 0 表示使用最新 active 版本

​

Inline environment

创建请求中的 environment 可以是 Environment ID 字符串，也可以是以下对象。

字段	类型	必填	说明
name	string	否	Environment 名称；省略或空白时默认为 "Session Environment"
description	string	否	Environment 描述
config	Environment config	是	Environment 配置
metadata	object	否	Metadata 对象

​

Session 环境变量

创建请求中的 environment_variables 是字符串，不是对象。服务端会解析并在 Session 响应中以 environment_variables 对象返回。

规则	说明
格式	用分号或换行分隔的 KEY=VALUE 条目
变量名格式	[A-Za-z_][A-Za-z0-9_]*
空值	允许，例如 EMPTY=
变量数量上限	64
单个值大小上限	8 KiB
总大小上限	变量名和值合计 64 KiB
保留名称	SERVER_ENDPOINT、USER_ID、WORK_DIR
保留前缀	CAW_、QODER_
self-hosted Environment	不支持

​

Session resource

resources[] 通过 type 区分不同结构。

​

File resource

字段	类型	必填	说明
type	string	否	"file"；省略时默认为 "file"
file_id	string	是	File ID，前缀为 file_；文件必须处于 ready 状态
path	string	否	容器内挂载路径，默认 /data/{file_id}。相对路径会补成 /data/ 下路径；归一化后必须仍在 /data/ 下，最长 512 字符
mount_path	string	否	请求中的 path 别名；如果与 path 同时提供，二者必须相同。响应中保存为归一化后的 path

​

GitHub repository resource

字段	类型	必填	说明
type	string	是	"github_repository"
url	string	是	仓库 URL
mount_path	string	否	容器内 clone 目标路径
authorization_token	string	否	访问私有仓库的 token

​

Session stats

字段	类型	说明
active_seconds	number	活跃处理时长（秒），新建 Session 为 0
duration_seconds	number	Session 持续时长（秒），新建 Session 为 0

​

Event 对象

发送事件、列表事件和事件流返回的事件是随 type 变化的 JSON 对象，通用字段如下。

字段	类型	说明
id	string	Event ID，前缀为 evt_
type	string	事件类型
schema_version	string	事件 schema 版本；CAS 创建的用户事件当前为 "1.0"
session_id	string	所属 Session ID
turn_id	string	事件属于某个 turn 时存在
created_at	string	创建时间
processed_at	string | null	处理时间

​

客户端事件请求类型

Type	必填字段	说明
user.message	content	开始一个新 turn。content 可以是 string 或 content block 数组
user.interrupt	无	请求中断/取消
user.tool_confirmation	tool_use_id、result	result 必须是 allow 或 deny；deny_message 可选
user.custom_tool_result	custom_tool_use_id	content 可选，最终保存为 text content blocks
user.define_outcome	服务端不强制	额外字段会被保留

​

Session Thread 对象

在 Managed Agents 场景下，Session 内的每个线程由以下结构表示。

字段	类型	说明
id	string	Thread ID，前缀为 sthr_
type	string	固定值 "session_thread"
session_id	string	所属 Session ID
parent_thread_id	string | null	父线程 ID；coordinator 线程为 null
agent	object	该线程使用的 Agent 快照（过滤后的精简版本，包含 id、type、name、model、version）
agent_id	string	Agent ID
agent_version	integer	该线程锁定的 Agent 版本号
name	string	线程显示名称。coordinator 通常为空；child 可由 create_agent 的 agent_name 参数指定
role	string	线程角色："coordinator" 或 "child"
status	string	线程状态："idle"、"running"、"archived"、"terminated"、"blocked"
stop_reason	object	停止原因。空对象 {} 表示正在运行；{"type": "end_turn"} 表示正常完成；{"type": "archive"} 表示被归档；{"type": "requires_action", ...} 表示等待操作
created_by_tool_use_id	string | null	创建该线程的工具调用 ID；coordinator 为 null
archived_at	string | null	归档时间；未归档时为 null
created_at	string	创建时间
updated_at	string	最后更新时间

​

线程事件类型

在 managed agents 场景下，事件流中会出现以下新事件类型。所有事件都包含 session_thread_id 字段。

事件类型	说明	特有字段
session.thread_created	新子线程被创建	parent_thread_id、agent_id、agent_version、agent_name、role、created_by_tool_use_id
session.thread_status_running	线程开始执行	agent_name、status
session.thread_status_idle	线程执行完成或暂停	status、stop_reason
session.thread_status_terminated	线程被归档或终止	status、stop_reason
agent.thread_message_sent	线程间发送消息	direction（"coordinator_to_child"）、content、from_session_thread_id、to_session_thread_id
agent.thread_message_received	线程间接收消息	direction（"child_to_parent"）、content、is_error、from_session_thread_id、to_session_thread_id

​

相关

启动 Session

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