Session 数据结构

Session 对象

创建、获取、列出、更新和归档接口都会返回该对象。

字段	类型	说明
`id`	string	`sess_` 前缀的 Session ID
`type`	string	固定为 `"session"`
`agent`	object	本 Session 使用的 Agent 快照，字段裁剪规则见 Session 嵌入 agent
`environment_id`	string	Session 使用的 Environment ID
`status`	string	生命周期状态：`rescheduling`、`running`、`idle` 或 `terminated`。Cancel 端点响应中的 `canceling` 是固定确认值，不是 Session 对象的持久化状态
`title`	string \| null	Session 标题
`metadata`	object	Session 元数据
`environment_variables`	object	Session 级环境变量，以字符串 key 到字符串 value 的 map（`{"NAME":"value"}`）注入到 agent 运行时；无配置时返回 `{}`。详见创建 Session
`resources`	Session resource 数组	挂载到 Session 的 file、GitHub、通用 Git 或 Memory Store 资源
`vault_ids`	string 数组	挂载到 Session 的 Vault ID
`deployment_id`	string \| null	由 Deployment 创建时的 Deployment ID，否则为 `null`
`outcome_evaluations`	array	Outcome 评估结果；新 Session 返回 `[]`
`stats`	Session stats	Session 统计信息
`usage`	Session usage	Session 的模型、沙箱运行时与总 credits 累计快照；usage 数据不可用时省略该字段
`archived_at`	string \| null	归档时间，未归档时为 `null`
`created_at`	string	创建时间
`updated_at`	string	最近更新时间

Session 响应不再包含旧字段 agent_id、turn_status 或 memory_store_ids。

Agent 引用

创建 Session 时的 agent 可以是 Agent ID 字符串，也可以是如下对象：

字段	类型	必填	说明
`id`	string	是	`agent_` 前缀的 Agent ID
`type`	string	是（仅对象形式）	必须固定为 `"agent"`，对象形式下缺失或为其他值返回 400。直接传字符串 Agent ID 时不校验该字段
`version`	integer	否	要固定的 Agent 版本；省略或传 `0` 表示使用最新活跃版本

Session 嵌入 agent

Session 对象中返回的 agent 是该 Session 固定的 Agent 快照，与原始 Agent 相比有以下字段会被裁剪：发布更新的源 Agent 配置不会替换这份快照。更新 Session时提交 agent 字段，可以只为当前 Session 修改受支持的运行配置，但不会推进内嵌的 agent.version；链接文档也说明了 Skill version 的生效规则。

created_at、updated_at：嵌入 Agent 中始终不返回。
archived、archived_at：嵌入 Agent 中始终不返回；Session 不受 Agent 归档状态影响。
metadata：Agent 自身的 metadata 被裁剪；只暴露 Session 级别的 metadata。
instructions：被替换为 system。

agent.multiagent.agents[] 的返回结构见 Multiagent 阵列元素，单个线程的 Agent 结构见 Session Thread 对象。

`agent.model.effective_context_window`

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

Session resource

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

File resource

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

GitHub repository resource

字段	类型	必填	说明
`id`	string	仅响应	Resource ID
`type`	string	是	`"github_repository"`
`url`	string	是	仓库 URL
`authorization_token`	string	否（仅写入）	访问私有仓库或 push 使用的 GitHub token；响应中不会返回
`mount_path`	string	否	容器内 clone 目标路径；省略时根据仓库名生成
`checkout`	object	否	Git checkout 目标，例如 `{"type":"branch","name":"main"}`
`created_at`	string	仅响应	资源创建时间
`updated_at`	string	仅响应	资源更新时间

通用 Git repository resource

GitLab、Gitee、Bitbucket 以及其他 HTTP(S) Git 服务使用该资源类型。

字段	类型	必填	说明
`id`	string	仅响应	Resource ID
`type`	string	是	`"git_repository"`
`url`	string	是	HTTP(S) Clone URL。公开仓库无需用户名；需要鉴权时在 URL 中包含平台用户名，例如 `https://username@gitlab.com/group/repo.git`
`password`	string	否（仅写入）	私有仓库或需要推送时，与 URL 中的用户名同时提供；可填写账号密码或平台要求的 Access Token/PAT。响应中不会返回
`mount_path`	string	否	容器内 clone 目标路径；省略时根据仓库名生成
`checkout`	object	否	Git checkout 目标，例如 `{"type":"branch","name":"main"}`
`created_at`	string	仅响应	资源创建时间
`updated_at`	string	仅响应	资源更新时间

