Skip to main content
Sessions

Session 数据结构

Session、资源、事件和线程的共享结构。

Session 对象

创建、获取、列出、更新和归档接口都会返回该对象。
字段类型说明
idstringsess_ 前缀的 Session ID
typestring固定为 "session"
agentobject本 Session 使用的 Agent 快照，字段裁剪规则见 Session 嵌入 agent
environment_idstringSession 使用的 Environment ID
statusstring生命周期状态：rescheduling、running、idle、canceling 或 terminated。canceling 是 Cancel 端点确认时返回的瞬态状态；轮询 Session 或监听状态事件可获得最终状态
titlestring | nullSession 标题
metadataobjectSession 元数据
environment_variablesobjectSession 级环境变量，注入到 agent 运行时；返回值是 JSON 对象（{"NAME":"value"}），无配置时返回 {}。请求侧使用单字符串（详见 创建 Session）
resourcesSession resource 数组挂载到 Session 的 file、GitHub repository 或 Memory Store 资源
vault_idsstring 数组挂载到 Session 的 Vault ID
deployment_idstring | null由 Deployment 创建时的 Deployment ID，否则为 null
outcome_evaluationsarrayOutcome 评估结果；新 Session 返回 []
statsSession statsSession 统计信息
archived_atstring | null归档时间，未归档时为 null
created_atstring创建时间
updated_atstring最近更新时间
Session 响应不再包含旧字段 agent_id、turn_status、memory_store_ids 或 usage。

Agent 引用

创建 Session 时的 agent 可以是 Agent ID 字符串，也可以是如下对象：
字段类型必填说明
idstring是agent_ 前缀的 Agent ID
typestring是（仅对象形式）必须固定为 "agent"，对象形式下缺失或为其他值返回 400。直接传字符串 Agent ID 时不校验该字段
versioninteger否要固定的 Agent 版本；省略或传 0 表示使用最新活跃版本

Session 嵌入 agent

Session 对象 中返回的 agent 是该 Session 固定的 Agent 快照，与原始 Agent 相比有以下字段会被裁剪：
  • created_at、updated_at：嵌入 Agent 中始终不返回。
  • archived、archived_at：嵌入 Agent 中始终不返回；Session 不受 Agent 归档状态影响。
  • metadata：Agent 自身的 metadata 被裁剪；只暴露 Session 级别的 metadata。
  • instructions：被替换为 system。
当 Agent 配置 multiagent.type = "coordinator" 时，agent.multiagent.agents[] 中的桩 {type, id, version} 会被服务端展开为完整 Agent 定义（详见 Multiagent 阵列元素）。在 Session Thread 对象 中，嵌入 agent 还会额外去掉 multiagent 字段——协调器子线程只携带各自的 Agent 快照。

agent.model.effective_context_window

Session 响应在 agent.model 中额外返回只读字段 effective_context_window（int64，单位 token），表示当前 Session 实际生效的上下文窗口（已考虑 Environment 级 override）。值为非正或缺失时不返回；客户端将该字段视为参考即可。

Session resource

resources[] 通过 type 区分资源类型。

File resource

字段类型必填说明
idstring仅响应Resource ID
typestring是"file"
file_idstring是file_ 前缀的 File ID，文件必须已 ready
mount_pathstring否容器内挂载路径。省略时默认 /mnt/session/uploads/<file_id>
created_atstring仅响应资源创建时间
updated_atstring仅响应资源更新时间

GitHub repository resource

字段类型必填说明
idstring仅响应Resource ID
typestring是"github_repository"
urlstring是仓库 URL
authorization_tokenstring是（仅写入）访问仓库使用的 GitHub token；响应中不会返回
mount_pathstring否容器内 clone 目标路径；省略时根据仓库名生成
checkoutobject否Git checkout 目标，例如 {"type":"branch","name":"main"}
created_atstring仅响应资源创建时间
updated_atstring仅响应资源更新时间

Memory Store resource

字段类型必填说明
typestring是"memory_store"
memory_store_idstring是memstore_ 前缀的 Memory Store ID
accessstring | null否可选访问模式。允许值："read_write"、"read_only"。空字符串或省略表示采用默认值（不覆盖）
instructionsstring | null否可选指令，存在 Session resource 上。最大长度 4096 字符
namestring | null仅响应可查询到时返回当前 Memory Store 名称
descriptionstring仅响应可查询到时返回当前 Memory Store 描述
mount_pathstring | null仅响应当前实现除已有快照值外返回 null
Memory Store resource 不包含 id、created_at 或 updated_at 字段。

Session stats

字段类型说明
active_secondsnumber活跃处理时长；新 Session 为 0
duration_secondsnumberSession 持续时长；新 Session 为 0

Multiagent 阵列元素

当嵌入 Agent 配置 multiagent.type = "coordinator" 时，Session 接口返回的 agent.multiagent.agents[] 每条元素都会从原始桩引用展开为完整 Agent 定义（同样遵循 Session 嵌入 agent 的字段裁剪规则，且每条元素自身的 multiagent 字段会被裁掉）。
字段类型说明
typestring兄弟 Agent 取 "agent"；表示协调器自身时取 "self"
idstringAgent ID。type = "agent" 时存在；type = "self" 时与协调器自身 ID 相同
versioninteger固定的 Agent 版本号；type = "agent" 时存在
namestring展开后的 Agent 名称
descriptionstring | null展开后的 Agent 描述
systemstring展开后的 Agent 系统提示词（替代 instructions）
modelstring | object与嵌入 Agent 一致；包含 effective_context_window
其他 Agent 字段各异tools、MCP servers、skills 等字段，遵循与嵌入 Agent 相同的裁剪规则
桩引用解析失败（例如目标 Agent 版本已删除）的元素将原样返回。

