# 配置上下文压缩

> 全部文档的索引见 [llms.txt](https://ark.volcengine.com/llms.txt)；在任一文档页面地址后追加 `.md` 可获取该页的 Markdown 版本。

单个 Session 的对话历史会随着交互持续增长。配置生效后，运行时会按保存的策略判断是否需要压缩上下文，以控制后续模型调用使用的上下文长度。

压缩只调整后续模型调用看到的上下文，不删除 Session 的 Event 记录。需要查询完整交互历史时，调用 [查询会话事件列表](/docs/list-events-api)。需要查看事件字段含义时，参见 [会话事件结构参考](/docs/sessions-events-reference-v2)。

## 工作原理

`context_management` 是一个最多包含一项策略的数组。当前策略类型固定为 `compaction`。

你可以按任务范围选择配置位置：

1. 只有当前 Session 需要不同策略时，才在创建 Session 的 `agent` 对象中设置 `context_management`，并将 `agent.type` 设为 `agent_with_overrides`。
2. 后续 Session 都需要同一策略时，将 `context_management` 保存到 Agent 版本。
3. 没有自定义上下文压缩策略时，不传 `context_management`，由运行时使用平台默认行为。

创建 Session 后，系统只将显式保存的策略冻结到 Agent 配置快照中。后续更新基础 Agent 不会改变已有 Session。查询 Agent 或 Session 时，响应可能展示平台当前默认策略或默认阈值，当前默认阈值为 `192000` token。

> **说明**
>
> 上下文压缩、上下文缓存和长期记忆解决的问题不同：
>
> - 上下文压缩：缩短单个 Session 提交给模型的历史内容。
> - 上下文缓存：复用重复输入，降低推理延迟和输入 token 成本。
> - 长期记忆（Memory Store）：跨 Session 保存并复用长期信息。

## 为 Agent 配置上下文压缩

需要让后续 Session 默认使用同一策略时，在创建 Agent 或更新 Agent 时配置 `context_management`：

```json
{
  "context_management": [
    {
      "type": "compaction",
      "compact_threshold": 100000,
      "instructions": "保留任务目标、已确认事实、关键标识、执行结果、未完成事项和下一步。"
    }
  ]
}
```

`compact_threshold` 控制自动压缩何时触发。只有需要固定触发阈值时才传入该字段；省略该字段或传 `null` 时，运行时使用平台默认阈值，查询响应会展示当前默认值。当前平台默认阈值为 `192000` token。

`instructions` 用于指导系统生成压缩摘要。只有需要改变摘要关注点时才填写；没有自定义要求时，可以省略、传 `null` 或传空字符串。

完整请求字段、取值规则和响应结构，详情请参见 [创建智能体](/docs/create-agent-api) 和 [更新智能体](/docs/update-agent-api)。

### 更新或清除策略

更新 Agent 时，`context_management` 会整体替换当前配置：

| 请求值 | 服务端处理 | 后续 Session 的行为 |
| --- | --- | --- |
| 省略或 `null` | 保留当前 Agent 版本中的配置。 | 继续继承原策略。 |
| `[]` | 清除 Agent 的自定义策略。 | 使用平台默认压缩策略；查询响应可展示平台当前默认策略和默认阈值。 |
| 单条 `compaction` 策略 | 整体替换当前配置。 | 继承新策略。 |

> **注意**
>
> 传入 `[]` 的含义是回到平台默认压缩策略，不是关闭压缩。当 Session 历史持续增长并达到平台默认阈值（当前为 `192000` token）时，运行时仍会按默认策略判断是否需要压缩较早的上下文，避免后续模型调用因上下文过长失败。当前接口不提供关闭自动压缩的配置项。

不要把高于模型上下文窗口的阈值当作关闭开关。服务端会保存该值，但模型调用可能在达到阈值前因输入超出模型窗口而失败。

## 为 Session 配置上下文压缩

如果只有当前任务需要不同策略，创建 Session 时设置 `agent.context_management`，并将 `agent.type` 设为 `agent_with_overrides`。覆写只写入当前 Session 的 Agent 配置快照，不创建新的 Agent 版本，也不影响其他 Session。

```json
{
  "agent": {
    "type": "agent_with_overrides",
    "id": "<AGENT_ID>",
    "context_management": [
      {
        "type": "compaction",
        "compact_threshold": 80000,
        "instructions": "保留代码片段、变量名、技术决策、测试结果和下一步。"
      }
    ]
  },
  "environment_id": "<ENVIRONMENT_ID>"
}
```

Session 覆写支持以下三种传值方式：

- 省略或传 `null`：继承所选 Agent 版本的配置。
- 传 `[]`：清除继承的自定义策略，改用平台默认压缩策略；查询响应可展示平台当前默认策略和默认阈值。
- 传入一项：整体替换所选 Agent 版本的策略。

完整请求结构，详情请参见 [创建会话](/docs/create-session-api)。

## 查询配置

查询 Agent 或 Session 时，响应会显示上下文管理策略。当前平台默认阈值为 `192000` token：

- 已显式保存 `compact_threshold` 时，响应返回保存的阈值。
- 已保存 `compaction` 策略但未保存 `compact_threshold` 时，响应保留已保存的 `instructions`，并显示平台当前默认阈值。
- 未保存自定义上下文压缩策略，或已通过 `[]` 清除自定义策略时，响应可显示一条 `compaction` 策略和平台当前默认阈值。
- 多智能体 Session 中，每个成员的 `context_management` 来自该成员创建时冻结的配置快照；响应展示默认值时，也不会改写成员快照。

查询响应中显示的默认值仅用于展示，不会写回 Agent 版本或 Session 快照。客户端如果把查询结果原样用于创建或更新请求，默认阈值 `192000` 会被保存为显式配置，之后不再跟随平台默认值变化。要继续使用平台默认阈值，创建或更新时省略 `compact_threshold` 或传 `null`。

压缩真正发生时，Session 事件流会返回 `agent.thread_context_compacted` 事件。该事件用于确认线程上下文已经完成摘要压缩，详情请参见 [会话事件结构参考](/docs/sessions-events-reference-v2)。

## 配置限制

- `context_management` 最多包含一项，`type` 固定为 `compaction`。
- 显式配置的 `compact_threshold` 不能小于 50000；其他字段取值、长度限制和错误码以对应 API Reference 为准。
- Agent 更新只影响之后创建的 Session，不改写已有 Session 的配置快照。
- Session Upgrade 不支持修改 `context_management`。需要使用新策略时，更新 Agent 后创建新 Session。

## 相关文档

- [Agent](/docs/define-agent)
- [启动 Session](/docs/start-session)
- [持久化记忆](/docs/persistent-memory)
- [上下文缓存](/docs/context-cache)