Memory Store resource

字段	类型	必填	说明
`type`	string	是	`"memory_store"`
`memory_store_id`	string	是	`memstore_` 前缀的 Memory Store ID
`access`	string \| null	否	可选访问模式。允许值：`"read_write"`、`"read_only"`。空字符串或省略表示采用默认值（不覆盖）
`instructions`	string \| null	否	可选指令，存在 Session resource 上。最大长度 4096 字符
`name`	string \| null	仅响应	可查询到时返回当前 Memory Store 名称
`description`	string	仅响应	可查询到时返回当前 Memory Store 描述
`mount_path`	string \| null	仅响应	当前实现除已有快照值外返回 `null`

Memory Store resource 不包含 id、created_at 或 updated_at 字段。

Session stats

字段	类型	说明
`active_seconds`	number	活跃处理时长；新 Session 为 `0`
`duration_seconds`	number	Session 持续时长；新 Session 为 `0`

Session usage

usage 是 Session 级累计快照：

字段	类型	说明
`model_credits`	number	Session 中已记录模型调用累计消耗的 credits
`sandbox_runtime_credits`	number	Session 使用可计费云端沙箱运行时累计消耗的 credits
`total_credits`	number	Session 各 usage 分项累计消耗的 credits 总和

没有 usage 数据的 Session 省略 usage 字段。三个 credits 数值都向下取整而不是四舍五入，最多保留 2 位小数；例如 7.6681 返回为 7.66。JSON number 不保证补齐末尾的 0，因此 1.20 可能返回为 1.2。这三个字段共同组成一次快照，重复查询时应按 Session ID 覆盖本地记录，不要再次累加。

Multiagent 阵列元素

Session 响应的 agent.multiagent.agents[] 中，普通 Agent 和 self 条目返回对应的 Agent 定义，字段如下；不包含条目自身的 multiagent 字段。 Advisor 仅返回 type 和 model，例如 {"type":"advisor","model":"ultimate"}，见 Advisor 对象。

字段	类型	说明
`type`	string	兄弟 Agent 取 `"agent"`；表示协调器自身时取 `"self"`
`id`	string	Agent ID。`type = "agent"` 时存在；`type = "self"` 时与协调器自身 ID 相同
`version`	integer	当前会话使用的子 Agent 版本号，`type = "agent"` 时存在。例如，子 Agent 配置为 `"latest"`，创建会话时最新版本是 v3，这里返回 `3`；该会话始终使用 v3
`name`	string	展开后的 Agent 名称
`description`	string \| null	展开后的 Agent 描述
`system`	string	展开后的 Agent 系统提示词（替代 `instructions`）
`model`	string \| object	与嵌入 Agent 一致；包含 `effective_context_window`
其他 Agent 字段	各异	tools、MCP servers、skills 等字段，遵循与嵌入 Agent 相同的裁剪规则

无法读取被引用 Agent 的定义时（例如目标版本已删除），该条目保留原始引用。

Event 对象

send、list 和 stream 接口返回的事件是按事件类型变化的 JSON 对象。公开响应只暴露文档中定义的公开字段。

字段	类型	说明
`id`	string	以 `evt_` 为前缀的 Event ID
`type`	string	Event 类型
`processed_at`	string	事件被处理后出现。许多 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 或 model_usage 等字段。

客户端可发送事件类型

POST /api/v1/cloud/sessions/{session_id}/events 只接受以下事件类型：