Event 对象

send、list 和 stream 接口返回的事件是按事件类型变化的 JSON 对象。公开响应只暴露文档中定义的公开字段。
字段类型说明
idstring以 evt_ 为前缀的 Event ID
typestringEvent 类型
processed_atstring事件被处理后出现。许多 agent 生成的事件不包含此字段。
不同事件类型还可能包含 content、input、name、tool_use_id、mcp_tool_use_id、custom_tool_use_id、result、deny_message、rubric、outcome_id、session_thread_id、stop_reason、error 或 usage 等字段。

客户端可发送事件类型

POST /api/v1/cloud/sessions/{session_id}/events 只接受以下事件类型：
类型必填字段说明
user.messagecontentcontent 必须是非空 content block 数组
user.interrupt无session_thread_id 可选；省略时响应回显 null
user.tool_confirmationtool_use_id, resultresult 为 allow 或 deny；deny_message 可选
user.tool_resulttool_use_idself-hosted worker 返回内置工具结果。content 可选；传入时必须是 content block 数组。is_error 可选
user.custom_tool_resultcustom_tool_use_id返回客户端自定义工具结果。content 可选；传入时必须是 content block 数组。is_error 可选
user.define_outcomedescription, rubricrubric 是对象，例如 {"type":"text","content":"..."} 或 {"type":"file","file_id":"file_..."}；max_iterations 可选
system.messagecontentcontent 必须是非空文本 content block 数组，且必须跟在 user/tool result 事件后

公开事件类型

list 和 stream 接口可能暴露以下事件类型： user.message、user.interrupt、user.tool_confirmation、user.custom_tool_result、user.define_outcome、user.tool_result、system.message、agent.custom_tool_use、agent.mcp_tool_result、agent.mcp_tool_use、agent.message、agent.thinking、agent.thread_context_compacted、agent.thread_message_received、agent.thread_message_sent、agent.tool_result、agent.tool_use、session.deleted、session.error、session.status_idle、session.status_rescheduled、session.status_running、session.status_terminated、session.thread_created、session.thread_status_idle、session.thread_status_rescheduled、session.thread_status_running、session.thread_status_terminated、session.updated、span.model_request_start、span.model_request_end、span.outcome_evaluation_start、span.outcome_evaluation_ongoing 和 span.outcome_evaluation_end。

Event delta stream 帧

buffered 事件是内容生成完成后输出并写入 Session 事件历史的完整公开 Event 对象，也是客户端应采用的权威结果。 event_start 和 event_delta 是用于增量输出的 stream-only SSE payload，不属于公开 Event 对象，也不会出现在事件 list/history 响应中。它们的 JSON payload 不包含顶层 id 或 processed_at；SSE id: 字段携带正在增量输出的事件 ID，并可用于 Last-Event-ID。

Event start 帧

event_start 帧用于标识已经开始增量输出的公开事件。
字段类型说明
typestring固定为 "event_start"
eventobject增量事件引用
event 对象包含以下字段：
字段类型说明
idstring以 evt_ 为前缀的 Event ID；SSE id:、相关 delta 和 buffered 事件使用同一个 ID
typestring"agent.message" 或 "agent.thinking"
agent.message 的 start 之后会输出文本 event_delta。agent.thinking 只有 start，不会输出 delta；如果本轮产生 thinking，则使用相同 ID 的 buffered agent.thinking 事件表示该 thinking 阶段结束。 
{
  "type": "event_start",
  "event": {
    "id": "evt_00jjujk9fbnr4wkj2gh8",
    "type": "agent.message"
  }
}

Event delta 帧

event_delta 帧用于向增量输出的 agent.message 追加文本。
字段类型说明
typestring固定为 "event_delta"
event_idstring与对应 event_start.event.id 和 SSE id: 相同的 Event ID
deltaobject内容增量
delta 对象包含以下字段：
字段类型说明
typestring固定为 "content_delta"
indexinteger被更新 content block 的从零开始的索引
contentobject文本片段，包含 type: "text" 和字符串字段 text
{
  "type": "event_delta",
  "event_id": "evt_00jjujk9fbnr4wkj2gh8",
  "delta": {
    "type": "content_delta",
    "index": 0,
    "content": {
      "type": "text",
      "text": "你好"
    }
  }
}

Model request span 事件

span.model_request_start 表示一次模型请求开始。
字段类型说明
idstring以 evt_ 为前缀的 Event ID
processed_atstringRFC 3339 时间戳
typestring固定为 "span.model_request_start"
span.model_request_end 表示该模型请求结束。
字段类型说明
idstring以 evt_ 为前缀的 Event ID
is_errorboolean模型请求是否因错误或取消而结束
model_request_start_idstring对应 span.model_request_start 事件的 ID
processed_atstringRFC 3339 时间戳
typestring固定为 "span.model_request_end"
Model request span 的公开响应不包含模型用量或内部耗时信息。

Session Thread 对象

Managed-agent 场景下，Session 内的每个线程使用如下结构。
字段类型说明
idstringsthr_ 前缀的 Thread ID
typestring固定为 "session_thread"
session_idstring所属 Session ID
parent_thread_idstring | null父线程 ID；协调器主线程为 null
agentobject该线程使用的 Agent 快照，结构同 Session 嵌入 agent，并额外去掉 multiagent 字段
statusstring生命周期状态：running、idle、rescheduling 或 terminated
statsobject | null线程统计信息；当前实现返回 null
archived_atstring | null归档时间，未归档时为 null
created_atstring创建时间
updated_atstring最近更新时间
Thread 响应不再包含旧字段 agent_id、agent_version、name、role、stop_reason、created_by_tool_use_id 或 usage。
快速入门
管理 Session
构建Agent
运行环境
实践教程
API参考