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，默认 [] |
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 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
让 Agent 在环境中以有状态对话的方式运行。