类型	必填字段	说明
`user.message`	`content`	`content` 必须是非空 content block 数组
`user.interrupt`	无	`session_thread_id` 可选；省略时响应回显 `null`
`user.tool_confirmation`	`tool_use_id`, `result`	`result` 为 `allow` 或 `deny`；`deny_message` 可选
`user.tool_result`	`tool_use_id`	self-hosted worker 返回内置工具结果。`content` 可选；传入时必须是 content block 数组。`is_error` 可选
`user.custom_tool_result`	`custom_tool_use_id`	返回客户端自定义工具结果。`content` 可选；传入时必须是 content block 数组。`is_error` 可选
`user.define_outcome`	`description`, `rubric`	`rubric` 是对象，例如 `{"type":"text","content":"..."}` 或 `{"type":"file","file_id":"file_..."}`；`max_iterations` 可选
`system.message`	`content`	`content` 必须是非空文本 content block 数组，且必须跟在 user/tool result 事件后

消息内容块

events[].type 表示事件类型，content[].type 表示消息内容块类型，图片的 source.type 表示来源。

事件	接受的 `content[].type`	`content` 要求
`user.message`	`text`、`image`	必填、非空数组，可混合文本与图片
`system.message`	`text`	必填、非空数组
`user.tool_result`、`user.custom_tool_result`	`text`、`image`、`document`、`search_result`	可省略；传入时必须为数组，可为空

用户消息

内容块字段如下，均为必填；仅使用表中对应字段。

`content[].type`	字段	说明
`text`	`type`、`text`	`text` 为非空、非纯空白字符串
`image`	`type`、`source`	`source` 为以下三种来源之一

图片 source 的字段均为字符串：

`source.type`	必填字段	说明
`base64`	`type`、`media_type`、`data`	`media_type` 为 `image/png`、`image/jpeg`、`image/webp` 或 `image/gif`；`data` 为纯 Base64，允许省略末尾 `=`，不带 Data URL 前缀
`url`	`type`、`url`	外部 HTTPS 图片地址，需能被模型服务读取；不能指向内网、回环等受限地址
`file`	`type`、`file_id`	通过上传文件获取的图片 File ID，当前身份可读取且状态为 `ready`；支持 PNG、JPEG、WebP、GIF

图片限制：

每条 user.message 最多 100 个图片块，Session 需使用支持图片输入的模型。
单张 Base64 编码文本最多 10 MiB（10,485,760 字节），宽、高分别不超过 8000 像素。超过编码长度限制时可改用 File 来源。
Base64 和 File 图片可能被缩放或压缩；URL 图片由下游模型服务读取。

用户消息示例

以下为单个事件对象，发送时放入 events 数组。文本：

{
  "type": "user.message",
  "content": [{"type": "text", "text": "你好"}]
}

Base64 图片：

{
  "type": "user.message",
  "content": [{"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": "<图片的纯 Base64 字符串>"}}]
}

URL 图片：

{
  "type": "user.message",
  "content": [{"type": "image", "source": {"type": "url", "url": "https://example.com/image.png"}}]
}

File 图片：

{
  "type": "user.message",
  "content": [{"type": "image", "source": {"type": "file", "file_id": "file_..."}}]
}

发送接口见发送事件。

公开事件类型

list 和 stream 接口可能暴露以下事件类型： user.message、user.interrupt、user.tool_confirmation、user.custom_tool_result、user.define_outcome、user.tool_result、system.message、agent.artifact_delivered、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、session.usage、span.model_request_start、span.model_request_end、span.outcome_evaluation_start、span.outcome_evaluation_ongoing 和 span.outcome_evaluation_end。

`agent.thread_context_compacted` 事件

上下文压缩完成后发送。上游返回可计费 credits 时，usage.credits 表示该次压缩消耗的 credits；上游未返回时省略 usage。这笔费用已经计入 Session 的 usage.model_credits，客户端不要重复累加。事件不返回 token 数。

`agent.artifact_delivered` 事件

agent.artifact_delivered 表示 Agent 已成功交付一个产物文件。每个成功交付的文件对应一条事件；一次交付多个文件时会产生多条事件。它由服务端生成，可通过事件 list 和 stream 接口读取，不能通过发送事件接口提交。

字段	类型	说明
`id`	string	以 `evt_` 为前缀的 Event ID
`type`	string	固定为 `agent.artifact_delivered`
`file_id`	string	已交付文件的 File ID，前缀为 `file_`
`original_filename`	string	交付文件的原始文件名
`size`	integer (int64)	文件大小，单位为字节
`content_type`	string	文件的 MIME 类型，例如 `application/pdf`
`processed_at`	string	可选的事件处理时间，RFC 3339 格式

