> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Session 数据结构

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

## Session 对象

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

| 字段                      | 类型                                       | 说明                                                                                                                                        |
| ----------------------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                    | string                                   | `sess_` 前缀的 Session ID                                                                                                                    |
| `type`                  | string                                   | 固定为 `"session"`                                                                                                                           |
| `agent`                 | object                                   | 本 Session 使用的 Agent 快照，字段裁剪规则见 [Session 嵌入 agent](#session-嵌入-agent)                                                                      |
| `environment_id`        | string                                   | Session 使用的 Environment ID                                                                                                                |
| `status`                | string                                   | 生命周期状态：`rescheduling`、`running`、`idle`、`canceling` 或 `terminated`。`canceling` 是 Cancel 端点确认时返回的瞬态状态；轮询 Session 或监听状态事件可获得最终状态             |
| `title`                 | string \| null                           | Session 标题                                                                                                                                |
| `metadata`              | object                                   | Session 元数据                                                                                                                               |
| `environment_variables` | object                                   | Session 级环境变量，注入到 agent 运行时；返回值是 JSON 对象（`{"NAME":"value"}`），无配置时返回 `{}`。请求侧使用单字符串（详见 [创建 Session](/zh/cloud-agents/api/sessions/create)） |
| `resources`             | [Session resource](#session-resource) 数组 | 挂载到 Session 的 file、GitHub repository 或 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-stats)          | Session 统计信息                                                                                                                              |
| `archived_at`           | string \| null                           | 归档时间，未归档时为 `null`                                                                                                                         |
| `created_at`            | string                                   | 创建时间                                                                                                                                      |
| `updated_at`            | string                                   | 最近更新时间                                                                                                                                    |

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

## Agent 引用

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

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

## Session 嵌入 agent

[Session 对象](#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 阵列元素](#multiagent-阵列元素)）。在 [Session Thread 对象](#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

| 字段           | 类型     | 必填  | 说明                                             |
| ------------ | ------ | --- | ---------------------------------------------- |
| `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 | 是（仅写入） | 访问仓库使用的 GitHub token；响应中不会返回                         |
| `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` |

## Multiagent 阵列元素

当嵌入 Agent 配置 `multiagent.type = "coordinator"` 时，Session 接口返回的 `agent.multiagent.agents[]` 每条元素都会从原始桩引用展开为完整 Agent 定义（同样遵循 [Session 嵌入 agent](#session-嵌入-agent) 的字段裁剪规则，且每条元素自身的 `multiagent` 字段会被裁掉）。

| 字段            | 类型               | 说明                                                          |
| ------------- | ---------------- | ----------------------------------------------------------- |
| `type`        | string           | 兄弟 Agent 取 `"agent"`；表示协调器自身时取 `"self"`                     |
| `id`          | string           | Agent ID。`type = "agent"` 时存在；`type = "self"` 时与协调器自身 ID 相同 |
| `version`     | integer          | 固定的 Agent 版本号；`type = "agent"` 时存在                          |
| `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` 等字段。

## 客户端可发送事件类型

`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 事件后                                                  |

## 公开事件类型

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

| 字段      | 类型     | 说明                  |
| ------- | ------ | ------------------- |
| `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 阶段结束。

```json theme={null}
{
  "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` |

```json theme={null}
{
  "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` 表示该模型请求结束。

| 字段                       | 类型      | 说明                                   |
| ------------------------ | ------- | ------------------------------------ |
| `id`                     | string  | 以 `evt_` 为前缀的 Event ID               |
| `is_error`               | boolean | 模型请求是否因错误或取消而结束                      |
| `model_request_start_id` | string  | 对应 `span.model_request_start` 事件的 ID |
| `processed_at`           | string  | RFC 3339 时间戳                         |
| `type`                   | string  | 固定为 `"span.model_request_end"`       |

Model request span 的公开响应不包含模型用量或内部耗时信息。

## 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](#session-嵌入-agent)，并额外去掉 `multiagent` 字段 |
| `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`。