{
  "id": "evt_019e392c0d787cfaa21bda98e06cd914",
  "type": "agent.artifact_delivered",
  "file_id": "file_019e3bb9b0c2752688aeb5fdacf00565",
  "original_filename": "report.pdf",
  "size": 1234,
  "content_type": "application/pdf",
  "processed_at": "2026-05-18T03:40:50Z"
}

收到事件后，可使用 file_id 获取文件详情。文件的 downloadable 为 true 时，调用下载文件内容（GET /api/v1/cloud/files/{file_id}/content）取得临时下载 URL，再请求该 URL 下载文件。事件本身不包含文件内容或下载 URL。

`session.updated` 事件

Session 更新成功后会发出 session.updated。事件固定包含 id、type 和 processed_at，并根据请求选择性包含以下字段：

字段	类型	说明
`title`	string \| null	请求提交 `title` 时返回
`metadata`	object	请求提交 `metadata` 且更新后的 Metadata 非空时返回
`agent`	object	通过更新 Session动态更新运行配置后返回的内嵌运行配置快照

如果请求只修改 environment_variables，事件只包含固定字段。事件始终不会包含环境变量名称和值。

`session.error` 事件

session.error 表示 Session 执行过程中出现错误。事件包含 id、type、processed_at 和 error。 error 对象包含以下字段：

字段	类型	说明
`type`	string	错误分类。客户端应兼容 `unknown_error` 和以后新增的类型
`message`	string	可读的错误说明
`retry_status`	object	重试状态；`type` 为 `retrying`、`exhausted` 或 `terminal`
`qoder_error_code`	string	可选诊断码。客户端不应据此判断是否重试

retry_status.type 的语义：

值	说明
`retrying`	服务端正在自动重试，客户端继续等待
`exhausted`	自动重试次数或恢复时限已用尽，或者错误不可重试而直接失败；本轮不再自动恢复。客户端等待后续状态事件，再决定是否发送新消息
`terminal`	当前错误不可恢复，服务端不再自动重试；最终状态以后续 Session/Thread 状态事件为准

Advisor 事件

Advisor 的生命周期事件通过 agent_name: "qoder.advisor" 标识，session_thread_id 用于区分每次咨询。

事件	获取位置	关键字段
`agent.thread_message_received`	主线程事件流	`from_session_thread_id` 为咨询线程 ID，`from_agent_name` 为 `qoder.advisor`，`content` 为建议内容
`agent.thread_message_sent`	Advisor Thread 事件流	`to_session_thread_id` 和 `to_agent_name` 标识主线程，`content` 为建议内容
`session.error`	Advisor Thread 事件流	`error` 包含错误原因和重试状态，见 session.error 事件
`session.thread_status_idle`	Session 事件流	`stop_reason.type` 为 `end_turn` 时咨询结束（含中断），为 `retries_exhausted` 时咨询失败，具体原因见该线程的 `session.error`

主线程接收建议的示例：

{
  "id": "evt_advisor_received",
  "type": "agent.thread_message_received",
  "processed_at": "2026-09-09T08:00:05Z",
  "from_session_thread_id": "sthr_advisor_call",
  "from_agent_name": "qoder.advisor",
  "content": [{"type": "text", "text": "先灰度迁移，并验证回滚步骤。"}]
}

咨询失败不会终止主 Agent 的任务，也不会产生建议消息；错误详情通过 Thread 事件接口获取。

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 帧用于标识已经开始增量输出的公开事件。

字段	类型	说明
`type`	string	固定为 `"event_start"`
`event`	object	增量事件引用

event 对象包含以下字段：

字段	类型	说明
`id`	string	以 `evt_` 为前缀的 Event ID；SSE `id:`、相关 delta 和 buffered 事件使用同一个 ID
`type`	string	`"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 追加文本。

字段	类型	说明
`type`	string	固定为 `"event_delta"`
`event_id`	string	与对应 `event_start.event.id` 和 SSE `id:` 相同的 Event ID
`delta`	object	内容增量

delta 对象包含以下字段：

字段	类型	说明
`type`	string	固定为 `"content_delta"`
`index`	integer	被更新 content block 的从零开始的索引
`content`	object	文本片段，包含 `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 表示一次模型请求开始。

字段	类型	说明
`id`	string	以 `evt_` 为前缀的 Event ID
`processed_at`	string	RFC 3339 时间戳
`type`	string	固定为 `"span.model_request_start"`

span.model_request_end 表示该模型请求结束，本次调用有 credits 数据时包含 model_usage。model_usage.credits 向下取整，最多保留 2 位小数。

字段	类型	说明
`id`	string	以 `evt_` 为前缀的 Event ID
`is_error`	boolean	模型请求是否因错误或取消而结束
`model_request_start_id`	string	对应 `span.model_request_start` 事件的 ID
`model_usage`	object	可选。本次模型调用的 usage；credits 数据不可用时省略
`processed_at`	string	RFC 3339 时间戳
`type`	string	固定为 `"span.model_request_end"`

model_usage 只包含：

字段	类型	说明
`credits`	number	本次模型调用消耗的 credits。值可以为 `0`；向下取整，最多保留 2 位小数

Session Thread 对象

Managed-agent 场景下，Session 内的每个线程使用如下结构。

字段	类型	说明
`id`	string	`sthr_` 前缀的 Thread ID
`type`	string	固定为 `"session_thread"`
`session_id`	string	所属 Session ID
`parent_thread_id`	string \| null	父线程 ID；协调器主线程为 `null`
`agent`	object	普通线程使用的 Agent 快照，结构同 Session 嵌入 agent，并额外去掉 `multiagent` 字段；Advisor Thread 使用 `{"type":"advisor","model":"..."}`
`status`	string	生命周期状态：`running`、`idle`、`rescheduling` 或 `terminated`
`stats`	object \| null	线程统计信息；当前实现返回 `null`
`archived_at`	string \| null	归档时间，未归档时为 `null`
`created_at`	string	创建时间
`updated_at`	string	最近更新时间

Thread 响应不再包含旧字段 agent_id、agent_version、name、role、stop_reason、created_by_tool_use_id 或 usage。

Session budget

通过 budget: {"type":"limit","max_credit_cost":"100.00"} 设置 credit 总上限。type 目前只支持 limit；max_credit_cost 是正十进制字符串，最多 12 位整数、2 位小数。Session 默认不设上限。更新 Session 时，省略 budget 会保留原设置，传 null 会取消限制。预算按 usage.total_credits 的累计值精确计算。该值包括所有线程、Advisor、Grader、上下文压缩和沙箱运行时费用。CAS 在收到新用户消息时检查预算。执行中的轮次即使超限也会继续完成，下一条用户消息会被拒绝。 Session 因达到预算上限而拒绝新消息后，如需继续使用，应将上限提高到已用 credits 之上或取消限制，然后重新发送一条用户消息。调整预算不会自动恢复执行。新上限低于或等于已用 credits 时返回 400；已归档或结束的 Session 不可更新。

session.usage 事件

每次对外发送 session.status_idle 前，如果已有用量数据，事件流会先发送一条 session.usage。除通用事件字段外，事件顶层还包含 model_credits、sandbox_runtime_credits 和 total_credits。这些字段是累计值，客户端应使用新快照覆盖旧快照，不要将多条快照相加。轮次运行期间不会发送用量事件。本轮 idle 后才结算的沙箱费用不包含在本次 session.usage 中；结算后可通过 GET Session 获取，并会包含在下一次 idle 前发送的用量快照中。

​Session 对象

​Agent 引用

​Session 嵌入 agent

​agent.model.effective_context_window

​Session resource

​File resource

​GitHub repository resource

​通用 Git repository resource

​Memory Store resource

​Session stats

​Session usage

​Multiagent 阵列元素

​Event 对象

​客户端可发送事件类型

​消息内容块

​用户消息

​用户消息示例

​公开事件类型

​agent.thread_context_compacted 事件

​agent.artifact_delivered 事件

​session.updated 事件

​session.error 事件

​Advisor 事件

​Event delta stream 帧

​Event start 帧

​Event delta 帧

​Model request span 事件

​Session Thread 对象

​Session budget

​session.usage 事件